flowchart TB
    subgraph KernelLayer["Kernel 层"]
        KTx[KernelTransaction]
        CommitProc[TransactionCommitProcess]
    end
    
    subgraph StorageEngine["Storage Engine"]
        RecordEngine[RecordStorageEngine]
        StorageReader[StorageReader]
        CommandCreator[CommandCreationContext]
        
        subgraph WALSystem["WAL 系统"]
            TxLog[TransactionLog]
            LogAppender[LogAppender]
            LogRotation[LogRotation]
            Recovery[LogRecovery]
        end
    end
    
    subgraph NeoStoresLayer["NeoStores 层"]
        NeoStores[NeoStores<br/>存储容器]
        
        subgraph CoreStores["核心存储"]
            NodeStore[NodeStore<br/>节点存储]
            RelStore[RelationshipStore<br/>关系存储]
            PropStore[PropertyStore<br/>属性存储]
            RelGroupStore[RelationshipGroupStore<br/>关系组存储]
        end
        
        subgraph TokenStores["Token 存储"]
            LabelTokenStore[LabelTokenStore]
            RelTypeTokenStore[RelTypeTokenStore]
            PropKeyTokenStore[PropKeyTokenStore]
        end
        
        subgraph DynamicStores["动态存储"]
            PropStringStore[PropertyStringStore<br/>长字符串]
            PropArrayStore[PropertyArrayStore<br/>大数组]
            NodeLabelStore[NodeLabelStore<br/>标签列表]
        end
        
        subgraph MetaStores["元数据存储"]
            SchemaStore[SchemaStore<br/>模式定义]
            MetaDataStore[MetaDataStore<br/>数据库元信息]
        end
    end
    
    subgraph PageCacheLayer["Page Cache 层"]
        PageCache[PageCache<br/>页面缓存]
        PagedFile[PagedFile<br/>文件映射]
        PageCursor[PageCursor<br/>页面游标]
        
        subgraph CacheManagement["缓存管理"]
            EvictionThread[EvictionThread<br/>驱逐线程]
            PageFaulter[PageFaulter<br/>缺页处理]
            DirtyTracker[DirtyTracker<br/>脏页追踪]
        end
    end
    
    subgraph IOLayer["I/O 层"]
        FileSystem[FileSystem<br/>文件系统抽象]
        PageSwapper[PageSwapper<br/>页面交换器]
        DiskIO[(磁盘存储)]
    end
    
    subgraph Support["支撑组件"]
        IdGen[IdGeneratorFactory<br/>ID 生成器]
        RecordFormat[RecordFormats<br/>存储格式]
        CheckpointScheduler[CheckpointScheduler<br/>Checkpoint 调度]
    end
    
    %% 连接关系
    KTx --> CommitProc
    CommitProc --> RecordEngine
    
    RecordEngine --> NeoStores
    RecordEngine --> WALSystem
    RecordEngine --> CommandCreator
    
    TxLog --> LogAppender
    TxLog --> Recovery
    LogAppender --> PageCache
    
    NeoStores --> CoreStores
    NeoStores --> TokenStores
    NeoStores --> DynamicStores
    NeoStores --> MetaStores
    
    NodeStore --> PageCache
    RelStore --> PageCache
    PropStore --> PageCache
    RelGroupStore --> PageCache
    
    PageCache --> PagedFile
    PagedFile --> PageCursor
    PageCache --> CacheManagement
    
    PageCursor --> PageSwapper
    PageSwapper --> FileSystem
    FileSystem --> DiskIO
    
    NeoStores --> IdGen
    NeoStores --> RecordFormat
    RecordEngine --> CheckpointScheduler

