# 2.4 后端服务启动

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

## 启动命令

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

# Windows 无 make 时
make.bat run
```

## 启动过程

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

## 常用启动变体

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

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

## 验证服务

```bash
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](/zh/quickstart/faq.html)。

## 下一步

→ [2.5 前端服务启动](/zh/quickstart/frontend-start.html)