user-system/docs/runbooks/03-配置更新.md

配置更新 Runbook

用途: 安全地更新系统配置

适用场景: 修改系统参数、调整安全设置、更新外部服务配置

---

风险等级评估

风险等级	配置类型	需要审批	需要备份
低	日志级别、超时设置	否	否
中	端口、缓存设置	是	是
高	JWT密钥、数据库路径	是	是

---

配置更新步骤

1. 备份当前配置

# 备份当前配置文件
cp configs/config.yaml configs/config.yaml.bak.$(date +%Y%m%d_%H%M%S)

# 如果是 Docker 环境，备份环境变量
docker inspect user-management-app | grep -A 50 "Env" > configs/env_backup_$(date +%Y%m%d_%H%M%S).txt

2. 审查变更内容

# 查看当前配置（生产环境慎用 cat）
cat configs/config.yaml

# 或使用 diff 对比
diff configs/config.yaml configs/config.yaml.bak.*

3. 应用配置更新

方式 A: 通过环境变量更新（推荐）

# 设置环境变量后重启
export JWT_SECRET="your-new-secret-here"
docker-compose up -d

方式 B: 直接编辑配置文件

vi configs/config.yaml

# 验证 YAML 语法
python3 -c "import yaml; yaml.safe_load(open('configs/config.yaml'))"

4. 验证配置生效

# 重启服务
docker-compose restart

# 检查日志确认启动正常
docker-compose logs --tail=50 | grep -i "config\|start\|error"

5. 测试关键功能

# 测试认证功能
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

# 测试 API 调用
curl http://localhost:8080/api/v1/health

---

高风险配置更新

JWT 密钥更新

警告: 更新 JWT 密钥会导致所有现有登录会话失效

# 1. 通知所有用户将断开连接

# 2. 备份当前配置
cp configs/config.yaml configs/config.yaml.jwt_backup.$(date +%Y%m%d)

# 3. 更新配置
vi configs/config.yaml
# 修改 jwt.secret

# 4. 重启服务
docker-compose restart

# 5. 确认服务正常
curl http://localhost:8080/api/v1/health

数据库路径变更

# 1. 停止服务
docker-compose stop

# 2. 备份数据库
./scripts/backup/backup.sh

# 3. 更新配置
vi configs/config.yaml
# 修改 database.path

# 4. 移动数据库文件
mv data/user_management.db data/new_path/

# 5. 启动服务
docker-compose up -d

# 6. 验证数据完整性
sqlite3 data/new_path/user_management.db "PRAGMA integrity_check;"

---

回滚配置

如果配置更新后出现问题：

# 1. 停止服务
docker-compose stop

# 2. 恢复备份的配置
cp configs/config.yaml.bak.* configs/config.yaml

# 3. 如果需要，恢复数据库
./scripts/backup/backup.sh --restore

# 4. 重启服务
docker-compose up -d

# 5. 验证
curl http://localhost:8080/api/v1/health

---

配置变更记录

所有生产配置变更必须记录：

日期	变更内容	变更人	审批人	回滚方案
YYYY-MM-DD	描述变更内容	姓名	姓名	如需要

---

相关文档

• 服务启动 - 初始配置指导
• 备份恢复 - 数据备份与恢复

---

维护日期: 2026-04-11 下次审查: 每月检查一次