chore(docs): docs/ 目录全面重新编号 + 重组
**重构前**（旧编号 02-11）： - docs/02-产品需求/ → 00 产品规划/PRD - docs/03-技术架构/ → 01-05 子目录散落 - docs/04-原型设计/ → 01-02 产品设计（HTML 原型） - docs/05-原型设计/ → screens/ - docs/06-测试素材/ → 02-E2E / 03-功能 / 04-版本测试 - docs/07-项目管理/ → 任务说明书/日报/计划 - docs/08-安全审计/ → 审计报告 - docs/09-堡垒运维/ → toolbox / deploy - docs/10-项目管理/ → 任务说明书（重复） - docs/11-历史归档/ → deploy-nas-archived **重构后**（新编号 00-07，语义化）： - docs/00-产品开发流程与文档管理规范.md - docs/00-版本迭代总览.md - docs/01-产品文档/ （PRD/原型/认证/会话/AI 服务/坐席/集成） - docs/02-技术文档/ （技术方案/架构图/重构记录/前端改造/实现配置） - docs/03-测试文档/ （E2E/功能用例/版本报告/缺陷单） - docs/04-运维文档/ （部署运维/运维指南） - docs/05-运营文档/ （品牌推广/用户手册） - docs/06-安全审计/ （审计报告） - docs/07-项目管理/ （任务说明书/日报/计划/看板） **净收益**： - 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号） - 消除 02-产品需求 与 10-项目管理 的编号重叠 - 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录） - 把运维/安全/项目管理从 0X 散落改为 04/06/07 合计 494 文件 + 78495 行 / - 14076 行
This commit is contained in:
Simon
@@ -0,0 +1,246 @@
|
||||
# Token多IP异常检测 - 部署指南
|
||||
|
||||
> **任务ID**: 待分配
|
||||
> **版本**: v1.0
|
||||
> **关联文档**:
|
||||
> - 技术设计-Token多IP异常检测.md
|
||||
> - Token多IP异常检测测试用例.md
|
||||
|
||||
---
|
||||
|
||||
## 1. 部署概述
|
||||
|
||||
### 1.1 部署范围
|
||||
|
||||
| 组件 | 容器 | 说明 |
|
||||
|------|------|------|
|
||||
| 检测服务 | backend | Token异常检测定时任务 |
|
||||
| Redis | redis | IP存储 |
|
||||
| 告警通道 | 企微机器人 | 复用现有webhook |
|
||||
|
||||
### 1.2 部署方式
|
||||
|
||||
- **部署类型**: 增量部署（不涉及基础设施变更）
|
||||
- **停机时间**: 无需停机（定时任务后台运行）
|
||||
- **回滚**: 代码级别回滚
|
||||
|
||||
---
|
||||
|
||||
## 2. 部署前检查
|
||||
|
||||
### 2.1 环境检查
|
||||
|
||||
| 检查项 | 命令 | 预期结果 |
|
||||
|--------|------|----------|
|
||||
| Redis连接 | `docker exec backend redis-cli ping` | PONG |
|
||||
| APScheduler状态 | 检查日志 | 定时任务启动成功 |
|
||||
| webhook配置 | 检查环境变量 | CONTENT_AUDIT_WEBHOOK已设置 |
|
||||
|
||||
### 2.2 配置检查
|
||||
|
||||
确认以下环境变量已配置（如需自定义）：
|
||||
|
||||
```bash
|
||||
# 可选配置
|
||||
TOKEN_ANOMALY_THRESHOLD=3 # 触发告警的IP数量阈值
|
||||
TOKEN_ANOMALY_WINDOW=3600 # 时间窗口(秒)
|
||||
TOKEN_ANOMALY_AUTO_DISABLE=false # 是否自动禁用Token
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 部署步骤
|
||||
|
||||
### 3.1 步骤1：代码变更
|
||||
|
||||
**新增文件**：
|
||||
```
|
||||
backend/app/tasks/token_anomaly_detection.py (新建)
|
||||
```
|
||||
|
||||
**修改文件**：
|
||||
```
|
||||
backend/app/services/token_service.py (增加record_token_ip方法)
|
||||
backend/app/main.py (注册定时任务)
|
||||
```
|
||||
|
||||
### 3.2 步骤2：配置变更
|
||||
|
||||
在 `.env` 或 docker-compose.yml 中添加（可选）：
|
||||
|
||||
```bash
|
||||
# 如需自定义阈值，在 .env 中添加
|
||||
TOKEN_ANOMALY_THRESHOLD=3
|
||||
TOKEN_ANOMALY_AUTO_DISABLE=false
|
||||
```
|
||||
|
||||
### 3.3 步骤3：重启服务
|
||||
|
||||
```bash
|
||||
# 重启backend容器（不中断其他服务）
|
||||
docker compose restart backend
|
||||
|
||||
# 查看日志确认定时任务启动
|
||||
docker logs backend --tail 50 | grep -i "token"
|
||||
```
|
||||
|
||||
预期日志：
|
||||
```
|
||||
✅ Token多IP异常检测任务已启动（每60秒执行一次）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 部署后验证
|
||||
|
||||
### 4.1 功能验证
|
||||
|
||||
| 验证项 | 验证方法 | 预期结果 |
|
||||
|--------|----------|----------|
|
||||
| 定时任务运行 | 查看日志 | 每分钟执行一次 |
|
||||
| IP记录 | 模拟API请求 | Redis中记录IP |
|
||||
| 告警触发 | 构造3个IP的Token | 企微收到告警 |
|
||||
|
||||
### 4.2 冒烟测试
|
||||
|
||||
执行测试用例：
|
||||
```bash
|
||||
# 进入backend容器
|
||||
docker exec -it backend bash
|
||||
|
||||
# 运行单元测试
|
||||
pytest app/tests/test_token_anomaly.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 监控与运维
|
||||
|
||||
### 5.1 日志位置
|
||||
|
||||
| 日志类型 | 路径 |
|
||||
|----------|------|
|
||||
| 应用日志 | `/app/logs/wecom-it-desk.log` |
|
||||
| 定时任务日志 | 集成在应用日志中 |
|
||||
|
||||
### 5.2 监控指标
|
||||
|
||||
| 指标 | 说明 |
|
||||
|------|------|
|
||||
| token_anomaly_triggered_total | 触发告警次数 |
|
||||
| token_anomaly_false_positive | 误报次数 |
|
||||
|
||||
### 5.3 运维命令
|
||||
|
||||
```bash
|
||||
# 查看定时任务状态
|
||||
docker exec backend python -c "from app.main import _scheduler; print(_scheduler.get_jobs())"
|
||||
|
||||
# 手动触发检测（调试）
|
||||
docker exec backend python -c "
|
||||
import asyncio
|
||||
from app.tasks.token_anomaly_detection import detect_token_anomaly
|
||||
asyncio.run(detect_token_anomaly())
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 回滚方案
|
||||
|
||||
### 6.1 回滚步骤
|
||||
|
||||
```bash
|
||||
# 1. 撤销代码变更
|
||||
git checkout -- backend/app/services/token_service.py
|
||||
git checkout -- backend/app/main.py
|
||||
git rm backend/app/tasks/token_anomaly_detection.py
|
||||
|
||||
# 2. 重启服务
|
||||
docker compose restart backend
|
||||
```
|
||||
|
||||
### 6.2 数据清理
|
||||
|
||||
```bash
|
||||
# 清理Redis中的检测数据（可选，1小时后自动过期）
|
||||
docker exec backend redis-cli KEYS "token_ips:*" | xargs redis-cli DEL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 部署清单
|
||||
|
||||
| 序号 | 步骤 | 执行人 | 检查人 | 日期 |
|
||||
|------|------|--------|--------|------|
|
||||
| 1 | 代码变更 | 开发 | | |
|
||||
| 2 | 配置检查 | 开发 | | |
|
||||
| 3 | 重启服务 | 运维 | | |
|
||||
| 4 | 功能验证 | 测试 | | |
|
||||
| 5 | 冒烟测试 | 测试 | | |
|
||||
| 6 | 监控确认 | 运维 | | |
|
||||
|
||||
---
|
||||
|
||||
## 8. 附录
|
||||
|
||||
### 8.1 相关文件
|
||||
|
||||
| 文件路径 | 说明 |
|
||||
|----------|------|
|
||||
| `backend/app/tasks/token_anomaly_detection.py` | 检测任务 |
|
||||
| `backend/app/services/token_service.py` | Token服务 |
|
||||
| `docs/04-运维文档/部署运维/技术设计-Token多IP异常检测.md` | 技术设计 |
|
||||
|
||||
### 8.2 环境变量参考
|
||||
|
||||
| 变量 | 必需 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| CONTENT_AUDIT_WEBHOOK | 是 | - | 企微机器人webhook |
|
||||
| TOKEN_ANOMALY_THRESHOLD | 否 | 3 | 告警阈值 |
|
||||
| TOKEN_ANOMALY_AUTO_DISABLE | 否 | false | 自动禁用 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 部署测试结果（2026-07-14）
|
||||
|
||||
### 9.1 部署清单
|
||||
|
||||
| 序号 | 步骤 | 执行人 | 检查人 | 日期 | 结果 |
|
||||
|------|------|--------|--------|------|------|
|
||||
| 1 | 代码变更 | 开发 | | 2026-07-14 | ✅ 完成 |
|
||||
| 2 | 配置检查 | 开发 | | 2026-07-14 | ✅ 完成 |
|
||||
| 3 | 重启服务 | 运维 | | 2026-07-14 | ✅ 完成 |
|
||||
| 4 | 功能验证 | 测试 | | 2026-07-14 | ✅ 通过 |
|
||||
| 5 | 冒烟测试 | 测试 | | 2026-07-14 | ✅ 通过 |
|
||||
| 6 | 监控确认 | 运维 | | 2026-07-14 | ✅ 完成 |
|
||||
|
||||
### 9.2 功能测试结果
|
||||
|
||||
| 用例ID | 测试项 | 预期结果 | 实际结果 | 状态 |
|
||||
|--------|--------|-----------|-----------|------|
|
||||
| T001 | 创建测试数据 | Redis中记录3个IP | ✅ token_ip:ed733a26239b8f18 = 3个IP | ✅ 通过 |
|
||||
| T002 | 触发检测 | 检测到异常并告警 | ✅ 检测到 token_hash=ed733a26239b8f18, ip_count=3 | ✅ 通过 |
|
||||
| T003 | 企微告警 | 发送markdown告警 | ✅ Token异常告警已发送: 1条 | ✅ 通过 |
|
||||
|
||||
### 9.3 验证日志
|
||||
|
||||
```
|
||||
检测到Token异常使用: token_hash=ed733a26239b8f18, ip_count=3, ips=['192.168.1.100', '192.168.1.102', '192.168.1.101']
|
||||
HTTP Request: POST https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=09120612-9d19-4f93-bd00-bfbaef548dde "HTTP/1.1 2
|
||||
Token异常告警已发送: 1 条
|
||||
Token异常检测完成: 检测到 1 个异常
|
||||
```
|
||||
|
||||
### 9.4 发现问题与修复
|
||||
|
||||
| 问题 | 原因 | 解决方案 |
|
||||
|------|------|----------|
|
||||
| 告警未发送 | 容器内.env文件路径错误 | 修改config.py的env_file为"/app/app/.env"，并复制.env到挂载目录 |
|
||||
| webhook未配置 | .env未同步到容器 | 复制.env到/app/app/.env |
|
||||
|
||||
---
|
||||
|
||||
> **编制人**: 威胁检测工程师
|
||||
> **日期**: 2026-07-14
|
||||
> **审核人**: 待定
|
||||
Reference in New Issue
Block a user