mnote/design/cloudflare-path-a-runbook.md

路径 A 实施手册：Cloudflare 入口 + 本地/自建服务器跑完整后端

目标：用户访问你的域名（Cloudflare，当前为 aichem.dpdns.org），请求通过 Cloudflare Tunnel 回源到你自建服务器（或家里电脑）上的 Next.js（wolai-frontend）与 Supabase/LightRAG/MinerU 等服务。

1. 推荐拓扑（最接近你当前代码形态）

• app.aichem.dpdns.org → wolai-frontend（Next 3000：页面 + /api/*）
• supabase.aichem.dpdns.org → Supabase Kong（示例 18000）
• backend.aichem.dpdns.org → wolai-backend（示例 8000，可选）
• lightrag.aichem.dpdns.org → LightRAG（示例 7777，建议加 Access）
• mineru.aichem.dpdns.org → MinerU（示例 18888，建议加 Access）

用子域名的原因：Supabase JS 在浏览器端需要一个“稳定的 base URL”。把 Supabase 放在 path（例如 /supabase）会牵涉 WebSocket/重写/多服务路径复杂度，不建议前期这样做。

2. Cloudflare Tunnel 配置

仓库提供了示例文件（已按 aichem.dpdns.org 预填 hostname，可直接改端口/删减服务）：

• scripts/cloudflared/config.yml.example
• scripts/cloudflared/docker-compose.cloudflared.example.yml

你需要做的事：

1. Cloudflare 控制台创建 Tunnel
2. 下载 credentials.json
3. 替换 config.yml 里的 tunnel 与 credentials-file
4. 绑定 DNS：为每个 hostname 绑定到该 tunnel
5. 在服务器上运行 cloudflared（Windows 可直接运行；Linux 可用 docker compose）

3. 环境变量（关键：区分“浏览器访问地址”和“服务端内网地址”）

在路径 A 下，浏览器端必须访问 Cloudflare 域名；但 Next 服务端访问 Supabase/Backend 建议走内网地址（更快、更稳定，不绕 Cloudflare）。

3.1 wolai-frontend

浏览器端（公开）：

• NEXT_PUBLIC_SUPABASE_URL=https://supabase.aichem.dpdns.org
• NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon key>
• NEXT_PUBLIC_BACKEND_URL=https://backend.aichem.dpdns.org（可选）

服务端内网（仅 Next 服务器用，不暴露给浏览器）：

• SUPABASE_INTERNAL_URL=http://127.0.0.1:18000
• SUPABASE_ANON_KEY=<同一个 anon key>
• BACKEND_URL=http://127.0.0.1:8000（可选）

推荐用 wolai-frontend/.env.production.local 来承载生产配置；仓库提供了模板：

• wolai-frontend/.env.production.example

已做代码支持：wolai-frontend/src/lib/supabase/server.ts 会优先用 SUPABASE_INTERNAL_URL；wolai-frontend/src/app/api/media/ocr/route.ts 会优先用 BACKEND_URL。

3.2 ingest_service / rag_gateway

你现在的 services/ingest_service/app/core/config.py 已优先读取仓库根目录 .env.local/.env。 因此只要在根目录 .env.local 正确配置：

• SUPABASE_URL=http://127.0.0.1:18000
• SUPABASE_SERVICE_ROLE_KEY=...
• LIGHTRAG_URL=http://127.0.0.1:7777
• MINERU_ENDPOINT=http://127.0.0.1:18888

即可。

4. 安全建议（路径 A 很重要）

• lightrag.<域名>、mineru.<域名>：建议用 Cloudflare Access 或至少 IP 白名单，否则等同于把内部能力直接暴露到公网。
• supabase.<域名>：若暴露到公网，务必确认 RLS 与 Auth 配置正确；不要泄露 service_role key。