# 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/09-部署运维/技术设计-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
> **审核人**: 待定