# AI 合同平台生产拆分部署指南

> 目标：按 `hyburk.com` 当前生产方式部署 AI 合同平台。公网入口在阿里云 `47.94.178.212`，业务后端和数据服务在 `192.168.3.90`。
>
> 回收、恢复、3.90 基础环境参考：`D:\hyburk.com\backup\docs\3.90生产环境部署教程.md` 与 `D:\hyburk.com\backup\docs\3.90快速部署命令清单.md`。

## 1. 拓扑

| 组件 | 地址 | 说明 |
|---|---|---|
| 用户访问入口 | `https://contact.yuqei.com` | 阿里云 Nginx，站点域名 |
| 阿里云公网主机 | `47.94.178.212` | 运行 Nginx + Next.js 前端 Docker 容器 |
| 前端容器 | `127.0.0.1:3003 -> 3000` | `docker-compose.frontend.aliyun.yml` |
| 公网 API | `https://contact.yuqei.com/api/v1` | Nginx 代理到 3.90 后端 |
| 3.90 后端 | `http://192.168.3.90:8001` | FastAPI Docker 后端 |
| 阿里云到后端隧道 | `http://10.20.0.11:8001` | WireGuard 内网地址，沿用 hyburk 代理方式 |
| PostgreSQL | `192.168.3.90:5432` | 数据库 `ai_contract_platform` |
| Redis | Docker service `redis:6379` | 后端 Compose 内部访问 |
| MinIO | `192.168.3.90:9000` | Bucket: `contracts` |
| Shared AI Platform | `http://192.168.3.90:18011` | 后端调用 |

## 2. 首次部署前检查

### 2.1 192.168.3.90

按 hyburk 文档完成：

1. Docker、PostgreSQL 16、Redis/MinIO 基础服务。
2. WireGuard 客户端，确保阿里云可以访问 `10.20.0.11`。
3. 数据库：

```bash
su - postgres -c "createdb ai_contract_platform"
PGPASSWORD=<password> pg_restore -U <user> -h localhost -d ai_contract_platform -c /tmp/db_backup/ai_contract_platform.dump
```

4. 远程项目目录：

```bash
mkdir -p /opt/ai-contract-platform
cd /opt/ai-contract-platform
# 放置 docker-compose.server.yml、backend/、.env
```

5. `.env` 以 `infra/env/backend.3.90.env.example` 为模板，必须替换：
   - `SECRET_KEY`
   - `DATABASE_URL`
   - `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`
   - `SHARED_AI_PLATFORM_API_KEY`

### 2.2 阿里云 47.94.178.212

1. Docker、Nginx、WireGuard 已安装并运行。
2. DNS：`contact.yuqei.com` 指向 `47.94.178.212`。
3. WireGuard 连通性：

```bash
curl http://10.20.0.11:8001/health
curl http://10.20.0.11:8001/api/v1/system/readiness
```

4. 远程项目目录：

```bash
mkdir -p /opt/ai-contract-platform-frontend
```

5. Nginx 配置使用 `infra/nginx/contact.yuqei.com.conf`。如果已配置 HTTPS 证书，将该 server 块合并到 TLS 配置或由 certbot/现有证书工具扩展 443 server。

## 3. 发布命令

### 3.1 后端发布到 192.168.3.90

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\deploy-backend-docker.ps1 `
  -ServerHost 192.168.3.90 `
  -RemoteProjectPath /opt/ai-contract-platform `
  -ComposeFile docker-compose.server.yml `
  -FrontendBaseUrl https://contact.yuqei.com `
  -BackendBaseUrl http://192.168.3.90:8001 `
  -ApiUrl https://contact.yuqei.com/api/v1 `
  -ReadinessUrl https://contact.yuqei.com/api/v1/system/readiness
