版本：v4.1 ｜ 状态：评审稿 v4.1 变更：落定并发编辑/发布冲突策略——单一管理员会话（同时只允许一个用户登录 admin）；变更说明见 §7 上游依据：dev_docs/proposl.md（v1）→ dev_docs/proposal-v2.md（v2）→ dev_docs/proposal-v3.md（v3）＋ 可行性分析 v3 结论 本版变更：引入版本与发布模型——修改配置不立即生效，全部改完后新建版本并发布才通知客户端； 支持版本历史与回滚（变更说明见 §7）
实现一个分布式的配置文档服务：以多实例集群方式运行，配置按 项目 → 分支 → 分组 → item 组织，修改经"草稿 → 版本 → 发布"闭环生效，向多语言应用提供配置的存取、共享、分支对比、 版本化发布、变更推送与多格式输出，并以单二进制、零外部依赖、内嵌管理控制台的方式交付。
- 主体服务：Rust 实现，单二进制交付
- SDK：TypeScript / Go / Python 三种官方 SDK
- 管理端 Web Admin UI 内嵌于服务二进制（R10）
项目 Project（如 order-service）
├── 结构草稿 StructureDraft（项目级，未发布的结构修改）
├── 已发布结构 Structure（当前所有分支共用，项目级唯一事实源）
├── 分支 Branch（默认 dev/test/prod + 自定义）
│ ├── 值草稿 ValueDraft：（分支, item）未发布的值修改
│ ├── 活动版本 ActiveVersion（当前客户端可见的已发布快照）
│ └── 版本链 Versions：v1 → v2 → … → vN（不可变快照）
└── 共享库引用（引用集群级共享项，见 3.5）
- 结构（分组集合 + 每组的 item 集合）在项目级定义且只定义一次；值按 (分支, item) 存储
- 不变量：任意时刻，一个项目下所有分支的分组与 item 完全一致，仅值不同；由系统保证
- 结构变更走项目级结构草稿，发布时对全部分支同时生效（见 3.3）
原则：修改配置不立即生效；所有编辑先进入草稿；新建版本并发布后，客户端才可见并收到通知。
- 三层草稿 → 发布：
- 分支值草稿：编辑 (分支, item) 的值 → 发布 → 仅该分支产生新版本
- 项目结构草稿：编辑分组/item（增删改、改类型）→ 发布 → 结构对全部分支同时生效， 所有分支版本号同时推进（值不变）
- 共享库草稿：编辑集群级共享项 → 发布 → 自动级联引用它的所有 (项目, 分支) （发布前预览受影响项目，全程审计）
- 版本 = 不可变快照（结构 + 该分支的值）；每 (项目, 分支) 一条版本链 v1…vN，vN 为活动版本
- 发布 = 单个原子操作（Raft 一次写入）：固化草稿 → 创建新版本 → 推进活动版本指针 → 生成变更 diff → 通知订阅的 SDK
- 并发编辑/发布冲突策略 = 单一管理员会话：同一时刻仅允许一个有效的 admin 登录 （会话状态存于 Raft 状态机，集群范围线性一致地强制）；第二个登录请求被拒绝并提示已有管理员在线。 从机制上消除人工并发编辑/发布冲突；发布仍保持"单次 Raft 写入 + 快照"语义作为系统级保证 （防程序化发布与未来多用户）
- 发布前完整性校验：必填项未填 → 默认阻断发布（策略可配为仅警告）
- 回滚：基于历史版本的内容创建新版本（历史不可变、可审计），而非删除历史
- 保留策略：默认全量保留；可配置按版本数 / 时间裁剪
- SDK 订阅粒度 = (项目, 分支)；事件仅在发布时产生，携带 版本号 + 变更 diff （变更 item 列表 + 新值）；需要完整配置时通过 get 拉取
- SDK 断线重连后从最后收到的版本号续传（服务端可重放该版本之后的发布事件）
- 编辑中的草稿对 SDK 完全不可见（半成品不上线）
- 集群级共享库（分组 + item），项目分组可引用（组级 / item 级），渲染 / 输出时解析
- 共享项同样走草稿 → 发布；共享库发布即自动级联引用项目（决策已确认）： 受影响 (项目, 分支) 版本号推进、SDK 收到新版本 diff 事件；发布前展示受影响项目列表 + 审计
- 循环引用检测（共享项→共享项、项目→共享项）并拒绝发布
string / int / float / bool / json / array / secret（secret 强制加密存储，见 R11）
- AC1.1 任意实例通过
--join <已有实例端点>加入集群，无需手动同步成员列表 - AC1.2 首节点
--bootstrap自举；其余节点仅凭一个已有实例端点即可加入 - AC1.3 节点数 ≥3 时，任选一节点宕机，读写不中断（多数派存活）
- AC1.4 新节点自动追平历史数据（快照 + 日志回放）后参与服务
- AC2.1 任意时刻集群至多一个 leader 接受写请求
- AC2.2 写请求返回成功即已复制到多数派并持久化
- AC2.3 网络分区时少数派侧拒绝写入（防脑裂），恢复后数据自动一致
- AC2.4 读可路由任意节点；提供线性一致读选项
- AC3.1 SDK 接受多端点，连接失败/超时/RPC 错误时自动切换
- AC3.2 切换对业务代码透明（回调/事件通知，不抛业务异常）
- AC3.3 SDK 从服务端动态获取集群成员并更新端点池
- AC3.4 写请求命中非 leader 时服务端返回 leader 重定向，SDK 自动跟随
描述：SDK 订阅指定 (项目, 分支)，仅在版本发布后收到变更通知。
- AC4.1 订阅 (项目, 分支) 后，仅当该分支发布新版本时收到通知（草稿编辑不通知）
- AC4.2 通知携带版本号 + 变更 diff（变更 item 列表 + 新值）；发布后 SDK 在目标时延（默认 ≤1s）内收到
- AC4.3 断线重连后按版本号续传（服务端重放断线期间发布的版本事件），不丢发布
- AC4.4 支持一次订阅多个 (项目, 分支)；监听器动态注册注销
描述：见 §3.1–3.3。
- AC5.1 项目/分支/分组/item 四级 CRUD（均先写草稿，见 R14）
- AC5.2 结构（分组+item）在项目级定义；任意时刻全部分支结构完全一致（系统保证）
- AC5.3 分支可自定义创建/删除，默认 dev/test/prod；新建分支继承当前已发布结构与活动版本值
- AC5.4 item 类型含 secret，secret 强制加密存储（R11）
- AC5.5 值可为空；发布时执行必填项完整性校验（未填默认阻断发布，策略可配）
- AC5.6 结构变更（增删改 item/分组）进入项目级结构草稿，发布时对全部分支同时生效 （所有分支版本号同时推进），发布前提供影响预览与确认
描述：集群级共享项库，项目分组可引用，降低跨项目重复配置。
- AC6.1 共享项（分组+item）支持 CRUD（写草稿，发布后生效），敏感项强制加密（R11）
- AC6.2 项目分组可引用共享库（组级/item 级），输出/发布时解析
- AC6.3 循环引用检测并拒绝发布
- AC6.4 共享项发布后自动级联：引用它的所有 (项目, 分支) 版本号推进并通知 SDK； 发布前展示受影响项目列表 + 审计；可配置"显式发布"模式防风暴
描述：分支间差异对比与值复制（promotion）。
- AC7.1 分支间值对比（diff）：同结构按 key 对比，展示差异与缺失值（基于活动版本）
- AC7.2 结构一致性校验：任意时刻展示"全部分支结构一致"状态（正常应恒等）
- AC7.3 值提升（promotion）：把源分支的值复制到目标分支的值草稿，目标分支发布后才生效； 复制前校验目标分支缺失项，操作记录审计日志（R13）
- AC7.4 支持单 item、整组、整分支三种粒度的值提升
描述：按 (项目, 分支) 输出配置文档，支持 YAML / TOML / JSON。
- AC8.1 按 (项目, 分支) 输出活动版本完整配置文档（分组→文档小节），支持 YAML/TOML/JSON
- AC8.2 支持按历史版本输出（
?version=N）与草稿预览（管理端） - AC8.3 三格式语义等价（等价性校验测试）
- AC8.4 schema 以 TOML 表达力为下限
- AC9.1 每季度更新竞品对比表（含版本/发布能力列）
- AC9.2 竞品新功能上线时评估吸收或差异化
描述：管理端 Web UI 与主服务同进程、同端口部署，静态资源编译进二进制。
- AC10.1 单二进制同时提供数据面 API 与管理控制台（默认
/admin） - AC10.2 控制台功能：项目/分支/分组/item 树形管理、草稿编辑（含待发布变更视图）、 发布操作（含完整性校验结果与影响预览）、版本历史与回滚、分支对比（diff）、 值提升（promotion）、共享库管理、变更历史/审计、格式预览（YAML/TOML/JSON 三栏）
- AC10.3 默认启用鉴权（初始管理员凭证启动配置或首启自动生成）；同源免 CORS
- AC10.4 前端产物内嵌（基准 ≤5MB），无外链依赖，离线可用
- AC10.5 单一管理员会话：同一时刻仅允许一个有效管理员登录；第二个登录请求被拒绝 （提示"已有管理员在线"）；会话支持 TTL/心跳续期与 CLI 强制下线，避免会话卡死占用
描述：secret 类型 item 与共享库敏感项静态强加密；明文仅按需解密；展示与导出脱敏。
- AC11.1 静态加密使用 AEAD（AES-256-GCM 或 ChaCha20-Poly1305），每项独立数据密钥（信封加密）
- AC11.2 主密钥来源可配置：环境变量 / 密钥文件 / KMS（企业版）；主密钥不明文落盘
- AC11.3 支持主密钥轮换与数据密钥版本化，轮换不中断服务
- AC11.4 明文仅存在于解密瞬间；存储/备份/导出均为密文；界面与导出默认掩码
- AC11.5 草稿与历史版本中的敏感值均为密文；读取/导出触发审计日志（R13）
- AC12.1 仅两个核心启动参数即可跑通：
--bootstrap/--join <endpoint>，其余全部有默认值 - AC12.2 存储内嵌，不依赖外部数据库
- AC12.3 配置覆盖优先级：环境变量 > 配置文件 > 命令行参数
- AC12.4 基准目标：单机最小内存 ≤128MB；二进制 ≤50MB（含 Admin UI）
- AC12.5 提供 Docker 镜像与 docker compose 一键三节点示例
描述：健康检查、指标、结构化日志、审计日志。
- AC13.1 提供
/healthz与/readyz - AC13.2 Prometheus 指标：节点角色、Raft 状态、QPS/延迟、watch 连接数、成员数、 结构一致性状态、共享库引用数、版本数、待发布草稿数、发布次数、回滚次数
- AC13.3 结构化日志（可选 JSON）；管理操作 / 密钥访问 / 发布与回滚 审计可查询
- AC13.4 可选 OpenTelemetry 追踪（企业版）
描述：修改配置不立即生效；所有修改进入草稿；全部改完后新建版本并发布，发布后才通知客户端。
- AC14.1 编辑操作（值/结构/共享库）只写草稿，不改变客户端可见配置（SDK 读到的始终是活动版本）
- AC14.2 发布操作原子完成：固化草稿 → 创建新版本 → 推进活动版本指针 → 生成变更 diff → 通知订阅的 SDK（默认 ≤1s）
- AC14.3 每次发布产生唯一递增版本号；SDK 事件携带版本号与变更 diff
- AC14.4 支持版本历史查询：任意历史版本的内容、发布时间、发布者（审计）
- AC14.5 支持回滚：基于历史版本内容创建新版本并发布（历史不可变）；回滚同样产生版本号与审计
- AC14.6 保留策略：默认全量保留，可配置按版本数 / 时间裁剪；裁剪不破坏活动版本与回滚可用性
- AC14.7 发布前完整性校验：必填项未填 → 默认阻断发布（可配为仅警告）
- AC14.8 结构发布对全部分支同时生效（所有分支版本号同时推进，值不变）
- AC14.9 共享库发布自动级联引用项目（受影响项目预览 + 审计）
- AC14.10 并发编辑/发布冲突策略：默认由单一管理员会话（R10）消除人工并发； 发布仍以"单次 Raft 写入 + 快照"为系统级保证（防程序化发布并发）
| 类别 | 要求（基准值，后续压测校准） |
|---|---|
| 性能 | 单节点写 QPS ≥ 10k；watch 并发连接 ≥ 10k；发布到 SDK 通知延迟默认 ≤1s；单项目分支数 ≤100 时结构校验 <100ms |
| 存储 | 版本全量保留为默认；单版本存储 = 快照 + diff（checkpoint 机制，见可行性分析）；提供裁剪策略 |
| 安全 | 全链路 TLS 可选（默认提示开启）；管理端强制鉴权 + 单一管理员会话（R10）；secret 项加密（R11） |
| 可移植性 | 静态编译；Linux x86_64 / arm64 为主，macOS 支持开发 |
| 兼容性 | 数据模型与 SDK 协议版本化（v1 起）；版本号语义向后兼容 |
| 可靠性 | 故障注入测试（分区/丢包/重启）通过后方可发布 |
- 分支级细粒度权限（如"生产分支仅运维可发布"）——企业版（RBAC）
- 多管理员并发协作（多会话同时在线编辑）——企业版多用户/RBAC 后再考虑；v4.1 起开源版为单管理员会话
- 服务发现 / 注册中心：不承接 Nacos/Consul 的发现业务
- 完整密钥生命周期管理：动态密钥轮换、加密网关交给 Vault 类系统；本项目只做静态加密 + 脱敏
- 灰度发布（按节点/百分比放量）、多租户、SSO、审计报表：企业版路线图，不进开源 MVP
| 变更 | 理由 / 决策 |
|---|---|
| 新增 §3.3 版本与发布模型（草稿→版本→发布→回滚） | 本次用户决策："修改配置不立即生效，全部改完后新增版本并发布，才会通知客户端" |
| R4 改为"仅发布时通知，携带版本号 + 变更 diff" | 本次用户决策：发布通知内容 = 变更 diff + 版本号 |
| R14 版本与发布（新增，核心需求） | 上述原则的正式化，含发布原子性/版本历史/回滚/保留策略/完整性校验 |
| 结构变更 = 项目级结构草稿，发布时全部分支同时生效 | 本次用户决策：不破坏"未发布不生效"与结构恒等不变量 |
| 共享库发布即自动级联引用项目 | 本次用户决策：共享库发布本身是显式发布动作，带受影响项目预览 + 审计 |
| 版本保留 = 默认全量 + 可配置裁剪 | 本次用户决策：审计友好，存储可控 |
| R7 promotion 作用于草稿、发布后才生效 | 与版本模型对齐：promotion 不再直接改线上 |
| R8 输出活动版本 + 历史版本查询 + 草稿预览 | 与版本模型对齐 |
| R10 Admin UI 增加草稿编辑/发布/版本历史/回滚 | 与版本模型对齐 |
| R13 增加版本/草稿/发布/回滚指标 | 让发布流程可观测 |
| 回滚语义 = 基于历史版本内容创建新版本（历史不可变） | 设计默认：可审计、不破坏历史；如要"指针切换式回滚"可另议 |
| 新增"单一管理员会话"约束（R10/AC14.10） | 本次用户决策："同时只允许一个用户登录 admin"——落定 v4 待拍板问题③（草稿并发冲突策略）：以单会话从机制上消除人工并发；发布原子性保留为系统级保证 |