企业官网建设流程全解析

• 数据库
• 安全
• 后端

immudb 对外暴露的 gRPC 与 REST 接口统一由 pkg/api/schema/schema.proto 定义，并自动生成 Go 代码（schema.pb.go、schema_grpc.pb.go）、REST 网关（schema.pb.gw.go）、Swagger 定义（schema.swagger.json）以及本文档（pkg/api/schema/docs.md）。本文以协议文档为主体，完整梳理消息类型体系、三个核心枚举、ImmuService 的全部 RPC 方法，并结合仓库源码解释事务头（TxHeader）、双证明（DualProof）、预条件（Precondition）、索引可见性（sinceTx）等关键设计，帮助你在开发客户端、做二次集成或审计协议时快速定位每个字段与方法的语义。

协议概览：一份文档、两种接入方式

docs.md是schema.proto的渲染产物，包名为immudb.schema。从 schema.proto 可以看到，协议同时声明了：

• gRPC 服务：service ImmuService，提供约 100 个 RPC 方法；
• REST 映射：每个 RPC 通过google.api.http注解暴露 HTTP 端点（由 grpc-gateway 生成，如POST /db/set、POST /user）；
• OpenAPI/Swagger 元数据：base path 为/api，所有get/safeget类接口返回 base64 编码的 key/value，所有set/safeset类接口也要求 base64 编码输入；认证方式为Authorization: Bearer <token>。

因此在服务端实现层面，同一个业务逻辑同时服务 gRPC 与 REST 两种通道。服务端实现分散在 pkg/server 目录下，例如 KV/事务方法集中在 pkg/server/transaction.go，数据库管理集中在 pkg/server/db_operations.go，SQL 方法集中在 pkg/server/sql.go。

消息类型体系：按功能域归类

协议文档共定义了约 100 个 message，本文按功能域归类展开，每个字段的含义均以协议文档注释为准。

认证、会话与用户权限

Key-Value 读写

事务与读取一致性参数

TxHeader是 immudb 事务的元数据核心，理解它就能理解"为什么 immudb 可以证明数据没被篡改"：

配套消息：

• TxEntry：事务内原始条目，key含 1 字节类型前缀；hValue是值的哈希；注意字段注释：当len(value)==0且vLen>0时 value 必须忽略，否则sha256(value)必须等于hValue（即未内嵌值只给摘要，客户端可据此校验）。
• Tx：完整事务，含header、entries（原始条目）、kvEntries（解析后的 KV 条目）、zEntries（解析后的排序集合条目）。
• TxList/TxRequest/TxScanRequest：事务列表、按 ID 查询、事务扫描（initialTx、limit、desc、entriesSpec）。
• TxMetadata：事务级元数据，含truncatedTxID与extra。

读取一致性由KeyRequest.sinceTx/noWait控制，语义如下：

• atTx > 0：读取指定事务处的值（时间旅行）；
• sinceTx == 0且noWait == false：等待索引追上最新事务，提供 read-latest / read-your-writes 语义；
• sinceTx > 0且noWait == false：只要求索引至少处理到sinceTx事务；
• noWait == true：不等待任何索引更新，只考虑当前已索引状态；
• atRevision > 0：取第 n 个版本（1 为第一个版本）；atRevision < 0：取历史第 n 个版本（-1 为上一版本）。

ScanRequest.sinceTx的语义在协议文档中有更细致的描述：为 0（默认）时服务端在收到请求时刻捕获最新已提交事务 ID，并阻塞到索引器至少处理完该事务后再取快照，这给多客户端并发写入场景提供了"读最新/读己写"语义（文档注释中引用了 issue #2082）；> 0时只要求sinceTx之前的事务被索引，之后提交的事务可能仍在处理中、可能出现在结果里也可能不出现。ScanRequest.noWait已标记 Deprecated 并被忽略：服务端总是等待sinceTx解析出的事务被索引后才返回。

引用与排序集合

immudb 支持"引用"（Reference）与"排序集合"（Sorted Set，即 Z 结构，常用于排行榜类业务）：

• ReferenceRequest：key（引用名）、referencedKey（被引用 key）、atTx（绑定事务 ID）、boundRef（true 时绑定到特定事务，false 时始终读最新值）、noWait、preconditions。
• Reference：tx（引用写入事务）、key、atTx（绑定的事务，0 表示未绑定、读最新）、metadata、revision。
• ZAddRequest：set（集合名）、score（double）、key、atTx、boundRef、noWait。
• ZEntry：set、key、entry（被引用的 Entry）、score、atTx。
• ZScanRequest：set、seekKey、seekScore、seekAtTx、inclusiveSeek、limit、desc、minScore、maxScore、sinceTx、noWait（Deprecated）、offset——支持按 score 区间、游标与偏移三种扫描方式。
• Score：score(double)。

