2.2 后端服务启动

概述

后端为标准 GoFrame v2 工程，单入口 main.go，启动后监听 :8000。本节覆盖从编译到运行的完整步骤与常见启动问题。

启动流程

main.go
  ├─ 注册五数据库驱动（mysql/pgsql/mssql/oracle/sqlite blank import）
  ├─ 注册 Redis 适配器
  └─ internal/cmd.Run(ctx)
       ├─ 1) utility/cache.Init         Redis 探测，失败降级进程内存
       ├─ 2) wireDependencies           校验中间件依赖接线（缺失仅告警）
       ├─ 3) g.Server + router.Register  中间件链 + 路由绑定
       ├─ 4) DaemonInit（延时 2s）       定时任务调度器加载 status=1 任务
       ├─ 5) gcron 注册 CleanTemp        每日 03:30 清理上传临时目录
       └─ 6) s.Run()                     阻塞运行 HTTP 服务

编译与运行

# 在项目根目录执行

# 方式一：直接运行（开发）
go run main.go

# 方式二：编译后运行（推荐）
go build -o bin/admin-server.exe main.go
./bin/admin-server.exe

启动成功后控制台输出路由表与监听地址，服务监听 :8000。

启动前检查

1. 配置文件：确认 manifest/config/config.yaml 中：
   • database.default.link 数据库连接串（默认 MySQL root/root）
   • redis.default 地址与密码
2. 数据库已初始化：参见 2.4 数据库初始化
3. 端口未占用：

# Windows 查看端口占用
netstat -ano | findstr ":8000" | findstr LISTENING

验证启动成功

# 健康检查（免登录公开接口）
curl http://127.0.0.1:8000/api/health
# {"code":0,"ok":true,"msg":"操作成功","data":{"status":"up"}}

# OpenAPI 文档
# 浏览器打开 http://127.0.0.1:8000/swagger （本地 Redoc 页面）
# 原生 JSON：http://127.0.0.1:8000/api.json

服务重启（Windows）

netstat -ano | findstr ":8000" | findstr LISTENING
taskkill /F /PID <pid>
go build -o bin/admin-server.exe main.go && ./bin/admin-server.exe

服务已开启优雅重启（server.graceful: true），生产环境可使用进程管理器发 SIGHUSR2 热重启。

启动日志说明

日志	含义
IdentityLoader/TenantLoader/LogSink 告警	中间件依赖未接线（不阻断启动），表现为不加载角色权限/跳过租户校验/日志不落库
Redis 连接失败告警 + memory fallback	已降级内存缓存，多实例共享能力退化
路由表输出（server.dumpRouterMap）	配置为 true 时打印全部注册路由，调试路由问题用

常见启动失败原因

• 端口占用：8000 被其他进程占用，改 server.address 或释放端口
• 数据库连不上：检查 link 串、库是否存在、账号密码；库名含点需确认拼写
• 配置文件缺失：必须从项目根目录运行（相对路径读取 manifest/config/config.yaml）
• Go 版本过低：go.mod 声明 1.27.2，低版本报 go.mod requires go >= 1.27.2