mnote/design/natfrp-migration-runbook.md

从 Cloudflare Tunnel 切换到 SakuraFrp（NATFRP）操作指南

本文用于把当前的 Cloudflare Tunnel 替换为 SakuraFrp（NATFRP）HTTP/HTTPS 穿透，并保持域名不变（例如 app.aichem.dpdns.org 等），从而让远程浏览器与客户端都能通过固定域名访问本机服务。

参考文档（官方）：https://doc.natfrp.com/app/http.html

---

0. 你需要先确认的前置条件

1. 你拥有 SakuraFrp 账号，并已开通/购买支持 HTTP/HTTPS 的穿透资源（隧道/节点）。
2. 你能管理 DNS（这里是 *.aichem.dpdns.org），可以新增/修改 CNAME 记录并等待生效。
3. 本机服务在本地能正常访问（端口以你实际为准）：
   • Web 前端：例如 http://127.0.0.1:3000
   • 后端：例如 http://127.0.0.1:8000
   • Supabase（Kong 网关）：例如 http://127.0.0.1:54321
   • ONLYOFFICE（Web）：例如 http://127.0.0.1:8081

注意：NATFRP 的“HTTP/HTTPS 隧道”通常只需要你填 本地地址 + 本地端口 + 域名；外部访问走 NATFRP 节点转发，不要求你在路由器上做端口映射。

---

1. 建议的域名与本地端口映射（按你的项目约定）

请把这些域名继续作为“唯一入口”，不要在客户端里写 127.0.0.1（避免远程客户端失败）：

对外域名	作用	本地服务（示例）
app.aichem.dpdns.org	Web 前端（Next.js）	127.0.0.1:3000
backend.aichem.dpdns.org	FastAPI 后端	127.0.0.1:8000
supabase.aichem.dpdns.org	Supabase Kong	127.0.0.1:54321
onlyoffice.aichem.dpdns.org	ONLYOFFICE（Web）	127.0.0.1:8081

如果你本机端口不是这些值：以你实际运行的端口为准（只要域名保持不变，应用侧无需改动）。

---

2. 关闭 Cloudflare Tunnel（避免“同时生效”导致混乱）

目标：确保 app/backend/supabase/onlyoffice 这几个域名不再回源到 Cloudflare tunnel。

建议顺序：

1. 在 Cloudflare Zero Trust / Tunnel 面板中暂停或删除对应 Public Hostname 规则。
2. 在本机停止 cloudflared（如果你用的是服务方式/计划任务）：
   • Windows 服务：停止对应服务
   • 或命令行启动的：关闭该进程窗口
3. 等待 1～2 分钟，确保 Cloudflare 侧不再回源。

---

3. 在 SakuraFrp 客户端 App 中创建（或导入）HTTP/HTTPS 隧道

3.1 为每个域名创建 1 条隧道

在 SakuraFrp 客户端 App（或其网页管理面板）里分别创建 4 条隧道（建议一个域名一条，便于排障）：

• 类型：HTTP 或 HTTPS（建议优先 HTTPS）
• 本地地址：127.0.0.1
• 本地端口：填你实际端口（参考上表）
• 绑定域名：填对应子域名（例如 app.aichem.dpdns.org）

3.2 HTTPS 证书的两种做法（选其一）

做法 A（推荐）：在 SakuraFrp 的隧道设置里启用/配置 HTTPS（如果支持自动证书或上传证书）。

做法 B：只用 HTTP 隧道，然后在你自己的反代层（例如 VPS 上的 Caddy/Nginx）终止 TLS，再转发到 NATFRP 的 HTTP 外网域名。

你当前使用的是 https://app.aichem.dpdns.org，因此最终必须能提供 HTTPS（要么由 NATFRP 提供，要么由你自己的反代层提供）。

---

4. 修改 DNS：把域名解析指向 SakuraFrp

核心思路：让 app.aichem.dpdns.org 等域名，解析到 NATFRP 提供的“外网域名/入口”。

常见做法（按 NATFRP 面板给出的信息填写）：

