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

配置更新 Runbook

触发条件

• 修改系统配置
• 更新环境变量
• 更改配置文件

警告

配置更新可能影响服务行为：

• 某些配置需要重启服务才能生效
• 错误的配置可能导致服务启动失败
• 生产环境修改前请确认备份

配置位置

# 配置文件
./configs/config.yaml

# 环境变量文件
.env

# Docker Compose 配置
docker-compose.yml

配置更新步骤

1. 确认当前配置

# 查看当前配置（测试环境）
cat ./configs/config.yaml

# 查看环境变量
cat .env | grep -v SECRET

# 确认服务状态
docker compose ps

2. 备份当前配置

# 备份配置文件
cp ./configs/config.yaml ./configs/config.yaml.bak.$(date +%Y%m%d)

# 备份环境变量（不包含敏感值）
cp .env .env.bak.$(date +%Y%m%d)

3. 执行配置更新

方式一：更新环境变量（推荐）

# 编辑 .env 文件
vi .env

# 常用配置项：
# JWT_SECRET          - JWT 签名密钥（必须 32+ 字符）
# DB_TYPE            - 数据库类型（sqlite/postgres）
# DB_PATH            - SQLite 数据库路径
# TOTP_ENCRYPTION_KEY - TOTP 加密密钥
# TZ                 - 时区设置

方式二：更新配置文件

# 编辑配置文件
vi ./configs/config.yaml

# 关键配置项：
# jwt.secret         - JWT 签名密钥
# jwt.access_token_expire_minutes - Token 过期时间
# server.port       - 服务端口
# cors.allow origins - CORS 白名单

4. 验证配置更新

# 重启服务使配置生效
docker compose restart

# 检查服务状态
docker compose ps

# 检查健康端点
curl http://localhost:8080/api/v1/health

# 检查日志无错误
docker compose logs | grep -i error

5. 验证功能

# 测试登录
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 密钥

# 生成新密钥（32+ 字符随机字符串）
openssl rand -base64 32

# 更新 .env
echo "JWT_SECRET=your-new-secret-key-here" >> .env

# 重启服务
docker compose restart

2. 修改数据库路径

# 编辑配置文件
vi ./configs/config.yaml

# 修改 db.path
# 注意：修改数据库路径后需要确保新路径可写

# 重启服务
docker compose restart

3. 修改 CORS 配置

# 编辑配置文件
vi ./configs/config.yaml

# 修改 cors.allow_origins
# 例如：["http://localhost:3000", "https://yourdomain.com"]

# 重启服务
docker compose restart

4. 修改端口

# 编辑 docker-compose.yml
vi docker-compose.yml

# 修改 ports:
# - "8080:8080" -> - "8090:8080"

# 重启服务
docker compose down
docker compose up -d

回滚步骤

如果配置更新后服务异常：

# 停止服务
docker compose stop

# 恢复配置文件
cp ./configs/config.yaml.bak.* ./configs/config.yaml

# 恢复环境变量
cp .env.bak.* .env

# 重启服务
docker compose restart

配置验证清单

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

联系人

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