部署与回滚

1. 前置条件

Linux x86_64 主机，建议 4 核、8 GB 内存、50 GB 可扩展磁盘。
Docker Engine 24+、Compose v2。
域名、HTTPS 证书和可访问的 Telegram Gateway。
出站可访问 Telegram、WhatsApp、DeepSeek、邮箱服务和 Stripe。

2. 首次部署

git clone ssh://git@git.ohkeji.cn:23/wmq/lingxi-web.git
cd lingxi-web

# 先配置并启动 Telegram Gateway
cp telegram-gateway/.env.example telegram-gateway/.env
# 编辑 telegram-gateway/.env，配置 TG_API_ID、TG_API_HASH 和强随机密钥
docker compose --env-file telegram-gateway/.env \
  -f telegram-gateway/docker/docker-compose.yml up -d --build

# 再启动灵犀跨境平台
cp .env.example .env
# 编辑 .env 并替换全部占位值
docker compose --env-file .env build
docker compose --env-file .env up -d
docker compose ps

检查：

curl -fsS http://127.0.0.1:8088/health
docker compose exec api node -e "fetch('http://127.0.0.1:3100/health/ready').then(async r=>{console.log(await r.text());process.exit(r.ok?0:1)})"
docker compose logs --tail=100 api whatsapp-gateway web

平台的 TELEGRAM_GATEWAY_URL 指向网关 /api 地址。生产环境应通过私有网络连接，不把 Gateway 管理接口直接暴露公网。详细配置见 Telegram Gateway 接入指南。

2.1 仅消息网关使用出站代理

生产环境可以创建一个不映射宿主机端口的专用 Docker 网络和 V2Ray/Xray 容器，并只将 Telegram、WhatsApp 网关接入该网络。不要设置 Docker Daemon、宿主机或平台 API 的全局 HTTP_PROXY/HTTPS_PROXY。

# Telegram Gateway
TG_DEFAULT_PROXY_TYPE=socks5
TG_DEFAULT_PROXY_HOST=lingxi-egress
TG_DEFAULT_PROXY_PORT=10808

# 平台 WhatsApp Gateway
WHATSAPP_DEFAULT_PROXY_URL=http://lingxi-egress:10809

账号级代理优先于上述默认代理。代理容器应使用 internal/external Docker network + no host ports 的方式隔离；配置文件和认证信息仅保存在服务器受限目录，不进入 Git。上线前至少验证 Telegram API 与 WhatsApp Web 的 HTTPS 连接，并确认 API、数据库、邮箱和 AI 服务未配置全局代理变量。

若部署网络无法访问 Debian 官方源或 FFmpeg GitHub Release，可通过 .env 的 DEBIAN_MIRROR、DEBIAN_SECURITY_MIRROR 和 FFMPEG_BINARIES_URL 指定构建镜像；这些变量只影响镜像构建，不改变运行时出口。

3. 生产入口

在 Compose 外层部署 Caddy、Nginx 或云负载均衡：

只对公网开放 80/443。
将 HTTPS 请求转发到 127.0.0.1:8088。
保留 Host、X-Forwarded-For、X-Forwarded-Proto。
WebSocket 路径启用 Upgrade/Connection 头并提高空闲超时。
PostgreSQL、API、WhatsApp Gateway 不映射公网端口。

将 APP_PUBLIC_URL 和 PUBLIC_WEBHOOK_BASE_URL 改为正式 HTTPS 地址，随后重建 API。

当前生产拓扑使用 Caddy 与 NPS 时，应在 NPS HTTP Host 中将域名指向平台内网 8088，Caddy 只反向代理到 NPS 的本机 HTTP 入口。修改前分别备份 NPS Host 配置和 Caddyfile，验证配置后再重启 NPS、平滑重载 Caddy。

4. 更新

git fetch --tags
git checkout main
git pull --ff-only
docker compose --env-file .env build
docker compose --env-file .env up -d
docker compose ps

更新前先执行数据库和 WhatsApp 登录态备份。更新后验证登录、渠道状态、收发、WebSocket、AI、媒体和健康检查。

5. 回滚

记录当前版本：git describe --tags --always。
恢复与目标版本兼容的数据库备份。
检出稳定标签，例如 git checkout v1.0.0。
重新构建并启动：docker compose up -d --build。
执行健康和关键业务检查。

snapshot-* 是历史源码归档，不保证数据库向后兼容，不应直接作为生产回滚点。

6. 零停机演进

当前 Compose 是单实例，会有短暂重启窗口。需要零停机时应：

将 PostgreSQL 迁移到托管或高可用实例。
将 Web/API 部署为至少两个实例并使用外部负载均衡。
WebSocket 使用共享事件总线或粘性会话。
将持久任务改用共享队列并确保幂等。
数据库变更采用“先兼容、再切换、后清理”的多阶段迁移。

4.2 KiB Raw Blame History