# 11.4 后端部署

:::tip 概述
后端为单二进制部署：go build 产物 + manifest 配置 + resource 静态资源 + ip2region 数据文件。生产用 systemd/supervisor 守护，开启优雅重启。
:::

## 编译

```sh
# 本机编译
go build -o bin/admin-server main.go

# Linux 交叉编译（Windows 开发机部署 Linux 服务器）
GOOS=linux GOARCH=amd64 go build -o bin/admin-server main.go

# 静态编译（无 CGO 依赖，容器友好）
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/admin-server main.go
```

## 部署产物清单

```text
admin-server                二进制
manifest/config/config.yaml 生产配置（或环境变量覆盖）
manifest/data/ip2region.xdb 归属地库
resource/static/            静态资源（验证码字体等）
resource/swagger/           API 文档页面
upload/                     上传目录（持久卷，提前建好并授权）
```

## systemd 配置示例

```ini
# /etc/systemd/system/admin-server.service
[Unit]
Description=EasyGoAdmin Server
After=network.target mysql.service redis.service

[Service]
Type=simple
WorkingDirectory=/opt/easygoadmin
ExecStart=/opt/easygoadmin/admin-server
Restart=always
RestartSec=5
# 生产密钥走环境变量（不写配置文件；前缀必须全大写 GF_，Linux 环境变量大小写敏感）
Environment=GF_JWT_SECRET=your-random-secret
Environment=GF_APP_ERRORMSG=false

[Install]
WantedBy=multi-user.target
```

```sh
systemctl daemon-reload
systemctl enable --now admin-server
journalctl -u admin-server -f      # 日志跟随
```

## 启动验证

```sh
curl http://127.0.0.1:8000/api/health        # {"code":0,...,"status":"up"}
curl -s http://127.0.0.1:8000/api.json | head    # OpenAPI
# 启动日志检查：
#   无 IdentityLoader/LogSink 告警（接线正常）
#   Redis 连接正常（无 memory fallback 告警）
```

## 优雅重启（graceful）

```yaml
server:
  graceful: true    # 已默认开启
```

生产发版流程：部署新二进制 → systemctl restart（优雅重启：处理完存量请求后换新进程）→ health 验证。多实例滚动重启实现零停机。

## 端口与反代

```text
服务监听 :8000（server.address）——生产不直接对外
前置 Nginx 终止 HTTPS + 反代：
  location /api/     → proxy_pass http://127.0.0.1:8000
  location /upload/  → proxy_pass http://127.0.0.1:8000（或直挂文件服务）
  location /swagger  → proxy_pass（可选：收紧为内网）
反代后把 Nginx 地址加入 api.proxyIps（IP 与限流准确性）
```

## 日志与监控

```text
应用日志：logger.path（默认 log/）——轮转交给 logrotate
运行监控：/api/server/info（内存/磁盘/DB/缓存/调度器）
健康探针：/api/health（负载均衡挂载）
告警建议：磁盘 >85%、health 失败、mode=memory、Scheduler 不健康
```

## 常见部署问题

| 症状 | 排查 |
|------|------|
| 启动即退出 | 配置文件路径（须从部署目录运行）/ 端口占用 / Go 版本 |
| 上传 404 | uploadDir 路径与权限；SetServerRoot 静态映射 |
| 归属地显示 "-" | ip2region.xdb 缺失或路径错 |
| 限流/IP 不准 | api.proxyIps 未含反代地址 |
| 多实例行为不一致 | Redis 不可用（mode=memory） |