docs: clarify RPC/Cloudflare tunnels are local-only

README.md

@@ -22,7 +22,7 @@
 | Twenty Workspace | ✅ 已创建（admin@yehwang.com，workspace 已 ACTIVE） |
 | Twenty API Key | ✅ 已在库内生成并写入 `.env`，GraphQL 验证通过 |
 | 商机写入 | ✅ `create_opportunity` 实测创建 company/person/opportunity/note/task |
-| 业务 RPC | ✅ 测试服 24503/24505/24506/24509 外网被封，已用 SSH 隧道（`scripts/rpc-tunnel.sh`） |
+| 业务 RPC | ✅ 本地开发用 SSH 隧道（`scripts/rpc-tunnel.sh`）；测试/生产应直连内网 RPC，不需要隧道 |
 | 邮件通知（OTP） | ✅ 163 SMTP 已配置，实测验证码邮件已送达 163 收件箱 |
 | Email 渠道 | ✅ 163 收件（imap-proxy 绕过 Unsafe Login）+ AI 回复邮件（模板）已实测 |
 | IMAP 代理 | ✅ `services/imap-id-proxy`（LibreDesk 不发 IMAP ID，163 会拒绝 SELECT） |
@@ -80,15 +80,17 @@ crm-new/
 │   ├── configure-email.js     # 配置 163 SMTP（通知/OTP 邮件）
 │   ├── add-email-inbox.js     # 配置 Email Inbox + 默认外发模板 + Automation
 │   ├── e2e-widget-jwt.js      # 端到端验证 widget JWT + 订单工具
-│   ├── rpc-tunnel.sh          # 测试服 JSON-RPC 端口 SSH 隧道（bridge 依赖）
+│   ├── rpc-tunnel.sh          # 仅本地开发：测试服 RPC 端口 SSH 隧道
-│   ├── public-https.sh        # Cloudflare Tunnel 公网 HTTPS + 白名单网关
+│   ├── public-https.sh        # 仅本地联调：Cloudflare Quick Tunnel + 白名单网关
 │   ├── set-public-url.js      # 更新 LibreDesk app.root_url
 │   ├── import-kb-helpcenter.js  # 旧 KB -> 帮助中心文章（幂等）
 │   ├── verify-rag.js         # 临时助手 + preview，验证检索/引用
-│   └── smoke.sh
+│   ├── smoke.sh
+│   └── serve-web.sh           # 仅本地预览 demo 页面
 ├── web/                      # 站点接入：ai-snippet.js + demo.html（widget JWT 演示）
-├── docs/                     # 架构、LibreDesk 配置、接口对照、迁移说明、运维手册
+├── docs/                     # 架构、LibreDesk 配置、环境差异、上线/运维手册
 │   ├── go-live.md            # 上线文档（范围/切流/验收/监控/回滚）
+│   ├── environments.md       # 本地开发 vs 测试/生产：RPC/Cloudflare 隧道差异
 │   ├── human-routing.md      # Email/WhatsApp 人工团队分配
 │   └── plan-a.md             # 方案 A：bridge 接管 AI 编排进度
 └── deploy/nginx.conf.example
