From 128efbc09f58028d7e63b30daf27aaaa8e8255c2 Mon Sep 17 00:00:00 2001
From: long-agent <admin@sub2api.local>
Date: Wed, 8 Apr 2026 22:52:14 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=203=20=E4=B8=AA=20Ru?=
 =?UTF-8?q?nbook=20-=20=E9=85=8D=E7=BD=AE=E6=9B=B4=E6=96=B0=E3=80=81?=
 =?UTF-8?q?=E5=AE=89=E5=85=A8=E4=BA=8B=E4=BB=B6=E5=93=8D=E5=BA=94=E3=80=81?=
 =?UTF-8?q?=E4=BA=8B=E4=BB=B6=E5=93=8D=E5=BA=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

完成 Runbook 目录建设：
- 05-config-update.md: 配置更新流程和回滚
- 06-security-incident.md: 安全事件分级和响应流程
- 07-incident-response.md: 服务事件分级和应急响应
---
 docs/runbooks/05-config-update.md     | 196 ++++++++++++++++++++
 docs/runbooks/06-security-incident.md | 223 +++++++++++++++++++++++
 docs/runbooks/07-incident-response.md | 250 ++++++++++++++++++++++++++
 docs/runbooks/README.md               |   2 +-
 4 files changed, 670 insertions(+), 1 deletion(-)
 create mode 100644 docs/runbooks/05-config-update.md
 create mode 100644 docs/runbooks/06-security-incident.md
 create mode 100644 docs/runbooks/07-incident-response.md

