服务管理
同一套代码提供两个独立服务进程：管理端 API 与用户端 API，可分别启动、停止、部署与扩容。
服务概览
| 服务 | 启动命令 | 默认地址 | 路由前缀 | 面向对象 |
|---|---|---|---|---|
| 管理端 API | go run . service admin | :8001 | /admin | 管理后台前端 |
| 用户端 API | go run . service api | :8002 | /api | 小程序 / APP / H5 |
地址、超时等由 config.yaml 的 server 段配置：
| 配置 | 说明 | 默认 |
|---|---|---|
server.admin_addr / server.api_addr | 两端监听地址 | :8001 / :8002 |
server.read_header_timeout_seconds | 读取请求头超时 | 5 |
server.read_timeout_seconds / write_timeout_seconds | 读/写超时 | 60 |
server.idle_timeout_seconds | 空闲连接超时 | 120 |
server.shutdown_timeout_seconds | 优雅停机最长等待 | 15 |
version | 系统版本号（必填） | 无 |
编译打包
后端编译为单一二进制文件（在 server_api 目录执行）：
bash
go build -o server_api .
# 交叉编译示例：Linux 服务器（Apple Silicon 本机打包时）
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o server_api .管理端打包（在 admin_client 目录执行）：
bash
pnpm install # 依赖安装
pnpm build # 类型检查 + 生产构建，产物在 dist/管理端打包前的接口地址由构建环境变量决定（.env.production）：
dotenv
# 默认使用当前站点域名，由 Nginx 等反代将 /admin、/api 转发到后端
VITE_ADMIN_API_BASE_URL=/
# 直连后端时改为实际地址，如 http://127.0.0.1:8001发布产物清单：
| 产物 | 来源 | 说明 |
|---|---|---|
server_api | go build | 后端单一二进制，配合 config.yaml 运行 |
config.yaml | 手工维护 | 由 config.example.yaml 复制修改，不入库，含 version 必填项 |
admin_client/dist/ | pnpm build | 管理端静态资源，部署到 Nginx / 对象存储 |
打包前检查：后端 gofmt -l .、go vet ./...、go build ./... 通过；管理端 pnpm exec vue-tsc --noEmit 通过（详见代码规范）。
启动服务
开发模式：
bash
go run . service admin -c config.yaml # 管理端 API
go run . service api -c config.yaml # 用户端 API编译部署：
bash
go build -o server_api .
./server_api service admin -c config.yaml
./server_api service api -c config.yaml启动成功会输出带版本号的日志（如 管理端 API v0.0.3 启动: http://0.0.0.0:8001），随后是 Gin 的路由注册信息。
启动自检
服务启动阶段会依次执行以下检查，任一失败即拒绝启动并给出明确提示：
- 配置校验：
version必填、监听地址非空、MySQL 连接池参数合法； - MySQL / Redis 连接与健康检查；
- 核心必需表检查（
sys_user、sys_member、sys_menu等），缺表提示执行对应版本 SQL； - 初始数据检查：
sys_user无账号时提示导入初始化脚本； - 插件检查：数据库中已启用的插件必须已编译进程序，版本、迁移摘要、依赖一致，否则报错阻止启动。
停止与优雅停机
服务监听 SIGINT / SIGTERM，收到信号后：
- 取消插件运行 Context，按启动相反顺序调用插件
Stop（受shutdown_timeout_seconds约束）； - HTTP 服务优雅关闭：停止接收新请求，等待进行中的请求完成，超时后强制退出；
- 释放 Redis 与 MySQL 连接。
因此重启服务即插件启停的生效方式：在插件管理页面修改启停状态后，必须重启两端 API。
日志与观测
- 服务日志：标准库
log+ Gin 请求日志（方法、路径、状态码、耗时、来源 IP）； - 慢 SQL 阈值 1 秒，超时会在日志中告警；
- 启动即输出版本号，可结合
go run . version -c config.yaml核对部署版本； - 操作审计走
sys_operation_log表（管理端写操作自动记录），详见功能模块。
部署顺序建议
- 停止旧版管理端 API 与用户端 API；
- 备份数据库，执行对应版本的增量 SQL；
- 更新
config.yaml（含version），必要时更新反向代理； - 发布并启动新版后端两个服务；
- 发布新版
admin_client静态资源； - 按版本更新中的部署检查清单冒烟验证。
生产环境建议使用 systemd / supervisor 等守护进程管理两个服务进程，异常退出自动拉起。以 systemd 为例：
ini
[Unit]
Description=cf_Ghbf Admin API
After=network.target mysql.service redis.service
[Service]
WorkingDirectory=/opt/go_basic_frame/server_api
ExecStart=/opt/go_basic_frame/server_api/server_api service admin -c config.yaml
Restart=always
RestartSec=3
KillSignal=SIGTERM
[Install]
WantedBy=multi-user.target注意
用户端与管理端是两个独立进程，需要分别配置守护；Restart + SIGTERM 配合服务内置的优雅停机，可保证升级时请求不丢。