fix/status-review-sync-20260409 #1

Merged
long merged 65 commits from fix/status-review-sync-20260409 into main 2026-04-18 15:05:51 +00:00
7 changed files with 0 additions and 1142 deletions
Showing only changes of commit bc17db352e - Show all commits

View File

@@ -1,135 +0,0 @@
# 服务启动 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
```
## 联系人
- 运维负责人:[填写]
- 技术支持:[填写]

View File

@@ -1,111 +0,0 @@
# 服务停止 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
```
## 联系人
- 运维负责人:[填写]
- 安全团队:[填写]

View File

@@ -1,173 +0,0 @@
# 备份恢复 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如有[填写]
- 项目经理:[填写]

View File

@@ -1,217 +0,0 @@
# 日志分析 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")'
```
## 联系人
- 运维负责人:[填写]
- 开发团队:[填写]

View File

@@ -1,196 +0,0 @@
# 配置更新 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
```
## 配置验证清单
- [ ] 配置文件语法正确
- [ ] 环境变量已正确设置
- [ ] 服务成功启动
- [ ] 健康检查通过
- [ ] 主要功能正常
- [ ] 已通知相关人员配置变更
## 联系人
- 运维负责人:[填写]
- 开发团队:[填写]

View File

@@ -1,250 +0,0 @@
# 事件响应 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. 复盘会议
- 讨论事件过程
- 识别改进点
- 分配行动项
- 更新应急流程

View File

@@ -1,60 +0,0 @@
# 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新增 05-07 Runbook*