user-system/docs/runbooks/01-服务启动.md

服务启动 Runbook

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

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

---

前提条件

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

---

启动步骤

1. 检查系统环境

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

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

2. 准备配置文件

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

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

必须配置项:

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

3. 启动服务

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

# 查看服务状态
docker-compose ps

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

4. 验证服务

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

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

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

5. 初始化数据库

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

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

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

---

故障排查

服务启动失败

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

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

数据库初始化失败

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

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

网络/防火墙问题

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

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

---

回滚操作

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

# 停止服务
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 下次审查: 每月检查一次