预条件（Precondition）：条件写入

Precondition是 immudb 实现 CAS（Compare-And-Swap）类语义的载体，支持三种：

它可挂在SetRequest、ExecAllRequest、ReferenceRequest上，配合pkg/api/schema/preconditions.go的校验实现，可用于实现"若 key 仍等于某版本则更新"的乐观锁写入。

可验证性：证明数据不可篡改

这是 immudb 与普通数据库最大的区别：读取返回的不只是数据，还有可离线校验的密码学证明。

• TxHeader中的prevAlh构成线性哈希链，blRoot/blTxId将事务接入主 Merkle 树；
• DualProof：包含 inclusion（包含性）与 consistency（一致性）双重证明，字段包括sourceTxHeader（较早事务头）、targetTxHeader（较晚事务头）、inclusionProof（源事务哈希在主 Merkle 树中的包含证明）、consistencyProof（源/目标两棵 Merkle 树间的一致性证明）、targetBlTxAlh、lastInclusionProof、linearProof（从targetBlTxAlh到最终状态值的线性证明）、LinearAdvanceProof（旧线性链与新 Merkle 树之间的一致性证明）；
• DualProofV2：V2 版本，仅含sourceTxHeader、targetTxHeader、inclusionProof、consistencyProof；
• InclusionProof：leaf（叶索引）、width（叶层树宽）、terms（证明项：从树中选出的哈希序列）；
• LinearProof：线性部分证明，sourceTxId、TargetTxId、terms（事务条目的内部哈希）；
• LinearAdvanceProof：linearProofTerms（线性链证明项）与inclusionProofs（链上各步的包含证明）；
• VerifiableTx/VerifiableTxV2：tx（待验证事务）+dualProof+signature（新状态值的签名）；
• VerifiableEntry：entry+verifiableTx+inclusionProof（条目在事务内的包含证明）；
• VerifiableSetRequest/VerifiableGetRequest/VerifiableReferenceRequest/VerifiableZAddRequest/VerifiableSQLGetRequest：可验证写/读请求，均带proveSinceTx（生成证明时与指定事务状态做一致性证明）；
• VerifiableSQLEntry：SQL 行的可验证读取，附带DatabaseId、TableId、PKIDs及ColNamesById、ColIdsByName、ColTypesById、ColLenById四组映射（用于校验原始条目值），以及MaxColId（新列分配 ID 的上限）；
• ImmutableState：db、txId、txHash、signature（状态哈希签名）、precommittedTxId、precommittedTxHash——即"最新状态 + 签名"，客户端可将其与本地信任锚对比；
• Signature：publicKey、signature。

上述证明机制的底层实现在 embedded/ahtree（Appendable Hash Tree）与 embedded/store 中，可验证性整体设计可参考 docs/security/PROOFS.md。

SQL 相关消息

immudb 内置 SQL 引擎，协议层设计如下：

数据库管理与运行时设置

• CreateDatabaseRequest：name、settings(DatabaseNullableSettings)、ifNotExists（已存在时不报错）；CreateDatabaseResponse返回name、settings（当前生效设置）、alreadyExisted。
• UpdateDatabaseRequest/UpdateDatabaseResponse：更新数据库设置并回读当前设置。
• DatabaseSettingsRequest/DatabaseSettingsResponse：查询当前设置。
• LoadDatabaseRequest/LoadDatabaseResponse：加载数据库到内存（文档注释提及未来可能增加 createIfNotExist）。
• UnloadDatabaseRequest/UnloadDatabaseResponse：卸载数据库。
• DeleteDatabaseRequest/DeleteDatabaseResponse：删除数据库。
• DatabaseListResponse/DatabaseListResponseV2/DatabaseInfo：数据库列表；V2 携带更丰富信息（name、settings、loaded（是否已加载）、diskSize、numTransactions、created_at、created_by）。
• DatabaseHealthResponse：pendingRequests（正在执行的请求数）、lastRequestCompletedAt（最近完成时间戳）。
• TruncateDatabaseRequest/Response：按retentionPeriod（数据保留期）截断数据库。
• FlushIndexRequest/Response：cleanupPercentage（flush 时节点文件清理百分比）、synced（是否全量磁盘同步）；返回database名。
• UseDatabaseReply：token（已 Deprecated 的数据库访问令牌）。

DatabaseNullableSettings是数据库级全部可调参数的载体（均用 Nullable 包装以支持部分更新），完整字段包括：