@@ -107,6 +109,8 @@ bash scripts/bootstrap.sh
 bash scripts/smoke.sh
 ```
 
+> `scripts/rpc-tunnel.sh`、`scripts/public-https.sh`、`scripts/serve-web.sh` 仅本地开发/联调使用；测试/生产环境不需要，见 [docs/environments.md](docs/environments.md)。
+
 启动完成后：
 
 1. **LibreDesk**（`System`，密码见 `.env` 的 `LIBREDESK_SYSTEM_USER_PASSWORD`）
@@ -184,6 +188,8 @@ bash scripts/serve-web.sh          # http://localhost:8088/demo.html
 
 ## 运维
 
+环境差异见 [docs/environments.md](docs/environments.md)（RPC 隧道/Cloudflare 隧道仅本地开发用）。
+
 上线清单见 [docs/go-live.md](docs/go-live.md)，常用命令见 [docs/runbook.md](docs/runbook.md)（启动/停止/日志/备份/升级/回滚/排错）。
 
 ## 测试

docs/environments.md

@@ -0,0 +1,124 @@
+# 环境差异：本地开发 / 测试 / 生产
+
+> 结论：`rpc-tunnel.sh` 和 `public-https.sh` 是**本地开发联调工具**，测试/生产环境不应依赖它们。
+
+## 1. 对比表
+
+| 能力 | 本地开发（当前机器） | 测试 / 生产 |
+|---|---|---|
+| 业务 RPC | 用 SSH 隧道 `scripts/rpc-tunnel.sh`，因为 RPC 端口外网不可达 | **不需要隧道**，直接填内网 RPC 地址（服务 DNS / VPC / 专线） |
+| RPC 地址 | `jsonrpc://<tunnel-gateway>:24503` 等隧道网关地址 | `jsonrpc://<rpc-host>:24503` 等真实内网地址 |
+| 公网 HTTPS | Cloudflare Quick Tunnel + `scripts/public-https.sh` | **不需要 Quick Tunnel**，用正式域名 + Ingress/Nginx/ALB + TLS |
+| WhatsApp webhook | 临时 Quick Tunnel URL，重启会变 | 正式域名，例如 `https://crm.example.com/webhooks/whatsapp/...` |
+| 公网路径白名单 | `public-gateway`（本地 compose 服务） | 由 Ingress/Nginx 统一处理，或保留 gateway 作为内部服务 |
+| Demo 页面 | `scripts/serve-web.sh`，:8088 | 不需要 |
+| 数据库/Redis | compose 内 Postgres/Redis，宿主机端口仅绑 `127.0.0.1` | 使用托管数据库/Redis 或内网集群，不暴露宿主机端口 |
+| 环境变量 | `.env` 指向本地/测试地址 | `.env` 指向测试/生产真实地址 |
+| 密钥 | 本地 `.env` | Secret Manager / CI/CD Secret，不入库 |
+
+## 2. RPC：本地隧道 vs 测试/生产直连
+
+### 本地开发
+
+RPC 端口外网不可达时，才需要：
+
+```bash
+bash scripts/rpc-tunnel.sh --apply
+```
+
+它会：
+
+- 在本机建 SSH 隧道到远端 RPC
+- 把 `.env` 的 RPC URL 改为隧道网关地址
+- 重建 bridge
+
+### 测试 / 生产
+
+**不要运行 `rpc-tunnel.sh`。**
+
+直接配置：
+
+```env
+RECOMMEND_URL=jsonrpc://<recommend-service>:24503
+ORDER_API_URL=jsonrpc://<order-service>:24505
+MEMBER_RPC_URL=jsonrpc://<member-service>:24506
+INVENTORY_API_URL=jsonrpc://<inventory-service>:24509
+```
+
+要求：
+
+- bridge 容器能直接访问这些地址
+- 测试/生产网络放行对应端口
+- 不要指向开发机的 SSH 隧道网关
+
+如果测试/生产网络确实隔离，应该用 **VPC 对等连接 / 专线 / VPN / 内网反向代理**，而不是开发机上的 SSH 隧道。
+
+## 3. 公网 HTTPS：Quick Tunnel vs 正式域名
+
+### 本地开发
+
+只有本地联调 WhatsApp/公网 webhook 时才需要：
+
+```bash
+bash scripts/public-https.sh
+```
+
+特点：
+
+- Cloudflare Quick Tunnel
+- URL 每次重启可能变化
+- 需要重新更新 LibreDesk `root_url` 和 Meta webhook
+- 只适合临时联调
+
+### 测试 / 生产
+
+**不要使用 Cloudflare Quick Tunnel。**
+
+使用：
+
+- 正式域名（`crm.example.com`）
+- Ingress / Nginx / ALB / API Gateway
+- 正式 TLS 证书
+- 固定公网出口
+
+配置：
+
+```env
+PUBLIC_BASE_URL=https://crm.example.com
+```
+
+并同步：
+
+- LibreDesk `app.root_url`
+- Meta WhatsApp callback URL
+- `public-gateway` 的上游地址（如果保留）
+
+### public-gateway 的去留
+
+`services/public-gateway` 只负责路径白名单：
+
+```
+/webhooks/whatsapp/
+/hc/
+/widget*
+/static/public/
+```
+
+测试/生产可以：
+
+- 继续保留它，放在 Ingress 后面
+- 或者把同样的路径规则直接写进 Ingress/Nginx
+
+Quick Tunnel 只是本地把请求转发进来的手段，不是生产架构的一部分。
+
+## 4. 测试/生产上线检查
+
+- [ ] 未运行 `rpc-tunnel.sh`
+- [ ] RPC URL 指向内网真实地址，不是 `172.23.0.1`
+- [ ] 未运行 `public-https.sh`
+- [ ] `PUBLIC_BASE_URL` 是正式 HTTPS 域名
+- [ ] LibreDesk `root_url` 是正式域名
+- [ ] Meta webhook 是正式域名
+- [ ] 数据库/Redis 不暴露公网
+- [ ] 不使用 `serve-web.sh` 的 8088 demo
+- [ ] 密钥来自 Secret Manager / CI Secret，不在仓库和镜像里

docs/go-live.md

@@ -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 隧道，断了商品/订单/库存工具不可用。
+2. **RPC 隧道（仅本地开发）**：依赖本机 SSH 隧道，断了商品/订单/库存工具不可用。测试/生产应直连内网 RPC。
-3. **公网 URL**：Cloudflare Quick Tunnel URL 不固定，重启可能失效。
+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/rpc-tunnel.sh        # 仅本地开发
-scripts/public-https.sh
+scripts/public-https.sh      # 仅本地联调
 scripts/build-site-map.js
 scripts/rebuild-kb-index.sh
 scripts/e2e-widget-jwt.js

