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 索引文档
This commit is contained in:
2026-04-08 22:31:43 +08:00
parent 1b96715b55
commit 3b0bcf0ff7
11 changed files with 1191 additions and 1 deletions

View File

@@ -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
```
## 联系人
- 运维负责人:[填写]
- 技术支持:[填写]