crm-ai/docs/environments.md

环境差异：本地开发 / 测试 / 生产

结论：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 scripts/rpc-tunnel.sh --apply

它会：

• 在本机建 SSH 隧道到远端 RPC
• 把 .env 的 RPC URL 改为隧道网关地址
• 重建 bridge

测试 / 生产

不要运行 rpc-tunnel.sh。

直接配置：

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 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 证书
• 固定公网出口

配置：

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，不在仓库和镜像里