# 配置更新 Runbook

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

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

---

## 风险等级评估

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

---

## 配置更新步骤

### 1. 备份当前配置

```bash
# 备份当前配置文件
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. 审查变更内容

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

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

### 3. 应用配置更新

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

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

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

```bash
vi configs/config.yaml

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

### 4. 验证配置生效

```bash
# 重启服务
docker-compose restart

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

### 5. 测试关键功能

```bash
# 测试认证功能
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 密钥会导致所有现有登录会话失效

```bash
# 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
```

### 数据库路径变更

```bash
# 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;"
```

---

## 回滚配置

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

```bash
# 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 | 描述变更内容 | 姓名 | 姓名 | 如需要 |

---

## 相关文档

- [服务启动](./01-服务启动.md) - 初始配置指导
- [备份恢复](./05-备份恢复.md) - 数据备份与恢复

---

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