classDiagram
    class NodeRecord {
        +long id
        +long nextProp
        +long nextRel
        +long labels
        +boolean dense
        +List~DynamicRecord~ dynamicLabelRecords
        
        +initialize(inUse, nextProp, dense, nextRel, labels)
        +getNextRel() long
        +setNextRel(nextRel)
        +getLabels() long
        +isDense() boolean
    }
    
    class RelationshipRecord {
        +long id
        +long firstNode
        +long secondNode
        +int type
        +long firstPrevRel
        +long firstNextRel
        +long secondPrevRel
        +long secondNextRel
        +long nextProp
        +boolean firstInFirstChain
        +boolean firstInSecondChain
        
        +initialize(...)
        +getFirstNode() long
        +getSecondNode() long
        +getType() int
    }
    
    class PropertyRecord {
        +long id
        +long nextProp
        +List~PropertyBlock~ propertyBlocks
        
        +addPropertyBlock(PropertyBlock)
        +getPropertyBlock(int) PropertyBlock
        +numberOfProperties() int
    }
    
    class PropertyBlock {
        +int keyId
        +PropertyType type
        +long[] valueBlocks
        +List~DynamicRecord~ valueRecords
        
        +getSingleValueLong() long
        +getSingleValueInt() int
        +getValueRecords() List~DynamicRecord~
    }
    
    class DynamicRecord {
        +long id
        +byte[] data
        +long nextBlock
        +int length
        +boolean startRecord
        
        +getData() byte[]
        +getNextBlock() long
        +isStartRecord() boolean
    }
    
    class PageCursor {
        <<interface>>
        +next() boolean
        +next(long pageId) boolean
        +shouldRetry() boolean
        +getByte() byte
        +getByte(int offset) byte
        +putByte(byte value)
        +putByte(int offset, byte value)
        +getLong() long
        +putLong(long value)
        +getOffset() int
        +setOffset(int offset)
    }
    
    class PagedFile {
        <<interface>>
        +io(long pageId, int flags, CursorContext) PageCursor
        +pageSize() int
        +fileSize() long
        +flushAndForce() void
        +close() void
    }
    
    class StorageCommand {
        <<interface>>
        +handle(CommandVisitor) void
    }
    
    class NodeCommand {
        -NodeRecord before
        -NodeRecord after
        
        +getBefore() NodeRecord
        +getAfter() NodeRecord
        +handle(CommandVisitor) void
    }
    
    class RelationshipCommand {
        -RelationshipRecord before
        -RelationshipRecord after
        
        +getBefore() RelationshipRecord
        +getAfter() RelationshipRecord
    }
    
    PropertyRecord --> PropertyBlock
    PropertyBlock --> DynamicRecord
    NodeRecord --> DynamicRecord
    
    StorageCommand <|-- NodeCommand
    StorageCommand <|-- RelationshipCommand
    
    NodeCommand --> NodeRecord
    RelationshipCommand --> RelationshipRecord
    
    PagedFile --> PageCursor

enum PropertyType {
    BOOL,           // 1 字节
    BYTE,           // 1 字节
    SHORT,          // 2 字节
    INT,            // 4 字节
    LONG,           // 8 字节
    FLOAT,          // 4 字节
    DOUBLE,         // 8 字节
    SHORT_STRING,   // 内联字符串（< 64 字节）
    STRING,         // 长字符串（动态记录）
    SHORT_ARRAY,    // 内联数组（< 64 字节）
    ARRAY           // 大数组（动态记录）
}

public interface StorageEngineTransaction extends AutoCloseable {
    // 获取事务ID
    long getTransactionId();
    
    // 获取命令列表
    List<StorageCommand> commands();
    
    // 获取追加索引（日志位置）
    long getAppendIndex();
}

public enum TransactionApplicationMode {
    // 内部应用（事务提交）
    INTERNAL,
    
    // 外部应用（WAL 恢复）
    EXTERNAL,
    
    // 恢复应用（崩溃恢复）
    RECOVERY,
    
    // 反向应用（回滚）
    REVERSE
}

// community/record-storage-engine/src/main/java/org/neo4j/internal/recordstorage/RecordStorageEngine.java
public void apply(StorageEngineTransaction batch, TransactionApplicationMode mode) throws IOException {
    // 1. 获取批次锁（串行化写操作）
    lockService.acquireShared(
        LockTracer.NONE,
        ResourceTypes.SCHEMA,
        ResourceIds.schemaResource()
    );
    
    try {
        // 2. 应用命令到存储
        for (StorageCommand command : batch.commands()) {
            // 访问者模式：每种命令类型有不同的处理逻辑
            command.handle(new CommandHandler() {
                @Override
                public void visitNodeCommand(NodeCommand command) {
                    // 应用节点命令
                    applyNodeCommand(command, mode);
                }
                
                @Override
                public void visitRelationshipCommand(RelationshipCommand command) {
                    // 应用关系命令
                    applyRelationshipCommand(command, mode);
                }
                
                @Override
                public void visitPropertyCommand(PropertyCommand command) {
                    // 应用属性命令
                    applyPropertyCommand(command, mode);
                }
                
                // ... 其他命令类型
            });
        }
        
        // 3. 更新索引（如果是内部应用）
        if (mode == TransactionApplicationMode.INTERNAL) {
            indexingService.apply(batch.commands());
        }
        
        // 4. 更新统计信息
        if (mode != TransactionApplicationMode.REVERSE) {
            countsStore.apply(batch.getTransactionId(), batch.commands());
        }
    } finally {
        // 5. 释放锁
        lockService.releaseShared(
            ResourceTypes.SCHEMA,
            ResourceIds.schemaResource()
        );
    }
}

