企业官网建设流程全解析

• 数据库客户端
• 数据库
• 桌面应用
• CLI
• 后端
• MCP 服务
• AI 应用

本文基于 MIGRATION_PARITY.md 展开，深入解析 dbx 将 etcd 连接代理（Agent）从 Java（jetcd 0.8.x）迁移到原生 Go 实现的全过程与对等性（parity）验收标准。文章以该迁移文档为骨架，结合仓库内 Go 源码与集成测试，说明 33 个协议方法、14 项能力（capabilities）、错误信号文本、lease/watch/history/status 等核心机制的移植方式，以及"迁移完成"的四个判定条件（实现、自动化测试、真实集群验证、接入原生构建发布链路）。读完本文，你将掌握 dbx etcd Go Agent 的协议形态、连接与 TLS 配置、KV/CAS/TTL、watch 预算系统、auth 权限处理等关键实现细节，并能对照源码与测试继续深入。

迁移背景与基线（Baseline）

etcd Java Agent（EtcdAgent，基于 jetcd 0.8.x，实现 33 个协议方法）已被本仓库中的原生 Go Agent 取代。文档明确指出：迁移只有在某能力同时满足四个条件时才视为完成——已实现、有自动化测试覆盖、已针对真实 etcd 集群验证、并接入原生构建与发布路径（native build and release path）。

基线信息如下：

• Java 基线：DBX Java 基线为 jetcd 0.8.x 的EtcdAgent，所有协议形状（protocol shapes）、能力字符串（capability strings）和错误信号文本均逐字复制（copied verbatim）。
• Go 客户端：使用go.etcd.io/etcd/client/v3v3.7.1，底层走 gRPC。
• 能力集合（与 Java 完全一致，不含structured_error_v1）：connect、test_connection、kv、kv_ttl、kv_cas、kv_list_values、kv_status、kv_history、etcd_compaction、etcd_defrag、etcd_watch、etcd_lease、etcd_auth、multi_session。
• 错误信号字符串（如ETCD_CAS_CONFLICT、ETCD_NOT_FOUND、ETCD_COMPACTED、ETCD_WATCH_LIMIT等）逐字匹配，原因是宿主（host）侧通过错误消息文本对 Agent 错误做归一化处理（agent_kv.rs::normalize_agent_kv_error）。
• go-semver 的 vendor 处理：共享模块go-semver被 vendor 到 agents/go-common/go-semver，因为上游v0.3.1标签声明了损坏的模块路径（module path 不含/semver后缀）。这一点在 go.mod 中以replace指令落地。

从源码看，main.go 中capabilities数组与文档列出的集合一一对应，handshake响应（handshakeResult，见 main.go）会返回protocolVersion = 2与完整能力列表，这是宿主探测 Agent 能力面的入口。

当前能力矩阵：逐项解读

原文档给出的能力矩阵是迁移对等性的核心验收清单，必须逐行理解：

矩阵中的几处关键语义值得展开：

1. test_connection 的受限探测：当受限 etcd 用户不允许调用Maintenance.Status时，返回PERMISSION_DENIED仍能证明通道到达了 etcd 服务端，因此探测结果标记为limited: true而不是失败。源码见 client.go 的probeClient：对每个 endpoint 发起Maintenance.Status，若status.Code(err) == codes.PermissionDenied，返回{"ok": true, "endpoint": ..., "limited": true}。

2. Status 的 raft 字段按无符号十进制字符串输出：raftTerm、raftIndex、raftAppliedIndex、memberId、clusterId等字段通过unsignedLongString（strconv.FormatUint(uint64(v), 10)）序列化，与 Java 侧longString(int64(uint64))的位级（bit-level）行为保持一致。这在 status.go 中可见。

3. etcd 3.3 降级模式：LeaseLeases 在 3.3 上返回 UNIMPLEMENTED 或超时，此时 lease 列表回退到会话内已知 lease 集合（knownLeases）并标记partial: true；kv_history 也有相应的回退逻辑。由于未保留 3.3 fixture，该路径仅完成编码与单元测试，未做真实服务器验证。回退判定见 lease.go 的isLeaseListFallbackError。

4. etcd 2.x 由独立 Agent 承担：本 Agent 不处理 etcd 2.x 协议，仓库中另有 agents/drivers/etcd2-go 专门负责。

连接层：endpoints、TLS、基本认证与连接探测

连接参数在 client.go 的connectionParams中定义，支持宿主侧多种配置形式：

连接建立流程（connect，client.go）分四步：解析连接对象 →buildClient构造clientv3.Config（含 TLS、认证）→probeClient探测任一 endpoint 可达 →detectAuthEnabled检测 Auth 是否启用。探测失败即关闭客户端并返回错误，避免留下半开连接。