• 存储：fileSize（磁盘文件最大尺寸）、maxKeyLen、maxValueLen、maxTxEntries（单事务最大条目数）、embeddedValues（值是否与事务头一起存储，默认 true）、preallocFiles（文件预分配）、vLogCacheSize（值日志缓存）、txLogCacheSize（事务日志缓存）、vLogMaxOpenedFiles/txLogMaxOpenedFiles/commitLogMaxOpenedFiles（各类文件同时打开上限）；
• 并发与事务：maxConcurrency（同时准备写入的提交数）、maxIOConcurrency（并发 IO 写）、readTxPoolSize（读缓冲池）、maxActiveTransactions（预提交事务上限）、mvccReadSetLimit（每事务读条目上限）、writeBufferSize（写内存缓冲）、syncFrequency（提交过程 fsync 频率，毫秒）；
• 时间戳与兼容：excludeCommitTime（事务头不含提交时间戳）、writeTxHeaderVersion（事务头版本，限制可用特性）；
• 生命周期：autoload（启动时自动加载数据库，默认 true）；
• 子设置：replicationSettings、indexSettings、ahtSettings、truncationSettings。

IndexNullableSettings控制索引子系统（B 树实现位于 embedded/tbtree）：flushThreshold（两次磁盘 flush 之间的新索引条目数）、syncThreshold（两次带文件同步的 flush 之间的条目数）、cacheSize（B 树节点缓存字节数）、maxNodeSize（单节点最大字节）、maxActiveSnapshots（活动快照上限）、renewSnapRootAfter（快照根自动续期毫秒数）、compactionThld（触发全量压缩的最少更新条目数）、delayDuringCompaction（全量压缩期间索引的附加延迟）、nodesLogMaxOpenedFiles/historyLogMaxOpenedFiles/commitLogMaxOpenedFiles、flushBufferSize、cleanupPercentage（每次 flush 清理节点文件的百分比）、maxBulkSize（批量索引的最大事务数）、bulkPreparationTimeout（等待更多事务进入同一批次的超时毫秒数）。

ReplicationNullableSettings控制复制（实现位于 pkg/replication）：replica、primaryDatabase、primaryHost、primaryPort、primaryUsername、primaryPassword、syncReplication（同步复制）、syncAcks（提交所需同步副本确认数）、prefetchTxBufferSize、replicationCommitConcurrency、allowTxDiscarding（副本与主库分歧时丢弃预提交事务）、skipIntegrityCheck、waitForIndexing。

AHTNullableSettings：syncThreshold（树中两次同步落盘之间的新叶子数）、writeBufferSize（内存写缓冲大小）。TruncationNullableSettings：retentionPeriod（数据保留期）、truncationFrequency（截断频率）。

复制、流式与辅助消息

• Chunk/Chunk.MetadataEntry：流式传输的数据块，content(bytes) + 元数据键值对。
• ExportTxRequest：tx（要导出的事务 ID）、allowPreCommitted（允许导出未提交事务）、replicaState（同步复制时向主库通知副本状态）、skipIntegrityCheck（读取时跳过完整性校验）。
• ReplicaState：UUID、committedTxID、committedAlh、precommittedTxID、precommittedAlh——副本向主库报告自己的复制进度。
• EntriesSpec/EntryTypeSpec：控制事务内条目的解析方式（见枚举EntryTypeAction）。
• NewTxRequest/NewTxResponse：显式事务模式，mode(TxMode)、snapshotMustIncludeTxID（可复用包含指定事务的快照）、snapshotRenewalPeriod（快照最大年龄，毫秒）、unsafeMVCC（MVCC 时索引可能未追上）；transactionID为内部事务 ID。
• UseSnapshotRequest：sinceTx、asBeforeTx。
• ServerInfoRequest/ServerInfoResponse：version、startedAt（启动 Unix 秒时间戳）、numTransactions（全部数据库事务总数）、numDatabases、databasesDiskSize（全部数据库磁盘占用）。
• HealthResponse：status（服务端自评健康）、version。
• ErrorInfo（code、cause）、RetryInfo（retry_delay，毫秒）、DebugInfo（stack）：错误/重试/调试信息载体。
• Nullable 包装族：NullableBool、NullableFloat、NullableMilliseconds、NullableString、NullableUint32、NullableUint64——用于设置类消息实现"字段可部分更新"。
• AuthConfig与MTLSConfig：均标记 DEPRECATED（分别含kind与enabled字段），对应 RPCUpdateAuthConfig/UpdateMTLSConfig也已废弃。

枚举定义

EntryTypeAction（事务条目解析动作）

PermissionAction（权限动作）

TxMode（显式事务模式）

ImmuService：全部 RPC 方法一览

ImmuService是 immudb 唯一的服务接口，文档按功能标注了 DEPRECATED 与 NOT YET SUPPORTED 状态，下面按域归纳（方法签名细节以 pkg/api/schema/schema.proto 为准）：

