GoFrame + Vue3 后台管理框架的完整部署方案：XYGo Admin 从构建到上线全流程

部署为何是后台框架的试金石

很多团队选型后台管理框架时，只看 Demo 跑得通不通、UI 漂不漂亮。但真正决定项目存活率的，是这套框架能不能快速且可靠地部署到生产环境。

如果你用的是一套基于 GoFrame 的敏捷后台开发框架，后端是 Go 编译的单体二进制，前端是 Vue3 的 SPA 构建产物，那部署本身并不复杂。但问题往往出在细节上——Nginx 怎么配？多租户的独立域名怎么做？Docker 编排里依赖顺序对不对？API 代理漏了一个路径导致 404 怎么办？

本文以 XYGo Admin 为例，拆解一套 GoFrame + Vue3 后台管理框架从构建到独立部署的完整流程，覆盖 Docker Compose 编排、Nginx 反代配置、多租户域名隔离等生产实战要点。

构建：前后端分别打包

前端构建

XYGo Admin 前端基于 Vite 7 构建，产物输出到 `web/dist/`。核心配置：

- Target: ES2015，兼容主流现代浏览器
- 压缩：Terser 自动移除 console 和 debugger
- Gzip：vite-plugin-compression 自动生成 .gz 文件
- Chunk 分包：阈值 2000KB，超过自动拆分

执行构建只需要一条命令：

```bash
cd web
pnpm build
```

构建产物是一个纯静态目录，后续交给 Nginx 托管即可。

后端构建

GoFrame 框架的后端是编译型语言，编译成单个可执行文件：

```bash
cd server
go build -o xygoadmin main.go
```

或者用 GoFrame CLI 一行搞定：

```bash
gf build
```

编译出来的 `xygoadmin` 是一个无外部依赖的二进制文件，直接扔到服务器上就能跑——这是 Go 语言做后台服务最大的工程优势之一。配置文件 `manifest/config/config.yaml` 放在同级目录即可。

Docker Compose：一键编排全栈应用

把前端静态资源挂进 Nginx 容器，后端 Go 服务、PostgreSQL、Redis 分别编排，一套 `docker-compose.yml` 就能把整个系统拉起来：

```yaml
version: '3.8'
services:
app:
build: .
ports:
- "8000:8000"
depends_on:
- db
- redis
environment:
- GF_GCFG_FILE=config.yaml

db:
image: postgres:15
environment:
POSTGRES_DB: xygoadmin
POSTGRES_PASSWORD: 123456
volumes:
- pgdata:/var/lib/postgresql/data

redis:
image: redis:7-alpine
ports:
- "6379:6379"

volumes:
pgdata:
```

Dockerfile 用多阶段构建，编译产物只拿最终二进制，镜像体积极小：

```dockerfile
FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY server/ .
RUN go build -o xygoadmin main.go

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/xygoadmin .
COPY --from=builder /app/manifest/config/ ./manifest/config/
EXPOSE 8000
CMD ["./xygoadmin"]
```

一条 `docker-compose up -d`，整个 Vue3 后台管理系统框架的后端基础设施就齐了。

Nginx 配置：前后端反代与静态资源

生产环境的典型拓扑是：Nginx 在前面统一收口，静态资源直接返回，API 请求反代到后端 8000 端口。

```
server {
listen 80;
server_name admin.example.com;
root /var/www/xygoadmin/web/dist;
index index.html;

# API 反代
location /admin/ { proxy_pass http://127.0.0.1:8000; }
location /system/ { proxy_pass http://127.0.0.1:8000; }
location /attachment/ { proxy_pass http://127.0.0.1:8000; }
location /captcha/ { proxy_pass http://127.0.0.1:8000; }

# WebSocket
location /socket/ {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}

# SPA 兜底
location / {
try_files $uri $uri/ /index.html;
}
}
```

关键点：所有 API 路径（`/admin/`、`/system/`、`/attachment/`、`/captcha/`）缺一不可，漏掉一个对应功能就 404。WebSocket 需要单独配置 HTTP Upgrade，否则即时通讯功能不可用。

独立部署：多租户的域名级隔离

XYGo Admin 的多租户方案不同于常见的"一个域名 + 路径区分"，它是每个租户端前端作为一个独立 SPA 部署，有自己的域名和构建流程。

为什么要独立部署？

1. 域名级隔离：租户端用 `tenant.example.com`，平台端用 `admin.example.com`，品牌感和安全边界都完全不同
2. 独立发布：平台端更新不影响租户端，回滚互不干扰
3. 按需定制：每个租户端可以有自己的主题色、Logo，裁掉不需要的模块
4. Cookie 天然隔离：不同域名下的 localStorage 和 Cookie 互不干扰

构建与域名配置

```bash
cd web-tenant
pnpm install
pnpm build
```

生产环境中 `VITE_BASE_URL = /`（独立域名部署），Nginx 配置加一条：

```
server {
listen 80;
server_name tenant.example.com;
root /var/www/xygoadmin/web-tenant/dist;

location /tenant/ { proxy_pass http://127.0.0.1:8000; }
location /site/ { proxy_pass http://127.0.0.1:8000; }
location /attachment/ { proxy_pass http://127.0.0.1:8000; }
location /captcha/ { proxy_pass http://127.0.0.1:8000; }
location /system/ { proxy_pass http://127.0.0.1:8000; }

location /tenant-socket/ {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}

location / {
try_files $uri $uri/ /index.html;
}
}
```

注意租户端的 WebSocket 路径是 `/tenant-socket/`（与平台端 `/socket/` 区分），同样要配好 Upgrade。

进程管理：Systemd 保活

生产环境别用 `nohup` 凑合。用 systemd 管理后端进程，挂了自动拉起来：

```ini
[Unit]
Description=XYGo Admin Server
After=network.target

[Service]
Type=simple
User=www
WorkingDirectory=/var/www/xygoadmin/server
ExecStart=/var/www/xygoadmin/server/xygoadmin
Restart=always
RestartSec=5

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

```bash
systemctl enable xygoadmin
systemctl start xygoadmin
```

总结

一套 GoFrame + Vue3 后台管理框架的部署链路，概括下来就是：

1. 前端 `pnpm build` → 纯静态产物
2. 后端 `go build` → 单体二进制
3. Docker Compose 一键编排全栈服务
4. Nginx 收口反代 + 静态托管
5. 多租户做独立域名部署，安全隔离
6. Systemd 保活，别手动起进程

整个流程不超过 10 分钟，比手动在服务器上逐项配置省心得多。如果你正选型 vue3 后台管理框架，建议把部署便利性作为核心评估维度——Demo 跑得快不算快，能稳定上线才算真本事。