AI GO ADMIN 项目部署上线(Linux 环境)
本文基于 ai-go-admin 官方部署文档(部署服务端 / 部署前端)整理,并结合我在 CentOS 7.6 + 宝塔面板服务器上的实际部署经历做了补充。技术栈:Go + Gin + GORM + PostgreSQL + Vue3。
部署形态
ai-go-admin 的部署物非常干净:
- 后端:一个 Go 静态编译的二进制文件,无需在服务器上装 Go
- 前端:Vite 构建出的纯静态文件,就是一个普通静态网站
- 数据库:PostgreSQL,迁移 SQL 已内嵌进二进制
也就是说,服务器上只需要 PostgreSQL + Nginx + 一个进程守护方式,官方提供了两种后端托管方案:宝塔面板的 Go 项目,或 systemd 服务。前端则是宝塔的 HTML 项目或自装 Nginx 静态站。
一、编译后端
Go 默认静态编译,能把程序逻辑和依赖全部打包进单个可执行文件。编译前确认三件事:
config/cors.yaml里配置前端的部署域名允许跨域(如果前后端不同域名)config/config.yaml配置好数据库连接信息- 确认目标服务器架构:
uname -m,一般是x86_64(amd64),少见 arm64
在项目根目录(go.mod 所在目录)执行:
# Linux / MacOS
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o ./tmp/aigo-linux-amd64 ./cmd/main.go
# Windows CMD
set CGO_ENABLED=0
set GOOS=linux
set GOARCH=amd64
go build -o ./tmp/aigo-linux-amd64 ./cmd/main.go
# Windows PowerShell
$env:CGO_ENABLED=0;$env:GOOS="linux";$env:GOARCH="amd64"; go build -o ./tmp/aigo-linux-amd64 ./cmd/main.go官方提示的几个要点:
- 不同架构的二进制不可混用,架构不匹配会报
exec format error go tool dist list可查看所有支持的平台/架构- 编译产物即可直接上传运行,此时已可用
服务器IP:8080访问接口(端口需对外开放)
我的补充:加上 -trimpath -ldflags "-s -w" 可以去掉路径信息和调试符号,二进制体积能小不少:
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags "-s -w" -o ./tmp/aigo-linux-amd64 ./cmd/main.go二、迁移数据库
如果服务器上的 PostgreSQL 还未初始化,直接用编译好的二进制执行迁移:
./aigo-linux-amd64 migrate up相当于执行 cmd/migrate/migrations 中的所有 SQL。注意:如果你本地做了二开但没往 migrations 文件夹加迁移 SQL,需要自行同步本地库的数据。
可以在迁移前用 migrate status 确认待执行的迁移。
三、部署服务端二进制
部署到生产不只是跑起来,还包括开机启动、守护进程(挂了自动重启)、指定运行用户、Nginx 反代和 SSL。官方给了两种方式。
方式一:宝塔面板 Go 项目(推荐面板用户)
- 网站 → 顶栏选 Go 项目 → 添加
- 选择编译好的二进制文件,项目名称自取(如
aigo) - 项目端口填
config/config.yaml里server.port配置的端口,默认8080 - 环境变量选指定变量,填
GIN_MODE=release - 按需绑定域名、配置 SSL
方式二:systemd 服务
创建 service 文件:
vim /etc/systemd/system/aigo.service粘贴以下内容(替换工作目录和二进制完整路径):
[Unit]
Description=ai-go-admin
After=network.target postgresql.service
[Service]
# 工作目录
WorkingDirectory=/www/wwwroot/aigo
# 二进制完整路径
ExecStart=/www/wwwroot/aigo/aigo-linux-amd64
# 进程退出总是自动重启
Restart=always
# 间隔秒数,避免程序反复崩溃高频重启打满 CPU
RestartSec=5
# 运行用户,需对二进制和工作目录有读/执行权限
User=www
Environment="GIN_MODE=release"
[Install]
WantedBy=multi-user.target常用命令:
systemctl start aigo # 启动
systemctl status aigo # 状态(active (running) 即运行中)
systemctl restart aigo # 重启
systemctl enable aigo # 开机自启
journalctl -u aigo -f # 实时日志
journalctl -u aigo -r # 倒序看日志,排查更方便我的补充:WorkingDirectory 是个隐藏大坑
这个项目的配置加载机制是:config/*.yaml 等被打进二进制,运行时差异靠二进制同目录的 .env.yaml 覆盖。而 .env.yaml 是按相对路径读取的——工作目录不对,程序不会报错,只会静默用内置默认配置,然后在连接数据库时才发现问题。所以不管用宝塔还是 systemd,WorkingDirectory / 运行目录都必须设成二进制所在目录。
另外如果用 Nginx 反代,记得确认 trusted_proxies 包含 127.0.0.1,且反代时传递 X-Forwarded-For,否则依赖客户端 IP 的功能(如限流)会把代理当客户端。
四、绑定域名与反向代理
通常用 Nginx 反代后端并绑定域名、配置 SSL,官方示例:
server
{
listen 80;
server_name api.example.com;
index index.html index.htm default.htm default.html;
# SSL 证书
ssl_certificate /etc/nginx/ssl/api.example.com.crt;
ssl_certificate_key /etc/nginx/ssl/api.example.com.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header REMOTE-HOST $remote_addr;
add_header X-Cache $upstream_cache_status;
proxy_set_header X-Host $host:$server_port;
proxy_set_header X-Scheme $scheme;
proxy_connect_timeout 30s;
proxy_read_timeout 86400s;
proxy_send_timeout 30s;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
access_log /www/wwwlogs/aigo.log;
error_log /www/wwwlogs/aigo.error.log;
}五、编译前端
前端编译后是纯静态文件,可直接作为静态网站部署。
编译前先检查 web/.env.production 的 VITE_AXIOS_BASE_URL(线上接口地址):
- 前端部署到
ask.test.com,后端部署到ask-api.test.com,则填https://ask-api.test.com - 需要正确填写协议和端口(80/443 可省略),尾部不带
/
然后在 web 目录执行:
pnpm build产出 web/dist 目录,把里面所有内容打包上传到服务器建站即可。
我的补充:如果前后端用同一个域名(Nginx 按路径分流 API 和静态文件),VITE_AXIOS_BASE_URL 留空即可,前端请求走相对路径,也不用再配跨域。
六、部署前端站点
方式一:宝塔面板 HTML 项目
- 面板 → 网站 → 顶栏选 HTML 项目 → 添加
- 填写网站域名(如
ask.test.com) - 选择网站根目录,把
web/dist内所有文件上传进去 - 按需配置 SSL 证书
注意宝塔的「网站」是按项目类型分栏的(PHP / Java / Node / Go / Python / .NET / 反向代理 / HTML项目 / 其他),纯静态前端站要去「HTML项目」里建,别在「Go项目」里找它。
方式二:自装 Nginx 静态站
核心就是一个静态网站配置,无特殊之处:
server
{
listen 80;
listen 443 ssl http2;
server_name ask.test.com;
index index.html index.htm default.htm default.html;
root /www/wwwroot/ask.test.com;
#SSL-START SSL 相关配置
ssl_certificate /www/server/panel/vhost/cert/ask.test.com/fullchain.pem;
ssl_certificate_key /www/server/panel/vhost/cert/ask.test.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
add_header Strict-Transport-Security "max-age=31536000";
error_page 497 https://$host$request_uri;
#SSL-END
# 静态资源缓存
location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$ {
expires 30d;
error_log /dev/null;
access_log /dev/null;
}
location ~ .*\.(js|css)?$ {
expires 12h;
error_log /dev/null;
access_log /dev/null;
}
access_log /www/wwwlogs/ask.test.com.log;
error_log /www/wwwlogs/ask.test.com.error.log;
}七、单域名方案的反代要点
如果不想给后端单独申请一个子域名,可以让 Nginx 在同一个 server 块里按路径分流:前端静态文件 + /admin、/common、/ping 等路径反代到 8080。这时有三点必须注意:
- 上传附件路径要用
^~前缀匹配反代给后端(如location ^~ /static/),普通前缀会被站点里其他正则规则抢走,表现为上传成功但图片 404 client_max_body_size要大于后端上传上限(默认 10MB),否则上传直接 413- 反代必须带
X-Forwarded-For/X-Real-IP,配合后端trusted_proxies配置,否则限流会按代理 IP 计算
八、验收清单
# 后端直连
curl http://127.0.0.1:8080/ping
# 前端首页
curl -I https://ask.test.com/
# 反代是否通(应返回 JSON 业务响应而非 502/404)
curl https://ask.test.com/ping
# 后端端口不应从公网可达
curl --connect-timeout 3 http://<服务器IP>:8080/ping全部通过后,登录后台(种子账号 admin/admin888)第一件事改密码,然后按需修改站点配置里默认的备案号等种子数据。
结语
ai-go-admin 的部署链路设计得比较省心:后端单二进制自带迁移和静态资源,前端纯静态,整体只有「编译 → 传上去 → 守护 → 反代」四步。官方文档把两种主流托管方式(宝塔 / systemd)都覆盖了。真正需要花心思的反而是那些文档不会写、只在自己项目里才存在的细节——配置文件的加载机制、工作目录、可信代理、上传路径匹配。部署完把验收清单跑一遍,比「页面能打开就收工」靠谱得多。
评论 (0)