Ubuntu 26.04 + Docker 搭建 Go Gin 开发环境（全记录）
从 Windows WSL2 无缝迁移到 Ubuntu 裸机，基于现有 MySQL/Redis 容器构建 Go 开发环境，并接入自定义网络。
📌 前言
之前一直在 Windows 10 + WSL2 中学习 go-gin-learning 项目，现在换到了全新的 Ubuntu 26.04 系统。希望继续使用 Docker 来隔离开发环境，同时复用已经部署好的 MySQL 8.0 和 Redis 7.2 容器（位于自定义网络 services_dev-network 中）。
本文记录了从零开始配置的全部步骤，包含：
- 系统工具检查与安装
- Docker 环境验证
- 项目代码克隆
- 编写 Dockerfile 预装
git - 编写 docker-compose.yml 接入现有网络
- 容器内运行 Gin 应用并测试连通性
- 常见问题与避坑建议
🧰 一、准备工作：检查系统已有工具
在 Ubuntu 中养成“先检查，后安装”的习惯，可以避免重复操作。
1.1 检查 Git
git --version
输出示例（已安装）：
git version 2.53.0
若未安装，执行：
sudo apt install git -y
1.2 检查 Docker
docker --version
docker compose version
输出示例：
Docker version 29.5.2, build 79eb04c
Docker Compose version v5.1.4
若未安装，请参考 Docker 官方文档 安装。
✅ 建议：将当前用户加入
docker组，避免每次输入sudo：sudo usermod -aG docker $USER然后注销并重新登录。
🌐 二、确认已有数据库网络环境
之前已经在 ~/docker/services 中通过 docker-compose.yml 运行了 MySQL 8.0 和 Redis 7.2，并创建了自定义网络 services_dev-network。
2.1 查看网络
docker network ls | grep dev-network
输出：
71f462c6ef91 services_dev-network bridge local
2.2 查看数据库容器状态
docker ps --filter "name=mysql80" --filter "name=redis72"
输出：
CONTAINER ID IMAGE ... NAMES
9ec38ca384b6 redis:7.2 ... redis72
4e93fd2e2c3f mysql:8.0 ... mysql80
💡 关键信息：
- MySQL 容器名：
mysql80，内部端口 3306，宿主机映射端口 3307- Redis 容器名：
redis72，内部端口 6379- 网络名：
services_dev-network（注意前缀，由~/docker/services目录名派生）
📁 三、创建代码目录并克隆项目
选择一个语义清晰的目录存放项目代码，这里使用 ~/code（全小写，符合 Linux 惯例）。
mkdir -p ~/code
cd ~/code
git clone https://github.com/shuijingwan/go-gin-learning.git
cd go-gin-learning
检查项目结构：
ls -la
🐳 四、编写 Dockerfile（预装 git）
为了不在每次进入容器时手动安装 git，我们创建一个自定义镜像。
创建 Dockerfile：
FROM golang:1.26-alpine
# 安装 git（go mod 下载某些依赖时需要）
RUN apk add --no-cache git
# 设置工作目录，与后面的 docker-compose 保持一致
WORKDIR /code
# 保持容器运行（开发模式）
CMD ["tail", "-f", "/dev/null"]
📌 说明：
- 使用 Alpine 版本镜像，体积小
apk add --no-cache不保留缓存，减小镜像大小WORKDIR /code后续可以省略 docker-compose 中的working_dir，但为了明确，两边都保留也没问题
⚙️ 五、编写 docker-compose.yml（接入现有网络）
关键点：
- 使用
build: .而不是image: ... - 加入外部网络
services_dev-network - 传递数据库连接所需的环境变量
- 删除已过时的
version字段
最终 docker-compose.yml 内容：
services:
go:
build: .
container_name: go-gin-learning
working_dir: /code
volumes:
- ./:/code
ports:
- "8080:8080"
tty: true
stdin_open: true
environment:
- GOPROXY=https://goproxy.io,direct
- GOSUMDB=sum.golang.google.cn
- CGO_ENABLED=0
# 数据库连接配置（使用现有网络中的服务名）
- DB_HOST=mysql80
- DB_PORT=3306
- DB_USER=root
- DB_PASSWORD=mystrongpwd80
- DB_NAME=go_gin
- REDIS_HOST=redis72
- REDIS_PORT=6379
- REDIS_PASSWORD=myredispass
networks:
- services_dev-network
networks:
services_dev-network:
external: true
⚠️ 注意：
DB_PASSWORD和REDIS_PASSWORD要与~/docker/services/docker-compose.yml中的密码完全一致。- 容器间通信使用内部端口 3306 和 6379，而不是宿主机映射的 3307。
🚀 六、构建并启动开发容器
# 停止并删除旧容器（如果有）
docker compose down
# 构建镜像（--no-cache 确保重新安装 git）
docker compose build --no-cache
# 启动容器（后台运行）
docker compose up -d
查看运行状态：
docker ps --filter "name=go-gin-learning"
🧪 七、进入容器并验证连接
7.1 进入容器
docker exec -it go-gin-learning sh
此时提示符变为 /code #。
7.2 验证 git 已安装
git --version
应输出类似 git version 2.52.0。
7.3 测试网络连通性
# 安装测试工具（仅调试用，正式镜像可不加）
apk add iputils mysql-client redis
# ping 数据库容器
ping -c 2 mysql80
ping -c 2 redis72
7.4 测试 MySQL 连接（禁用 SSL）
MySQL 8.0 默认要求 SSL，但在容器内部使用 --ssl=0 即可绕过证书验证：
mariadb -h mysql80 -P 3306 -u root -pmystrongpwd80 -e "SHOW DATABASES;" --ssl=0
预期输出：如图1
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
| performance_schema |
| sys |
+--------------------+
💡 若使用
mysql命令，请用--ssl-mode=DISABLED。
7.5 测试 Redis 连接
redis-cli -h redis72 -a myredispass PING
预期输出：如图2
PONG
🏃 八、运行 Gin 应用
在容器内执行：
go run main.go
看到如下日志表示成功：如图3
go: downloading github.com/go-playground/locales v0.14.1
[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
- using env: export GIN_MODE=release
- using code: gin.SetMode(gin.ReleaseMode)
[GIN-debug] GET /albums --> main.getAlbums (3 handlers)
[GIN-debug] GET /albums/:id --> main.getAlbumByID (3 handlers)
[GIN-debug] POST /albums --> main.postAlbums (3 handlers)
[GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value.
Please check https://github.com/gin-gonic/gin/blob/master/docs/doc.md#dont-trust-all-proxies for details.
[GIN-debug] Listening and serving HTTP on 0.0.0.0:8080
[GIN] 2026/06/03 - 11:19:14 | 404 | 1.219µs | 172.18.0.1 | GET "/"
[GIN] 2026/06/03 - 11:19:14 | 404 | 778ns | 172.18.0.1 | GET "/favicon.ico"
[GIN] 2026/06/03 - 11:19:45 | 200 | 147.412µs | 172.18.0.1 | GET "/albums"
在宿主机测试 API
打开另一个终端，执行：
curl http://localhost:8080/albums
或直接在浏览器访问 http://localhost:8080/albums。
📸 浏览器显示 JSON 数据，如图4
🧹 九、常用管理命令
| 操作 | 命令 |
|---|---|
| 启动开发容器 | cd ~/code/go-gin-learning && docker compose up -d |
| 停止容器 | docker compose down |
| 重新构建镜像 | docker compose build --no-cache |
| 查看日志 | docker compose logs -f |
| 进入容器 | docker exec -it go-gin-learning sh |
| 重启 MySQL/Redis（若需要） | cd ~/docker/services && docker compose restart |
⚠️ 十、避坑指南
10.1 容器内 git 缺失导致 go run 失败
现象：
unable to resolve git version: exec: "git": executable file not found in $PATH
解决：使用自定义 Dockerfile 安装 git，见第四章。
10.2 MySQL 连接报 TLS/SSL 错误
现象：
ERROR 2026 (HY000): TLS/SSL error: Certificate verification failure
解决：在连接命令中添加 --ssl=0（mariadb）或 --ssl-mode=DISABLED（mysql）。
10.3 容器无法访问 MySQL/Redis
原因：未加入正确的网络，或网络名称写错。
解决：
- 确认
docker network ls中有services_dev-network - 检查 docker-compose.yml 中
networks名称是否完全一致（包括下划线） - 在容器内
ping mysql80测试
10.4 宿主机无法访问 8080 端口
原因：Gin 监听的是 127.0.0.1:8080 而不是 0.0.0.0:8080，导致端口映射失效。
解决：在代码中设置 router.Run(":8080") 或 router.Run("0.0.0.0:8080")。
📝 十一、总结
通过本次实践，我实现了：
- ✅ 在 Ubuntu 26.04 上搭建完整的 Go 开发环境
- ✅ 利用已有的 MySQL/Redis 容器（独立部署）和自定义网络
- ✅ 构建带
git的 Go 1.26 Alpine 开发镜像 - ✅ 编写 docker-compose.yml 挂载代码并接入外部网络
- ✅ 在容器内成功运行 Gin 应用并验证数据库连通性
这种“数据库与代码分离容器”的模式非常适合多项目共用基础设施，既节省资源，又保持环境一致性。
下一步，便可以：
- 在
main.go中编写连接 MySQL/Redis 的业务逻辑 - 使用任意代码编辑器（如 VS Code、Sublime 等）直接编辑项目文件，保存后容器内实时同步
- 将
docker-compose.yml加入版本控制，与队友共享环境配置
