运维操作手册

运维操作手册

你是谁 / 本手册范围

你是运维工程师：负责记录和维护项目的基础设施配置信息，包括 AWS Amplify 部署配置、后端各服务环境变量、数据库用户、Redis 互通说明、IAM 角色权限策略。这些配置文档推送到文档站后，后台工程师可按需拉取查阅（只读）。

重要原则：敏感值（密码、密钥、证书）一律不记录，只记录键名、用途说明和值来源。

本手册假设你已按下方「首次配置」步骤完成环境初始化。

---

首次配置

1. 初始化 .docs.env

跑 /docs-init，把管理员通过安全渠道发给你的配置整段粘贴进 .docs.env。运维角色必须包含以下字段：

# 顶层
GITLAB_BASE_URL=https://gitlab.ironetwork.com
GITLAB_DOCS_BRANCH=main
GITLAB_DOCS_PROJECT_ID=213              # docs-site 仓库，所有项目共用
GITLAB_DOCS_WRITE_TOKEN=glpat-xxxx      # 读 + 写 content/{project}/**

# 你的身份（/notify 用）
MEMBER_NAME=your_name
MEMBER_TG=@your_tg

# Skills 安装用（运维只需 common）
SKILLS_ROLE=common
SKILLS_COMMON_TOKEN=glpat-xxxx

# Telegram（全局一个 bot token；chat id 按项目）
TELEGRAM_BOT_TOKEN=bot123:xxx

# 按项目一段
[pay-fi]
TELEGRAM_CHAT_ID=-100...

[fomo-pad]
TELEGRAM_CHAT_ID=-100...

2. 安装运维 skill 包

/skills-install

• SKILLS_ROLE=common 会拉 skills-common 仓库，包含运维所需的全部 skills
• 完成后按提示重启 Claude Code

---

日常工作流

场景 A：首次初始化运维配置文档

什么时候用：项目上线前，首次把基础设施配置信息整理成文档。

触发命令：

/ops-docs-gen

关键输入：

1. 选择目标项目（多项目时列出选项）
2. 选择要生成的模板（可多选或全部）：
   • amplify.md — AWS Amplify 部署配置
   • env-vars.md — 后端各服务环境变量
   • database.md — 数据库用户
   • redis.md — 服务间 Redis 互通说明
   • iam.md — AWS IAM 角色权限策略
3. 对每类模板批量回答问题，AI 根据回答填充生成

产出结果：

docs/{project}/ops/
├── amplify.md
├── env-vars.md
├── database.md
├── redis.md
└── iam.md

所有模板的「键名」和「用途」填充完毕，敏感值（密码、密钥）保持空白。

场景 B：日常维护配置文档

什么时候用：基础设施变更后（新增环境变量、修改数据库用户、更新 IAM 策略等）。

做法：直接用编辑器打开 docs/{project}/ops/ 下对应的 md 文件修改，无需运行任何 skill。

也可以在 docs/{project}/ops/ 下新增任意 md 文件记录其他配置信息（如 nginx 配置、Cloudflare 规则、监控告警策略等），格式不限。

场景 C：推送文档到文档站

什么时候用：配置信息更新完成后，推送让后台工程师可以拉取查阅。

触发命令：

/docs-push-gitlab

关键输入：

1. 多项目时选择目标项目
2. 文档类型选 6. ops

产出结果：docs/{project}/ops/ 下所有文件一次性批量提交到 GitLab，只触发一次 CI 构建，约 30 秒后文档站自动部署生效。

场景 D：通知后台工程师

什么时候用：推送完成后，通知后台团队拉取最新配置文档。

触发命令：

/notify

关键输入：选场景 1. 需求文档已更新（文档更新通知），选项目后发送。

产出结果：Telegram 通知自动 @mention 后台工程师，提示他们执行 /backend-docs-pull 拉取 ops 文档。

---

后台工程师如何查看运维配置

后台工程师执行 /backend-docs-pull 时，会询问是否同时拉取运维文档：

是否同时拉取运维配置文档（ops）？(y/回车跳过)

选 y 后，ops 文档全量同步到 .docs/{project}/ops/（只读目录），后台工程师可查阅但不会直接修改。

在线查看：https://team-docs.pages.dev/{project}/ops/

---

常见问题 / 故障排查

Q1：推送时提示 Token 无效（401）？

联系技术管理员，用 /member-token-gen 重新生成 GITLAB_DOCS_WRITE_TOKEN，更新 .docs.env 中的值。

Q2：推送后文档站没有更新？

GitLab CI 触发后约 30 秒自动部署。若超过 2 分钟未更新，检查 GitLab CI 流水线状态（项目 ID 213）。若 CI 失败，联系技术管理员排查。

Q3：敏感值如何管理？

文档站只记录键名和用途，实际值存放在：

• AWS Secrets Manager / 1Password / 运维内部系统

团队成员通过文档站了解「有哪些配置」和「去哪里找」，不通过文档站传递实际密钥。

Q4：docs/{project}/ops/ 目录可以自由新增其他文件吗？

可以。/ops-docs-gen 只初始化 5 类标准模板。你可以在该目录下新增任意 md 文件（如 nginx.md、monitoring.md、cloudflare.md），/docs-push-gitlab 会自动包含所有文件一起推送。

---

相关文档链接

• 通用工具箱：common.md — 环境准备 / git / docs-push / notify / FAQ
• 后台工程师手册：backend.md — 查看运维配置文档的拉取方式
• 管理员手册：admin.md — Token 申请 / skills 分发
• 运维文档在线查看：https://team-docs.pages.dev/{project}/ops/