diff --git a/docs/runbooks/05-config-update.md b/docs/runbooks/05-config-update.md
new file mode 100644
index 0000000..a76f0d1
--- /dev/null
+++ b/docs/runbooks/05-config-update.md
@@ -0,0 +1,196 @@
+# 配置更新 Runbook
+
+## 触发条件
+- 修改系统配置
+- 更新环境变量
+- 更改配置文件
+
+## 警告
+
+**配置更新可能影响服务行为：**
+- 某些配置需要重启服务才能生效
+- 错误的配置可能导致服务启动失败
+- 生产环境修改前请确认备份
+
+## 配置位置
+
+```bash
+# 配置文件
+./configs/config.yaml
+
+# 环境变量文件
+.env
+
+# Docker Compose 配置
+docker-compose.yml
+```
+
+## 配置更新步骤
+
+### 1. 确认当前配置
+
+```bash
+# 查看当前配置（测试环境）
+cat ./configs/config.yaml
+
+# 查看环境变量
+cat .env | grep -v SECRET
+
+# 确认服务状态
+docker compose ps
+```
+
+### 2. 备份当前配置
+
+```bash
+# 备份配置文件
+cp ./configs/config.yaml ./configs/config.yaml.bak.$(date +%Y%m%d)
+
+# 备份环境变量（不包含敏感值）
+cp .env .env.bak.$(date +%Y%m%d)
+```
+
+### 3. 执行配置更新
+
+#### 方式一：更新环境变量（推荐）
+
+```bash
+# 编辑 .env 文件
+vi .env
+
+# 常用配置项：
+# JWT_SECRET          - JWT 签名密钥（必须 32+ 字符）
+# DB_TYPE            - 数据库类型（sqlite/postgres）
+# DB_PATH            - SQLite 数据库路径
+# TOTP_ENCRYPTION_KEY - TOTP 加密密钥
+# TZ                 - 时区设置
+```
+
+#### 方式二：更新配置文件
+
+```bash
+# 编辑配置文件
+vi ./configs/config.yaml
+
+# 关键配置项：
+# jwt.secret         - JWT 签名密钥
+# jwt.access_token_expire_minutes - Token 过期时间
+# server.port       - 服务端口
+# cors.allow origins - CORS 白名单
+```
+
+### 4. 验证配置更新
+
+```bash
+# 重启服务使配置生效
+docker compose restart
+
+# 检查服务状态
+docker compose ps
+
+# 检查健康端点
+curl http://localhost:8080/api/v1/health
+
+# 检查日志无错误
+docker compose logs | grep -i error
+```
+
+### 5. 验证功能
+
+```bash
+# 测试登录
+curl -X POST http://localhost:8080/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"your-password"}'
+
+# 测试需要认证的接口
+curl http://localhost:8080/api/v1/users \
+  -H "Authorization: Bearer <token>"
+```
+
+## 常见配置更新
+
+### 1. 修改 JWT 密钥
+
+```bash
+# 生成新密钥（32+ 字符随机字符串）
+openssl rand -base64 32
+
+# 更新 .env
+echo "JWT_SECRET=your-new-secret-key-here" >> .env
+
+# 重启服务
+docker compose restart
+```
+
+### 2. 修改数据库路径
+
+```bash
+# 编辑配置文件
+vi ./configs/config.yaml
+
+# 修改 db.path
+# 注意：修改数据库路径后需要确保新路径可写
+
+# 重启服务
+docker compose restart
+```
+
+### 3. 修改 CORS 配置
+
+```bash
+# 编辑配置文件
+vi ./configs/config.yaml
+
+# 修改 cors.allow_origins
+# 例如：["http://localhost:3000", "https://yourdomain.com"]
+
+# 重启服务
+docker compose restart
+```
+
+### 4. 修改端口
+
+```bash
+# 编辑 docker-compose.yml
+vi docker-compose.yml
+
+# 修改 ports:
+# - "8080:8080" -> - "8090:8080"
+
+# 重启服务
+docker compose down
+docker compose up -d
+```
+
+## 回滚步骤
+
+如果配置更新后服务异常：
+
+```bash
+# 停止服务
+docker compose stop
+
+# 恢复配置文件
+cp ./configs/config.yaml.bak.* ./configs/config.yaml
+
+# 恢复环境变量
+cp .env.bak.* .env
+
+# 重启服务
+docker compose restart
+```
+
+## 配置验证清单
+
+- [ ] 配置文件语法正确
+- [ ] 环境变量已正确设置
+- [ ] 服务成功启动
+- [ ] 健康检查通过
+- [ ] 主要功能正常
+- [ ] 已通知相关人员配置变更
+
+## 联系人
+
+- 运维负责人：[填写]
+- 开发团队：[填写]
diff --git a/docs/runbooks/06-security-incident.md b/docs/runbooks/06-security-incident.md
new file mode 100644
index 0000000..f40f110
--- /dev/null
+++ b/docs/runbooks/06-security-incident.md
@@ -0,0 +1,223 @@
+# 安全事件响应 Runbook
+
+## 触发条件
+- 发现未授权访问
+- 收到安全漏洞报告
+- 发现异常登录行为
+- 遭受 DDoS 攻击
+- 发现数据泄露
+
+## 紧急程度
+
+| 级别 | 说明 | 响应时间 |
+|------|------|----------|
+| P0 | 数据泄露、服务器被入侵 | 立即 |
+| P1 | 账户被盗用、疑似入侵 | 1小时内 |
+| P2 | 暴力破解、异常行为 | 4小时内 |
+| P3 | 潜在漏洞、配置风险 | 24小时内 |
+
+## 响应步骤
+
+### P0/P1 紧急响应（数据泄露、服务器被入侵）
+
+#### 1. 立即隔离
+
+```bash
+# 立即停止服务（保持证据）
+docker compose kill
+
+# 阻止外部访问（防火墙）
+sudo ufw deny 8080/tcp
+
+# 不要删除任何日志或数据 - 这是证据
+```
+
+#### 2. 通知相关人员
+
+```bash
+# 通知运维负责人
+# 通知开发团队
+# 通知安全团队
+# 如有数据泄露，通知法务/合规团队
+```
+
+#### 3. 保留证据
+
+```bash
+# 导出当前日志
+docker compose logs > incident_logs_$(date +%Y%m%d_%H%M%S).txt
+
+# 备份数据库（包含时间戳）
+cp ./data/user_management.db ./data/user_management.db.incident.$(date +%Y%m%d)
+
+# 记录当前系统状态
+docker compose ps > system_status_$(date +%Y%m%d_%H%M%S).txt
+```
+
+#### 4. 评估影响
+
+```bash
+# 检查未授权操作
+grep -E "unauthorized|failed login|invalid token" ./logs/app.log | tail -100
+
+# 检查异常 IP 访问
+grep "client_ip" ./logs/app.log | awk '{print $NF}' | sort | uniq -c | sort -rn | head -20
+
+# 检查账户异常
+sqlite3 ./data/user_management.db "SELECT username, created_at, last_login FROM users WHERE status='suspended';"
+```
+
+#### 5. 恢复服务（在隔离后）
+
+```bash
+# 在确定原因并修复后，以最小权限重新启动
+docker compose up -d
+
+# 监控系统异常
+docker compose logs -f | grep -E "error|warning|unauthorized"
+```
+
+### P2 响应（账户被盗用、疑似入侵）
+
+#### 1. 确认事件
+
+```bash
+# 检查登录日志
+docker compose logs | grep -E "login|logout" | tail -50
+
+# 检查失败登录尝试
+grep "login.*failed" ./logs/app.log | tail -20
+
+# 检查异常 IP
+grep "192.168.1.1" ./logs/app.log  # 替换为可疑IP
+```
+
+#### 2. 锁定可疑账户
+
+```bash
+# 暂停可疑账户
+curl -X PUT http://localhost:8080/api/v1/users/{user_id}/status \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"status":"suspended"}'
+
+# 撤销可疑设备信任
+curl -X POST http://localhost:8080/api/v1/devices/{device_id}/untrust \
+  -H "Authorization: Bearer <admin_token>"
+```
+
+#### 3. 重置相关凭证
+
+```bash
+# 强制用户重置密码
+# 通过管理员后台操作
+
+# 撤销所有活跃 token
+# 需要开发团队介入清理 Redis/session 存储
+```
+
+### P3 响应（潜在漏洞、配置风险）
+
+#### 1. 记录漏洞
+
+```bash
+# 创建漏洞记录
+cat > vulnerability_report_$(date +%Y%m%d).md << EOF
+# 漏洞报告
+
+日期：[填写]
+发现人：[填写]
+漏洞描述：[详细描述]
+影响范围：[评估影响]
+复现步骤：[如何复现]
+修复建议：[建议的修复方案]
+EOF
+```
+
+#### 2. 验证漏洞
+
+```bash
+# 如果是配置问题，检查当前配置
+cat ./configs/config.yaml | grep -E "jwt|secret|password"
+
+# 如果是代码漏洞，在测试环境复现
+```
+
+#### 3. 修复验证
+
+```bash
+# 在测试环境验证修复
+# 确认修复有效后，在维护窗口更新生产环境
+```
+
+## 安全检查清单
+
+### 立即检查
+
+- [ ] 服务已隔离或已停止（如需要）
+- [ ] 防火墙规则已更新
+- [ ] 相关人员已通知
+- [ ] 证据已保存
+
+### 事件评估
+
+- [ ] 确认受影响账户/数据范围
+- [ ] 确认攻击向量
+- [ ] 评估业务影响
+
+### 恢复步骤
+
+- [ ] 已修复漏洞/攻击向量
+- [ ] 已重置受影响凭证
+- [ ] 已加强监控
+- [ ] 服务已恢复正常
+
+### 事后处理
+
+- [ ] 编写事件报告
+- [ ] 更新安全措施
+- [ ] 安排复盘会议
+- [ ] 更新 Runbook
+
+## 常用命令参考
+
+```bash
+# 查看活跃登录
+docker compose logs | grep "login.*success"
+
+# 查看失败登录
+docker compose logs | grep "login.*failed"
+
+# 查看 Token 验证失败
+docker compose logs | grep "invalid token"
+
+# 查看账户创建
+docker compose logs | grep "user.*created"
+
+# 查看权限变更
+docker compose logs | grep "permission"
+
+# 踢出指定用户所有会话
+curl -X POST http://localhost:8080/api/v1/users/{user_id}/logout-all
+
+# 禁用账户
+curl -X PUT http://localhost:8080/api/v1/users/{user_id}/status \
+  -H "Authorization: Bearer <admin_token>" \
+  -d '{"status":"suspended"}'
+```
+
+## 联系人
+
+- 安全团队：[填写]
+- 运维负责人：[填写]
+- 开发团队：[填写]
+- 法务/合规：[填写]
+
+## 事后复盘
+
+事件响应完成后，需要：
+1. 编写详细事件报告
+2. 分析根本原因
+3. 制定长期改进措施
+4. 更新安全 Runbook
+5. 进行团队培训
diff --git a/docs/runbooks/07-incident-response.md b/docs/runbooks/07-incident-response.md
new file mode 100644
index 0000000..b5a6cf1
--- /dev/null
+++ b/docs/runbooks/07-incident-response.md
@@ -0,0 +1,250 @@
+# 事件响应 Runbook
+
+## 触发条件
+- 服务无响应
+- 服务报错
+- 性能严重下降
+- 依赖服务故障
+- 硬件/基础设施故障
+
+## 事件分级
+
+| 级别 | 说明 | 响应时间 | 示例 |
+|------|------|----------|------|
+| SEV1 | 服务完全不可用 | 立即 | 服务崩溃、数据库损坏 |
+| SEV2 | 部分功能不可用 | 30分钟内 | 登录失败、API 超时 |
+| SEV3 | 性能下降 | 2小时内 | 响应变慢、偶发错误 |
+| SEV4 | 轻微问题 | 24小时内 | 日志错误、非关键功能异常 |
+
+## SEV1 响应（服务完全不可用）
+
+### 1. 确认事件
+
+```bash
+# 检查服务状态
+docker compose ps
+
+# 检查容器日志
+docker compose logs --tail=100
+
+# 检查系统资源
+docker stats --no-stream
+```
+
+### 2. 收集信息
+
+```bash
+# 保存当前日志
+docker compose logs > incident_logs_$(date +%Y%m%d_%H%M%S).txt
+
+# 检查磁盘空间
+df -h
+
+# 检查内存
+free -h
+
+# 检查进程
+ps aux | grep docker
+```
+
+### 3. 尝试重启
+
+```bash
+# 优雅重启
+docker compose restart
+
+# 等待 30 秒后检查
+sleep 30
+docker compose ps
+curl http://localhost:8080/api/v1/health
+```
+
+### 4. 如果重启失败
+
+```bash
+# 查看详细错误
+docker compose up
+
+# 检查端口占用
+lsof -i :8080
+
+# 检查配置文件
+cat ./configs/config.yaml
+```
+
+### 5. 数据库问题
+
+```bash
+# 检查数据库文件
+ls -la ./data/
+
+# 验证 SQLite 完整性
+sqlite3 ./data/user_management.db "PRAGMA integrity_check;"
+
+# 如果损坏，从备份恢复
+./scripts/backup/backup.sh --restore
+```
+
+## SEV2 响应（部分功能不可用）
+
+### 1. 确认问题范围
+
+```bash
+# 测试健康端点
+curl http://localhost:8080/api/v1/health
+
+# 测试登录
+curl -X POST http://localhost:8080/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"test","password":"test"}'
+
+# 查看错误日志
+docker compose logs | grep -E "error|ERROR|fail|FAIL" | tail -50
+```
+
+### 2. 检查依赖
+
+```bash
+# 检查数据库连接
+docker compose logs | grep -i "database"
+
+# 检查外部服务（如邮件、短信）
+docker compose logs | grep -i "external\|oauth\|sms\|email"
+```
+
+### 3. 针对性修复
+
+```bash
+# 如果是数据库连接问题
+docker compose restart
+
+# 如果是配置问题，更新配置后重启
+vi ./configs/config.yaml
+docker compose restart
+
+# 如果是资源问题，清理资源
+docker system prune -a
+docker compose restart
+```
+
+## SEV3 响应（性能下降）
+
+### 1. 诊断
+
+```bash
+# 查看实时资源使用
+docker stats
+
+# 检查慢请求
+grep -E "[0-9]+ms" ./logs/app.log | awk '{if($NF ~ /[0-9]+ms/ && $NF+0 > 1000) print}' | head -20
+
+# 检查数据库查询
+sqlite3 ./data/user_management.db "SELECT COUNT(*) FROM users;"
+
+# 查看当前连接数
+lsof ./data/user_management.db | wc -l
+```
+
+### 2. 常见解决方案
+
+```bash
+# 重启服务清理缓存
+docker compose restart
+
+# 如果是数据库锁等待，等待或重启
+docker compose restart
+
+# 检查是否有慢查询
+# 参考 04-log-analysis.md 的查询分析
+```
+
+### 3. 监控恢复
+
+```bash
+# 持续监控
+watch -n 5 'curl -s http://localhost:8080/api/v1/health'
+
+# 检查响应时间
+time curl -s http://localhost:8080/api/v1/health
+```
+
+## SEV4 响应（轻微问题）
+
+### 1. 记录问题
+
+```bash
+# 创建问题记录
+cat > issue_$(date +%Y%m%d).md << EOF
+# 问题记录
+
+日期：[填写]
+问题描述：[详细描述]
+影响：[影响范围]
+日志：[相关日志片段]
+EOF
+```
+
+### 2. 安排修复
+
+```bash
+# 在下一个维护窗口修复
+# 或安排开发团队跟进
+```
+
+## 回滚步骤
+
+如果当前修复导致新问题：
+
+```bash
+# 停止服务
+docker compose stop
+
+# 恢复到上一个稳定版本
+git checkout <previous-version>
+docker compose up -d
+
+# 或从备份恢复数据
+./scripts/backup/backup.sh --restore
+```
+
+## 事件恢复清单
+
+- [ ] 服务恢复正常
+- [ ] 健康检查通过
+- [ ] 主要功能验证正常
+- [ ] 性能指标正常
+- [ ] 无新增错误
+- [ ] 通知相关人员恢复完成
+
+## 联系人
+
+- 运维负责人：[填写]
+- 开发团队：[填写]
+- 基础设施团队：[填写]
+- 项目经理：[填写]
+
+## 事后处理
+
+### 1. 事件记录
+
+创建详细的事件报告，包括：
+- 事件时间线
+- 根本原因
+- 影响评估
+- 修复步骤
+- 经验教训
+
+### 2. 预防措施
+
+根据事件分析：
+- 增强监控告警
+- 优化自动化恢复流程
+- 更新 Runbook
+- 加强容量规划
+
+### 3. 复盘会议
+
+- 讨论事件过程
+- 识别改进点
+- 分配行动项
+- 更新应急流程
diff --git a/docs/runbooks/README.md b/docs/runbooks/README.md
index 13e8ba6..ec3123f 100644
--- a/docs/runbooks/README.md
+++ b/docs/runbooks/README.md
@@ -57,4 +57,4 @@
 
 ---
 
-*最后更新：2026-04-08*
+*最后更新：2026-04-08（新增 05-07 Runbook）*