80 lines
2.2 KiB
Markdown
80 lines
2.2 KiB
Markdown
# 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)
|