Hybrid 部署 · Cloudflare Pages + 腾讯云轻量

v0.3.0-rc1 · 见 ADR-005 决策背景
把 boss-skills 拆成静态层 + API 层分别部署. 静态走 Cloudflare CDN ($0), API 走腾讯云 VM (70-80 元/月). 整体最优 cost / speed / 安全。

0. 架构总览

                                  ┌──── 用户 (国内 / 海外) ────┐
                                  │                          │
                                  │  浏览器看 docs            │ curl 调 API
                                  ▼                          ▼
       ╔══════════════════════════╗            ╔═══════════════════════╗
       ║  Cloudflare Pages        ║            ║  腾讯云轻量 (CN-1)     ║
       ║  · landing.html          ║            ║  · uvicorn boss_server║
       ║  · 5 showcase            ║            ║  · attribution cron   ║
       ║  · openapi.json          ║            ║  · anchors/raw (700)  ║
       ║  · README                ║            ║  · nginx + SSL        ║
       ║                          ║            ║                       ║
       ║  $0 · 全球 CDN           ║            ║  ~70-80 元/月 · 2C2G  ║
       ║  boss-vault.pages.dev    ║            ║  api.boss-vault.com   ║
       ║  或自定义域名             ║            ║                       ║
       ╚══════════════════════════╝            ╚═══════════════════════╝
                ▲                                       ▲
                │ push to main                          │ git pull
                │ Cloudflare GitHub integration         │ systemctl restart
                └──────── GitHub (source) ──────────────┘

职责拆分:

资源	性质	host	成本
`landing.html`	公开, 无 secret	Cloudflare Pages	$0
`docs/showcase/*.html` (5 个)	公开, 无 secret	Cloudflare Pages	$0
`docs/api/openapi.json`	公开 API spec	Cloudflare Pages	$0
`README.md` 渲染	公开	Cloudflare Pages	$0
`scripts/boss_server.py` (5 endpoint)	有 secret, long-running	腾讯云 systemd	$10/月
`scripts/attribution_check.py` (cron)	有 secret + 数据	腾讯云 systemd timer	(含上面)
`anchors/<slug>/raw/` (data)	confidential	腾讯云 home (chmod 700)	(含上面)

1. 决策框架 · 你需要哪几层?

不一定一次全部署. 按你的实际需求挑:

你的场景	A 静态 (Cloudflare)	B API (腾讯云)	C Cron + Data (腾讯云)
想给外部人看 docs / 信息图	✅ 必做	❌ 不必	❌ 不必
想让外部 LLM runtime 调 API	✅ 必做	✅ 必做	(可选, attribution 可推迟)
想 always-on attribution cron	✅ 必做 (展示)	✅ 必做 (API trigger)	✅ 必做 (cron)
完整生产 + 飞书 push + 多 anchor	✅ 必做	✅ 必做	✅ 必做 + 升 4C8G

最低 MVP = A only. 静态文档对外公开, API 完全本地 Claude Code 跑.

2. Phase 1 · Cloudflare Pages 静态部署 (推荐立即做)

时间: 10-30 min · 成本: $0 · 风险: 0

2.1 · 前置

[x] GitHub repo 公开 (已: zhanglunet/boss-vault)
[x] www/ + docs/internal/ 拆分完成 (2026-05-28): 公网内容在 www/, 内部文档在 docs/internal/
[x] public-safe preflight 通过: python3 scripts/check_public_safe.py 25/25 PASS (硬规则 0 命中)
[ ] Cloudflare 账号 (免费注册)
[ ] (可选) 自定义域名 (例: boss-skills.example.com)

重要: redact_check.py 把 docs/ + www/ 都加 allowlist (允许 methodology placeholder). CF 公网部署需要更严的 preflight — 用 check_public_safe.py 只扫硬规则 (真名 / 内部 URL), 默认扫 www/.

2.2 · 步骤

preflight (必跑):

bash

python3 scripts/check_public_safe.py
# 期望: ✅ check_public_safe PASSED — 25 文件 0 硬规则命中, 公网部署安全

登录 Cloudflare (dash.cloudflare.com) · Workers & Pages 菜单 · Create application · Pages · Connect to Git
授权 GitHub · 选 zhanglunet/boss-vault repo

配置 build:

Project name:        boss-vault          (默认, → boss-vault.pages.dev)
Production branch:   main
Framework preset:    None (静态)
Build command:       (留空)
Build output:        www                 ← 关键 (不是 docs)
Root directory:      /                   (默认)

说明: www/index.html 是 CF Pages 默认首页 (内容 = 原 landing.html marketing 页). docs/internal/ 不在 build path, CF Pages 根本拿不到, 无需 exclude / redirects 拦截.

(已配) www/_redirects 历史兼容: 仅 1 条规则保留对老书签 /landing.html 的兼容
```
/landing.html        /index.html         301
```
第一次 deploy · 点 Save and Deploy · ~ 30s 完成
验证:
- https://boss-vault.pages.dev/ → 对外门户 marketing (= 原 landing 内容)
- https://boss-vault.pages.dev/landing.html → 301 重定向到 /
- https://boss-vault.pages.dev/docs.html → 文档总览
- https://boss-vault.pages.dev/showcase/2026-05-28-anchor-wiki.html → 锚点 Wiki
- https://boss-vault.pages.dev/showcase/2026-05-29-hybrid-deploy.html → Hybrid Deploy SPA
- https://boss-vault.pages.dev/api/openapi.json → API spec JSON
- https://boss-vault.pages.dev/adr/ADR-005-hybrid-deployment.md → ADR-005 markdown (raw)
- https://boss-vault.pages.dev/internal/prd-v3.1.md → 404 (不在 build path)
(可选) 自定义域名 · Custom domains · Add a domain · 填入你的域名 · Cloudflare 自动配 DNS + SSL

2.3 · CI/CD 自动化

push 到 main → Cloudflare Pages GitHub integration 自动 deploy. 无需 GitHub Actions.

每次 deploy 都有独立 URL (例 cf12ab.boss-vault.pages.dev), 可以 preview 后再 promote.

2.4 · 故障排查

现象	根因	修法
Build fail · pip install pydantic-core 卡	CF 探测 `requirements.txt` 自动 pip install · Python 3.13 与 pydantic-core 不兼容	加环境变量 `SKIP_DEPENDENCY_INSTALL=1` (Production + Preview 都加) · 静态站根本不需 pip · build command 设 `echo "static"` 也只能 cover B 阶段, auto-install 在 A 阶段在前
部署成功但访问显示 "Hello world"	创建项目时误进 Workers tab → 创建了 Worker, 默认模板返回 Hello world · 不是 Pages	项目 URL 是 `.workers.dev` 不是 `.pages.dev` 就确认是 Worker · 解绑 custom domain → 删 Worker → 重新创建时顶部 tab 切到 Pages
*`/internal/` 返回 200 + 首页 (非 404)**	CF Pages 默认 "soft 404" — unknown URL fallback 到 `index.html` 200	加 `www/404.html` (CF 自动用作 404) + `www/_redirects` 显式拦 `/internal/` `/docs/internal/` 等 → 强制返回 404
跨目录 link 全 broken (.../README.md 等 404)	vault root / docs/internal/ 文件不在 `www/` build output 里 · 相对路径 `../../X` 在公网解析不到	把所有跨 build output 边界的引用改为 absolute github URL (`https://github.com/.../blob/main/X`) · build output 内部 sibling 引用保留相对
404 on home (`/` 路径)	没有 `www/index.html` 或 `_redirects` 未配	确认 `www/index.html` 存在; 或 `_redirects` 加 `/ /landing.html 302`
国内访问慢	Cloudflare 默认含 China Network 但有限	若仍慢, 启用 Argo Smart Routing (~ $5/月)
Stale content	CF 边缘 cache	dash → Cache → Purge Everything (一键)
新 commit 后 build 没触发	GitHub integration 未授权 / branch 不匹配	Settings → Builds & deployments → 检查 Production branch = `main` · 看最近 webhook delivery 是否 200

关键 "3 个默认坑" 速记 (ADR-005 Phase 1 部署实战痛点):

#	坑	表象	解药
1	auto-install Python deps	build fail	env `SKIP_DEPENDENCY_INSTALL=1`
2	创建默认进 Workers tab	Hello world	显式点 Pages tab
3	200 SPA fallback	`/internal/*` 200 而非 404	`404.html` + `_redirects` 显式拦截

详见复盘 docs/internal/dev-log/2026-05-28_cf-pages-live-deploy.md §3.2-§3.5.

3. Phase 2 · 腾讯云轻量部署 API (按需启动)

