# 生产部署与恢复手册

本文适用于单机 Docker Compose 私有化部署，覆盖首次部署、升级、监控、备份、恢复和
故障处理。多节点、高可用数据库和企业 Kubernetes 部署需要在此基线之上另行设计。

## 1. 部署拓扑与前置条件

生产 Compose 包含：

- PostgreSQL 16 + pgvector
- Redis 7
- MinIO
- ClamAV
- Django + Gunicorn
- Celery Worker、Celery Beat
- Nginx 静态前端与 API 反向代理
- 可选 Prometheus、Alertmanager

最低前置条件：

- 64 位 Linux
- Docker Engine 与 Compose 插件
- 可持续运行的本地或挂载数据盘
- 企业 DNS 和 TLS 证书
- NTP 时间同步
- 独立备份目录和异地加密存储

试运行建议至少 4 核 CPU、8 GB 内存和 100 GB 可用磁盘；正式规格必须根据附件量、
模型并发、知识向量和保留周期压测确定。ClamAV 病毒库初始化和 PostgreSQL/MinIO 数据量
会显著影响内存与磁盘需求。

## 2. 目录、账号和权限

建议使用专用系统账号部署，例如 `ai-ticket`：

```text
/opt/ai-ticket-platform/       应用代码和 .env
/var/lib/ai-ticket-backups/    本机备份
/etc/ai-ticket/                监控令牌和告警地址
```

要求：

- `.env`、监控令牌和告警 Webhook 仅部署账号可读。
- 备份账号只拥有 Docker 和备份目录所需权限。
- 不把 Docker Socket、PostgreSQL、Redis、MinIO 或 ClamAV 端口暴露到公网。
- `infra/secrets/*.example` 只是结构示例，不能作为生产凭据。

## 3. 生产配置

复制模板：

```bash
cp .env.example .env
chmod 600 .env
```

必须修改：

```env
DJANGO_DEBUG=false
DJANGO_SECRET_KEY=<高强度随机值>
DJANGO_ALLOWED_HOSTS=tickets.example.com
CORS_ALLOWED_ORIGINS=https://tickets.example.com
CSRF_TRUSTED_ORIGINS=https://tickets.example.com
FRONTEND_APP_URL=https://tickets.example.com
OIDC_CALLBACK_BASE_URL=https://tickets.example.com

DJANGO_SUPERUSER_PASSWORD=<首次登录后仍需立即轮换>
POSTGRES_PASSWORD=<数据库密码>
MINIO_ROOT_USER=<MinIO 管理账号>
MINIO_ROOT_PASSWORD=<MinIO 管理密码>
MINIO_ACCESS_KEY=<应用访问账号>
MINIO_SECRET_KEY=<应用访问密钥>

AI_CREDENTIAL_ENCRYPTION_KEY=<稳定 Fernet 密钥>
INTERNAL_MCP_TOKEN=<独立随机令牌>
METRICS_TOKEN=<独立随机令牌>
```

Fernet 密钥生成：

