b5826ee469
🚀 新增功能: - wwjcloud-nest-v1: 完整的 NestJS 智能框架 - AI 自愈机制: @wwjcloud/auto-healing 模块 - 智能代码生成: tools-v1/php-tools 迁移工具链 - AI 能力规划: v1/docs/AI-CAPABILITY-ROADMAP.md 📦 核心模块: - libs/wwjcloud-ai: AI 策略和恢复服务 - libs/wwjcloud-boot: 启动和配置管理 - libs/wwjcloud-core: 核心基础设施 - libs/wwjcloud-addon: 插件系统 🏗️ 架构特性: - 分层渐进式 AI 策略 - 微服务导向的模块化设计 - 与 PHP 项目 100% 业务一致性 - Docker 容器化部署支持 📋 版本信息: - 版本: v0.1.0 - 发布日期: 2025-01-25 - 分支: v1
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` |