# 2.2 后端服务启动

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

## 启动流程

```text
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 服务
```

## 编译与运行

```sh
# 在项目根目录执行

# 方式一：直接运行（开发）
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 数据库初始化](./database-init)
3. **端口未占用**：

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

## 验证启动成功

```sh
# 健康检查（免登录公开接口）
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）

```sh
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`