wmq
104 lines
4.2 KiB
Markdown
104 lines
4.2 KiB
Markdown
# 部署与回滚
|
|
|
|
## 1. 前置条件
|
|
|
|
- Linux x86_64 主机，建议 4 核、8 GB 内存、50 GB 可扩展磁盘。
|
|
- Docker Engine 24+、Compose v2。
|
|
- 域名、HTTPS 证书和可访问的 Telegram Gateway。
|
|
- 出站可访问 Telegram、WhatsApp、DeepSeek、邮箱服务和 Stripe。
|
|
|
|
## 2. 首次部署
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
检查：
|
|
|
|
```bash
|
|
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 接入指南](TELEGRAM-GATEWAY.md)。
|
|
|
|
### 2.1 仅消息网关使用出站代理
|
|
|
|
生产环境可以创建一个不映射宿主机端口的专用 Docker 网络和 V2Ray/Xray 容器，并只将 Telegram、WhatsApp 网关接入该网络。不要设置 Docker Daemon、宿主机或平台 API 的全局 `HTTP_PROXY`/`HTTPS_PROXY`。
|
|
|
|
```env
|
|
# 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. 更新
|
|
|
|
```bash
|
|
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. 回滚
|
|
|
|
1. 记录当前版本：`git describe --tags --always`。
|
|
2. 恢复与目标版本兼容的数据库备份。
|
|
3. 检出稳定标签，例如 `git checkout v1.0.0`。
|
|
4. 重新构建并启动：`docker compose up -d --build`。
|
|
5. 执行健康和关键业务检查。
|
|
|
|
`snapshot-*` 是历史源码归档，不保证数据库向后兼容，不应直接作为生产回滚点。
|
|
|
|
## 6. 零停机演进
|
|
|
|
当前 Compose 是单实例，会有短暂重启窗口。需要零停机时应：
|
|
|
|
- 将 PostgreSQL 迁移到托管或高可用实例。
|
|
- 将 Web/API 部署为至少两个实例并使用外部负载均衡。
|
|
- WebSocket 使用共享事件总线或粘性会话。
|
|
- 将持久任务改用共享队列并确保幂等。
|
|
- 数据库变更采用“先兼容、再切换、后清理”的多阶段迁移。
|