```bash
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

密钥一旦用于加密模型、MCP、渠道或 OIDC 凭据，必须进入企业密钥备份流程。直接替换会导致
历史密文不可解密。

生产建议：

- `KNOWLEDGE_EMBEDDING_ALLOW_HASH_FALLBACK=false`
- `TICKET_AUTO_RESOLVE_ENABLED=false`，完成真实案例验收后再按策略开启
- 使用正式 Embedding 部署并保持向量维度与数据库字段一致
- 根据数据保留政策设置 Agent 运行和临时受理保留周期
- 默认管理员仅用于初始化，随后创建实名管理员并停用或轮换默认账号

## 4. TLS 与网络边界

仓库 Compose 暴露 `${HTTP_PORT:-8080}` 的 HTTP 服务。生产环境应在其前方部署企业负载
均衡器或 TLS 反向代理：

- 外部只开放 443。
- HTTP 强制跳转 HTTPS。
- 保留 `Host`、`X-Forwarded-Proto` 和真实客户端 IP。
- 限制上传体积不低于平台总材料上限 100 MB。
- `/internal-mcp`、MinIO 控制台和监控端点只允许可信网络访问。
- 对模型、MCP、OIDC 和渠道出站目标使用网络白名单，应用层 URL 校验不能替代防火墙。

OIDC 回调地址固定为：

```text
https://<域名>/api/identity/auth/oidc/<provider-slug>/callback
```

## 5. 首次部署

先校验变量展开：

```bash
docker compose -f infra/docker-compose.prod.yml --env-file .env config
```

构建并启动：

```bash
docker compose -f infra/docker-compose.prod.yml --env-file .env up -d --build
docker compose -f infra/docker-compose.prod.yml --env-file .env ps
```

后端入口会等待 PostgreSQL、执行迁移并初始化治理数据。首次部署仍应检查日志：

```bash
docker compose -f infra/docker-compose.prod.yml --env-file .env logs backend --tail 200
docker compose -f infra/docker-compose.prod.yml --env-file .env logs worker --tail 100
docker compose -f infra/docker-compose.prod.yml --env-file .env logs beat --tail 100
```

探针：

```bash
curl -fsS http://127.0.0.1:8080/api/system/health/live
curl -fsS http://127.0.0.1:8080/api/system/health/ready
```

`live` 只表示进程可响应；`ready` 同时检查数据库和缓存。部署完成后验证：

1. HTTPS、登录和权限菜单。
2. 创建、查询和状态流转一张测试工单。
3. 上传安全测试附件并下载。
4. 启动一次 Agent 运行并查看事件。
5. 如已配置渠道，执行入站、出站和回执。
6. 检查后台任务、指标和告警。

## 6. 监控与告警

创建仅运维账号可读的文件：

```bash
install -m 600 /dev/null /etc/ai-ticket/metrics-token
install -m 600 /dev/null /etc/ai-ticket/alert-webhook-url
```

写入与 `.env` 中 `METRICS_TOKEN` 一致的指标令牌，以及真实告警 Webhook。设置路径并启动：

```bash
export METRICS_TOKEN_FILE=/etc/ai-ticket/metrics-token
export ALERT_WEBHOOK_URL_FILE=/etc/ai-ticket/alert-webhook-url
docker compose -f infra/docker-compose.prod.yml --env-file .env \
  --profile monitoring up -d
```

Prometheus 与 Alertmanager 默认只绑定宿主机回环地址。指标接口接受
`X-Metrics-Token` 或 Bearer Token。当前告警覆盖：

- 后端无法抓取
- 渠道失败或积压
- Agent/Tool 近期失败
- 任务中心积压

上线前必须触发一条测试告警，确认接收人、升级路径、静默策略和恢复通知。

## 7. 备份、校验和保留

Linux：

```bash
sh infra/scripts/backup.sh
sh infra/scripts/verify-backup.sh backups/<timestamp>
BACKUP_RETENTION_DAYS=30 sh infra/scripts/prune-backups.sh
```

Windows PowerShell：

```powershell
& infra/scripts/backup.ps1
& infra/scripts/verify-backup.ps1 -BackupDirectory backups/<timestamp>
```

备份包含：

- PostgreSQL 自定义格式转储
- 可枚举数据库结构清单
- MinIO 数据归档
- SHA-256 校验文件
- 备份元数据

默认流程会暂停运行中的 backend、worker 和 beat，并在对象卷归档期间停止 MinIO，
形成数据库与对象存储的一致静默窗口。只有确认没有常驻业务写入的隔离演练才允许使用
`BACKUP_SKIP_APPLICATION_SERVICES=true` 或 `-SkipApplicationServices`。

`infra/backup-cron.example` 是宿主机 cron 模板。安装前替换绝对路径和专用账号。校验成功的
备份必须复制到独立、加密、不可被应用主机直接删除且具有保留策略的异地存储。

备份成功不代表可恢复；至少按季度执行恢复演练，并在重大版本发布前再次执行。

## 8. 升级

升级前：

1. 确认当前 Git 版本和镜像标签可追溯。
2. 阅读迁移和配置变更。
3. 执行完整质量门和生产 Compose 校验。
4. 创建并验证一致性备份。
5. 记录维护窗口和回滚负责人。

构建新版本：

```bash
docker compose -f infra/docker-compose.prod.yml --env-file .env build
docker compose -f infra/docker-compose.prod.yml --env-file .env up -d
```

观察：

```bash
docker compose -f infra/docker-compose.prod.yml --env-file .env ps
docker compose -f infra/docker-compose.prod.yml --env-file .env logs backend worker --tail 200
curl -fsS http://127.0.0.1:8080/api/system/health/ready
```

然后执行首次部署中的业务冒烟。迁移必须向后兼容时，才允许应用容器滚动替换；破坏性迁移
需要单独维护窗口和数据转换方案。

## 9. 回滚

应用回滚：

1. 停止写入或进入维护窗口。
2. 切回已验证的代码版本和镜像标签。
3. 使用相同 `.env` 启动旧版本。
4. 检查就绪探针和业务冒烟。

数据库迁移不能盲目反向执行。若新版本已写入旧版本不理解的数据，使用升级前的一致性备份
恢复数据库与 MinIO，而不是只恢复其中一侧。

## 10. 恢复

恢复会替换当前数据库和对象存储，只能在确认的维护窗口执行。

Linux：

```bash
RESTORE_CONFIRM=restore-ai-ticket-platform \
  sh infra/scripts/restore.sh backups/<timestamp>
