user-system/docs/runbooks/05-config-update.md

# 配置更新 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
```

## 配置验证清单

- [ ] 配置文件语法正确
- [ ] 环境变量已正确设置
- [ ] 服务成功启动
- [ ] 健康检查通过
- [ ] 主要功能正常
- [ ] 已通知相关人员配置变更

## 联系人

- 运维负责人：[填写]
- 开发团队：[填写]