# 从 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/缓存误导：

```bash
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 路径。