온프레미스 배포 가이드

1. 交付边界（合同口径）

通语云托管仅作官方演示，不作为客户正式交付默认形态。

2. 架构（最小可交付）

用户 / App
   │ HTTPS
   ▼
Nginx（仅反代 api 域名 → 127.0.0.1:5000，开 WebSocket）
   │
   ▼
Nest API :5000（控制面 + 门面）
   ├── /api/auth、billing… → Nest
   └── /api/im、客服、/ws/*、/uploads → Go Gateway :5100
        ├── MySQL 8（与 Nest 同一库）
        └── 本地 uploads 或租户 OSS

通话媒体：通语 IM 自带音视频（可选 TURN / SFU 提升跨网与大群）

单机推荐：一台机器跑 Nest + Go Gateway + 静态前端 + MySQL； 防火墙只开 80/443，勿对公网开 5000/5100。 客户实例不要配置 IM_LICENSE_PRIVATE_KEY（签发私钥只留在通语侧）。

3. 环境要求

可选：Docker 仅起数据库；Redis 仅多机 / 多进程时再配。

4. 安装步骤（客户机）

4.0 Docker 一键 API（推荐）

cp deploy/env.onprem.example deploy/.env.onprem
# 编辑 JWT_SECRET / PUBLIC_BASE_URL / CORS_ORIGINS / IM_ICE_SERVERS …

docker compose -f deploy/docker-compose.onprem.yml --env-file deploy/.env.onprem up -d --build
# 可选 Redis：再加 --profile redis，并在 .env.onprem 写 REDIS_URL=redis://redis:6379

# 健康检查（含 storage / turn）
curl -s http://127.0.0.1:5000/api/health

镜像定义见 deploy/Dockerfile.api；通语官方宝塔部署见 deploy/宝塔官方部署.md（伪静态 deploy/宝塔伪静态.conf）。统一外网 API https://api.tongyuim.com；前端构建写入 VITE_API_BASE，站点只需伪静态。

4.1 源码安装（备选）

pnpm install
pnpm build:shared
pnpm build:widget
pnpm --filter @ai-cs/api exec prisma generate
pnpm --filter @ai-cs/im build
# 手机 IM：HBuilderX 打开 apps/uni-im-x 发行到 Web
pnpm --filter @ai-cs/admin build
pnpm --filter @ai-cs/super build

须同时守护 Nest（:5000）与 Gateway（:5100，建议 GATEWAY_HOST=127.0.0.1）；勿用开发用的 pnpm dev 上线。

4.2 数据库

本机 MySQL，或 docker compose up -d db（映射 3306）。

cp apps/api/.env.example apps/api/.env
# 编辑 DATABASE_URL、JWT_SECRET、PUBLIC_BASE_URL、CORS_ORIGINS …

pnpm db:setup
# = migrate deploy + seed

仅迁移：pnpm --filter @ai-cs/api db:migrate。生产须改密或清理 seed 演示账号。

4.3 必查环境变量

NODE_ENV=production
PORT=5000
HOST=127.0.0.1
JWT_SECRET=<至少 32 位强随机，与 gateway 相同>
DATABASE_URL=mysql://...
GATEWAY_URL=http://127.0.0.1:5100
PUBLIC_BASE_URL=https://api.客户域名.com
ADMIN_BASE_URL=https://admin.客户域名.com
CORS_ORIGINS=https://im.…,https://m.…,https://admin.…,https://super.…

# Gateway（apps/gateway/.env 或共用 api/.env）
GATEWAY_HOST=127.0.0.1
GATEWAY_PORT=5100

IM_REGISTER_TENANT_ID=tenant_xxxx

# 可选：跨网 TURN / STUN（提升弱网接通率）
IM_ICE_SERVERS=[{"urls":"stun:..."},{"urls":"turn:...","username":"...","credential":"..."}]

# 客户实例禁止配置签发私钥
# IM_LICENSE_PRIVATE_KEY=

4.4 反向代理（WebSocket）

单机推荐整站反代到 Nest（形态 A，见 deploy/nginx-api.conf）；IM/客服由 Nest 门面转到 Gateway。 实时路径为 /ws/im、/ws/agent、/ws/widget。

location / {
  proxy_pass http://127.0.0.1:5000;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_read_timeout 3600s;
  proxy_send_timeout 3600s;
  client_max_body_size 64m;
}

各前端 dist 静态托管；构建时 VITE_API_BASE=https://api.客户域名.com。 验收：pnpm smoke:single。

5. License 与开通

1. 超管开户，开通套餐 im_open，部署形态选私有化。
2. 通语签发 TY1，安全交付给客户。
3. 客户超管粘贴 License，确认到期日。
4. 需要通话：确认 License 含 av 模块；跨网可配 TURN，大群可配 SFU。
5. IM_REGISTER_TENANT_ID 指向已授权租户，开放注册才可用。

6. 音视频（通语 IM 自带）

音视频随软件交付，不是「客户自备火山 RTC」。私有化建议同时满足：

1. imDeployMode=onprem
2. 有效 TY1 License（含 av 模块）
3. 跨网场景可配 IM_ICE_SERVERS（TURN）；大群可配 SFU

客户端请求 GET /api/im/rtc-config。 AI 实时语音等才接火山等云能力；真人通话走通语 IM 内置通道。

7. 离线推送（可选 · UniPush）

1. App 工程 apps/uni-im-x：开通 DCloud UniPush 2.0 并打含 uni-push 的自定义基座。
2. 登录后 POST /api/im/push/register 上报 UniPush CID。
3. Gateway 配置 IM_PUSH_GETUI_APP_ID / APP_KEY / MASTER_SECRET（DCloud 控制台复制；平台级共用）。
4. 验收：App「设置 → 测试离线推送」或商家后台「向本账号发测试推送」。
5. 未配凭证时只注册不发送；对方在线仍走 Socket。

8. 媒体存储

推荐上传：POST /api/im/media/upload。内地自有域名通常需 ICP。

生效驱动可查 GET /api/health 的 storage.driver （配置了 s3 但缺密钥时会回退 local）。

9. App（UniApp）

• 生产设置 API 基址指向客户 HTTPS 域名。
• 客户使用自有 DCloud AppID、证书、包名、UniPush，不宜长期用演示身份上架。
• Windows 可通过 HBuilderX 云打包出 iOS。

10. 验收清单

基础

• 健康检查与 HTTPS / CORS 正常
• 强 JWT_SECRET；生产 NODE_ENV
• 迁移已执行；超管可登录
• WebSocket：两端实时互发消息

授权

• 租户 im_open + onprem；TY1 到期日正确
• 删/过期 License 后 IM 不可用（抽检）
• 开放注册指向正确租户

通话与运维

• License 含 av；跨网场景 ICE/TURN 可接通；大群可配 SFU
• 数据库与 uploads（或 S3）备份；进程守护

11. 备份与升级

备份：MySQL 每日；本地存储同步 uploads；.env 密钥分级保管。

升级：备份 → 更新指定版本 → install / build → db:migrate → 重启 → 按验收清单冒烟。勿跳迁移。

12. 常见问题