# Cloudflare 部署评估与操作指南 (2026-06-11 · v0.5.0)

> 回答 "能不能部署到 Cloudflare?" — **能, 而且一部分已经在上面跑了。**
> 但不同组件答案不同: 静态门户 ✅ 已在 Pages · API 公网暴露 ✅ 推荐 Tunnel ·
> 后端全栈搬 Workers/Containers ❌ 现阶段不推荐 (详见 §3)。
> 配套: 服务器必要性验证与阿里云方案见 [`cloud-server-deployment.md`](./cloud-server-deployment.md);
> 通用 Linux 细则见 [`production-runbook.md`](./production-runbook.md)。

## §0 结论速览

| 组件 | 能上 Cloudflare 吗 | 形态 | 状态 |
|---|---|---|---|
| 门户/落地页/live.html 快照 | ✅ | **Pages** (main 推送自动部署) | **已在线** (现行流程) |
| FastAPI live API 公网暴露 | ✅ | **Tunnel** (cloudflared, 替代 caddy) | 推荐, 可选项 |
| API 鉴权加固 | ✅ | **Access** (SSO/OTP, ≤50 用户免费) | 可选叠加 |
| FastAPI + SQLite 后端本体 | ❌ | Workers (Python beta) / Containers (GA) | 不推荐, 见 §3 |
| cron 作业 (5 标准 job) | ❌ | Workers Cron Triggers | 留服务器 crontab |
| X 抓取 (twikit) | ❌ | — | 必须 operator 本机 (风控) |

**一句话**: 维持 "Cloudflare Pages 静态快照 (主入口) + Linux 自托管后端" 的现行架构,
增量上 **Cloudflare Tunnel** 替代反向代理拿免费 HTTPS + 零开端口; 不做全栈搬迁。

## §1 已在 Cloudflare 上的部分 (Pages, 现行)

仓库 main 分支已接 Cloudflare Pages 自动部署: 门户 36 页 (index/plan/docs/落地页 I·II/
live.html 等) + `agent/docs/sample/*.json` 静态快照。每次合入 main 自动发布。

- live.html 在 `*.pages.dev` 域名下自动进 **snapshot demo 模式** (fetch 静态 JSON,
  不打 REST), 顶部 banner 标注; 想看实时数据在 API 框填自托管端点切回 live。
- **数据每日自动刷新 (续 32 上线)**: GitHub Actions `data-refresh.yml` 每日
  UTC 22:45 (北京 06:45) 跑 `agent/scripts/refresh_live_data.py` — RSS 实抓
  (SpaceNews) → 追加 `agent/data-live/events-archive.jsonl` 纯文本归档
  (url+occurred_at 去重, DB 每次确定性重建不存二进制) → 重生成
  `docs/sample/*.json` 快照 → 提交 main (`[skip ci]`) → Pages 自动部署。
  **不需要任何服务器, 公网仪表盘即此自动保持日更**。LLM 不参与 (规则口径);
  X 信号不在此链路 (x.sqlite3 在 operator 本机, runbook §8)。
- `_headers` / `_redirects` 已在仓库根, Pages 直接识别。

**这已经覆盖了产品主入口形态** (飞书周报推送 + 静态快照仪表盘, 见 runbook 开头),
即: 对首批用户而言, "部署到 Cloudflare" 的核心部分已完成。

## §2 推荐增量: Cloudflare Tunnel 暴露 live API (替代 caddy)

runbook §4 的可选公网 live 模式原方案是 caddy 反代。**Tunnel 是更优替代**:
cloudflared 守护进程从服务器向 Cloudflare 建 4 条 **纯出站** 连接, 不开任何入站端口,
源站 IP 不暴露, HTTPS 证书由 Cloudflare 边缘签发, 免费。