TLS 细节（tlsConfigFor，client.go）：CA 证书 PEM 读入后追加到RootCAs；客户端证书与私钥必须同时存在否则报错 "Client certificate and key must be provided together"。当未显式配置用户名但启用了 TLS 时，用户名回退为客户端证书的Subject.CommonName（clientCertificateUsername），这与 etcd 基于证书身份的认证方式对齐。

Auth 状态的动态刷新值得注意：refreshAuthEnabled（client.go）会在长连接会话期间轮询AuthStatus，当管理员在 DBX 已连接后开启或关闭 etcd Auth 时，会话内的authEnabled与只读权限缓存（readAccess）会随之失效重建；若探测失败则保留上次已知状态而不是翻转权限，保证安全边界不因探测抖动而放宽。

KV 能力：list/get/put/delete/rename 与 CAS、TTL

KV 实现集中在 kv.go，覆盖kv_list_prefix、kv_get、kv_put、kv_delete、kv_rename五个方法（方法路由见 main.go）。

• kv_list_prefix：按前缀列出键，支持limit（默认 100，最小 1）、revision（历史快照读）、includeValues（是否带回值）、continuation（base64 编码的游标，实现分页）。返回值含keys、revision与continuation。分页游标通过对最后一个键追加\x00后再 base64 编码生成（nextContinuation）。
• kv_get：返回found、key、keyBytes、value、metadata；metadataOnly: true时可跳过值体。元数据含createRevision、modRevision、version、lease、valueSize，其中 version、revision 类字段全部以十进制字符串输出。
• kv_put：核心亮点是三选一的 lease 语义——lease（挂接已有 lease ID）、ttl（先 Grant 再挂接，写入失败时自动 Revoke 回滚）、preserveLease（保留键已有 lease 重写值）三者互斥，同时指定会报错。preserveLease采用最多 3 次尝试（preserveLeaseMaxAttempts = 3）的 CAS 循环：读取当前ModRevision与Lease，用事务校验ModRevision未变后写入，并发变更则重试，最终失败返回 "Cannot preserve lease: key changed concurrently; retry the save"。
• CAS（乐观锁）：expectedModRevision/expectedCreateRevision通过client.Txn的Compare(ModRevision/CreateRevision, "=", ...)实现，冲突时返回ETCD_CAS_CONFLICT: key changed after it was loaded。集成测试 integration_test.go 专门验证了陈旧 revision 触发 CAS 冲突、新 revision 成功写入的完整路径。
• kv_delete：支持expectedModRevision条件删除；无条件删除返回deleted计数与revision。
• kv_rename：事务内"复制到新键 + 删除旧键"，保留源键的 lease；若目标键已存在或源键已被并发修改则返回ETCD_CAS_CONFLICT。源键不存在返回ETCD_NOT_FOUND，缺少newKey参数返回ETCD_NEWKEY_REQUIRED。

二进制值处理遵循统一编码约定：UTF-8 合法字节以{"encoding":"utf8","data":...}返回，否则回退为{"encoding":"base64","data":...}（valueObject）；keyBytes始终以 base64 形式输出。集成测试覆盖了0x00 0xff 0x81这类二进制键值的往返（integration_test.go）。

Lease 管理：列表分页、自定义 ID Grant 与 3.3 回退

Lease 能力（etcd_lease_*）实现在 lease.go，包括 list/get/grant/keepalive/revoke 五个方法。

• LeaseGrant 自定义 ID：当请求携带id且大于 0 时，走原始 protobuf RPC（etcdserverpb.NewLeaseClient(...).LeaseGrant，携带TTL与ID字段），取代了 Java 侧通过反射处理 wire 的方式；不传id或传 0 时走client.Lease.Grant。文档明确这是内部实现变更，不属于协议偏差。
• LeaseList 分页与预算：通过LeaseLeasesRPC 获取集群全部 lease ID（clusterLeaseIDs），排序后按limit（默认 100，上限 200）分页，continuation为上一页最后一个 lease ID 的无符号十进制字符串。随后以并发 8 路、总截止 5 秒（leaseListConcurrency、leaseListDeadlineSeconds）批量查询每个 lease 的 TTL；单 lease 超过截止返回ETCD_LEASE_LIST_TIMEOUT，命中截止或 UNIMPLEMENTED 时回退到会话内knownLeases并标记partial: true。返回结构含leases、partial、nextContinuation三字段。
• LeaseGet：查询单个 lease 的ttl、grantedTtl，includeKeys: true时携带挂接键（最多 256 个，超出标记truncated）。
• KeepAliveOnce / Revoke：分别调用Lease.KeepAliveOnce与Lease.Revoke，成功/失败后同步维护会话内的knownLeases集合（rememberLease/forgetLease），为 3.3 回退路径提供数据来源。

Watch 与 History：预算系统与重放边界