```

Windows PowerShell：

```powershell
& infra/scripts/restore.ps1 `
  -BackupDirectory backups/<timestamp> `
  -Confirm restore-ai-ticket-platform
```

脚本会先验证备份，在覆盖对象卷前停止 MinIO，并在 MinIO 恢复健康后再启动应用服务。
恢复后依次检查：

1. 就绪探针和登录。
2. 工单数量、抽样状态和解决结果。
3. 附件记录与 MinIO 对象。
4. Agent、任务中心和审计记录。
5. 渠道入站、出站和回执。

隔离自动演练：

```powershell
& infra/scripts/drill-restore.ps1
```

演练创建唯一 Compose 项目和独立数据卷，写入工单、附件及 MinIO 标记，执行备份、删除、
恢复和一致性检查，最后清理临时资源。最近一次证据见
[隔离恢复演练记录](recovery-drill-2026-07-27.md)。

## 11. 故障排查

### 就绪探针失败

```bash
docker compose -f infra/docker-compose.prod.yml --env-file .env ps
docker compose -f infra/docker-compose.prod.yml --env-file .env logs backend postgres redis --tail 200
```

重点检查数据库连接、Redis 地址、迁移状态和磁盘空间。

### Celery 任务积压

检查 worker、Redis 和模型服务连通性。不要通过重复点击绕过幂等控制；先确认任务是否已经
创建业务终态。

### 材料一直扫描失败

检查 ClamAV 健康和病毒库日志。不得为恢复业务而在生产关闭恶意文件扫描。

### 模型、MCP、渠道或 OIDC 凭据无法解密

确认 Django 与 Celery 使用同一 Fernet 主密钥。不要覆盖主密钥；从企业密钥备份恢复原值。

### 磁盘快速增长

分别检查 PostgreSQL、MinIO、ClamAV、Prometheus 和备份目录。先确认保留策略和备份可恢复，
不要直接删除 Docker 数据卷。

## 12. 上线安全检查表

- [ ] `DJANGO_DEBUG=false`，域名和可信来源仅包含生产地址。
- [ ] 默认管理员密码已替换，管理员使用实名账号。
- [ ] `.env`、Fernet、MCP、指标和告警凭据已纳入密钥管理。
- [ ] 外部只开放 HTTPS，内部端口受防火墙限制。
- [ ] 模型、MCP、OIDC 和渠道出口有网络白名单。
- [ ] 自动解决保持关闭，或已经通过真实案例和审批策略验收。
- [ ] 监控、真实告警接收方和升级路径已验证。
- [ ] 定时备份已安装，校验后复制到异地加密存储。
- [ ] 已完成隔离恢复演练并记录 RPO/RTO。
- [ ] 统一蓝图报告明确区分已通过和待真实环境验收门槛。