wecom_it_smart_desk/docs/04-运维文档/部署运维/Token多IP异常检测部署指南.md

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 配置检查

确认以下环境变量已配置（如需自定义）：

# 可选配置
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 中添加（可选）：

# 如需自定义阈值，在 .env 中添加
TOKEN_ANOMALY_THRESHOLD=3
TOKEN_ANOMALY_AUTO_DISABLE=false

3.3 步骤3：重启服务

# 重启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 冒烟测试

执行测试用例：

# 进入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 运维命令

# 查看定时任务状态
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 回滚步骤

# 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 数据清理

# 清理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 审核人: 待定