private void applyNodeCommand(NodeCommand command, TransactionApplicationMode mode) {
    NodeRecord after = command.getAfter();
    
    try (PageCursor cursor = pagedFile.io(
        nodeStore.pageIdForRecord(after.getId()),
        PagedFile.PF_SHARED_WRITE_LOCK,
        cursorContext
    )) {
        if (cursor.next()) {
            do {
                // 将 NodeRecord 编码到页面
                nodeStore.updateRecord(after, cursor, cursorContext, storeCursors);
            } while (cursor.shouldRetry());
        }
    }
}

// PagedFile 标志位
public static final int PF_SHARED_READ_LOCK = 0x01;   // 共享读锁
public static final int PF_SHARED_WRITE_LOCK = 0x02;  // 共享写锁
public static final int PF_NO_GROW = 0x04;            // 不扩展文件
public static final int PF_NO_FAULT = 0x08;           // 不触发缺页

// 读取节点记录
public NodeRecord readNode(long nodeId) {
    long pageId = nodeStore.pageIdForRecord(nodeId);
    int offset = nodeStore.offsetForId(nodeId);
    
    try (PageCursor cursor = pagedFile.io(
        pageId,
        PagedFile.PF_SHARED_READ_LOCK,
        cursorContext
    )) {
        if (cursor.next()) {
            do {
                // 定位到记录位置
                cursor.setOffset(offset);
                
                // 读取节点记录字段
                byte headerByte = cursor.getByte();
                boolean inUse = (headerByte & 0x01) != 0;
                boolean dense = (headerByte & 0x02) != 0;
                
                long nextRel = cursor.getLong();
                long nextProp = cursor.getLong();
                long labels = cursor.getLong();
                
                // 构造 NodeRecord
                return new NodeRecord(nodeId)
                    .initialize(inUse, nextProp, dense, nextRel, labels);
                    
            } while (cursor.shouldRetry());
        }
    }
    
    return null;
}

// 写入关系记录
public void writeRelationship(RelationshipRecord record) {
    long pageId = relationshipStore.pageIdForRecord(record.getId());
    int offset = relationshipStore.offsetForId(record.getId());
    
    try (PageCursor cursor = pagedFile.io(
        pageId,
        PagedFile.PF_SHARED_WRITE_LOCK,
        cursorContext
    )) {
        if (cursor.next()) {
            do {
                // 定位到记录位置
                cursor.setOffset(offset);
                
                // 写入关系记录字段
                byte headerByte = 0;
                headerByte |= record.inUse() ? 0x01 : 0x00;
                headerByte |= record.isFirstInFirstChain() ? 0x02 : 0x00;
                headerByte |= record.isFirstInSecondChain() ? 0x04 : 0x00;
                cursor.putByte(headerByte);
                
                cursor.putLong(record.getFirstNode());
                cursor.putLong(record.getSecondNode());
                cursor.putInt(record.getType());
                cursor.putLong(record.getFirstPrevRel());
                cursor.putLong(record.getFirstNextRel());
                cursor.putLong(record.getSecondPrevRel());
                cursor.putLong(record.getSecondNextRel());
                cursor.putLong(record.getNextProp());
                
                // 标记页面为脏页
                cursor.setDirty();
                
            } while (cursor.shouldRetry());
        }
    }
}

public interface TransactionChunkAppender {
    // 开始新的事务块
    ChunkWriter beginChunk();
    
    // 提交事务块
    void commitChunk(ChunkWriter writer) throws IOException;
}

// community/kernel/src/main/java/org/neo4j/kernel/impl/transaction/log/TransactionLogAppender.java
public long append(List<StorageCommand> commands, TransactionChunkAppender appender) throws IOException {
    // 1. 获取写锁（串行化日志写入）
    appendLock.lock();
    try {
        // 2. 开始新的事务块
        ChunkWriter writer = appender.beginChunk();
        
        // 3. 写入事务头
        writer.putByte(TX_START);
        writer.putInt(kernelVersion.version());
        writer.putLong(transactionId);
        writer.putLong(commitTime);
        writer.putLong(latestCommittedTxWhenStarted);
        
        // 4. 序列化命令
        for (StorageCommand command : commands) {
            // 写入命令类型标记
            writer.putByte(commandType(command));
            
            // 写入命令数据
            command.serialize(writer);
        }
        
        // 5. 写入事务尾
        writer.putByte(TX_END);
        
        // 6. 提交事务块（刷新到日志文件）
        appender.commitChunk(writer);
        
        // 7. 检查是否需要日志轮转
        if (channel.position() >= rotationThreshold) {
            logRotation.rotateLogFile(LogAppendEvent.NULL);
        }
        
        // 8. 返回追加索引（日志位置）
        return currentLogPosition.getByteOffset();
        
    } finally {
        appendLock.unlock();
    }
}