docs/runbook.md

@@ -77,10 +77,12 @@ node scripts/eval-offline.js
 # 真实模型离线评测（fake LibreDesk，不写真实会话；会调 LLM/RPC）
 node scripts/eval-live.js
 
-# 公网 HTTPS（WhatsApp webhook 需要）：Cloudflare Quick Tunnel + 路径白名单网关
+# 公网 HTTPS（仅本地联调需要）：Cloudflare Quick Tunnel + 路径白名单网关
+# 测试/生产：不要跑这个脚本，使用正式域名 + Ingress/Nginx + TLS
 bash scripts/public-https.sh
 
-# 测试服 RPC 端口外网被封：建 SSH 隧道并让 bridge 指向隧道（网关 IP）
+# 仅本地开发：测试服 RPC 端口外网被封时建 SSH 隧道
+# 测试/生产：不要跑这个脚本，直接把 RPC URL 配成内网可达地址
 bash scripts/rpc-tunnel.sh --apply
 
 # 配置 163 SMTP（自动重启 LibreDesk）
@@ -168,6 +170,6 @@ ss -ltnp | grep -E ':(9000|3100|4100|5440|6390)\s'
 | 管理员后台实时更新不工作 | 通过 http + IP 访问时 agent websocket 拒绝非 HTTPS 来源 | POC 可忽略；生产用 HTTPS 或经 localhost 访问 |
 | collect_info 槽位丢失 | Redis 不可用，退回了进程内存 | 检查 `REDIS_URL=redis://redis:6379/3` 和 `docker logs crmnew-bridge` 的 lead store 告警 |
 | 多站点商品推荐串站 | `bridge/config/sites.json` 的 inbox 映射没配 | 把对应 inbox 数字 ID 指到 us/eu/www profile，重建 bridge |
-| WhatsApp webhook 收不到 | 没有公网 HTTPS / Meta 回调地址不对 | 跑 `bash scripts/public-https.sh`，把输出的 `.../webhooks/whatsapp/<inbox_id>` 配到 Meta；quick tunnel URL 每次重启会变 |
+| WhatsApp webhook 收不到 | 没有公网 HTTPS / Meta 回调地址不对 | 本地联调跑 `bash scripts/public-https.sh`；测试/生产使用正式域名，不要用 Quick Tunnel |
 | 公网访问到管理后台 | 网关白名单配置 | `services/public-gateway` 只放行 `/webhooks/whatsapp/*`、`/hc/*`、`/widget*`、`/static/public/*`，其余 404 |
-| AI 回复"系统暂时无法查询订单" | 测试服 24503/24505/24506/24509 外网 TCP 被封，bridge 8s 超时 | 跑 `bash scripts/rpc-tunnel.sh --apply`，bridge RPC 指向 docker 网关（隧道只绑网关，不暴露 LAN） |
+| AI 回复"系统暂时无法查询订单" | RPC 不可达，bridge 8s 超时 | 本地开发跑 `bash scripts/rpc-tunnel.sh --apply`；测试/生产检查内网 RPC 地址/网络策略，不要用开发机隧道 |

scripts/public-https.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# 启动/重启公网 HTTPS（Cloudflare Quick Tunnel），并把 LibreDesk root_url 指过去。
+# 仅本地联调：启动/重启公网 HTTPS（Cloudflare Quick Tunnel），并把 LibreDesk root_url 指过去。
+# 测试/生产不要用 Quick Tunnel：使用正式域名 + Ingress/Nginx/ALB + TLS。
 # 注意：quick tunnel 每次重启 URL 会变，需要重新跑本脚本（Meta 里的 webhook 也要同步改）。
 set -euo pipefail
 cd "$(dirname "${BASH_SOURCE[0]}")/.."

scripts/rpc-tunnel.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# 测试服 JSON-RPC 端口外网被封：在本机建 SSH 隧道，供 crm-new 的 bridge 访问。
+# 仅本地开发：测试服 JSON-RPC 端口外网被封时，在本机建 SSH 隧道。
+# 测试/生产不需要此隧道：把 RPC URL 直接配成内网可达地址。
 #
 # 默认只启动隧道并打印 .env 需要的 4 行配置；
 # 加 --apply 会自动更新 .env 里的 RPC URL 并重建 bridge。

scripts/serve-web.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# 本地静态测试页（widget JWT 演示）
+# 仅本地预览：静态测试页（widget JWT 演示）；测试/生产不需要
 set -euo pipefail
 cd "$(dirname "${BASH_SOURCE[0]}")/../web"
 echo "http://localhost:${WEB_PORT:-8088}/demo.html"