```bash
# 服务器上 (Debian/Ubuntu; 其余发行版见官方 docs)
curl -L https://pkg.cloudflare.com/cloudflared/install.sh | sudo bash   # 或手动装包
cloudflared tunnel login                       # 浏览器授权, 选托管在 CF 的域名
cloudflared tunnel create satagent-api
cloudflared tunnel route dns satagent-api api.你的域名

# /etc/cloudflared/config.yml
# tunnel: <tunnel-id>
# credentials-file: /root/.cloudflared/<tunnel-id>.json
# ingress:
#   - hostname: api.你的域名
#     service: http://127.0.0.1:8000      # satagent-api systemd 只监听本机, 正好
#   - service: http_status:404

sudo cloudflared service install && sudo systemctl enable --now cloudflared
curl -s https://api.你的域名/health        # {"status":"ok","version":"0.5.0"}
```

与现有安全模型的叠加关系:
- `SATAGENT_ENV=production` 强制 Bearer token 不变 (Tunnel 只解决传输层);
- 可再叠加 **Cloudflare Access** (Zero Trust): 在 tunnel 前加 email OTP / Google/GitHub
  SSO 门, ≤50 用户免费 — 对 "首批内部用户" 规模刚好;
- live.html 的 CORS: `.env` 里 `SATAGENT_CORS_ORIGINS=https://你的pages域名` 即可。

## §3 为什么不推荐全栈搬 Workers / Containers (2026-06 口径)

调研结论 (官方文档/changelog, 2026-06-11 复核):

**Python Workers (开放测试期)**: FastAPI 本身可跑 (ASGI 适配官方支持, 含 snapshot
冷启动优化), 但对本项目有三个硬伤:
1. **SQLite 文件无持久化** — Workers 无持久文件系统, 必须重写 db 层到 D1。本项目
   db.py/repository.py 是手写 SQL + 文件路径语义 (`SATAGENT_DB`), 迁移 = 大改造;
2. **litellm 不在支持包列表** — LLM 兜底层要改直连 HTTP (zhipu OpenAI 兼容端点
   可以裸 httpx 调, 但要放弃 5-provider 统一路由);
3. **beta 定位** — 给真实用户的生产服务压在 beta 运行时上, 与 "上线" 目标冲突。

**Containers (2026-04 GA)**: 能直接跑现有 Docker 镜像 ($5/月 Workers Paid 起,
按活跃 10ms 计费), 但:
1. **磁盘 ephemeral** — 实例休眠/重建即丢; 官方建议 FUSE 挂 R2 持久化, 而
   SQLite on 网络文件系统是公认的损坏高发组合 (WAL 锁语义不保证), 不可接受;
2. **不保证实例存活时长** — monthly-validate 全量 +LLM 一跑 ~45min, 与
   "不承诺任何实例运行任意时长" 的生命周期模型冲突;
3. cron 调度要从 Worker 代码触发, 5 个标准 job 的 run_job.sh/退出码语义全要重做。

**何时重新评估**: Tier 2 迁 Postgres 之后 (PRODUCT-STRATEGY §6), 数据层不再绑
SQLite 文件, Containers + 外部托管 Postgres (如 Hyperdrive 接 Neon/Supabase)
才成为合理选项; 届时 X 抓取仍留 operator 本机不变。

## §4 参考来源 (2026-06-11 检索)

- Python Workers 总览/beta 状态: developers.cloudflare.com/workers/languages/python/
- FastAPI on Python Workers: developers.cloudflare.com/workers/languages/python/packages/fastapi/
- Python Workers 冷启动优化 (2026-01): blog.cloudflare.com/python-workers-advancements/
- Containers GA 公告 (2026-04-13): developers.cloudflare.com/changelog/post/2026-04-13-containers-sandbox-ga/
- Containers 架构/生命周期 (ephemeral 磁盘, FUSE→R2): developers.cloudflare.com/containers/platform-details/architecture/
- Containers 计费: developers.cloudflare.com/containers/pricing/
- Tunnel: developers.cloudflare.com/tunnel/ · Access 自托管应用: developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/