+----------------+
| TX_START (1B)  |
+----------------+
| Version (4B)   |
+----------------+
| TxId (8B)      |
+----------------+
| CommitTime(8B) |
+----------------+
| Commands...    |
+----------------+
| TX_END (1B)    |
+----------------+

sequenceDiagram
    autonumber
    participant KTx as KernelTransaction
    participant Ops as Operations
    participant TxState as TxState
    participant Commit as CommitProcess
    participant Engine as RecordStorageEngine
    participant NeoStores as NeoStores
    participant PageCache as PageCache
    participant WAL as TransactionLog
    
    KTx->>Ops: dataWrite().nodeCreate()
    Ops->>Ops: 分配节点 ID
    Note over Ops: commandCreationContext.reserveNode()
    Ops->>TxState: nodeDoCreate(nodeId)
    TxState->>TxState: 记录节点创建
    
    KTx->>Commit: commit(commands)
    Commit->>Engine: createCommands(txState, reader, ...)
    Engine->>TxState: 遍历变更集
    TxState-->>Engine: 返回新增节点列表
    
    Engine->>Engine: 生成 NodeCommand
    Note over Engine: NodeCommand{before=null, after=NodeRecord}
    Engine-->>Commit: 返回 StorageCommand 列表
    
    Commit->>WAL: append(commands)
    WAL->>WAL: 序列化命令
    WAL->>PageCache: 写入日志页面
    PageCache->>PageCache: 标记 Dirty Page
    WAL-->>Commit: 返回 TransactionId
    
    Commit->>Engine: apply(batch, INTERNAL)
    Engine->>NeoStores: getNodeStore()
    NeoStores-->>Engine: NodeStore 实例
    
    Engine->>PageCache: io(pageId, PF_SHARED_WRITE_LOCK)
    PageCache-->>Engine: PageCursor 实例
    
    Engine->>Engine: cursor.next()
    Engine->>Engine: cursor.setOffset(offset)
    Engine->>Engine: 编码 NodeRecord 到页面
    Note over Engine: cursor.putByte(headerByte)<br/>cursor.putLong(nextRel)<br/>cursor.putLong(nextProp)
    
    Engine->>Engine: cursor.setDirty()
    Engine->>Engine: cursor.close()
    
    Note over PageCache: Checkpoint 线程<br/>定期刷新 Dirty Pages
    
    PageCache->>PageCache: flushAndForce()
    PageCache->>PageCache: 遍历 Dirty Pages
    PageCache->>PageCache: pageSwapper.write(page, fileOffset)

sequenceDiagram
    autonumber
    participant Cursor as PageCursor
    participant PagedFile as PagedFile
    participant Cache as PageCache
    participant Faulter as PageFaulter
    participant Evictor as EvictionThread
    participant Swapper as PageSwapper
    participant Disk as 磁盘
    
    Cursor->>PagedFile: next(pageId)
    PagedFile->>PagedFile: 查找页面映射表
    PagedFile->>PagedFile: 页面未在内存中
    
    PagedFile->>Cache: acquirePage(pageId)
    Cache->>Cache: 查找空闲页面
    Cache->>Cache: 无空闲页面
    
    Cache->>Evictor: 触发驱逐
    Evictor->>Evictor: 扫描页面访问计数
    Evictor->>Evictor: 找到访问计数为 0 的页面
    
    alt 页面是脏页
        Evictor->>Swapper: write(page, fileOffset)
        Swapper->>Disk: 写入磁盘
        Disk-->>Swapper: 写入完成
    end
    
    Evictor->>Cache: 标记页面为空闲
    Cache-->>PagedFile: 返回空闲页面
    
    PagedFile->>Faulter: fault(page, pageId)
    Faulter->>Swapper: read(pageId)
    Swapper->>Disk: 读取页面数据
    Disk-->>Swapper: 返回页面数据
    Swapper-->>Faulter: 填充页面
    
    Faulter->>PagedFile: 更新页面映射表
    PagedFile-->>Cursor: 返回已绑定页面的游标
    
    Cursor->>Cursor: 读取页面数据

