# 服务启动 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
```

## 联系人

- 运维负责人：[填写]
- 技术支持：[填写]