• 为 app.aichem.dpdns.org 设置 CNAME → NATFRP 给该隧道分配的外网域名
• 为 backend.aichem.dpdns.org 设置 CNAME → 对应隧道外网域名
• 为 supabase.aichem.dpdns.org 设置 CNAME → 对应隧道外网域名
• 为 onlyoffice.aichem.dpdns.org 设置 CNAME → 对应隧道外网域名

建议：

• TTL 先设短一些（例如 60/120 秒）便于切换与回滚
• 修改后等待解析生效（可用 nslookup 或在线 DNS 工具验证）

---

5. 启动隧道并启动本机服务

1. 启动 SakuraFrp 客户端 App，确保 4 条隧道状态为“已连接/运行中”。
2. 启动本机服务：
   • 前端（Next.js）：监听 127.0.0.1:3000（或你的端口）
   • 后端（FastAPI）：监听 127.0.0.1:8000
   • Supabase：确保 Kong 网关在 127.0.0.1:54321
   • ONLYOFFICE：确保可通过 http://127.0.0.1:8081 打开

建议先确保“本机直连正常”，再用外网域名验证；不要一上来就只看外网，排障会非常痛苦。

---

6. 外网验证清单（强烈建议逐项验证）

下面命令建议在“非本机网络”（例如手机热点）执行，避免被 hosts/缓存误导：

curl -I https://app.aichem.dpdns.org/
curl -I https://app.aichem.dpdns.org/_next/static/chunks/  # 这里应当返回 200/403，而不是 404

curl -I https://backend.aichem.dpdns.org/health            # 以你后端真实 health 路由为准
curl -I https://supabase.aichem.dpdns.org/auth/v1/health   # Supabase GoTrue 健康检查

curl -I https://onlyoffice.aichem.dpdns.org/web-apps/apps/api/documents/api.js

如果 /_next/static/... 404，通常说明：

• 前端没跑起来；或
• 回源不是你预期的服务；或
• 你用的是 Next.js standalone，但 .next/static 没放到 server 期望位置。

---

7. 应用侧通常不需要改（但你应当检查这 3 件事）

在本项目的预期做法里，“域名是契约”，穿透只是把契约指到不同回源：

1. wolai-frontend/public/mnote-env.json 中的域名配置仍然使用：
   • supabaseUrl = https://supabase.aichem.dpdns.org
   • backendUrl = https://backend.aichem.dpdns.org
   • onlyofficeBaseUrlWeb = https://onlyoffice.aichem.dpdns.org
   • onlyofficeBaseUrlDesktop = http://127.0.0.1:<本地onlyoffice端口>（桌面端走本地）
2. 确保桌面端（Electron）不要再写死 127.0.0.1 作为“登录域名”，否则远程客户端必然失败。
3. Supabase 若涉及 OAuth 回调/邮件链接，域名变更会影响 redirect；但你这里“域名不变”，所以理论上不需要改 Supabase 配置。

---

8. 常见坑与处理建议

1. WebSocket：Supabase realtime、ONLYOFFICE 都可能用到 WebSocket；如果某条隧道出现“能打开页面但实时断开”，优先检查 NATFRP 节点/隧道是否支持 WebSocket。
2. 超时/大文件：ONLYOFFICE 打开大文档/图片时可能超时；可在 NATFRP/反代层上调大超时、允许更大 body。
3. 缓存污染：切换通道后浏览器可能缓存旧回源；建议强刷或无痕窗口验证。
4. DNS 未生效：nslookup app.aichem.dpdns.org 看到的目标仍是旧值时，先别排应用，先把 DNS 跑通。

---

9. 回滚方案（出问题快速恢复）

1. 把 DNS CNAME 改回 Cloudflare Tunnel 的目标（或恢复 Cloudflare 的 Public Hostname 规则）。
2. 停掉 SakuraFrp 对应隧道（避免双通道造成回源混乱）。
3. 验证 https://app.aichem.dpdns.org 能回到 Cloudflare 路径。