文档差距治理计划
本文把官方文档差距分析转化为可执行任务。目标不是一次性写满所有页面，而是先补齐生产采纳前必须明确的内容，再完善长期维护能力。
当前覆盖状态
| 维度 | 当前状态 | 下一步 |
|---|---|---|
| 安装 | 已有 Helm 安装和控制台访问路径 | 补安装排错、升级、回滚、卸载 |
| 教程 | 备份恢复、容灾、演练路径已建立 | 继续补齐关键状态截图 |
| API | 已有 REST、WebSocket、统计 API 文档 | 补认证、错误码、OpenAPI 生成说明 |
| 安全 | README 已有安全报告入口 | 建立 Security 章节 |
| 兼容性 | 依赖信息分散在代码和 Chart 中 | 建立兼容性矩阵 |
| 运维 | 有生产部署和基础排障 | 补监控、容量规划、生命周期操作 |
| 版本化 | 当前只有 current | 稳定版本发布前启用 Docusaurus versioning |
P0：生产采纳阻塞项
兼容性矩阵
交付页面：兼容性矩阵
验收标准：
- 标明 Chart、operator、server、web 镜像版本关系。
- 标明 Kubernetes、Velero、对象存储、CSI/PV 恢复的验证状态。
- 对无法确认的组合明确标注为“未验证”，避免误导用户。
安全章节
交付页面：
验收标准：
- 说明 Server API 认证、JWT、WebSocket token、公开端点。
- 说明 Operator 与 Server 在管理集群中的权限。
- 说明远端集群凭据的最小权限和保存边界。
- 说明 webhook TLS、License Secret、对象存储凭据和镜像拉取 Secret 的保护要求。
生产生命周期
交付页面：
验收标准：
- 每页都有前置检查、执行命令、验证命令和风险说明。
- 明确长流程操作进行中不建议升级或卸载。
- 明确 CRD、对象存储数据和远端集群数据的保留策略。
P1：官方文档完整性
| 任务 | 交付页面 |
|---|---|
| 错误码目录 | 错误码 |
| OpenAPI 生成 | OpenAPI 生成 |
| 安装排错 | 安装排错 |
| FAQ | FAQ |
| 监控 | 监控 |
| 容量规划 | 容量规划 |
| 发布流程 | 发布流程 |
版本化文档策略
当前站点仍处于首个开源文档版本建设阶段，暂不立即冻结版本。进入稳定发布节奏后执行：
- 确认首个公开版本号，例如
v2.3或v1.0。 - 使用 Docusaurus versioning 冻结当前文档。
- 保留
current作为下一版本开发文档。 - 增加版本切换入口和版本生命周期说明。
- 检查中英文版本切换、搜索索引和
Edit this page。
维护规则
- 新增用户可见能力时，同步更新概念、教程、API 或参考页。
- 修改 API 契约时，同步 OpenAPI、REST API 文档和错误码。
- 修改 Chart、镜像版本或部署参数时，同步安装、升级和兼容性矩阵。
- 修改安全、权限、认证行为时，同步 Security 章节。
- 新增截图时，中英文页面复用同一张真实截图，避免两套截图漂移。