OPERATIONS —— 运维手册

「这套线上系统由什么托起来、怎么看住它、出事怎么办」的运维(SRE)手册 —— 面向运行中的生产环境。「怎么在本地开发」看 DEVELOPMENT.md;「一处改动怎么走到生产」看 RELEASE.md(发版流程);域名 / DNS 方案看 DOMAINS.md。
⚠️ 运维动作多为不可逆 / 影响线上(改 secret、跑迁移、回滚、改 DNS)—— 执行前先对本文 + 跟老板确认,别 fire-and-forget。凭证一律走 vault,绝不明文进 agent context / 提交进仓库。

一、生产环境清单(Inventory)

资产	标识	平台 / 账号	说明
主应用 web	https://agentaily.pages.dev	Cloudflare Pages 项目 `agentaily`(yarnbcoder 账号)	Vite SPA + Pages Functions(`/api/*`),同源后端
官网 website	(CF Pages 项目 `official-website`)	Cloudflare Pages(同上账号)	双语营销落地页,base `/`
D1 数据库	`agentaily-db` · id `d910ce7b-cbc2-4bad-a229-4ee8d9c28db3`	Cloudflare D1(yarnbcoder,APAC)	主应用数据;schema 真相源 = `@agentaily/db`(Drizzle)
发布运行时	`@agentaily/publish`(`apps/publish`)	Cloudflare Workers(按 Host 路由)	UGC 子域 + 自带域名的产物托管;域名方案见 `DOMAINS.md`
反馈 Worker	`agentaily-feedback`(`apps/feedback`)	Cloudflare Workers(独立,无 D1)	收 `@agentaily/feedback-widget` 提交 → GitHub REST 开 PR;CD 未接,手动 deploy(同 publish)

⚠️ 账号别用错:部署只用 yarnbcoder(见记忆 vault-cf-accounts-dont-mix-up);另一个曾误名 main、实属 Yarnbgpt@gmail.com 的账号别碰。资源台账落 vault 的 resources/。

二、凭证与 Secret(谁、放哪、怎么设)

凭证真相源 = vault(credentials/)。落到运行环境分两类:

Secret	用在哪	怎么设	备注
`CLOUDFLARE_API_TOKEN`	GitHub Actions(`deploy.yml` / `deploy-website.yml`)	`gh secret set`(值经 stdin,不回显)	缺它 CD 自动跳过部署、job 仍绿(见下「就绪门」)
`CLOUDFLARE_ACCOUNT_ID`	同上	同上	yarnbcoder 账号 id
`BAILIAN_KEY` 等模型 key	Pages Functions 运行时(主应用 `/api/*`)	`wrangler pages secret put <NAME> --project-name=agentaily`	部署后设;百炼接入见 skill `bailian-api`
`EMAIL_FROM` / Resend key	发信(如启用)	同 `wrangler … secret put`	发件域 `mail.agentaily.com`(Resend 已验证)
`GITHUB_TOKEN`	`agentaily-feedback` Worker 运行时	`pnpm --filter @agentaily/feedback exec wrangler secret put GITHUB_TOKEN`	fine-grained PAT(scope `agentaily/agentaily`,Contents:write + Pull requests:write);没设时 Worker 返回清晰 503、不崩。本地用 `apps/feedback/.dev.vars`(gitignored)

铁律:设 secret 一律 jq … | gh secret set 或值经 stdin / 文件灌入,明文不进 agent context、不落仓库(参照 cloudflare-*-deploy / vault skill 的做法)。

三、持续部署机制(CD = 发版的执行层)

push main → 三个 workflow 并行触发(.github/workflows/):

Workflow	触发	干什么	失败影响
`ci.yml`	push main · 所有 PR	`pnpm install --frozen-lockfile` → `typecheck` → `test` → `build`	红 = 这次改动没过门禁(不直接拦部署,但必须修)
`deploy.yml`	push main · 手动 `workflow_dispatch`	`build` → `wrangler pages deploy dist --project-name=agentaily`	红 = 主应用没上线
`deploy-website.yml`	push main · 手动	`build`(全图,先构建 DS 的 dist)→ deploy 到 `official-website`	红 = 官网没更新;有 `concurrency` 取消旧跑

「就绪门」(guard):两个 deploy workflow 开头都检查 CLOUDFLARE_API_TOKEN 是否存在——没设就跳过 deploy 步、job 保持绿(不会因缺凭证而红)。所以看到 deploy「绿但没真部署」要确认是不是 token 没配 / 被跳过,别误判成已上线。

CD 的「怎么决定何时 push、怎么盯到绿」属于发版流程 —— 见 RELEASE.md。本文只描述机制与线上运维。

四、部署后冒烟(Smoke Check)

每次部署到生产后,人工 / 脚本至少确认:

主应用可达:curl -I https://agentaily.pages.dev → 200;首屏能加载、登录入口在。
后端 /api/* 活着:打一个只读 API(如健康 / 配置端点)→ 非 5xx;D1 绑定生效(能读到数据)。
官网可达:official-website 域名首页 200、双语切换正常。
控制台无致命报错:打开页面看浏览器 console 无红(可用 claude-in-chrome 的 read_console_messages 自动核)。

冒烟失败 → 走下面「回滚」,别让坏版本留在线上。

五、回滚(Rollback)

线上坏了,先止血再定位。优先级从快到慢:

Cloudflare Pages 即时回滚(最快):CF Dashboard → Pages → agentaily / official-website → Deployments → 选上一个好版本 Rollback。秒级生效,不依赖仓库。
revert 提交 + 重新 push:git revert <坏提交> → 经 push 锁 push main → CD 重新部署上一个好状态。绝不 force-push(铁律③)。
D1 数据问题:数据层故障比代码回滚更重 —— 见下「数据运维」,改数据前务必先确认有备份,且找老板拍板。

回滚后把「什么坏了、怎么回的」根因沉淀进记忆 / ROADMAP.md。

六、数据运维(D1 / 迁移)

Schema 真相源 = @agentaily/db(Drizzle);迁移生成到 db/migrations(别手改旧的 apps/web/migrations/**)。

应用迁移:

bash

# 本地(local sqlite,免账号):
pnpm --filter @agentaily/web exec wrangler d1 migrations apply agentaily-db --local
# 生产(account-gated,改线上数据 —— 跑前确认备份 + 找老板拍板):
pnpm --filter @agentaily/web exec wrangler d1 migrations apply agentaily-db --remote

破坏性迁移(删列 / 改类型 / 数据回填)= 高危:先备份、先在本地 / 预览验证、部署窗口与老板对齐,别在无人值守时跑(参见全局准则「有风险 / 不可逆的发布前先跟老板确认」)。
绑定以 apps/web/wrangler.toml 为准(binding = "DB" → agentaily-db)。

七、域名与 DNS

完整方案(官网根域 / 应用 / 发布 UGC 子域 + 自带域名)是 DOMAINS.md 的真相源,本文不复述。
DNS 托管在阿里云;CF Pages 自定义域走「阿里云加 CNAME → CF 绑定 → 等证书验证」(参照 skill cloudflare-pages-deploy)。
改 DNS / 换证书 = 影响可达性的运维动作 —— 改前确认、改后冒烟。

八、故障应急(Incident)清单

线上异常时,按序排查:

是不是刚部署的? → 看 gh run list 最近一次 deploy 是否绿、时间是否吻合;可疑就先回滚(第五节)。
CI 绿但没真部署? → 检查 CLOUDFLARE_API_TOKEN 就绪门是否把 deploy 跳过了(第三节)。
后端 5xx? → 看 Functions 运行时是否缺 secret(BAILIAN_KEY 等)/ D1 绑定是否生效;模型上游报错对照对应 provider skill(bailian-api / deepseek-api / volcengine-ark)。
数据异常? → 别急着改数据;先确认是代码 bug 还是数据被写坏,走第六节。
拿不准 / 要改不可逆的东西 → 停下,叫老板(worker 终端经信道问主会话)。

九、待补 / 已知缺口(Open Items)

跟 ROADMAP.md 对齐;运维能力补齐后回来勾掉。

⬜ 生产监控 / 告警:暂无统一健康探针 + 通知(ntfy / 邮件)。冒烟目前靠人工。
⬜ D1 自动备份 / 导出策略未固化(破坏性迁移前依赖人工备份)。
⬜ Studio 子路径打包 + 生产 LLM 代理接线:deploy.yml 注释标注仍是 TODO(当前只部署 apps/web/dist)。
⬜ 部署后自动冒烟:第四节目前手动,未接 CI 后置 smoke job。

真相源 / 根文档索引(运维相关)

文档	与运维的关系
`OPERATIONS.md`	运维手册(本文)—— 跑住线上、应急、回滚
`RELEASE.md`	发版流程 —— 一处改动怎么走到生产(CD 的「何时 / 怎么 push 到绿」)
`DEVELOPMENT.md`	本地开发指南(环境、端口、后端 / D1 本地跑)
`DOMAINS.md`	域名 / DNS 方案
`ROADMAP.md`	能力地图 + 当前进度(运维缺口在此跟踪)
`RELEASE.md`	发版手册(worktree + PR → 合并触发 CD)

维护纪律:任何改动新增 / 改变了线上资产、secret、CD 行为、迁移方式、回滚路径或域名时,在同一次改动里更新本文——把「文档声称的运维现实」与「线上真实状态」之间的漂移当 bug 修。详见 CLAUDE.md 的「根文档索引 + 维护纪律」。

OPERATIONS —— 运维手册 ​

一、生产环境清单(Inventory) ​

二、凭证与 Secret(谁、放哪、怎么设) ​

三、持续部署机制(CD = 发版的执行层) ​

四、部署后冒烟(Smoke Check) ​

五、回滚(Rollback) ​

六、数据运维(D1 / 迁移) ​

七、域名与 DNS ​

八、故障应急(Incident)清单 ​

九、待补 / 已知缺口(Open Items) ​

真相源 / 根文档索引(运维相关) ​