2.4 后端服务启动

概述

后端是单二进制服务，入口 cmd/api。启动时完成配置校验、数据库/缓存初始化、路由注册与定时任务装配，监听 :8000。

启动命令

# 前台启动（读 config/config.yaml）
make run

# Windows 无 make 时
make.bat run

启动过程

读取配置并校验（fail-fast：JWT 密钥与 DSN 不合法直接退出）
        │
        ▼
初始化日志 / 缓存（Redis 探测失败自动降级内存并告警）
        │
        ▼
连接数据库（gorm.Open + 连接池参数）
        │
        ▼
注册路由（registerControllers 内 Bind 反射扫描全部控制器，
         写入路由元数据表；公开白名单/权限码/日志配置同源落表）
        │
        ▼
启动定时任务调度器（service.DaemonInit）
        │
        ▼
监听 server.address（默认 :8000）

常用启动变体

make build                 # 编译到 bin/
./bin/admin-server         # 直接运行编译产物（Windows: bin\ 下可执行文件）

# 环境变量覆盖配置示例（临时切库）
APP_DATABASE_DEFAULT_DBNAME=mydb APP_SERVER_ADDRESS=:9000 make run

验证服务

curl http://127.0.0.1:8000/api/health

健康检查 /api/health 为免登录端点，返回 200 即服务就绪。

日志

• 控制台输出由 logger.stdout 控制
• 文件日志写入 log/ 目录（logger.path）
• 启动日志只打阶段就绪与非常态告警，不复述配置明细

优雅关闭

进程收到退出信号后按序关闭：停 HTTP → 停定时任务 → 关 DB → 关 Redis。直接 Ctrl+C 即触发完整关闭链。

常见启动失败

现象	原因与处理
配置校验失败退出	JWT 密钥为空/过短，或 DSN 字段不完整——修正 config.yaml 或环境变量
数据库连接失败	MySQL 未启动或账号密码错误——核对 database 节
端口占用	server.address 改端口或释放 8000 端口

更多见 2.8 常见问题 FAQ。

下一步

→ 2.5 前端服务启动