/path/to/neo4j-db/
├── neostore
├── neostore.nodestore.db
├── neostore.nodestore.db.id
├── neostore.relationshipstore.db
├── neostore.relationshipstore.db.id
├── neostore.propertystore.db
├── neostore.propertystore.db.id
├── neostore.propertystore.db.strings
├── neostore.propertystore.db.strings.id
├── neostore.propertystore.db.arrays
├── neostore.propertystore.db.arrays.id
├── neostore.relationshipgroupstore.db
├── neostore.relationshipgroupstore.db.id
├── neostore.schemastore.db
├── neostore.labeltokenstore.db
├── neostore.relationshiptypestore.db
├── neostore.propertystore.db.index.keys
├── neostore.transaction.db.0
├── neostore.transaction.db.1
├── neostore.transaction.db.2
└── neostore.counts.db

# ❌ 低效配置：仅 512MB
server.memory.pagecache.size=512M

# ✅ 推荐配置：8GB 物理内存 → 4-5GB Page Cache
server.memory.pagecache.size=4G

# 堆内存配置（剩余内存分配给堆）
server.memory.heap.initial_size=2G
server.memory.heap.max_size=2G

# 查看 Page Cache 命中率
neo4j-admin server report --verbose

# 目标命中率：> 90%
# 如果 < 90%，增加 Page Cache 大小或优化查询

// ❌ 低效查询：全关系扫描
MATCH (user:User {id: 1})-[r]->(friend)
RETURN count(friend)

// ✅ 高效查询：仅扫描 FOLLOWS 关系
MATCH (user:User {id: 1})-[r:FOLLOWS]->(friend)
RETURN count(friend)

# 降低 Dense 节点阈值（默认 50）
db.relationship_grouping_threshold=20

// ❌ 低效实现：每条执行一次事务
UNWIND $data AS row
CREATE (n:Person {name: row.name, age: row.age})

# ✅ 批量导入工具（离线）
neo4j-admin database import full \
  --nodes=Person=persons.csv \
  --relationships=KNOWS=knows.csv \
  --overwrite-destination \
  neo4j

# 性能提升：100 倍以上
# 原理：绕过事务层，直接写入存储文件

// 批量大小：10000
:auto USING PERIODIC COMMIT 10000
LOAD CSV WITH HEADERS FROM 'file:///persons.csv' AS row
CREATE (n:Person {name: row.name, age: toInteger(row.age)})

# ❌ 低效配置：30 分钟一次 Checkpoint
db.checkpoint.interval.time=30m

# ✅ 推荐配置：5 分钟一次 Checkpoint
db.checkpoint.interval.time=5m

# 或基于事务日志大小触发
db.checkpoint.interval.tx=10000

import org.neo4j.io.pagecache.PageCache;
import org.neo4j.io.pagecache.PagedFile;
import org.neo4j.io.pagecache.PageCursor;

public class PageCacheExample {
    public void readNodeRecord(PageCache pageCache, Path nodeStoreFile) throws IOException {
        // 1. 映射文件到 Page Cache
        try (PagedFile pagedFile = pageCache.map(
            nodeStoreFile,
            8192, // 页面大小
            "neo4j",
            ImmutableSet.of(StandardOpenOption.READ)
        )) {
            // 2. 创建游标
            try (PageCursor cursor = pagedFile.io(
                0, // 页面 ID
                PagedFile.PF_SHARED_READ_LOCK,
                cursorContext
            )) {
                // 3. 读取页面
                if (cursor.next()) {
                    do {
                        // 读取节点记录
                        byte headerByte = cursor.getByte();
                        boolean inUse = (headerByte & 0x01) != 0;
                        
                        if (inUse) {
                            long nextRel = cursor.getLong();
                            long nextProp = cursor.getLong();
                            System.out.println("Node: nextRel=" + nextRel + ", nextProp=" + nextProp);
                        }
                    } while (cursor.shouldRetry());
                }
            }
        }
    }
}

import org.neo4j.storageengine.api.StorageEngine;
import org.neo4j.storageengine.api.StorageEngineFactory;

@ServiceProvider
public class CustomStorageEngineFactory implements StorageEngineFactory {
    @Override
    public String name() {
        return "custom-storage";
    }
    
    @Override
    public StorageEngine instantiate(
        FileSystemAbstraction fs,
        DatabaseLayout layout,
        Config config,
        PageCache pageCache,
        TokenHolders tokenHolders,
        ...
    ) {
        // 返回自定义存储引擎实现
        return new CustomStorageEngine(...);
    }
}