long-agent
128efbc09f
完成 Runbook 目录建设： - 05-config-update.md: 配置更新流程和回滚 - 06-security-incident.md: 安全事件分级和响应流程 - 07-incident-response.md: 服务事件分级和应急响应
197 lines
3.4 KiB
Markdown
197 lines
3.4 KiB
Markdown
# 配置更新 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
|
||
```
|
||
|
||
## 配置验证清单
|
||
|
||
- [ ] 配置文件语法正确
|
||
- [ ] 环境变量已正确设置
|
||
- [ ] 服务成功启动
|
||
- [ ] 健康检查通过
|
||
- [ ] 主要功能正常
|
||
- [ ] 已通知相关人员配置变更
|
||
|
||
## 联系人
|
||
|
||
- 运维负责人：[填写]
|
||
- 开发团队：[填写]
|