# 🧭 生产部署手册（AI 恢复模块）

## 📋 目标
- 明确生产环境的守卫策略、队列驱动选择与观测性配置
- 保证 AI 恢复端点受控暴露、跨实例协同与稳定可观测

## ✅ 环境与前缀
- `AI_ENABLED=true`（启用 AI 模块）
- `GLOBAL_PREFIX=api`（统一前缀，保证基础设施路由状态码正确）
- 端口：建议 `apps/api` 使用 `3001`，根应用 `3000` 按需

## 🔐 路由守卫策略
- 开发期：`AiController` 带 `@Public()` 便于联调
- 生产期：务必加守卫或网关限制
  - `JwtAuthGuard` + `RolesGuard`
  - 网关层限制来源 IP、路径前缀 (`/api/ai/recovery/*`)
  - 限流与防刷：Nginx/网关 `rate-limit`，并在服务侧加入短时计数器

## 🔄 队列驱动选择
- `QUEUE_DRIVER=redis`（推荐，跨进程/跨实例可靠）
- 备选：`QUEUE_DRIVER=kafka`（企业内消息中间件）
- 开发/测试：`QUEUE_DRIVER=memory`（单进程快速闭环）

### Redis 驱动示例
```bash
QUEUE_DRIVER=redis
REDIS_ENABLED=true
REDIS_URL=redis://username:password@redis:6379/0
```

### Kafka 驱动示例
```bash
QUEUE_DRIVER=kafka
KAFKA_ENABLED=true
KAFKA_BROKER=kafka:9092
KAFKA_CLIENT_ID=wwjcloud-ai
KAFKA_GROUP_ID=wwjcloud-ai-group
```

## 📊 观测性配置
- 指标：`METRICS_ENABLED=true`，暴露 `/api/metrics`
- 追踪：`TELEMETRY_ENABLED=true`（按需开启）；配置采样率与后端（Jaeger/Tempo）
- 健康检查：`/api/health` 保留原始状态码（异常过滤器已处理）

### 示例
```bash
METRICS_ENABLED=true
TELEMETRY_ENABLED=true
TRACING_ENABLED=true
JAEGER_ENDPOINT=http://jaeger:14268/api/traces
```

## 🚧 暴露面与网关策略
- 仅在内网或受控网段暴露 `AiController` 路由；若必须外网，务必加守卫与限流
- 通过 API 网关或 WAF 设置：
  - 路由白名单：`/api/ai/recovery/status`（仅内部监控）
  - 隔离管理接口与前台接口的域名/前缀
  - 每秒/每分钟限流阈值与封禁策略

## 🧪 验证清单（生产前）
- 配置生效检查
  - `AI_ENABLED=true`、`GLOBAL_PREFIX=api`、`QUEUE_DRIVER` 为 `redis` 或 `kafka`
  - 指标与健康检查端点可访问且状态码正确
- 功能闭环
  - 触发失败事件 → 入队（跨实例）→ 处理 → 队列收敛
- 安全检查
  - 路由已加守卫或经网关限制
  - 限流与防刷策略生效
  - 日志中不包含敏感信息（脱敏）

## 📝 变更与灰度
- 将 `@Public()` 改为受控守卫或移除（由网关策略接管）
- 驱动切换：`memory → redis/kafka`，需在灰度期观察入队/处理时延与失败率
- 观测性：上线后先低采样启动，逐步提升采样率与指标抓取频率

## 🧯 回滚预案
- 路由临时关闭或仅内网可见
- 队列回退至 `memory` 模式以隔离中间件问题（仅在单实例应急）
- 观测性降级：关闭高频采样，保留关键健康检查

## 🔗 参考文档
- 配置指南：`docs/CONFIG_SETUP.md`
- 开发指南：`docs/DEVELOPMENT-GUIDE.md`
- 端点细节：`docs/AI-RECOVERY-DEV.md`
- 工作流指南：`docs/AI-WORKFLOW-GUIDE.md`