Watch 的完整预算系统

Watch 实现（watch.go）遵循文档所述的硬性预算：每连接最多 4 个 watch（maxWatches）、每个 watch 最多 256 个批次（maxWatchBatches）、1 万条事件（maxWatchEvents）、8 MiB 缓冲（maxWatchBufferBytes），会话聚合缓冲上限 16 MiB（maxSessionWatchBufferBytes）。超出任一预算即进入overflow终态，事件流关闭并返回ETCD_WATCH_OVERFLOW。

工作模式为 start/poll/stop 三段式：

• etcd_watch_start：校验 watch 数量上限与scope（key或prefix，默认 key）；未指定startRevision时，先以WithCountOnly()读取同一 scope 的当前 revision 并加 1（避免对受限用户发起全局 range 请求，见 watch.go），随后创建 watch channel 并异步消费。includePrevKv控制是否携带旧值。
• etcd_watch_poll：宿主轮询拉取缓冲批次，每次最多取出 64 个批次；当缓冲排空且处于终态时才对外暴露terminal（reason/message/compactedRevision），并自动从会话注销该 watch——"终态只在缓冲排空后浮现"的设计与 Java 实现一致。
• etcd_watch_stop：注销并关闭 watch，返回{"stopped": true}。

事件行结构统一为eventType（put/delete）、revision、key、keyBytes、value、previousValue、metadata；DELETE 事件的value置空、metadata取旧值。字节估算按 4 倍系数放大（estimatedBufferedBytes，len * 4），使预算判断更贴近真实内存占用。

kv_history：临时 watch 重放

kv_history（history.go）通过"临时 watch + prevKV + 进度通知"实现单键历史重放，是 jetcd 对等行为的关键移植：

• 先以请求的endRevision（默认当前头 revision）读一次键，确定重放终点；若该 revision 已被压缩，返回ETCD_COMPACTED: requested history was compacted at revision N。
• 默认回溯窗口为 10000 个 revision（historyDefaultRevisionWindow），limit上限 500（historyLimitMax），超出上限时滚动丢弃旧事件并置truncated。
• watch 必须显式设置clientv3.WithCreatedNotify()——文档特别指出，clientv3 仅在设置该选项后才投递 created 响应，而 created 门闩依赖它（与 jetcd 的withCreateNotify对齐）。watch 创建超 5 秒报ETCD_HISTORY_TIMEOUT: watcher was not created。
• 对已存在的精确键，其最新ModRevision是显式重放边界（避免依赖旧版本 etcd/jetcd 组合不稳定的 progress notify），同时调用RequestProgress推动进度；重放 15 秒未达目标 revision 报ETCD_HISTORY_TIMEOUT: history replay did not reach the requested revision。
• 压缩边界恢复：gRPC 错误不携带压缩 revision，compactedRevisionOf（history.go）通过从 revision 1 发起临时 watch 读取CompactRevision来恢复确切的压缩点，从而给出精确的ETCD_COMPACTED错误信息。

Status、Compaction、Defrag

• Status（kv_status）：status.go 组合MemberList、AlarmList、键计数与对每个 endpoint 的Maintenance.Status并发探测（单 endpoint 10 秒超时）。成员按MemberId去重，同一成员多个 URL 只保留首行；每个成员的latencyMs为探测耗时。raft 字段（raftTerm/raftIndex/raftAppliedIndex）、memberId、clusterId、leaderId一律按无符号十进制字符串输出（Java 位级兼容）。失败的 endpoint 行各字段置nil、reachable: false、errors数组含错误文本；成功行errors显式返回空数组（宿主协议要求该字段必须存在，否则无法反序列化完整 status 响应）。
• Compaction（etcd_compact）：compact保留了 Java 的参数校验顺序——先校验参数，再检查连接：revision必须为正整数；随后用WithRev(revision)做只读探测，若已被压缩返回ETCD_INVALID_REVISION: revision was already compacted，若大于当前 revision 返回ETCD_INVALID_REVISION: revision is newer than the current revision，最后才执行Compact。见 maintenance.go。
• Defrag（etcd_defrag）：按"先 followers、后 leader、逐 endpoint 报错"的顺序执行：nextDefragEndpoint依据状态探测确定 leader 并置于队尾，每个 endpoint 独立记录status（succeeded/failed）、durationMs、error；某 endpoint 失败即停止并标记剩余目标为未执行。endpoints参数必须非空，否则返回ETCD_DEFRAG_TARGET_REQUIRED。

Auth：用户/角色管理的 14 个方法

etcd_auth能力对应 main.go 中 14 个方法：用户侧etcd_auth_user_list/get/add/delete/change_password/grant_role/revoke_role，角色侧etcd_auth_role_list/get/add/delete/grant_permission/revoke_permission。