时间: 1-2 小时 · 成本: 70-80 元/月 (2C2G 年付) · 风险: 中 (需 SSH 运维)

3.1 · 启动信号

满足任一即启动 (来自 ADR-005 §5.3):

外部 user 明确要求 "我想 curl 你们 API"
内部团队 ≥ 3 人需要 always-on
D3 GitHub Actions schedule 高峰延迟 (实测 > 51 min) 影响 attribution

不满足这些信号 → 不浪费 80 元/月.

3.2 · 购买配置

腾讯云轻量 (访问 cloud.tencent.com/lighthouse):

项	推荐
Region	广州 / 上海 / 北京 (按你团队 IP 最近)
OS	Ubuntu Server 22.04 LTS
Plan	2C2G 40GB SSD · 4Mbps 峰值 · 300GB/月流量
价格	~ 70 元/月 (年付优惠)
续费	至少 1 年 (避免 cron 期间被删)
公网 IP	自带 (固定)
防火墙	仅开 22 + 80 + 443 (默认配置后改)

域名:

选项 A · 你已有域名 → DNS 加 api.your-domain.com A 记录指向 VM 公网 IP
选项 B · 没域名 → 买一个 (.com ~ 10 美元/年)
DNS 用 Cloudflare 管理 (与 Phase 1 同账号)

3.3 · 系统初始化 (SSH 后跑)

bash

# 1. SSH 登入 (用腾讯云控制台 reset root password)
ssh root@&lt;vm-public-ip&gt;

# 2. 创建 boss user (避免用 root 跑服务)
adduser boss
usermod -aG sudo boss
mkdir /home/boss/.ssh
cp ~/.ssh/authorized_keys /home/boss/.ssh/
chown -R boss:boss /home/boss/.ssh
chmod 700 /home/boss/.ssh
chmod 600 /home/boss/.ssh/authorized_keys

# 3. 关 root SSH (用 boss user 后)
nano /etc/ssh/sshd_config
# PermitRootLogin no
# PasswordAuthentication no
systemctl restart sshd

# 4. ufw 防火墙
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

# 5. 装基础工具 (退出 root, 用 boss user)
exit
ssh boss@&lt;vm-public-ip&gt;

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3.11 python3-pip python3-venv git nginx certbot python3-certbot-nginx

3.4 · 部署 boss-vault

bash

# 1. clone repo (公开 repo, 无需 SSH key)
cd ~
git clone https://github.com/zhanglunet/boss-vault.git
cd boss-vault

# 2. 装 Python 依赖
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. 配 .env
cp .env.example .env
nano .env
# 填:
#   ANTHROPIC_API_KEY=sk-ant-...
#   (可选) LARK_APP_ID / LARK_APP_SECRET
chmod 600 .env

# 4. 测一下 server 能起
python3 -m uvicorn scripts.boss_server:app --host 127.0.0.1 --port 8421 &
sleep 3
curl http://localhost:8421/v1/healthz
# 期望: {"status":"ok","timestamp":"..."}
pkill -f uvicorn

3.5 · systemd 服务 (always-on)

bash

# 1. 用 templates 模板
sudo cp templates/boss-hermes.service.example /etc/systemd/system/boss-hermes.service

# 2. 替换占位符
sudo sed -i \
    "s|__VAULT_ROOT__|/home/boss/boss-vault|g; \
     s|__USER__|boss|g" \
    /etc/systemd/system/boss-hermes.service

# 3. (重要) 改 ExecStart 用 venv 的 uvicorn
sudo nano /etc/systemd/system/boss-hermes.service
# 改成:
# ExecStart=/home/boss/boss-vault/.venv/bin/uvicorn scripts.boss_server:app \
#     --host 127.0.0.1 --port 8421 --workers 1 --no-access-log

# 4. enable + start
sudo systemctl daemon-reload
sudo systemctl enable boss-hermes
sudo systemctl start boss-hermes
sudo systemctl status boss-hermes
# 期望: active (running)

# 5. 看 log
journalctl -u boss-hermes -f

3.6 · nginx 反向代理 + SSL

bash

# 1. 用 templates 模板
sudo cp templates/nginx-boss-hermes.conf.example /etc/nginx/sites-available/boss-api

# 2. 替换占位符 (改成你的域名)
sudo sed -i "s|__DOMAIN__|api.your-domain.com|g" /etc/nginx/sites-available/boss-api