```

后端 Compose 默认只要求 3.90 运行 `backend`、`legal-change-impact-worker`、`redis`。前端服务保留在 `single-host` profile 中，不作为拆分生产路径必需项。

### 3.2 前端发布到阿里云

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\deploy-frontend-aliyun-docker.ps1 `
  -ServerHost 47.94.178.212 `
  -RemoteProjectPath /opt/ai-contract-platform-frontend `
  -BackendTunnelBaseUrl http://10.20.0.11:8001 `
  -FrontendBaseUrl https://contact.yuqei.com `
  -BackendBaseUrl http://192.168.3.90:8001 `
  -ApiUrl https://contact.yuqei.com/api/v1 `
  -ReadinessUrl https://contact.yuqei.com/api/v1/system/readiness
```

脚本会：

1. 打包 `frontend/`、`docker-compose.frontend.aliyun.yml`、`infra/nginx/contact.yuqei.com.conf`。
2. 上传到阿里云。
3. 备份当前远程前端和 Nginx 配置到 `/opt/ai-contract-platform-frontend/backups/frontend-aliyun-deploy/`。
4. 用 `BACKEND_BASE_URL=http://10.20.0.11:8001` 构建并重启前端容器。
5. 安装 Nginx 配置、执行 `nginx -t`、重载 Nginx。
6. 运行发布门禁（除非传 `-SkipReleaseGate`）。

## 4. 验证

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\run-production-release-gate.ps1 `
  -ServerHost 192.168.3.90 `
  -FrontendBaseUrl https://contact.yuqei.com `
  -BackendBaseUrl http://192.168.3.90:8001 `
  -ApiUrl https://contact.yuqei.com/api/v1 `
  -HealthUrl http://192.168.3.90:8001/health `
  -ReadinessUrl https://contact.yuqei.com/api/v1/system/readiness `
  -ExpectedRemoteServices backend,legal-change-impact-worker,redis
```

手工 smoke：

```bash
curl https://contact.yuqei.com/
curl https://contact.yuqei.com/api/v1/system/readiness
curl http://192.168.3.90:8001/health
```

## 5. 回滚

### 5.1 列出阿里云前端备份

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\rollback-frontend-aliyun-docker.ps1 -ListBackups
```

### 5.2 前端回滚预演

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\rollback-frontend-aliyun-docker.ps1 -DryRun
```

### 5.3 执行前端回滚

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\rollback-frontend-aliyun-docker.ps1 `
  -ServerHost 47.94.178.212 `
  -RemoteProjectPath /opt/ai-contract-platform-frontend `
  -BackendTunnelBaseUrl http://10.20.0.11:8001
```

回滚脚本会先备份当前前端到 `/opt/ai-contract-platform-frontend/backups/frontend-aliyun-rollback/`，再恢复最近一次 `frontend-aliyun-before-*.tgz`，重建前端容器并重载 Nginx。

## 6. 备份与恢复

- 数据库和 MinIO 的基础备份策略沿用 `D:\hyburk.com\backup\docs`：PostgreSQL 使用 `pg_dump -F c`，MinIO 使用 `mc mirror` 或归档备份。
- 前端发布脚本自动生成应用级回滚包。
- 后端发布脚本自动生成 `/opt/ai-contract-platform/backups/phase7-backend-deploy/backend-before-*.tgz`。
- 正式变更前应确认最近一次数据库备份、MinIO 备份、前端回滚包均存在且非空。

## 7. 端口清单

| 主机 | 端口 | 用途 |
|---|---:|---|
| 47.94.178.212 | 80/443 | Nginx / `contact.yuqei.com` |
| 47.94.178.212 | 3003 | 前端容器本机端口，建议仅本机访问 |
| 47.94.178.212 | 51820/udp | WireGuard |
| 192.168.3.90 | 8001 | AI 合同平台后端 |
| 192.168.3.90 | 5432 | PostgreSQL |
| 192.168.3.90 | 6379 | Redis（如对宿主暴露） |
| 192.168.3.90 | 9000/9001 | MinIO API/Console |