部署与排障
- 文档状态
- draft
- 文档 Owner
- DOC
- 事实源
- canonical-docs
- 更新
- 2026/10/16
先确认维护对象、目标环境和版本，再进入对应路径。文档站、Plane 产品和 Symphony 的发布 owner、执行环境与成功标准不同。
选择维护对象
| 对象 | 责任入口 | 从哪里开始 | 如何判断结果 |
|---|---|---|---|
| 当前 AutoDev 文档站 | 文档仓与 Cloudflare Pages | 下文“文档站” | 云构建、发布提交、页面身份、路径、搜索与阅读体验 |
| Plane 产品 | Plane 源码、发布与 GitOps owner | 构建与部署 | 同一发布身份下的 CI、镜像、TEST 验收、GitOps 与 PROD 观察 |
| Symphony 执行服务 | 当前项目注册的服务源码与 host owner | Symphony 维护 | 配置、安装与服务运行证据，再检查具体任务 |
无法确定对象、环境、owner 或授权范围时，先记录缺口并联系对应 owner；不要试用其他系统的部署命令。
文档站
当前配置与发布路径
本仓 README.md 和 scripts/build_pages.sh 记录当前文档站使用 GitHub main 与 Cloudflare Pages，构建命令为 bash scripts/build_pages.sh，输出目录为 build。这是当前源码配置，不能证明某次部署已经完成。
文档修改先形成独立分支的源码差异，经审查后由获授权的云构建检查精确提交，再按既有合并与发布权限推进。向已接入 Pages 的分支推送可能触发预览或生产构建，执行前须核对该分支的构建与发布设置。
云端脚本依次生成固定来源目录和导航、检查生成物一致性、执行合同与部署检查、构建 Docusaurus、检查结构无障碍，最后生成 Pages 元数据。中文搜索在完整站点构建时生成索引。
本仓禁止本地测试、校验器与构建。 缺少云构建证据时应写“未验证”，不能用本地启动页面替代。
核对发布结果
- 在 Pages 部署记录中核对目标项目、分支、提交和构建结果；失败时先看实际失败步骤。
- 比对站点
deploy-meta.json的提交身份与这次部署，不用旧 GitLab 快照代替 Pages 记录。 - 打开首页和受影响页面，检查标题、正文及链接；保留旧 URL，不用统一跳回首页掩盖失效页面。
- 在已构建站点检查中文搜索、键盘操作及手机宽度；构建成功不能替代阅读体验检查。
原 release-history.json 保存的是导入的旧发布快照。发布日志可用于追溯，不自动成为当前 Pages 的发布证据。
常见故障
| 现象 | 先核对 | 下一步 |
|---|---|---|
| 生成物不一致，云构建停止 | 导航输入、frontmatter、生成脚本与固定来源变更 | 修正输入，从受控外部生成结果取得完整产物或真实 diff，原样提交后重跑；不手工推导生成物或关闭门禁 |
| 页面或锚点构建失败 | 错误指向的 route、doc ID、slug 与锚点 | 修复精确引用，保留旧锚点，不降低严格检查 |
| 页面仍是旧版 | Pages 当前部署分支、提交与元数据 | 定位构建或发布差异，不重复推送无关改动 |
| 搜索结果不对 | 完整云构建的索引、目标页与当前部署身份 | 区分索引生成、部署与浏览器表现，按实际错误修复 |
| 需要恢复旧版 | Pages 实际可用的成功部署、提交与恢复授权 | 由部署 owner 按平台流程操作并回读页面，不套用旧内网目录切换命令 |
Plane 产品
先读环境与接入与测试和正式环境，再按构建与部署及发布流程核对现行合同。
这条链路描述 GitLab、Harbor、GitOps 与 Argo CD：版本包合入后触发受保护版本发布，TEST 验收通过后推进同一不可变镜像身份到 PROD。源码 MR、构建成功、Argo 健康与业务验收分别闭合；本文未核验目标环境本次运行状态。
- 版本或镜像不匹配：比对 exact version、tag、commit、pipeline 与 digest，不推测“最新版本”。
- TEST 验收或 PROD 观察缺失：停在具体失败步骤，交对应 owner 修复，不能跳过门禁。
- 需要恢复：阅读运维与恢复，按目标发布与 GitOps 合同处理，保留原证据。
Symphony
从Symphony 维护核对版本、有效 WORKFLOW、启动参数、日志与观察、升级和恢复。独立官方参考实例使用首次运行；已有团队实例从 Automation 实施说明确认绑定服务与 owning source，不照抄参考启动命令替换受管进程。协议见 Runtime 通信协议，切换与兼容见迁移说明。
任务未执行时，依次核对所属 tracker 的真实任务、依赖与授权、项目绑定、当前 WORKFLOW，以及 Symphony 运行状态。仅有委托开关、进度评论或源码合并不能证明服务在线。
使用者的逐步诊断见任务故障处理，公共重试与恢复语义见失败与恢复；本文不重复定义第二套机制。
服务维护由进程外 owner 的当前流程完成，业务 worker 不维护或替换自己的宿主。重试或接管前确认旧执行已停止，保留任务、工作目录、分支与交付证据，不删除锁来制造空闲，也不以反复切换开关代替诊断。
提交有用的故障说明
在原任务或 owning 维护入口记录：维护对象、环境、预期与实际结果、精确提交或发布身份、失败步骤、证据引用及下一 owner。私人日志、账号、凭据和原始敏感响应留在受控系统，不复制进公开文档。
缺少环境证据时明确写“待确认”；不可用的云构建、owner 工作流或权限是具体阻塞，不能据此采用未经授权的手工发布。
相关资料：任务跟进 · 开发 AutoDev · 系统边界