long-agent
3b0bcf0ff7
P0 问题修复（按照 gap analysis）： 1. JWT密钥配置修复 - config.yaml 移除占位符，改为空字符串 - 添加测试验证 JWT_SECRET 环境变量覆盖功能 2. Docker 部署完善 - 添加 deploy.resources 限制（内存 512M，CPU 0.5） - 添加 healthcheck 健康检查 - 添加 restart: unless-stopped 重启策略 3. 安全扫描集成 - 创建 scripts/security/run-gosec.sh 安全扫描脚本 - 创建 scripts/security/workflow-template.yml CI工作流模板 - 运行 gosec 扫描发现 6 个 HIGH 级别整数溢出问题 4. 备份自动化 - 创建 scripts/backup/backup.sh 自动备份脚本 - 支持 SQLite 数据库和配置文件备份 - 支持备份验证、自动清理、恢复功能 5. Runbook 文档 - 创建 docs/runbooks/ 目录 - 添加 4 个核心 Runbook：服务启动、服务停止、备份恢复、日志分析 - 添加 README.md 索引文档
136 lines
2.3 KiB
Markdown
136 lines
2.3 KiB
Markdown
# 服务启动 Runbook
|
|
|
|
## 触发条件
|
|
- 新服务器部署
|
|
- 服务故障后重启
|
|
- 常规启动
|
|
|
|
## 前置条件
|
|
- [ ] 服务器系统已安装 Docker 和 Docker Compose
|
|
- [ ] 已配置必要的环境变量
|
|
- [ ] 防火墙已开放 8080 端口
|
|
- [ ] 域名 DNS 已配置（如果需要）
|
|
|
|
## 启动步骤
|
|
|
|
### 1. 准备配置文件
|
|
|
|
```bash
|
|
# 创建必要的目录
|
|
mkdir -p ./data ./logs
|
|
|
|
# 如果是首次启动，创建空数据库
|
|
touch ./data/user_management.db
|
|
```
|
|
|
|
### 2. 配置环境变量
|
|
|
|
创建 `.env` 文件：
|
|
|
|
```bash
|
|
# JWT 密钥（必须设置，使用 32+ 字符随机字符串）
|
|
JWT_SECRET="your-very-secure-jwt-secret-key-here"
|
|
|
|
# 数据库配置（如果使用 SQLite 可忽略）
|
|
# DB_TYPE="sqlite"
|
|
# DB_PATH="./data/user_management.db"
|
|
|
|
# TOTP 加密密钥（可选，自动生成）
|
|
# TOTP_ENCRYPTION_KEY=""
|
|
|
|
# 时区
|
|
TZ="Asia/Shanghai"
|
|
```
|
|
|
|
### 3. 启动服务
|
|
|
|
```bash
|
|
# 拉取最新镜像并启动
|
|
docker compose up -d
|
|
|
|
# 查看服务状态
|
|
docker compose ps
|
|
|
|
# 查看日志
|
|
docker compose logs -f
|
|
```
|
|
|
|
### 4. 验证服务
|
|
|
|
```bash
|
|
# 检查健康端点
|
|
curl http://localhost:8080/api/v1/health
|
|
|
|
# 预期响应：{"status":"healthy"}
|
|
```
|
|
|
|
### 5. 验证数据库连接
|
|
|
|
```bash
|
|
# 检查日志中是否有数据库错误
|
|
docker compose logs app | grep -i error
|
|
```
|
|
|
|
## 启动验证清单
|
|
|
|
- [ ] 容器状态为 `running`
|
|
- [ ] 健康检查通过
|
|
- [ ] 日志无错误
|
|
- [ ] 可以访问 API 文档（可选）
|
|
|
|
## 故障排查
|
|
|
|
### 容器启动失败
|
|
|
|
```bash
|
|
# 查看详细错误
|
|
docker compose up
|
|
|
|
# 常见错误：
|
|
# - 端口被占用：修改 docker-compose.yml 中的端口映射
|
|
# - 权限错误：检查目录权限
|
|
```
|
|
|
|
### 数据库连接失败
|
|
|
|
```bash
|
|
# 检查数据库文件是否存在
|
|
ls -la ./data/user_management.db
|
|
|
|
# 重建数据库（会丢失数据！）
|
|
rm ./data/user_management.db
|
|
touch ./data/user_management.db
|
|
docker compose restart
|
|
```
|
|
|
|
### 端口访问被拒绝
|
|
|
|
```bash
|
|
# 检查防火墙
|
|
sudo ufw allow 8080/tcp
|
|
|
|
# 或检查端口是否被占用
|
|
lsof -i :8080
|
|
```
|
|
|
|
## 回滚步骤
|
|
|
|
如果启动失败且无法修复：
|
|
|
|
```bash
|
|
# 停止服务
|
|
docker compose down
|
|
|
|
# 恢复之前的数据库备份
|
|
./scripts/backup/backup.sh --restore
|
|
|
|
# 使用之前工作的版本
|
|
git checkout <previous-version>
|
|
docker compose up -d
|
|
```
|
|
|
|
## 联系人
|
|
|
|
- 运维负责人：[填写]
|
|
- 技术支持：[填写]
|