# 3. 启用 site
sudo ln -sfn /etc/nginx/sites-available/boss-api /etc/nginx/sites-enabled/
sudo nginx -t                                     # 语法检查
sudo systemctl reload nginx

# 4. 配 DNS (Cloudflare dash)
#    Type: A
#    Name: api
#    Content: &lt;vm-public-ip&gt;
#    Proxy: DNS only (灰云, 不走 Cloudflare proxy)
#    Cloudflare 代理 API 会导致 30s 超时 + 国内访问绕远, 关掉

# 5. 配 SSL (Let's Encrypt 免费, 自动 90 天续)
sudo certbot --nginx -d api.your-domain.com
# 选择: redirect HTTP to HTTPS

# 6. 验证
curl https://api.your-domain.com/v1/healthz
# 期望: {"status":"ok",...}

3.7 · attribution cron (systemd timer)

bash

# 1. 创建 service
sudo tee /etc/systemd/system/boss-attribution.service > /dev/null <<EOF
[Unit]
Description=boss-vault attribution checker (daily)
After=network-online.target

[Service]
Type=oneshot
User=boss
WorkingDirectory=/home/boss/boss-vault
EnvironmentFile=/home/boss/boss-vault/.env
ExecStart=/home/boss/boss-vault/.venv/bin/python3 scripts/attribution_check.py run

[Install]
WantedBy=multi-user.target
EOF

# 2. 创建 timer (每天 09:00 北京时间 = UTC 01:00)
sudo tee /etc/systemd/system/boss-attribution.timer > /dev/null <<EOF
[Unit]
Description=Run boss attribution daily at 09:00 CST

[Timer]
OnCalendar=*-*-* 01:00:00 UTC
Persistent=true

[Install]
WantedBy=timers.target
EOF

# 3. enable + start
sudo systemctl daemon-reload
sudo systemctl enable boss-attribution.timer
sudo systemctl start boss-attribution.timer
sudo systemctl list-timers --all | grep boss
# 期望: 下次触发时间显示

3.8 · 安全 / 监控

bash

# 1. ufw 状态
sudo ufw status verbose

# 2. fail2ban (防 SSH brute force)
sudo apt install fail2ban
sudo systemctl enable fail2ban

# 3. 监控 (最简)
# 看 systemd 日志: journalctl -u boss-hermes -n 100
# 看 nginx 日志: tail -f /var/log/nginx/boss-api.access.log
# 看 attribution: journalctl -u boss-attribution.service

# 4. (可选) 加 Cloudflare Health Check (cloudflare-pages 免费 1 个)
#    URL: https://api.your-domain.com/v1/healthz
#    Frequency: 5 min
#    Alert: email

3.9 · 部署 checklist

项	命令 / 验证
✅ VM SSH	`ssh boss@<vm-ip>`
✅ boss user + ufw	`sudo ufw status`
✅ Python 3.11 + venv	`python3 --version`
✅ repo clone + deps	`cd ~/boss-vault && pip list`
✅ .env + API key	`grep ANTHROPIC_API_KEY .env`
✅ uvicorn local test	`curl http://localhost:8421/v1/healthz`
✅ systemd boss-hermes	`systemctl status boss-hermes`
✅ nginx + SSL	`curl https://api.your-domain.com/v1/healthz`
✅ attribution timer	`systemctl list-timers \| grep boss`
✅ DNS Cloudflare	`dig api.your-domain.com`

全部 ✅ → API 上云成功.

4. 总成本

Phase	资源	价格
Phase 1	Cloudflare Pages (含 China Network)	$0/月
Phase 1 + 自定义域名	.com 域名	~ 10 美元/年 (≈ 6 元/月)
Phase 2 (年付)	腾讯云轻量 2C2G 40GB	~ 70 元/月
Phase 2 + monthly	腾讯云轻量 2C2G 40GB	~ 80-100 元/月
合计 (Phase 1 + 2)		~ 76-110 元/月
对比单 VM 全栈 (4C8G)	阿里云 / AWS	250-500 元/月

省 30-70% 同时性能更好 (国内外 docs 速度比单 VM 快 3-5x).

5. 故障 / 灾难恢复

5.1 · 静态层 (Cloudflare Pages)

页 404 · check docs/_redirects 配置 / build output 路径
deploy 失败 · check GitHub repo 是否 public + Cloudflare GitHub permission
DDoS · Cloudflare 自动防护 (free plan 已含)
重新构建 · dash → Deployments → Retry