实现细节（auth.go）中有一个与只读浏览强相关的机制：只读范围快照etcdReadAccess。Agent 不直接向 etcd 枚举全局键空间（受限账号不允许），而是基于当前用户的角色推导其可读的半开键区间（etcdReadRange{start, end}），缓存 15 秒（readAccessCacheTTL）避免浏览时反复调用AuthStatus/UserGet/RoleGet。etcd 用单个 NUL 字节（\x00）表示无界区间尾（unboundedRangeEnd），这是协议哨兵而非普通字节上界，普通字典序比较在此处是错误的——源码注释明确强调了这一点。kv_list_prefix在受限用户场景下会将 granted ranges 与请求前缀求交（intersectReadRanges），再逐个区间独立查询（listReadableRanges），使 etcd 永远不会看到未授权的全局 range 请求。

错误分类与多会话运行时

Agent 的错误响应用 protocol_error.go 统一分类：所有错误包装为 JSON-RPC 2.0 错误对象，附带结构化data（category、retryable、sessionDisposition、stage、contractVersion、operationOutcome、exceptionClass、agentSessionId）。分类规则：

• context.Canceled→category: "canceled"，会话隔离（quarantine）；
• 超时（DeadlineExceeded或实现Timeout()接口）→category: "timeout"，会话隔离；
• gRPCUnavailable、io.EOF、net.ErrClosed、net.OpError及 "connection refused/reset/broken pipe" 等错误文本 →category: "connection"，仅在 connect/validate 阶段可重试，非连接阶段将会话隔离。这复刻了 Java Agent 的传输层分类行为（protocol_error.go）。

stage 按方法映射（rpcErrorStage）：connect/open_session/test_connection →connect；validate_* →validate；watch_poll/lease_get →fetch；handshake →request；其余默认execute。

多会话运行时（multi_session能力）在 main.go 中体现：Agent 以"行协议"方式从 stdin 读取 JSON-RPC 请求、向 stdout 写响应，支持handshake、open_session、close_session、validate_session、cancel_session、connect/disconnect（遗留单会话别名__legacy__）与shutdown等运行时方法；会话上限 256（maxAgentSessions），每请求独立 goroutine 处理、编码加锁，RPC 默认 30 秒超时（rpcTimeoutSeconds），cancel_session通过activeCancel取消当前进行中的操作。configureRuntimeParallelism支持用DBX_AGENT_ETCD_GOMAXPROCS显式覆盖 GOMAXPROCS，否则钳制在min(NumCPU, 4)。

测试与验收：真实 etcd 集群的验证方式

迁移文档强调"自动化测试 + 真实集群验证"是 parity 成立的必要条件。仓库内的 integration_test.go 提供了可复现的验证入口：

• 通过环境变量启用：DBX_ETCD_LIVE=1；DBX_ETCD_ENDPOINTS、DBX_ETCD_USER、DBX_ETCD_PASSWORD配置目标集群（默认值对应部署配方：root/123456、http://127.0.0.1:10700的 3.7 版本）。
• 覆盖链路包括：connect 与 validate_connection 探测、UTF-8 与二进制（base64）KV 往返、陈旧/最新 revision 的 CAS put、TTL put 与 lease 元数据、preserveLease、kv_history 等，基本对应能力矩阵中标记 "parity passed" 的行。
• 单元测试（main_test.go）与集成测试共同支撑"Automated"列；矩阵中标记coded + unit tested的 3.3 回退路径因未保留 3.3 fixture，未出现在 Live server 列。

值得说明的是，矩阵中 Live server 列给出了实测过的 etcd 版本：3.7.0 与 3.5.21，这是仓库内测试所验证的事实范围，不应外推为对其他版本的保证。

已知偏差与版本边界

文档在 "Known divergences" 一节给出的结论是：无故意偏差（None intentional）。所有可观测的协议输出与 Java Agent逐字节兼容；Lease 操作使用原始 protobuf RPC 只是内部实现变更，不改变协议外观。

版本边界同样明确：

• etcd 3.3：仅提供 lease/history 降级路径（partial 实现），无保留的 3.3 fixture，属"已编码 + 单元测试"而非完整 parity；
• etcd 2.x：由独立的 etcd2-go Agent 承担，不在本 Agent 能力范围内。

综上，这份迁移对等文档的价值在于把"替换实现"变成可验证的工程承诺：能力面逐字对齐、错误文本逐字匹配、预算与并发模型显式化、版本边界清晰标注。配合 kv.go、lease.go、watch.go、history.go、status.go、auth.go 等源码与 integration_test.go 测试，读者可以沿着"文档 → 实现 → 测试"的路径完整验证每一个 parity 声明。

• 数据库客户端
• 数据库
• 桌面应用
• CLI
• 后端
• MCP 服务
• AI 应用