go-admin生产部署完全指南:Docker、docker-compose与Kubernetes三种方案对比
go-admin生产部署完全指南:Docker、docker-compose与Kubernetes三种方案对比
go-admin 是基于 Gin + Vue 的前后端分离权限管理系统脚手架,内置 JWT 鉴权、RBAC 权限控制、代码生成器、定时任务等功能,帮助开发者在 3 分钟内搭建自己的中后台项目。本文带你完整掌握 go-admin 生产部署的三种主流方式:Docker 单容器、docker-compose 编排、Kubernetes 集群部署,并对比它们的适用场景、操作步骤与常见坑点,帮你快速选出最合适的上线方案。
🧭 三种方案怎么选?一张表看懂
| 方案 | 复杂度 | 适用场景 | 典型用户 |
|---|---|---|---|
| Docker 单容器 | ⭐ 最简单 | 单机快速上线、临时验证 | 个人项目、内网系统 |
| docker-compose | ⭐⭐ 适中 | 单机正式服务、需要挂载配置/日志 | 小团队、长期运行的单体服务 |
| Kubernetes | ⭐⭐⭐ 较高 | 集群环境、统一运维体系 | 已有 K8s 平台的企业团队 |
选择建议:如果只有一台服务器,直接用 docker-compose(官方 Makefile 已内置一键命令);如果团队已有 Kubernetes 集群,项目也提供了开箱即用的清单文件,无需从零编写。
📋 部署前准备:两种方案通用的关键配置
无论用哪种方式上线,都先完成两件事:构建二进制文件 和 修改生产配置。
1. 构建静态二进制
go-admin 使用 Makefile 中的 build 目标即可打出体积精简、可直接放入镜像的静态二进制:
make build # 等价于 CGO_ENABLED=0 go build -ldflags="-w -s" -a -o go-admin .
2. 修改 settings.yml 生产配置
编辑 config/settings.yml,重点关注以下几项:
| 配置项 | 说明 | 生产建议 |
|---|---|---|
settings.application.mode |
运行模式 | 改为 prod |
settings.application.port |
服务端口,默认 8000 |
保持默认即可 |
settings.jwt.secret |
JWT 密钥 | 务必修改,默认值不适合上线 |
settings.jwt.timeout |
Token 过期时间(秒) | 默认 3600 |
settings.database.driver |
支持 mysql、sqlite3、postgres、sqlserver |
按环境选择 |
settings.database.source |
数据库连接串 | 填生产库地址与账号 |
settings.extend.rateLimit.inboundQPS |
全局限流,默认 200 QPS | 网关已限流时填 0 关闭 |
💡 提示:
settings.database中的maxOpenConns、connMaxLifeTime等连接池参数,配置文件内已附详细注释,高并发场景建议按需调整,否则可能出现 "can't assign requested address" 错误。
🐳 方案一:Docker 单容器部署(最快上手)
官方根目录的 Dockerfile 基于 Alpine 构建,只安装运行所需的最小依赖,并将预编译的二进制直接拷入镜像,最终镜像非常轻量。镜像启动时执行的命令为:
/main server -c /config/settings.yml
一键构建与启动
# 1. 构建镜像
docker build -t go-admin .
# 2. 启动容器,挂载配置、静态资源与日志目录
docker run --name go-admin \
-p 8000:8000 \
-v /your/path/config:/config \
-v /your/path/static:/static \
-v /your/path/temp:/temp \
-d --restart=always go-admin
要点说明:
- 容器内固定暴露
8000端口(见 Dockerfile 的EXPOSE 8000),宿主机侧可自行映射到任意端口; - 三个挂载目录各司其职:
config存放 settings.yml、static存放前端资源、temp存放日志(temp/logs); --restart=always保证服务器重启后服务自动恢复。
适合快速验证或单机简单上线,但缺少编排能力(无优雅停机配置),生产环境更推荐下面的方案。
🚀 方案二:docker-compose 部署(推荐新手生产使用)
项目根目录的 docker-compose.yml 是一份可直接投入生产使用的编排文件,配合 Makefile 只需两条命令:
# 进入项目根目录,先拉取代码(如尚未获取)
git clone https://gitcode.com/gh_mirrors/go/go-admin && cd go-admin
# 构建镜像并启动(build-linux 执行 docker build,run 执行 docker-compose up -d)
make build-linux
make run
compose 文件中值得关注的细节
官方 docker-compose.yml 里有两处对生产稳定性至关重要的配置:
stop_grace_period: 30s:go-admin 关闭时会依次执行"停止接收新请求 → 等待进行中的请求 → 清理回调"三个阶段(预算参数见 config/settings.yml 的extend.shutdown段)。默认的 10 秒不够用,会被 SIGKILL 强杀导致清理中断,因此官方给到了 30 秒;restart: always:容器异常退出后自动拉起,避免服务静默宕机。
升级与回滚流程
# 1. 部署新版本二进制后重新构建镜像
docker build -t go-admin:latest .
# 2. 停止旧容器(会等待 30 秒优雅停机)并启动新容器
docker-compose down
docker-compose up -d
停止与查看服务状态也可使用 Makefile 的 make stop 目标,逻辑与上面一致。
☸️ 方案三:Kubernetes 部署(集群环境)
项目内置了完整的 K8s 清单,位于 scripts/k8s/ 目录,包含三个文件:
| 文件 | 作用 |
|---|---|
| prerun.sh | 初始化脚本:创建 go-admin 命名空间 + 用 settings.yml 生成 ConfigMap |
| storage.yml | 创建 PersistentVolumeClaim,用于挂载 /static、/temp 日志目录 |
| deploy.yml | Service + Deployment 完整定义,含就绪/存活探针 |
部署步骤
# 1. 执行初始化脚本(创建命名空间和配置 ConfigMap)
bash scripts/k8s/prerun.sh
# 2. 应用存储与部署清单
kubectl apply -f scripts/k8s/storage.yml -n go-admin
kubectl apply -f scripts/k8s/deploy.yml -n go-admin
部署清单中的关键设计
官方 deploy.yml 在探针和停机预算上下了不少功夫,理解了它们能避开多数线上问题:
- 就绪探针指向
/api/v1/ready:数据库或缓存连不通时 Pod 自动摘除流量,避免"服务在但全报错"; - 存活探针指向
/api/v1/health:只做纯存活判断。刻意区分两个端点,是因为"数据库挂了"不应该触发 Pod 重启(重启解决不了问题); terminationGracePeriodSeconds: 30:与 docker-compose 方案同理,必须覆盖应用内部的优雅停机耗时;- ConfigMap 只读挂载
/config/:配置变更走 ConfigMap 更新流程,而不是直接改 Pod。
⚠️ 重要避坑:为什么副本数固定为 1?
deploy.yml 中 replicas 设为 1 并非偷懒,而是由 go-admin 当前的架构决定的:
- 定时任务冲突:任务调度器是进程级的,多个 Pod 会互相覆盖任务注册信息,导致任务重复执行或"禁用后仍生效";
- 日志文件竞争:多个副本共享同一 PVC,会同时追加写同一个滚动日志文件。
💡 结论:在 K8s 中请保持单副本部署,高可用通过"Deployment 自动重建 Pod + 外部网关"实现,而不是直接加副本。
✅ 部署后验证清单
三种方案上线后,按以下清单逐项确认:
- [ ] 访问
http://服务器IP:8000能看到登录页; - [ ] 健康检查
curl http://localhost:8000/api/v1/health返回 200; - [ ] 就绪检查
curl http://localhost:8000/api/v1/ready返回 200(数据库连通); - [ ] 日志正常输出到
temp/logs目录(或 K8s 的 stdout/挂载卷); - [ ] 已修改
jwt.secret、默认管理员密码等敏感项。
🔒 生产安全加固提醒
- 对外域名建议通过 Nginx/网关终结 TLS,而不是让服务直暴公网;
- 若网关已有限流能力,将
extend.rateLimit.inboundQPS设为0避免重复限流(超阈值请求会返回 HTTP 429); - 数据库账号使用最小权限原则,连接串不要明文提交进代码库。
📌 总结:三分钟回顾
| 场景 | 推荐方案 | 核心文件 |
|---|---|---|
| 快速验证 | Docker 单容器 | Dockerfile |
| 单机生产(推荐) | docker-compose | docker-compose.yml、Makefile |
| K8s 集群 | 内置清单 + 单副本 | scripts/k8s/ |
三种方案的本质是同一个 go-admin 二进制加上不同层级的编排:Docker 解决"环境一致",docker-compose 解决"配置持久化与自动恢复",Kubernetes 在此基础上补足了探针、滚动更新和存储编排。从单机起步、未来平滑迁移到集群,这条路径上的每个文件官方都已替你想好了。