fix: P0问题修复 - JWT配置、安全扫描、备份、Runbook

P0 问题修复（按照 gap analysis）： 1. JWT密钥配置修复 - config.yaml 移除占位符，改为空字符串 - 添加测试验证 JWT_SECRET 环境变量覆盖功能 2. Docker 部署完善 - 添加 deploy.resources 限制（内存 512M，CPU 0.5） - 添加 healthcheck 健康检查 - 添加 restart: unless-stopped 重启策略 3. 安全扫描集成 - 创建 scripts/security/run-gosec.sh 安全扫描脚本 - 创建 scripts/security/workflow-template.yml CI工作流模板 - 运行 gosec 扫描发现 6 个 HIGH 级别整数溢出问题 4. 备份自动化 - 创建 scripts/backup/backup.sh 自动备份脚本 - 支持 SQLite 数据库和配置文件备份 - 支持备份验证、自动清理、恢复功能 5. Runbook 文档 - 创建 docs/runbooks/ 目录 - 添加 4 个核心 Runbook：服务启动、服务停止、备份恢复、日志分析 - 添加 README.md 索引文档
2026-04-08 22:31:43 +08:00
parent 1b96715b55
commit 3b0bcf0ff7
11 changed files with 1191 additions and 1 deletions
--- a/docs/runbooks/01-service-startup.md
+++ b/docs/runbooks/01-service-startup.md
@@ -0,0 +1,135 @@
+# 服务启动 Runbook
+
+## 触发条件
+- 新服务器部署
+- 服务故障后重启
+- 常规启动
+
+## 前置条件
+- [ ] 服务器系统已安装 Docker 和 Docker Compose
+- [ ] 已配置必要的环境变量
+- [ ] 防火墙已开放 8080 端口
+- [ ] 域名 DNS 已配置（如果需要）
+
+## 启动步骤
+
+### 1. 准备配置文件
+
+```bash
+# 创建必要的目录
+mkdir -p ./data ./logs
+
+# 如果是首次启动，创建空数据库
+touch ./data/user_management.db
+```
+
+### 2. 配置环境变量
+
+创建 `.env` 文件：
+
+```bash
+# JWT 密钥（必须设置，使用 32+ 字符随机字符串）
+JWT_SECRET="your-very-secure-jwt-secret-key-here"
+
+# 数据库配置（如果使用 SQLite 可忽略）
+# DB_TYPE="sqlite"
+# DB_PATH="./data/user_management.db"
+
+# TOTP 加密密钥（可选，自动生成）
+# TOTP_ENCRYPTION_KEY=""
+
+# 时区
+TZ="Asia/Shanghai"
+```
+
+### 3. 启动服务
+
+```bash
+# 拉取最新镜像并启动
+docker compose up -d
+
+# 查看服务状态
+docker compose ps
+
+# 查看日志
+docker compose logs -f
+```
+
+### 4. 验证服务
+
+```bash
+# 检查健康端点
+curl http://localhost:8080/api/v1/health
+
+# 预期响应：{"status":"healthy"}
+```
+
+### 5. 验证数据库连接
+
+```bash
+# 检查日志中是否有数据库错误
+docker compose logs app | grep -i error
+```
+
+## 启动验证清单
+
+- [ ] 容器状态为 `running`
+- [ ] 健康检查通过
+- [ ] 日志无错误
+- [ ] 可以访问 API 文档（可选）
+
+## 故障排查
+
+### 容器启动失败
+
+```bash
+# 查看详细错误
+docker compose up
+
+# 常见错误：
+# - 端口被占用：修改 docker-compose.yml 中的端口映射
+# - 权限错误：检查目录权限
+```
+
+### 数据库连接失败
+
+```bash
+# 检查数据库文件是否存在
+ls -la ./data/user_management.db
+
+# 重建数据库（会丢失数据！）
+rm ./data/user_management.db
+touch ./data/user_management.db
+docker compose restart
+```
+
+### 端口访问被拒绝
+
+```bash
+# 检查防火墙
+sudo ufw allow 8080/tcp
+
+# 或检查端口是否被占用
+lsof -i :8080
+```
+
+## 回滚步骤
+
+如果启动失败且无法修复：
+
+```bash
+# 停止服务
+docker compose down
+
+# 恢复之前的数据库备份
+./scripts/backup/backup.sh --restore
+
+# 使用之前工作的版本
+git checkout <previous-version>
+docker compose up -d
+```
+
+## 联系人
+
+- 运维负责人：[填写]
+- 技术支持：[填写]
--- a/docs/runbooks/02-service-shutdown.md
+++ b/docs/runbooks/02-service-shutdown.md
@@ -0,0 +1,111 @@
+# 服务停止 Runbook
+
+## 触发条件
+- 计划维护
+- 紧急故障处理
+- 服务器关机
+
+## 警告
+
+**停止服务前请确保：**
+- 已通知相关人员
+- 已备份最新数据
+- 已记录当前操作
+
+## 停止步骤
+
+### 1. 通知相关人员
+
+在停止服务前，通知：
+- [ ] 管理员
+- [ ] 开发团队
+- [ ] 依赖该服务的下游系统
+
+### 2. 备份数据（可选）
+
+如果是有计划的维护，建议先备份：
+
+```bash
+# 执行备份
+./scripts/backup/backup.sh
+
+# 验证备份
+./scripts/backup/backup.sh --verify
+
+# 列出备份
+./scripts/backup/backup.sh --list
+```
+
+### 3. 停止服务
+
+```bash
+# 优雅停止（等待现有请求处理完成）
+docker compose stop
+
+# 或者强制停止（立即终止）
+docker compose kill
+```
+
+### 4. 确认服务已停止
+
+```bash
+# 检查容器状态
+docker compose ps
+
+# 预期输出：没有运行的容器
+```
+
+### 5. 清理资源（如果需要）
+
+```bash
+# 停止并移除容器（保留数据卷）
+docker compose down
+
+# 完全清理（包括数据卷 - 会丢失数据！）
+docker compose down -v
+```
+
+## 维护期间的替代方案
+
+如果需要短时间维护，可以：
+
+1. **使用维护页面**
+   ```bash
+   # 配置 nginx 返回维护页面
+   # 参考 nginx 配置文档
+   ```
+
+2. **切换到备用服务器**
+   ```bash
+   # 在备用服务器启动服务
+   docker compose -f docker-compose.backup.yml up -d
+   ```
+
+## 回滚步骤
+
+停止后重新启动：
+
+```bash
+# 重新启动
+docker compose up -d
+
+# 验证服务
+curl http://localhost:8080/api/v1/health
+```
+
+## 紧急停止
+
+如果遇到紧急安全事件：
+
+```bash
+# 立即停止所有容器
+docker compose kill
+
+# 阻止外部访问（防火墙）
+sudo ufw deny 8080/tcp
+```
+
+## 联系人
+
+- 运维负责人：[填写]
+- 安全团队：[填写]
--- a/docs/runbooks/03-backup-restore.md
+++ b/docs/runbooks/03-backup-restore.md
@@ -0,0 +1,173 @@
+# 备份恢复 Runbook
+
+## 触发条件
+- 数据损坏或丢失
+- 升级失败需要回滚
+- 灾难恢复
+
+## 警告
+
+**恢复操作会覆盖当前数据！**
+
+在执行恢复前：
+1. 确认当前数据已无法修复
+2. 记录当前状态
+3. 通知相关人员
+
+## 恢复步骤
+
+### 1. 确认备份存在
+
+```bash
+# 列出所有备份
+./scripts/backup/backup.sh --list
+
+# 验证最新备份
+./scripts/backup/backup.sh --verify
+```
+
+### 2. 停止服务
+
+```bash
+# 停止服务（保持容器运行以便回滚）
+docker compose stop
+```
+
+### 3. 备份当前数据（以防万一）
+
+```bash
+# 复制当前数据库
+cp ./data/user_management.db ./data/user_management.db.bak.$(date +%Y%m%d)
+
+# 复制当前配置
+cp ./configs/config.yaml ./configs/config.yaml.bak.$(date +%Y%m%d)
+```
+
+### 4. 执行恢复
+
+```bash
+# 从最新备份恢复
+./scripts/backup/backup.sh --restore
+
+# 或指定特定备份恢复
+# 1. 解压备份到临时目录
+mkdir -p /tmp/restore
+tar -xzf ./backups/user-management_YYYYMMDD_HHMMSS.tar.gz -C /tmp/restore
+
+# 2. 手动复制文件
+cp /tmp/restore/*/database.db ./data/user_management.db
+cp /tmp/restore/*/config.yaml ./configs/config.yaml
+
+# 3. 清理临时目录
+rm -rf /tmp/restore
+```
+
+### 5. 验证恢复
+
+```bash
+# 重启服务
+docker compose restart
+
+# 检查服务状态
+docker compose ps
+
+# 检查日志无错误
+docker compose logs | grep -i error
+
+# 验证数据库
+sqlite3 ./data/user_management.db "SELECT COUNT(*) FROM users;"
+
+# 测试 API
+curl http://localhost:8080/api/v1/health
+```
+
+### 6. 验证数据完整性
+
+```bash
+# 检查用户数量
+curl http://localhost:8080/api/v1/users | jq '.total'
+
+# 检查最近的日志
+curl http://localhost:8080/api/v1/logs/login | jq '.total'
+```
+
+## 时间点恢复（Point-in-Time Recovery）
+
+如果需要恢复到特定时间点：
+
+1. **找到最近的备份**
+   ```bash
+   ls -la ./backups/
+   ```
+
+2. **识别恢复点之前的数据**
+   - 检查备份中的数据时间戳
+
+3. **执行恢复**
+   ```bash
+   # 解压备份
+   mkdir -p /tmp/restore
+   tar -xzf ./backups/user-management_YYYYMMDD_HHMMSS.tar.gz -C /tmp/restore
+   ```
+
+4. **手动恢复数据**
+   ```bash
+   # 使用 SQLite 的挽回工具
+   sqlite3 ./data/user_management.db
+   ```
+
+## 回滚步骤
+
+如果恢复失败：
+
+```bash
+# 恢复之前的手动备份
+cp ./data/user_management.db.bak.* ./data/user_management.db
+cp ./configs/config.yaml.bak.* ./configs/config.yaml
+
+# 重启服务
+docker compose restart
+```
+
+## 恢复后检查清单
+
+- [ ] 服务正常运行
+- [ ] 健康检查通过
+- [ ] 用户数据完整
+- [ ] 配置正确
+- [ ] 日志正常
+- [ ] 通知相关人员恢复完成
+
+## 灾难恢复（全面故障）
+
+如果服务器完全不可用：
+
+1. **在新服务器上部署**
+   ```bash
+   # 克隆代码
+   git clone <repository-url>
+   cd user-management
+
+   # 安装 Docker
+   ./scripts/deploy/simple_deploy.sh
+   ```
+
+2. **恢复数据**
+   ```bash
+   # 从备份服务器复制备份文件
+   scp user@backup-server:/path/to/backups/*.tar.gz ./backups/
+
+   # 执行恢复
+   ./scripts/backup/backup.sh --restore
+   ```
+
+3. **验证服务**
+   ```bash
+   curl http://localhost:8080/api/v1/health
+   ```
+
+## 联系人
+
+- 运维负责人：[填写]
+- DBA（如有）：[填写]
+- 项目经理：[填写]
--- a/docs/runbooks/04-log-analysis.md
+++ b/docs/runbooks/04-log-analysis.md
@@ -0,0 +1,217 @@
+# 日志分析 Runbook
+
+## 日志位置
+
+```bash
+# Docker Compose 日志
+docker compose logs -f
+
+# 应用日志文件
+./logs/app.log
+
+# Docker 内部日志
+docker inspect user-management-app 2>/dev/null | jq '.[0].LogPath'
+```
+
+## 日志级别
+
+| 级别 | 说明 | 示例 |
+|------|------|------|
+| DEBUG | 调试信息 | 变量值、函数调用 |
+| INFO | 一般信息 | 请求处理、服务启动 |
+| WARN | 警告信息 | 配置缺失、性能下降 |
+| ERROR | 错误信息 | 数据库连接失败 |
+| FATAL | 致命错误 | 启动失败 |
+
+## 常用查询
+
+### 1. 查看实时日志
+
+```bash
+# 跟踪所有日志
+docker compose logs -f
+
+# 只看应用日志
+docker compose logs -f app
+
+# 只看错误
+docker compose logs -f | grep -i error
+```
+
+### 2. 搜索特定内容
+
+```bash
+# 搜索错误
+grep -i "error" ./logs/app.log
+
+# 搜索特定用户
+grep "user_id=123" ./logs/app.log
+
+# 搜索 IP 地址
+grep "192.168.1.1" ./logs/app.log
+
+# 搜索时间范围
+sed -n '/2026-04-08 10:00:00/,/2026-04-08 11:00:00/p' ./logs/app.log
+```
+
+### 3. 分析请求日志
+
+```bash
+# 查找慢请求 (> 1s)
+grep -E "[0-9]+ms" ./logs/app.log | awk '{if($NF ~ /[0-9]+ms/ && $NF+0 > 1000) print}'
+
+# 查找 5xx 错误
+grep -E "HTTP/.* 5[0-9][0-9]" ./logs/app.log
+
+# 查找登录失败
+grep "login.*failed" ./logs/app.log
+```
+
+### 4. 统计信息
+
+```bash
+# 统计错误数量
+grep -c "ERROR" ./logs/app.log
+
+# 统计各类型错误
+grep "ERROR" ./logs/app.log | cut -d' ' -f4 | sort | uniq -c | sort -rn
+
+# 统计请求来源 IP
+grep "client_ip" ./logs/app.log | awk '{print $NF}' | sort | uniq -c | sort -rn | head -10
+
+# 统计 API 调用次数
+grep "GET\|POST\|PUT\|DELETE" ./logs/app.log | cut -d' ' -f6 | sort | uniq -c | sort -rn
+```
+
+## 常见问题分析
+
+### 1. 数据库连接问题
+
+```
+错误特征：
+- "database connection failed"
+- "too many connections"
+- "connection timeout"
+```
+
+**排查步骤：**
+```bash
+# 1. 检查数据库文件
+ls -la ./data/user_management.db
+
+# 2. 检查 SQLite 完整性
+sqlite3 ./data/user_management.db "PRAGMA integrity_check;"
+
+# 3. 检查连接数
+lsof ./data/user_management.db | wc -l
+
+# 4. 重启服务
+docker compose restart
+```
+
+### 2. 认证/授权问题
+
+```
+错误特征：
+- "unauthorized"
+- "invalid token"
+- "permission denied"
+```
+
+**排查步骤：**
+```bash
+# 1. 检查 JWT 配置
+grep JWT ./configs/config.yaml
+
+# 2. 验证 token 格式
+curl -H "Authorization: Bearer <token>" http://localhost:8080/api/v1/health
+
+# 3. 检查密钥是否正确
+# 确保 JWT_SECRET 环境变量未被更改
+```
+
+### 3. 性能问题
+
+```
+错误特征：
+- 响应时间 > 2s
+- 请求超时
+- 服务无响应
+```
+
+**排查步骤：**
+```bash
+# 1. 检查系统资源
+docker stats
+
+# 2. 检查内存使用
+free -h
+
+# 3. 检查磁盘IO
+iostat -x 1 5
+
+# 4. 检查进程
+ps aux | grep -E "user-management|docker"
+
+# 5. 重启服务清理缓存
+docker compose restart
+```
+
+### 4. 内存泄漏
+
+```
+错误特征：
+- 内存使用持续增长
+- OOM (Out of Memory) 错误
+```
+
+**排查步骤：**
+```bash
+# 1. 查看内存使用趋势
+docker stats --no-stream
+
+# 2. 检查容器内存限制
+docker inspect user-management-app | grep -i memory
+
+# 3. 查看 Go 运行时的内存统计
+curl http://localhost:8080/metrics | grep go_memstats
+
+# 4. 如果持续增长，可能需要重启
+docker compose restart
+```
+
+## 日志保留
+
+```bash
+# 查看当前日志大小
+du -h ./logs/app.log
+
+# 轮转日志（如果配置了 logrotate）
+logrotate -f /etc/logrotate.d/user-management
+
+# 手动清理旧日志
+find ./logs -name "*.log.*" -mtime +7 -delete
+
+# 压缩旧日志
+find ./logs -name "*.log.*" -mtime +3 -exec gzip {} \;
+```
+
+## 结构化日志查询（JSON格式）
+
+如果日志是 JSON 格式：
+
+```bash
+# 使用 jq 解析
+cat ./logs/app.log | jq '.level == "error"'
+
+# 统计错误类型
+cat ./logs/app.log | jq -r '.error // .message' | sort | uniq -c | sort -rn | head -10
+
+# 按时间范围查询
+cat ./logs/app.log | jq 'select(.time > "2026-04-08T10:00:00Z" and .time < "2026-04-08T11:00:00Z")'
+```
+
+## 联系人
+
+- 运维负责人：[填写]
+- 开发团队：[填写]
--- a/docs/runbooks/README.md
+++ b/docs/runbooks/README.md
@@ -0,0 +1,60 @@
+# Runbooks 目录
+
+本文档包含用户管理系统的运维 Runbook（标准操作手册）。
+
+## 目录结构
+
+| Runbook | 用途 | 优先级 |
+|---------|------|--------|
+| [01-service-startup.md](01-service-startup.md) | 服务启动 | 🔴 必须 |
+| [02-service-shutdown.md](02-service-shutdown.md) | 服务停止 | 🔴 必须 |
+| [03-backup-restore.md](03-backup-restore.md) | 备份恢复 | 🔴 必须 |
+| [04-log-analysis.md](04-log-analysis.md) | 日志分析 | 🔴 必须 |
+| [05-config-update.md](05-config-update.md) | 配置更新 | 🟠 重要 |
+| [06-security-incident.md](06-security-incident.md) | 安全事件响应 | 🔴 必须 |
+| [07-incident-response.md](07-incident-response.md) | 事件响应 | 🟠 重要 |
+
+## 使用说明
+
+### 阅读顺序建议
+
+1. **新部署**：先阅读 [01-service-startup.md](01-service-startup.md)
+2. **日常维护**：阅读 [02-service-shutdown.md](02-service-shutdown.md)
+3. **故障处理**：阅读 [04-log-analysis.md](04-log-analysis.md)
+4. **数据恢复**：阅读 [03-backup-restore.md](03-backup-restore.md)
+
+### 快速参考
+
+| 操作 | 命令 |
+|------|------|
+| 启动服务 | `docker compose up -d` |
+| 停止服务 | `docker compose stop` |
+| 查看日志 | `docker compose logs -f` |
+| 执行备份 | `./scripts/backup/backup.sh` |
+| 恢复数据 | `./scripts/backup/backup.sh --restore` |
+
+## 紧急联系人
+
+| 角色 | 姓名 | 电话 | 邮箱 |
+|------|------|------|------|
+| 运维负责人 | [填写] | [填写] | [填写] |
+| 技术支持 | [填写] | [填写] | [填写] |
+| 开发团队 | [填写] | [填写] | [填写] |
+
+## 培训要求
+
+所有运维人员应熟悉：
+1. 服务启动和停止流程
+2. 备份和恢复操作
+3. 日志分析方法
+4. 常见故障排查
+
+## 文档更新
+
+- 每次重大变更后更新相关 Runbook
+- 每年至少审查一次所有 Runbook
+- 发现问题立即更新
+
+---
+
+*最后更新：2026-04-08*