immudb gRPC 协议深度指南：schema.proto 消息模型、ImmuService 服务与可验证性设计全解

数据库安全后端【免费下载链接】immudbimmudb - immutable database based on zero trust, SQL/Key-Value/Document model, tamperproof, data change history项目地址https://gitcode.com/gh_mirrors/im/immudb点击查看免费下载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 /userOpenAPI/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.goSQL 方法集中在 pkg/server/sql.go。消息类型体系按功能域归类协议文档共定义了约 100 个 message本文按功能域归类展开每个字段的含义均以协议文档注释为准。认证、会话与用户权限消息关键字段说明LoginRequest/LoginResponseuser(bytes)、password(bytes)token(string)、warning(bytes)已标记 Deprecated官方建议改用 session 认证warning用于提示如请修改密码等附加信息OpenSessionRequest/OpenSessionResponseusername、password、databaseNamesessionID、serverUUID会话式认证打开会话后返回会话 ID 与服务器 UUIDCreateUserRequestuser、password、permission(uint32)、databasepermission取值1 只读、2 读写、254 管理员ChangePasswordRequestuser、oldPassword、newPassword修改用户密码ChangePermissionRequestaction(PermissionAction)、username、database、permission授予/撤销数据库级权限1 只读、2 读写、254 管理员ChangeSQLPrivilegesRequest/Responseaction、username、database、privileges(repeated string)SQL 级权限SELECT、CREATE、INSERT、UPDATE、DELETE、DROP、ALTERSetActiveUserRequestactive(bool)、username激活/停用用户User/UserListuser、permissions、createdby、createdat、active、sqlPrivileges用户及其权限集合UserList.users为用户列表Permission/SQLPrivilegedatabase、permission(uint32)database、privilege权限值1 只读、2 读写、254 管理员、255 系统管理员UserRequestuser查询单个用户Key-Value 读写消息关键字段说明Key/KeyPrefix/KeyListRequestkey(bytes)、prefix(bytes)、keys(repeated bytes)单个 key、前缀扫描、批量 key 查询KeyValuekey、value、metadata(KVMetadata)KV 写入单元SetRequestKVs(repeated KeyValue)、noWait(bool)、preconditions(repeated Precondition)批量写入noWaittrue时不等待索引器处理该事务preconditions是写前条件校验DeleteKeysRequestkeys(repeated bytes)、sinceTx(uint64)、noWait逻辑删除不物理擦除仅打删除标记sinceTx0时等待索引追上最新状态0时只要求索引到指定事务GetAll方法使用KeyListRequest—批量读取返回EntriesKeyRequestkey、atTx、sinceTx、noWait、atRevision核心读取参数详见下文读取一致性小节Entrytx、key、value、referencedBy、metadata、expired、revision读取结果tx是目标值实际写入的事务 ID而非引用事务expiredtrue表示条目已过期且不返回 valuerevision在GetAt场景下为 0Entriesentries(repeated Entry)批量读取结果HistoryRequestkey、offset、limit、desc、sinceTx单 key 全部历史版本含偏移、倒序、索引可见性控制ScanRequestseekKey、endKey、prefix、desc、limit、sinceTx、noWait、inclusiveSeek、inclusiveEnd、offset范围/前缀扫描详见下文EntryCountcount(uint64)计数结果Count/CountAll方法目前标记为 NOT YET SUPPORTEDExpirationexpiresAt(int64)条目过期时间Unix 秒级时间戳KVMetadatadeleted、expiration、nonIndexable条目元数据逻辑删除标记、过期信息、不入索引仅可经GetAt访问Opkv、zAdd、ref复合写操作的一种KV 写 / 排序集合写 / 引用写ExecAllRequestOperations(repeated Op)、noWait、preconditions在单个事务内执行一组混合操作KV ZAdd Reference事务与读取一致性参数TxHeader是 immudb 事务的元数据核心理解它就能理解为什么 immudb 可以证明数据没被篡改字段含义id事务 ID单调递增prevAlh前一事务的状态值Accumulative HashAlh形成哈希链ts事务提交的 Unix 时间戳秒nentries事务内条目数eH条目哈希事务内所有条目的累积哈希blTxId二叉链接树事务 ID已进入主 Merkle 树的最后事务 IDblRoot二叉链接树根Merkle 树根哈希version事务头版本可通过数据库设置writeTxHeaderVersion限制可用特性metadata事务级元数据truncatedTxID、extra配套消息TxEntry事务内原始条目key含 1 字节类型前缀hValue是值的哈希注意字段注释当len(value)0且vLen0时 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 结构常用于排行榜类业务ReferenceRequestkey引用名、referencedKey被引用 key、atTx绑定事务 ID、boundReftrue 时绑定到特定事务false 时始终读最新值、noWait、preconditions。Referencetx引用写入事务、key、atTx绑定的事务0 表示未绑定、读最新、metadata、revision。ZAddRequestset集合名、scoredouble、key、atTx、boundRef、noWait。ZEntryset、key、entry被引用的 Entry、score、atTx。ZScanRequestset、seekKey、seekScore、seekAtTx、inclusiveSeek、limit、desc、minScore、maxScore、sinceTx、noWaitDeprecated、offset——支持按 score 区间、游标与偏移三种扫描方式。Scorescore(double)。预条件Precondition条件写入Precondition是 immudb 实现 CASCompare-And-Swap类语义的载体支持三种子类型语义KeyMustExistPrecondition仅当给定 key 存在时写入成功KeyMustNotExistPrecondition仅当给定 key 不存在时写入成功KeyNotModifiedAfterTXPrecondition仅当给定 key 在指定事务之后未被修改时写入成功txID用于对照它可挂在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 树之间的一致性证明DualProofV2V2 版本仅含sourceTxHeader、targetTxHeader、inclusionProof、consistencyProofInclusionProofleaf叶索引、width叶层树宽、terms证明项从树中选出的哈希序列LinearProof线性部分证明sourceTxId、TargetTxId、terms事务条目的内部哈希LinearAdvanceProoflinearProofTerms线性链证明项与inclusionProofs链上各步的包含证明VerifiableTx/VerifiableTxV2tx待验证事务dualProofsignature新状态值的签名VerifiableEntryentryverifiableTxinclusionProof条目在事务内的包含证明VerifiableSetRequest/VerifiableGetRequest/VerifiableReferenceRequest/VerifiableZAddRequest/VerifiableSQLGetRequest可验证写/读请求均带proveSinceTx生成证明时与指定事务状态做一致性证明VerifiableSQLEntrySQL 行的可验证读取附带DatabaseId、TableId、PKIDs及ColNamesById、ColIdsByName、ColTypesById、ColLenById四组映射用于校验原始条目值以及MaxColId新列分配 ID 的上限ImmutableStatedb、txId、txHash、signature状态哈希签名、precommittedTxId、precommittedTxHash——即最新状态 签名客户端可将其与本地信任锚对比SignaturepublicKey、signature。上述证明机制的底层实现在 embedded/ahtreeAppendable Hash Tree与 embedded/store 中可验证性整体设计可参考 docs/security/PROOFS.md。SQL 相关消息immudb 内置 SQL 引擎协议层设计如下消息关键字段说明SQLExecRequestsql(string)、params(repeated NamedParam)、noWait执行写 SQLnoWaittrue时不等待索引SQLExecResulttxs(repeated CommittedSQLTx)、ongoingTx(bool)执行结果产生的事务列表ongoingTx表示执行后是否仍有未提交事务CommittedSQLTxheader、updatedRows、lastInsertedPKs、firstInsertedPKs已提交 SQL 事务更新行数与自增主键的首/末值按表名映射SQLQueryRequestsql、params、reuseSnapshot(Deprecated)、acceptStream查询acceptStream表示客户端是否接受流式响应SQLQueryResultcolumns(repeated Column)、rows(repeated Row)查询结果Column/Rownametypecolumnsvalues列描述与行数据SQLGetRequesttable、pkValues(repeated SQLValue)、atTx、sinceTx按主键读取一行支持时间旅行NamedParamname、value命名参数绑定SQLValuenull、n(int64)、s(string)、b(bool)、bs(bytes)、ts(int64)、f(double)参数化 SQL 值类型覆盖 NULL / 整数 / 字符串 / 布尔 / 字节 / 时间戳 / 浮点SQLEntrytx、key、value、metadata行的原始 KV 表示TabletableName表描述数据库管理与运行时设置CreateDatabaseRequestname、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。DatabaseHealthResponsependingRequests正在执行的请求数、lastRequestCompletedAt最近完成时间戳。TruncateDatabaseRequest/Response按retentionPeriod数据保留期截断数据库。FlushIndexRequest/ResponsecleanupPercentageflush 时节点文件清理百分比、synced是否全量磁盘同步返回database名。UseDatabaseReplytoken已 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/tbtreeflushThreshold两次磁盘 flush 之间的新索引条目数、syncThreshold两次带文件同步的 flush 之间的条目数、cacheSizeB 树节点缓存字节数、maxNodeSize单节点最大字节、maxActiveSnapshots活动快照上限、renewSnapRootAfter快照根自动续期毫秒数、compactionThld触发全量压缩的最少更新条目数、delayDuringCompaction全量压缩期间索引的附加延迟、nodesLogMaxOpenedFiles/historyLogMaxOpenedFiles/commitLogMaxOpenedFiles、flushBufferSize、cleanupPercentage每次 flush 清理节点文件的百分比、maxBulkSize批量索引的最大事务数、bulkPreparationTimeout等待更多事务进入同一批次的超时毫秒数。ReplicationNullableSettings控制复制实现位于 pkg/replicationreplica、primaryDatabase、primaryHost、primaryPort、primaryUsername、primaryPassword、syncReplication同步复制、syncAcks提交所需同步副本确认数、prefetchTxBufferSize、replicationCommitConcurrency、allowTxDiscarding副本与主库分歧时丢弃预提交事务、skipIntegrityCheck、waitForIndexing。AHTNullableSettingssyncThreshold树中两次同步落盘之间的新叶子数、writeBufferSize内存写缓冲大小。TruncationNullableSettingsretentionPeriod数据保留期、truncationFrequency截断频率。复制、流式与辅助消息Chunk/Chunk.MetadataEntry流式传输的数据块content(bytes) 元数据键值对。ExportTxRequesttx要导出的事务 ID、allowPreCommitted允许导出未提交事务、replicaState同步复制时向主库通知副本状态、skipIntegrityCheck读取时跳过完整性校验。ReplicaStateUUID、committedTxID、committedAlh、precommittedTxID、precommittedAlh——副本向主库报告自己的复制进度。EntriesSpec/EntryTypeSpec控制事务内条目的解析方式见枚举EntryTypeAction。NewTxRequest/NewTxResponse显式事务模式mode(TxMode)、snapshotMustIncludeTxID可复用包含指定事务的快照、snapshotRenewalPeriod快照最大年龄毫秒、unsafeMVCCMVCC 时索引可能未追上transactionID为内部事务 ID。UseSnapshotRequestsinceTx、asBeforeTx。ServerInfoRequest/ServerInfoResponseversion、startedAt启动 Unix 秒时间戳、numTransactions全部数据库事务总数、numDatabases、databasesDiskSize全部数据库磁盘占用。HealthResponsestatus服务端自评健康、version。ErrorInfocode、cause、RetryInforetry_delay毫秒、DebugInfostack错误/重试/调试信息载体。Nullable 包装族NullableBool、NullableFloat、NullableMilliseconds、NullableString、NullableUint32、NullableUint64——用于设置类消息实现字段可部分更新。AuthConfig与MTLSConfig均标记 DEPRECATED分别含kind与enabled字段对应 RPCUpdateAuthConfig/UpdateMTLSConfig也已废弃。枚举定义EntryTypeAction事务条目解析动作名称值语义EXCLUDE0从结果中排除该类条目ONLY_DIGEST1以原始未解析形式提供 key仅提供值的摘要RAW_VALUE2以原始形式提供 key 与 valueRESOLVE3解析 key/value并在需要时解析引用PermissionAction权限动作名称值语义GRANT0授予权限REVOKE1撤销权限TxMode显式事务模式名称值语义ReadOnly0只读事务WriteOnly1只写事务ReadWrite2读写事务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 的异步与同步复制。SQLSQLExec、UnarySQLQuery为兼容 grpc-gateway API 保留、SQLQuery(stream)、ListTables、DescribeTable、VerifiableSQLGet。服务端对这些方法的实现在 pkg/server 下按文件拆分KV/事务见 pkg/server/transaction.go数据库生命周期见 pkg/server/db_operations.goSQL 见 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 /userCreateUser、POST /user/password/changeChangePassword、POST /user/changepermissionChangePermissionPOST /login、POST /logoutPOST /db/setSet、POST /db/verifiable/setVerifiableSet、GET /db/getGet、POST /db/verifiable/getVerifiableGet。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/float32int32/int64使用 varint 变长编码对负数不友好负值场景应改用sint32/sint64Go 为int32/int64uint32/uint64同样为 varint 编码Go 为uint32/uint64fixed32/fixed64固定 4/8 字节数值经常大于 2^28 / 2^56 时更高效bool/stringUTF-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与SignaturesinceTx/noWait贯穿所有读取接口以精细控制索引可见性Precondition提供条件写入能力设置类消息全部使用 Nullable 包装以支持增量更新。掌握这份协议无论使用 pkg/client 还是自行实现 gRPC/REST 客户端都能准确对应每个字段与方法的真实语义并为基于 immudb 做二次开发与集成奠定基础。赞分享数据库安全后端【免费下载链接】immudbimmudb - immutable database based on zero trust, SQL/Key-Value/Document model, tamperproof, data change history项目地址https://gitcode.com/gh_mirrors/im/immudb点击查看免费下载相关推荐Jina 内部通信协议详解DataRequest 消息模型与 gRPC 服务接口规范Jina 内部通信协议详解DataRequest 消息模型与 gRPC 服务接口规范 本指南以 docs/proto/docs.md https://link后端人工智能模型推理服务微服务immudb 协议文档深度解读Document Storage API v2gRPC/REST完整指南immudb 协议文档深度解读Document Storage API v2gRPC/REST完整指南 immudb 的 pkg/api/protomod数据库安全后端Certbot acme.messages 深度解析ACME 协议消息模型、错误码与证书签发全流程Certbot acme.messages 深度解析ACME 协议消息模型、错误码与证书签发全流程 acme.messages 是 EFF Certbot 项网络安全CLI后端上一篇OCRmyPDF成本效益分析开源解决方案vs商业OCR服务下一篇InstructIR提示词工程10个专业指令模板让修复效果提升30%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考