# 部署与回滚

## 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
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
```

## 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。

## 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 使用共享事件总线或粘性会话。
- 将持久任务改用共享队列并确保幂等。
- 数据库变更采用“先兼容、再切换、后清理”的多阶段迁移。