Appearance
docs/ops/ — 运维操作文档
本目录收录与运维 / 部署 / 持续交付相关的操作手册（"如何做"）， 与
docs/design/2.technical/specialized/L3-E-deployment-and-ops.md（"为什么"）形成互补关系。
一、目录定位
| 维度 | docs/ops/（本目录） | docs/design/2.technical/specialized/L3-E-* |
|---|---|---|
| 文档性质 | 操作手册（step-by-step、命令清单、踩坑） | 设计决策（架构、形态、演进路径） |
| 适用读者 | SRE / 运维 / 首次搭建环境的开发者 | 架构 Owner / 技术 review / 长期路线图 |
| 更新频率 | 高（随脚本/工具变化随时更新） | 低（重大决策才变更） |
二、当前文档清单
| 文件 | 状态 | 说明 |
|---|---|---|
README.md | ✅ 当前 | 本文件（索引） |
testbed-runbook.md | ✅ 当前 | ECS-B 测试机日常运维：部署 / 迁移 / OpenBao / seed / verify 探针 / gate·smoke·e2e |
cloud-agent-to-ecs-b-channel-setup.md | ✅ 当前 | Cloud Agent → ECS-B 四 Secret SSH 通道一次性搭建 |
ci-github-actions-setup.md | ✅ 当前 | GitHub Actions CI 接入指南（人类一次性操作） |
tenant-onboarding-runbook.md | ✅ 当前 | 租户入驻 / 模型 key 供给 / 常见故障 |
keycloak-registration-secrets.md | ✅ 当前 | Keycloak 自助注册相关 Secrets |
saas-mode-b-checklist.md | ✅ 当前 | SaaS Mode B 验收 checklist |
billing-free-run-mode.md | ✅ 当前 | 计费 free-run / 积分演示路径 |
production-topology-and-domains.md | ✅ 当前 | 团队阅读版：多域名 · 产品线 · 基座 · 仓库 · 服务器的生产部署架构（4 域名 + 5 仓库 + SGP 节点真实案例；请求走法 / realm 配置 / Google · PayPal / 运维手册 / FAQ / 缺口清单） |
realm-topology-rollout-guide.md | ✅ 当前 | 多 realm 拓扑逐步操作：§0 零回归确认 → §1 R1 预检 → §2 平台 realm 登记 → §3 PE3-1 品牌 realm → §5 跟进项 |
overseas-node-sgp-setup.md | ✅ 当前 | SGP 海外生产节点引导记录与部署通道 |
payment-go-live-gates.md | ✅ 当前 | 微信 / PayPal 投产闸门清单（PE2-4） |
ops-scope-grant-runbook.md | ✅ 当前 | Ops 控制台权限补授（KC 手工授予 ops:* scope）：背景边界 · 最小授权 · UI/API 双途径 · claim sync 耐久性 · 坑速查（issue #351） |
kc-spa-clients-reconcile.md | ✅ 当前 | KC 浏览器 SPA client 置备收敛：issue #352 根因 · 声明源三层设计 · testbed/SGP/CCA 三通道命令 · dry-run/apply 判读 · 回滚 · 新 client 接入流程（PE-FIX-03） |
ba6-brand-acceptance.md | ✅ 当前 | BA6 品牌资产真栈验收：sidecar S1~S16 判据对表 · 运营位占用预检 fail-closed · worm-aware 残留口径 · owner 人工主线剧本（2026-09-15 已收官 21/21） |
历史文档
ci-codeup-setup.md（云效 CodeUp + Yunxiao Flow）已于 2026-05-27 随迁移至 GitHub 移除。 见 ADR-0020 与 SEM-013。
三、白名单脚本速查（ECS-B）
事实源闸门：.trae/rules/remote-ops.md。严禁裸 ssh ecs-b "..." 跑业务命令。
| 脚本 | 用途 |
|---|---|
scripts/deploy-from-cloud-agent.sh | Cloud Agent → ECS-B 部署（ai_develop / cursor/*） |
scripts/deploy-to-testbed.sh | 本地人工部署（默认 base + testbed override，--base-only 兜底；ai_develop / 已 push cursor/*） |
scripts/verify-testbed.sh | 健康自检（基线 + 可选探针，含 --vault） |
scripts/logs-testbed.sh | 远程服务日志 |
scripts/seed-testbed.sh | KC / DB 种子 + --openbao AppRole 供给 |
scripts/e2e-testbed.sh | 真栈 e2e（含 --register-model vault 写路径） |
scripts/gate-testbed.sh | 任务包门禁代跑（sidecar + scratch 库，零接触活栈） |
scripts/smoke-conversation-testbed.sh | CV1 headless 会话 S1~S10 真栈冒烟 |
scripts/spike-testbed.sh | CV0-SPIKE AgentScope 嵌入验证 |
scripts/ba6-acceptance-testbed.sh | BA6 品牌资产真栈验收（sidecar S1~S16，零接触活栈；runbook docs/ops/ba6-brand-acceptance.md） |
操作步骤与踩坑见 testbed-runbook.md。
四、相关入口
- 远程操作约束（事实源）：
.trae/rules/remote-ops.md - ECS-B 引导手册：
docs/z.reference/dual-ecs-bootstrap-guide.md - 对外指南入口：
docs/guides/README.md（能力现状 / 模式 B / 品牌自托管 / 支付开闸边界） - 会话式接入教程：
docs/guides/tutorial/hello-agent.md§10 - 生产部署设计：
docs/design/2.technical/specialized/L3-E-deployment-and-ops.md