# 服务启动 Runbook

**用途**: 新服务器部署或服务重启后启动用户管理系统

**适用场景**: 首次部署、服务器重启、故障恢复后

---

## 前提条件

- [ ] 服务器系统已安装 Docker 和 Docker Compose
- [ ] 已配置防火墙开放 8080 端口
- [ ] 已准备好配置文件 `configs/config.yaml`
- [ ] 已设置必要的环境变量（参考 `.env.example`）

---

## 启动步骤

### 1. 检查系统环境

```bash
# 检查 Docker 版本
docker --version
docker-compose --version

# 检查端口占用
netstat -tlnp | grep 8080
# 或在 Windows 上
Get-NetTCPConnection -LocalPort 8080
```

### 2. 准备配置文件

```bash
# 复制配置模板
cp .env.example .env

# 编辑配置（重点关注以下项）
vi .env
```

**必须配置项**:
- `JWT_SECRET` - JWT 签名密钥（生产环境必须使用强密钥）
- `ADMIN_EMAIL` - 初始管理员邮箱
- `ADMIN_PASSWORD` - 初始管理员密码

### 3. 启动服务

```bash
# 使用 Docker Compose 启动
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志确认启动成功
docker-compose logs -f
```

### 4. 验证服务

```bash
# 健康检查
curl http://localhost:8080/api/v1/health

# 预期响应: {"status":"ok"}

# 检查所有端口
curl http://localhost:8080/api/v1/health/ready
```

### 5. 初始化数据库

首次启动时，系统会自动创建 SQLite 数据库文件 (`data/user_management.db`)。

```bash
# 确认数据目录存在
ls -la data/

# 确认数据库文件已创建
ls -la data/*.db
```

---

## 故障排查

### 服务启动失败

```bash
# 查看详细日志
docker-compose logs app

# 常见问题:
# 1. 端口被占用 -> 改端口或停止占用进程
# 2. 配置文件错误 -> 检查 config.yaml 语法
# 3. 权限问题 -> 检查目录权限
```

### 数据库初始化失败

```bash
# 检查数据目录
ls -la data/

# 手动初始化数据库
mkdir -p data
chmod 755 data
```

### 网络/防火墙问题

```bash
# Linux 检查防火墙
sudo firewall-cmd --list-ports
sudo iptables -L -n | grep 8080

# 测试本地连接
curl http://127.0.0.1:8080/api/v1/health
```

---

## 回滚操作

如果启动失败且无法修复：

```bash
# 停止服务
docker-compose down

# 查看之前运行的容器
docker ps -a | grep user-management

# 从备份恢复（参考 备份恢复 Runbook）
./scripts/backup/backup.sh --restore
```

---

## 验证检查清单

- [ ] `docker-compose ps` 显示 app 服务状态为 Up
- [ ] `curl http://localhost:8080/api/v1/health` 返回 `{"status":"ok"}`
- [ ] 可以访问管理后台 `http://localhost:8080/admin`
- [ ] 可以使用初始管理员账号登录

---

**维护日期**: 2026-04-11
**下次审查**: 每月检查一次
