85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
|
# 🧭 生产部署手册（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`
|