Cursor rule

1---
2description: "cutcli-cookbook 部署 — R2 + Worker 流程、CF API Token 权限、回滚、监控"
3globs:
4  - "worker/**"
5  - ".github/workflows/**"
6  - "scripts/upload-r2.mjs"
7  - "scripts/r2-gc.mjs"
8alwaysApply: false
9---
10 
11# 部署架构与流程
12 
13## 资源拓扑
14 
15```mermaid
16flowchart LR
17  user[Browser] -->|"https://docs.cutcli.com/*"| dns[Cloudflare DNS]
18  dns -->|"proxied A 192.0.2.1"| route[Worker Route]
19  route -->|"docs.cutcli.com/*"| worker[Worker docs-cutcli]
20  worker -->|"R2 binding DOCS"| r2[(R2 cutcli-docs)]
21```
22 
23## 资源清单
24 
25| 资源 | 标识 |
26|---|---|
27| R2 bucket | `cutcli-docs`（专放 VitePress build 产物） |
28| Worker | `docs-cutcli`（src 在本仓 `worker/`） |
29| Worker route | `docs.cutcli.com/*` + `docs.cutcli.com` |
30| DNS 记录 | `docs.cutcli.com` A 192.0.2.1 (proxied) |
31| Cloudflare account | `xuliang2022@gmail.com` (id `11c47779f0d4c3d0e69ccc6c484dc589`) |
32| Zone | `cutcli.com` (zone id `064059cb21d36956c11381995b964467`) |
33 
34## 路径解析（worker 行为）
35 
36`worker/src/index.ts` 收到请求时按下面顺序解析 R2 key：
37 
381. `/`             → `index.html`
392. `/foo/`         → `foo/index.html`
403. `/foo/bar.html` → `foo/bar.html` （直接命中）
414. `/foo/bar`（无扩展名）→ 依次试 `foo/bar.html` → `foo/bar/index.html`
425. 都不命中       → 返回 R2 中的 `404.html`，HTTP 404
43 
44## 缓存策略
45 
46| 路径 | Cache-Control |
47|---|---|
48| `assets/<hash>.{js,css}` | `public, max-age=31536000, immutable` (VitePress 文件名带 hash，安全) |
49| 其他（含 `.html`） | `public, max-age=3600, must-revalidate` |
50 
51## 本地部署
52 
53```bash
54# 一键
55npm run deploy
56 
57# 等价于
58npm run docs:build      # vitepress build → docs/.vitepress/dist
59npm run r2:upload       # 增量上传，仅 etag 变化的文件 (~10s)
60npm run worker:deploy   # 仅 worker 改动时需要
61```
62 
63`r2:upload` 用并发 6 路调用 `worker/node_modules/.bin/wrangler`，跳过 md5 相同的文件。设置 `UPLOAD_CONCURRENCY=8` 可提速。
64 
65## CI 部署（推荐）
66 
67合并到 `main` 后，`.github/workflows/deploy-docs.yml` 自动跑：
68 
69```text
70checkout
71  → setup-node v22
72  → npm ci (root + worker)
73  → npm run docs:build
74  → node scripts/upload-r2.mjs        # 增量上传
75  → cloudflare/wrangler-action@v3 deploy worker (仅 worker 有改动时)
76  → smoke test (curl 5 个关键路径)
77```
78 
79触发条件（`paths`）：
80 
81- `docs/**`
82- `worker/**`
83- `scripts/upload-r2.mjs`
84- `package.json` / `package-lock.json`
85- `.github/workflows/deploy-docs.yml`
86 
87也可手动 `gh workflow run deploy-docs.yml`。
88 
89## CF API Token 权限
90 
91GitHub Secrets 必须配：
92 
93| Secret | 用途 |
94|---|---|
95| `CLOUDFLARE_API_TOKEN` | wrangler 鉴权 |
96| `CLOUDFLARE_ACCOUNT_ID` | `11c47779f0d4c3d0e69ccc6c484dc589` |
97 
98Token 推荐**最小权限**（不要用 Global API Key）：
99 
100- Account → Workers Scripts → Edit
101- Account → Workers R2 Storage → Edit
102- Zone → Workers Routes → Edit (resource: `cutcli.com`)
103- Zone → DNS → Edit (resource: `cutcli.com`，仅首次绑域名时需要)
104 
105## 监控
106 
107```bash
108# 实时 worker 日志
109cd worker && npx wrangler tail
110 
111# 查 7 日错误率（目标 < 0.1%）
112# Cloudflare Dashboard → Workers & Pages → docs-cutcli → Logs / Analytics
113```
114 
115`scheduled-cases-test.yml` 每晚跑案例校验，失败自动开 issue。
116 
117## 回滚
118 
119### 文档内容回滚（最常见）
120 
121```bash
122# 回滚到上一个 commit
123git revert HEAD
124git push
125 
126# CI 自动重跑 deploy-docs，约 1 分钟内全球 R2 + worker 边缘节点同步完
127```
128 
129### Worker 回滚
130 
131```bash
132# Cloudflare Dashboard → Workers & Pages → docs-cutcli → Deployments
133# 选上一版本 → Rollback
134```
135 
136或用 wrangler：
137 
138```bash
139cd worker
140npx wrangler deployments list
141npx wrangler rollback --version-id &lt;previous-id&gt;
142```
143 
144### R2 整体回滚（极端情况）
145 
146R2 没有自动版本控制；需要从最近一次成功的 build 重新上传：
147 
148```bash
149git checkout &lt;good-sha&gt;
150npm run docs:build && npm run r2:upload
151# 再 git checkout main 回到当前
152```
153 
154## 周级 GC（清孤儿）
155 
156VitePress 每次 build 会生成新的 `assets/<hash>.{js,css}`，旧的会留在 R2。每周一次清理：
157 
158```bash
159CLOUDFLARE_API_TOKEN=$CLOUDFLARE_API_TOKEN \
160CLOUDFLARE_ACCOUNT_ID=11c47779f0d4c3d0e69ccc6c484dc589 \
161node scripts/r2-gc.mjs --dry-run    # 预览要删什么
162node scripts/r2-gc.mjs --yes         # 实际删
163```
164 
165## 首次部署 checklist（参考 .github/RELEASE_GUIDE.md）
166 
167- [x] R2 bucket `cutcli-docs` 已建
168- [x] Worker `docs-cutcli` 已部署
169- [x] DNS `docs.cutcli.com` A 192.0.2.1 proxied
170- [x] Worker routes 已绑
171- [x] GitHub repo 已创建并 push
172- [x] GitHub secrets 已配
173- [x] CI / Deploy 跑过一次全绿
174- [ ] `main` 分支保护（待开）
175- [ ] 90s demo 视频（待人手）
176