docs: clarify RPC/Cloudflare tunnels are local-only

2026-10-23 10:45:30 +08:00
parent 1ae25f1597
commit a161a0eee9
7 changed files with 175 additions and 24 deletions
@@ -53,6 +53,17 @@ Email (inbox 2) / WhatsApp (inbox 3)

 ---

+## 2.1 环境差异（本地开发 vs 测试/生产）
+
+> 详见 [environments.md](environments.md)。
+
+- `scripts/rpc-tunnel.sh`：**仅本地开发**，因为 RPC 端口外网不可达
+- `scripts/public-https.sh`：**仅本地联调**，Cloudflare Quick Tunnel
+- 测试/生产：RPC 直接配内网地址，公网 HTTPS 用正式域名 + Ingress/Nginx/ALB
+- 测试/生产不应运行上述两个脚本
+
+---
+
 ## 3. 访问入口

 | 服务 | 地址 | 备注 |
@@ -97,13 +108,13 @@ Email (inbox 2) / WhatsApp (inbox 3)

 - [ ] `.env` 已备份，且权限为 `600`
 - [ ] `docker compose config -q` 通过
- [ ] RPC 隧道可用（商品/订单/库存）
+- [ ] 本地开发：RPC 隧道可用；测试/生产：RPC 内网地址可直达
 - [ ] LibreDesk webhook `Bridge AI` 为启用状态
 - [ ] LibreDesk 规则 1 关闭
 - [ ] 规则 4/5 指向 `Wholesale Support`
 - [ ] agent1/agent2 可登录，必要时设为在线
 - [ ] WhatsApp access token 未过期（当前 token 有到期时间）
- [ ] 公网 URL 与 Meta webhook 已同步
+- [ ] 本地开发：Quick Tunnel 与 Meta webhook 已同步；测试/生产：正式域名与 Meta webhook 已同步
 - [ ] 163 SMTP / IMAP 可用
 - [ ] 已做数据库备份
 - [ ] bridge 测试通过
@@ -162,9 +173,11 @@ bash scripts/rebuild-kb-index.sh
 node scripts/upgrade-kb-schema.js
 ```

-### 6.4 RPC 隧道
+### 6.4 RPC 隧道（仅本地开发）

-商品/订单/库存依赖本机到内网的 RPC 隧道：
+> 测试/生产不需要这一步；直接配置内网 RPC 地址即可。
+
+本地 RPC 端口外网不可达时才需要：

 ```bash
 bash scripts/rpc-tunnel.sh
@@ -172,7 +185,11 @@ bash scripts/rpc-tunnel.sh

 隧道断了会导致 `search_products/search_orders/search_inventory` 失败。

-### 6.5 公网 HTTPS / WhatsApp webhook
+### 6.5 公网 HTTPS / WhatsApp webhook（仅本地联调）
+
+> 测试/生产不要用 Cloudflare Quick Tunnel；使用正式域名 + Ingress/Nginx/ALB + TLS。
+
+本地联调：

 ```bash
 bash scripts/public-https.sh
@@ -308,10 +325,10 @@ bridge 关键日志：

 ### 外部依赖巡检

- RPC 隧道进程
+- 本地开发：RPC 隧道进程
+- 本地开发：Cloudflare tunnel 状态
+- 测试/生产：内网 RPC 可达性、Ingress/证书、WhatsApp token 剩余有效期
 - 163 SMTP/IMAP
- WhatsApp token 剩余有效期
- Cloudflare tunnel 状态
 - 未分配/团队队列积压

 ---
@@ -386,8 +403,8 @@ docker compose stop bridge
 ### 高

 1. **单点**：bridge 只有一个实例；bridge 挂了 Live chat 无 AI 回复。
-2. **RPC 隧道**：依赖本机 SSH 隧道，断了商品/订单/库存工具不可用。
-3. **公网 URL**：Cloudflare Quick Tunnel URL 不固定，重启可能失效。
+2. **RPC 隧道（仅本地开发）**：依赖本机 SSH 隧道，断了商品/订单/库存工具不可用。测试/生产应直连内网 RPC。
+3. **公网 URL（仅本地开发）**：Cloudflare Quick Tunnel URL 不固定，重启可能失效。测试/生产使用正式域名。
 4. **WhatsApp token**：临时 token 有到期时间，需要提前续期。
 5. **Email 历史数据为空**：`kb_mail_docs` 只有测试邮件，真实客户历史未 ingest。

@@ -453,8 +470,8 @@ TWENTY_BASE_URL / TWENTY_API_KEY

 ```
 scripts/bootstrap.sh
-scripts/rpc-tunnel.sh
-scripts/public-https.sh
+scripts/rpc-tunnel.sh        # 仅本地开发
+scripts/public-https.sh      # 仅本地联调
 scripts/build-site-map.js
 scripts/rebuild-kb-index.sh
 scripts/e2e-widget-jwt.js