Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
247 lines
6.2 KiB
Markdown
247 lines
6.2 KiB
Markdown
# 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
|
||
> **审核人**: 待定
|