5.2 · API 层 (腾讯云)

systemd boss-hermes inactive · journalctl -u boss-hermes -n 200 看 error, 通常是 .env 缺 ANTHROPIC_API_KEY 或 port 占用
nginx 502 · check uvicorn 是否在 127.0.0.1:8421 听 (ss -tlnp)
SSL 过期 · certbot 自动续, 若失败 sudo certbot renew --dry-run 排查
VM 宕机 · 腾讯云控制台 reboot · 数据在 SSD 不丢
VM 彻底丢失 · 拉新 VM + git clone + .env 从 1Password 恢复 + 跑 §3.3-3.7 步骤

5.3 · 数据层 (anchors/raw/, cases/, reports/)

gitignored 不入 git · 唯一 source of truth = VM 磁盘
备份 (重要): rsync -av --exclude '.git' ~/boss-vault/{anchors,cases,reports} backup-server:/backup/boss-vault/$(date +%Y%m%d)/
本地 Mac 同步备份: 每周 rsync 一次到本地

6. 升级路径 (未来)

触发信号	升级动作
API QPS > 5/s	uvicorn `--workers 4` (2C2G 仍够)
API QPS > 20/s	升 4C8G (~ 250 元/月) + 4 workers
多 anchor (≥ 3)	升 4C8G + 加 docker compose
实时通知	加 Lark webhook (templates/nginx 已配 /feishu/event)
国际用户	加 Cloudflare Argo Smart Routing ($5/月) 或多 region VM
数据 ≥ 50 GB	升 80GB 或 100GB plan

7. 相关文档

ADR-003 · deployment 三形态可选
ADR-004 · boss-skills as a product
ADR-005 · 本文档 positioning 决策
docs/deployment.md · 三形态对比 (D1/D2/D3)
docs/api/integration-cookbook.md · 客户端接入示例
templates/boss-hermes.service.example · systemd unit
templates/nginx-boss-hermes.conf.example · nginx config

deployment-hybrid.md · v1 · 2026-05-28 · 见 ADR-005

Hybrid 部署 · Cloudflare Pages + 腾讯云轻量 ​

0. 架构总览 ​

1. 决策框架 · 你需要哪几层? ​

2. Phase 1 · Cloudflare Pages 静态部署 (推荐立即做) ​

2.1 · 前置 ​

2.2 · 步骤 ​

2.3 · CI/CD 自动化 ​

2.4 · 故障排查 ​

3. Phase 2 · 腾讯云轻量部署 API (按需启动) ​

3.1 · 启动信号 ​

3.2 · 购买配置 ​

3.3 · 系统初始化 (SSH 后跑) ​

3.4 · 部署 boss-vault ​

3.5 · systemd 服务 (always-on) ​

3.6 · nginx 反向代理 + SSL ​

3.7 · attribution cron (systemd timer) ​

3.8 · 安全 / 监控 ​

3.9 · 部署 checklist ​

4. 总成本 ​

5. 故障 / 灾难恢复 ​

5.1 · 静态层 (Cloudflare Pages) ​

5.2 · API 层 (腾讯云) ​

5.3 · 数据层 (anchors/raw/, cases/, reports/) ​

6. 升级路径 (未来) ​

7. 相关文档 ​

Hybrid 部署 · Cloudflare Pages + 腾讯云轻量

0. 架构总览

1. 决策框架 · 你需要哪几层?

2. Phase 1 · Cloudflare Pages 静态部署 (推荐立即做)

2.1 · 前置

2.2 · 步骤

2.3 · CI/CD 自动化

2.4 · 故障排查

3. Phase 2 · 腾讯云轻量部署 API (按需启动)

3.1 · 启动信号

3.2 · 购买配置

3.3 · 系统初始化 (SSH 后跑)

3.4 · 部署 boss-vault

3.5 · systemd 服务 (always-on)

3.6 · nginx 反向代理 + SSL

3.7 · attribution cron (systemd timer)

3.8 · 安全 / 监控

3.9 · 部署 checklist

4. 总成本

5. 故障 / 灾难恢复

5.1 · 静态层 (Cloudflare Pages)

5.2 · API 层 (腾讯云)

5.3 · 数据层 (anchors/raw/, cases/, reports/)

6. 升级路径 (未来)

7. 相关文档