• 用户与权限：ListUsers、CreateUser、ChangePassword、ChangePermission、ChangeSQLPrivileges、SetActiveUser、UpdateAuthConfig(DEPRECATED)、UpdateMTLSConfig(DEPRECATED)。
• 会话：OpenSession、CloseSession、KeepAlive、NewTx、Commit、Rollback、TxSQLExec、TxSQLQuery(stream)。
• 传统认证：Login(DEPRECATED)、Logout(DEPRECATED)。
• KV 读写：Set、VerifiableSet、Get、VerifiableGet、Delete、GetAll、ExecAll、Scan、Count(NOT YET SUPPORTED)、CountAll(NOT YET SUPPORTED)。
• 事务：TxById、VerifiableTxById、TxScan、History。
• 服务器信息与健康：ServerInfo、Health(DEPRECATED，用 ServerInfo 替代)、DatabaseHealth、CurrentState。
• 引用与排序集合：SetReference、VerifiableSetReference、ZAdd、VerifiableZAdd、ZScan。
• 数据库管理：CreateDatabase(DEPRECATED)、CreateDatabaseWith(DEPRECATED)、CreateDatabaseV2、LoadDatabase、UnloadDatabase、DeleteDatabase、DatabaseList(DEPRECATED)、DatabaseListV2、UseDatabase、UpdateDatabase(DEPRECATED)、UpdateDatabaseV2、GetDatabaseSettings(DEPRECATED)、GetDatabaseSettingsV2、FlushIndex、CompactIndex、TruncateDatabase。
• 流式传输：streamGet、streamSet、streamVerifiableGet、streamVerifiableSet、streamScan、streamZScan、streamHistory、streamExecAll——用于大数据量 KV 场景，以Chunk分块传输。
• 复制：exportTx、replicateTx、streamExportTx——事务导出/导入通道，支撑 pkg/replication 的异步与同步复制。
• SQL：SQLExec、UnarySQLQuery（为兼容 grpc-gateway API 保留）、SQLQuery(stream)、ListTables、DescribeTable、VerifiableSQLGet。

服务端对这些方法的实现在 pkg/server 下按文件拆分：KV/事务见 pkg/server/transaction.go，数据库生命周期见 pkg/server/db_operations.go，SQL 见 pkg/server/sql.go，流式复制见 pkg/server/stream_replication.go。

REST 网关与 Swagger

由于 schema.proto 中每个 RPC 都带google.api.http注解，grpc-gateway 生成的 schema.pb.gw.go 让同一协议自动暴露 REST 端点，例如：

• POST /user（CreateUser）、POST /user/password/change（ChangePassword）、POST /user/changepermission（ChangePermission）；
• POST /login、POST /logout；
• POST /db/set（Set）、POST /db/verifiable/set（VerifiableSet）、GET /db/get（Get）、POST /db/verifiable/get（VerifiableGet）。

Swagger 描述位于 schema.swagger.json，并可通过仓库 swagger 目录的默认页面在线浏览。REST 客户端务必注意：所有 key 与 value 均为base64 编码，认证头为Authorization: Bearer <token>（见 schema.proto 的 OpenAPI 元数据）。

标量类型映射

协议文档末尾给出了 .proto 标量到各语言（C++ / Java / Python / Go / C# / PHP / Ruby）的映射表，要点如下：

• double/float：各语言对应浮点类型（Go 为float64/float32）；
• int32/int64使用 varint 变长编码，对负数不友好，负值场景应改用sint32/sint64（Go 为int32/int64）；
• uint32/uint64同样为 varint 编码（Go 为uint32/uint64）；
• fixed32/fixed64固定 4/8 字节，数值经常大于 2^28 / 2^56 时更高效；
• bool/string（UTF-8 或 7-bit ASCII）/bytes（任意字节序列）为通用类型，Go 分别对应bool/string/[]byte。

这决定了客户端语言的字段类型选择，例如在 Go 客户端中直接使用生成代码 schema.pb.go 时，bytes字段天然映射为[]byte，与 pkg/client 的传输层无缝衔接。

小结

docs.md完整刻画了 immudb 的对外协议面：KV、排序集合、引用、SQL 四种数据模型共用同一服务接口；Set/Get与VerifiableSet/VerifiableGet成对出现，后者额外返回DualProof与Signature；sinceTx/noWait贯穿所有读取接口以精细控制索引可见性；Precondition提供条件写入能力；设置类消息全部使用 Nullable 包装以支持增量更新。掌握这份协议，无论使用 pkg/client 还是自行实现 gRPC/REST 客户端，都能准确对应每个字段与方法的真实语义，并为基于 immudb 做二次开发与集成奠定基础。

• 数据库
• 安全
• 后端