运维 / CI-CD¶

vault 的 CI/CD 架构、凭证流转、失败排查、扩展方法。

架构一览¶

编辑代码 ─→ git commit ─→ git push ─→ GitHub Actions ─→ Cloudflare Pages
            (本地)       (远端)        (3 个并行 job)   (全球 CDN)
             ↑                          ↓
       pre-commit hook                wrangler
       ~0.3s 秒回                    via CF_API_TOKEN
                                     (GitHub Secret)

本地 `pre-commit`（~0.3s）¶

拦秒级问题，挡不合格的 commit： - 语法：JSON / YAML / 行尾空白 / 末尾换行 - 代码风格：ruff lint + format - Schema：check-jsonschema 按 schemas/*.schema.json 校验 data/ - 自洽：vault check 扫所有引用关系

秒级内跑完。

GitHub Actions（~30-60s，3 个 job 并行）¶

ruff + schema + gitleaks
ruff lint / format 再跑一次（防止 pre-commit 被 --no-verify 绕过）
check-jsonschema 跑 schemas 文件本身
gitleaks 扫仓库历史，查误入的密钥
pytest (no-data)
跑单元测试 + coverage ≥ 70%
设 VAULT_SKIP_INTEGRATION=1，跳过需要真实 data/ 的 27 个测试
因为 CI 拿到的 data/ 是加密的
mkdocs build + deploy to Cloudflare Pages
mkdocs build --strict 构建静态文档
若 push 到 main：调 cloudflare/wrangler-action@v3 部署

Cloudflare Pages¶

项目名：agentaily-vault
域名：https://agentaily-vault.pages.dev/
每次 main push 自动新版本，旧版本保留为 "preview deployments"

凭证流转¶

  vault 里：
      credential cloudflare-pages-deploy
          ↓ 手动 gh secret set
  GitHub Repo Secret:
      CLOUDFLARE_API_TOKEN  ← 只 GitHub Actions runtime 能读
      CLOUDFLARE_ACCOUNT_ID
          ↓ workflow 注入 env
  wrangler-action 进程：
      读 env → 调 CF API → 推 ./site/
          ↓
  Cloudflare Pages 接收 → 全球 CDN 生效

最小权限：给 CI 的是 cloudflare-pages-deploy（只 Pages:Edit），不是 cloudflare-main（全权限）。泄漏了最多被别人挂 Pages，不会炸掉 DNS。

轮换 CF token¶

# 1. 在 CF 控制台（https://dash.cloudflare.com/profile/api-tokens）
#    建新的 vault-pages-deploy token（Custom Token，Cloudflare Pages:Edit）
#    复制新 token 值

# 2. 更新 GitHub Secret
gh secret set CLOUDFLARE_API_TOKEN --body "<新 token>"

# 3. 同步到 vault
vault credential edit cloudflare-pages-deploy
# 把 values.api_token 换成新的
# 在 metadata 里记 rotated_at: 2026-04-22

# 4. 触发一次 CI 确认新 token 能用
git commit --allow-empty -m "ci: verify new CF token"
git push
gh run watch

# 5. 回 CF 控制台删旧 token

失败排查¶

本地 `git commit` 被 hook 拦住¶

看终端输出，有具体哪个 hook 挂了：

ruff lint........................................Failed

# 查具体错
uv run ruff check src test scripts
# 或自动修
uv run ruff check --fix src test scripts

其它常见： - check-jsonschema 挂：data/ 里新加的 json 不符合 schema。看 schemas/.schema.json 的 required 字段 - vault check 挂：有悬空 ref。看报的 → persons/xxx.json not found，去补那个文件 - end-of-file-fixer 挂：文件没空行结尾。hook 自动修好了，git add 再 commit 就行

GitHub Actions 挂¶

gh run list --limit 5                     # 看最近几次
gh run view <ID> --log-failed | tail -40  # 看失败步骤日志
gh run view <ID> --web                    # 浏览器里看完整

按 job 名字诊断：

Job 挂了	通常原因
`ruff + schema + gitleaks`	本地 ruff 版本跟 pre-commit 钉的版本不一致 → 改 `.pre-commit-config.yaml` rev
`pytest (no-data)`	某个 unit 测试挂了 / coverage 跌破 70%
`mkdocs build + deploy`	文档里的链接断了 / markdown 语法错 / CF token 权限不够

CF Pages 部署挂¶

# 看 deploy 步骤的 stderr
gh run view <ID> --log-failed | grep -iE "error|fail|project"

常见： - Authentication error [code: 10000] → token 没 Pages:Edit 权限，重造 token - Project not found [code: 8000007] → CF 里没建这个项目

TOKEN="..." && ACCOUNT="..." && curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT/pages/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"agentaily-vault","production_branch":"main"}'

- Artifact storage quota has been hit → 账号 CI artifact 配额爆；换不上传 artifact 的方案

扩展 CI¶

加一个新 hook¶

编辑 .pre-commit-config.yaml：

repos:
  - repo: local
    hooks:
      - id: my-new-check
        name: 我的新校验
        entry: uv run python scripts/my_check.py
        language: system
        pass_filenames: false
        always_run: true

测试：uv run pre-commit run my-new-check --all-files

加一个新 Actions job¶

在 .github/workflows/ci.yml 加：

jobs:
  my-new-job:
    name: 我的新 job
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: ...
        run: ...

加一个新 GitHub Secret¶

gh secret set MY_NEW_SECRET --body "$(pbpaste)"
gh secret list

版本 & 工具链¶

组件	位置	版本来源
Python	`pyproject.toml` requires-python	≥3.12
uv	用户手动装	最新
ruff	`[dependency-groups].dev`	用 `pyproject.toml` 里的
ruff (pre-commit)	`.pre-commit-config.yaml`	必须钉死，和 uv 装的版本一致
pre-commit 框架	`[dependency-groups].dev`
mkdocs-material	`[dependency-groups].docs`
wrangler (CI)	`cloudflare/wrangler-action@v3` 内部	自动拉最新

升级 ruff 时一定要同步改两处（pyproject.toml 和 .pre-commit-config.yaml），否则 CI 和本地规则会打架。

速查卡¶

任务	命令
全跑一次 pre-commit	`uv run pre-commit run --all-files`
安装 hooks	`uv run pre-commit install --hook-type pre-commit --hook-type pre-push`
看最近 CI	`gh run list --limit 5`
看 CI 日志	`gh run view <ID> --log-failed`
手动触发一次 CI	`git commit --allow-empty -m "ci: rerun" && git push`
查 GitHub Secrets	`gh secret list`
查 CF Pages 项目	`curl .../accounts/$ID/pages/projects -H "Authorization: Bearer $TOKEN"`
本地预览文档	`uv run --group docs mkdocs serve`
线上文档	https://agentaily-vault.pages.dev/