版本：v2.0 ｜ 状态：评审稿 上游依据：dev_docs/proposl.md（v1 需求）＋ dev_docs/feasibility-report.md（可行性分析 v1 结论） 本版变更：依据可行性分析结论，新增 R8 嵌入式 Web Admin UI、R9 密码/密钥强加密、R10 极简配置、R11 可观测性 四项需求，并为全部需求补充验收标准（变更说明见 §6）
实现一个分布式的配置文档服务：以多实例集群方式运行，向多语言应用提供配置文档的 存取、共享、变更推送、多格式输出与极简化的运维体验（单二进制、零外部依赖、内嵌管理控制台）。
- 主体服务：Rust 实现，单二进制交付
- SDK：TypeScript / Go / Python 三种官方 SDK
- 管理端 Web Admin UI 内嵌于服务二进制，不单独部署（R8）
描述：支持多实例运行；启动新实例时，仅需指定集群内任意一个实例的注册端点即可加入集群。
验收标准
- AC1.1 任意实例通过
--join <已有实例端点>加入集群，无需手动同步成员列表 - AC1.2 首节点
--bootstrap自举；其余节点仅凭一个已有实例端点即可加入 - AC1.3 集群节点数 ≥3 时，任选一节点宕机，读写不中断（多数派存活）
- AC1.4 新节点加入后自动追平历史数据（快照 + 日志回放），追平后参与服务
描述：集群内多实例共享全部数据，杜绝脑裂（split-brain）导致的数据不一致。
验收标准
- AC2.1 任意时刻集群至多一个 leader 接受写请求
- AC2.2 写请求返回成功即已复制到多数派并持久化
- AC2.3 网络分区场景下，少数派侧拒绝写入（防脑裂），分区恢复后数据自动一致
- AC2.4 读请求可路由到任意节点；同时提供线性一致读选项
描述：SDK 连接失败时自动切换到备选节点。
验收标准
- AC3.1 SDK 接受多端点；当前端点连接失败/超时/RPC 错误时自动切换
- AC3.2 切换对业务代码透明（仅通过回调/事件通知，不抛业务异常）
- AC3.3 SDK 支持从服务端动态获取集群成员列表并更新端点池
- AC3.4 写请求命中非 leader 节点时，服务端返回 leader 重定向，SDK 自动跟随
描述：SDK 自动感知配置变更（watch / 推送）。
验收标准
- AC4.1 配置变更后，SDK 在可配置目标时延内（默认 ≤1s）收到通知
- AC4.2 watch 携带版本号（revision）；断线重连后从断点续传，不丢失断线期间的变更
- AC4.3 支持按文档 / 按命名空间监听；监听器可动态注册与注销
描述：配置文件之间可共享配置项（如基础服务地址、账号、密码）；配置文档可引用共享项以降低配置工作量。
验收标准
- AC5.1 共享配置项支持增删改查，带命名空间 / 环境维度
- AC5.2 配置文档可引用共享项，引用在输出/发布时解析
- AC5.3 循环引用检测并拒绝发布
- AC5.4 共享项变更 → 引用它的文档版本递增并推送。级联语义本版默认：自动级联 + 审计记录
- AC5.5 敏感类型共享项（密码/密钥）强制走加密存储（R9），支持掩码展示
描述：同一配置文档可同时输出 YAML / TOML / JSON。
验收标准
- AC6.1 同一配置文档可分别输出 YAML / TOML / JSON
- AC6.2 三种格式语义等价（具备格式等价性校验测试）
- AC6.3 支持按格式 URL 拉取与单文档多格式打包下载
- AC6.4 文档 schema 以 TOML 表达力为下限，保证三种格式均可完整表达
描述：持续跟踪竞品并维护对比（当前对比见可行性分析 §6）。 验收标准：AC7.1 每季度更新竞品对比表；AC7.2 竞品新功能上线时评估吸收或差异化。
描述：管理端 Web UI 与主服务同进程、同端口部署；静态资源编译进二进制，无需单独前端服务或 CDN。
验收标准
- AC8.1 单二进制同时提供数据面 API 与管理控制台（默认
/admin子路径） - AC8.2 控制台功能：集群成员与状态查看、配置文档 CRUD、共享配置项 CRUD、变更历史/审计查看、格式预览（YAML/TOML/JSON 三栏）
- AC8.3 控制台默认启用鉴权（初始管理员凭证由启动参数/环境变量配置或首启自动生成）；页面与 API 同源，免 CORS 配置
- AC8.4 前端产物内嵌（基准 ≤5MB），无外链依赖，离线可用
描述：敏感配置项（密码、密钥、Token 等）静态强加密存储；明文仅按需解密；展示与导出默认脱敏。
验收标准
- AC9.1 静态加密使用 AEAD（AES-256-GCM 或 ChaCha20-Poly1305），每项独立数据密钥（信封加密）
- AC9.2 主密钥来源可配置：环境变量 / 密钥文件 / KMS（企业版）；主密钥不以明文落盘
- AC9.3 支持主密钥轮换与数据密钥版本化，轮换过程不中断服务
- AC9.4 明文仅存在于解密瞬间；存储、备份、导出均为密文；管理界面与导出默认掩码展示
- AC9.5 解密/导出敏感项操作触发审计日志（R11）
描述：单二进制、零外部依赖（无外部数据库、无消息中间件）、默认即用。
验收标准
- AC10.1 仅两个核心启动参数即可跑通：
--bootstrap（首节点）/--join <endpoint>（加入集群），其余全部有合理默认值 - AC10.2 存储内嵌（嵌入式 KV/日志存储），不依赖外部数据库
- AC10.3 配置覆盖优先级：环境变量 > 配置文件 > 命令行参数
- AC10.4 基准目标：单机最小运行内存 ≤128MB；二进制体积 ≤50MB（含 Admin UI）
- AC10.5 提供 Docker 镜像与 docker compose 一键三节点示例
描述：健康检查、指标、结构化日志、审计日志。
验收标准
- AC11.1 提供
/healthz（存活）与/readyz（就绪）端点 - AC11.2 Prometheus 指标：节点角色、Raft 状态、请求 QPS/延迟、watch 连接数、集群成员数
- AC11.3 结构化日志（可选 JSON）；管理操作与密钥访问审计日志可查询
- AC11.4 可选 OpenTelemetry 追踪（企业版）
| 类别 | 要求（基准值，后续压测校准） |
|---|---|
| 性能 | 单节点写 QPS ≥ 10k；watch 并发连接 ≥ 10k |
| 安全 | 全链路 TLS 可选（默认提示开启）；管理端强制鉴权；敏感项加密（R9） |
| 可移植性 | 静态编译；Linux x86_64 / arm64 为主，macOS 支持开发 |
| 兼容性 | SDK 协议版本化（v1 起），向后兼容策略明确 |
| 可靠性 | 故障注入测试（分区/丢包/重启）通过后方可发布 |
- 服务发现 / 注册中心：不承接 Nacos/Consul 的发现业务
- 完整密钥生命周期管理：动态密钥轮换、加密网关等交给 Vault 类系统；本项目只做静态加密 + 脱敏
- 灰度发布、多租户、RBAC/SSO、审计报表：列入企业版路线图，不进开源 MVP
| 变更 | 理由（对应可行性分析结论） |
|---|---|
| 新增 R8 嵌入式 Admin UI | §3.3 D4 / §5 P6：降低采用门槛；对比 etcd 无官方 UI、Apollo 三组件部署，与"单二进制"定位一致 |
| 新增 R9 密码/密钥强加密 | §2.4 安全风险 / §5 P4：共享项含账号密码，明文存储不可接受；同时是合规与信任卖点 |
| 新增 R10 极简配置 | §3.3 D4 / §5 P6：对比 Nacos 依赖外部存储、Apollo 多组件，零外部依赖是核心差异化 |
| 新增 R11 可观测性 | §2.5 M4 计划：配置中心是信任型基础设施，可观测与审计是上线前提 |
| R1–R7 补充验收标准 | §7.2"先定契约再写代码"：验收标准即三端契约 |
| R5.4 级联语义明确为"自动级联 + 审计" | §7.2 待拍板问题①：默认自动级联便于 SDK 语义一致，审计保证可追溯 |