使用 Docker 部署 GitLab：再配置external_url 无法访问
使用 Docker 部署 GitLab 的完整实践指南在现代 DevOps 工作流中私有代码仓库是必不可少的基础设施。GitLab 凭借其强大的代码管理、CI/CD 和项目管理功能成为很多团队的首选。本文将以最简洁的方式记录如何使用 Docker 在一台服务器上快速部署 GitLab CE 版本并分享过程中容易遇到的陷阱和解决方法。环境与准备服务器一台 Linux 主机本文以 IP192.168.1.156为例请根据实际情况替换Docker已安装 Docker Engine持久化目录提前创建用于存放配置、日志和数据的宿主机目录mkdir-p/usr/local/gitlab/{config,logs,data}启动 GitLab 容器使用的docker run命令如下附带详细说明sudodockerrun-d\--hostname192.168.1.156\--namegitlab\--restartalways\--shm-size1g\-p8012:8012\-v/etc/localtime:/etc/localtime:ro\-v/usr/local/gitlab/config:/etc/gitlab\-v/usr/local/gitlab/logs:/var/log/gitlab\-v/usr/local/gitlab/data:/var/opt/gitlab\-eGITLAB_OMNIBUS_CONFIGexternal_url http://192.168.1.156:8012;\gitlab/gitlab-ce:latest参数解读--hostname设置 GitLab 实例的主机名这里直接使用内网 IP实际生产环境建议替换为可解析的域名。--restart always保证容器在退出或宿主机重启后自动启动。shm-size: 配置容器共享内存大小。端口映射8012:8012→ HTTP 访问端口也是我们浏览器访问的入口容器内默认为808013:22→ SSH 端口用于 Git 操作注意宿主机 22 端口通常已被占用此处映射为 8013 避免冲突不适用ssh可以忽略8011:443→ HTTPS 访问端口如需证书需自行配置否则可以忽略卷挂载核心/etc/localtime:ro保持容器内时间与宿主机同步避免时区问题。/usr/local/gitlab/config→/etc/gitlab存放 GitLab 配置文件包括gitlab.rb以及初次启动时生成的初始密码文件initial_root_password。/usr/local/gitlab/logs→/var/log/gitlab运行日志排错必备。/usr/local/gitlab/data→/var/opt/gitlab最重要的数据目录代码仓库、用户信息、Issue、上传附件等所有持久化数据都保存在这里务必妥善备份。首次启动会拉取镜像并初始化数据库耗时可能较长约 2-5 分钟可使用docker logs -f gitlab查看进度直到出现gitlab Reconfigured!之类信息即表示启动成功。获取并修改 root 初始密码GitLab 从较新版本开始默认不再使用固定的初始密码而是在初次启动时随机生成一个密码并存储在容器的/etc/gitlab/initial_root_password文件中。由于我们已将config目录挂载出来因此可以直接在宿主机查看cat/usr/local/gitlab/config/initial_root_password输出示例# WARNING: This value is valid only in the following conditions # 1. If provided manually (either via GITLAB_ROOT_PASSWORD environment variable or via gitlab_rails[initial_root_password] setting in gitlab.rb, it is provided directly before database is seeded for the first time (usually, the first reconfigure run). # ... (注释省略) Password: 9aBcD3FgHijkLm注意该密码文件会在 24 小时后被自动删除因尽快登录并修改 root 密码。可以通过命令行重置密码# 进入容器内部dockerexec-itgitlab /bin/bash# 执行密码重置按照提示输入两次新密码gitlab-rakegitlab:password:reset[root]或者直接一条命令搞定dockerexec-itgitlab gitlab-rakegitlab:password:reset[root]按照提示输入新密码后即可使用新密码登录。访问 GitLab 并登录在浏览器中访问http://192.168.1.156:8012使用用户名root和设置或查到的密码登录。成功登录后可以创建项目、管理用户配置 SSH 密钥若使用 SSH 方式推送代码需将远端地址中的端口指定为8013例如ssh://git192.168.1.156:8013/username/repo.git调整系统设置建议在/usr/local/gitlab/config/gitlab.rb中修改外部 URL 等配置后执行docker exec -it gitlab gitlab-ctl reconfigure使其生效遇到问题原启动命令sudodockerrun-d\--hostname192.168.233.156\--namegitlab\--restartalways\-p8012:80\-v/etc/localtime:/etc/localtime:ro\-v/usr/local/gitlab/config:/etc/gitlab\-v/usr/local/gitlab/logs:/var/log/gitlab\-v/usr/local/gitlab/data:/var/opt/gitlab\swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/gitlab/gitlab-ce:latest一. 频繁出现 500 或 502 错误部署后偶尔出现页面 500/502 错误刷新几次可能恢复正常这通常不是 GitLab 服务本身崩溃而是由服务器磁盘空间不足引起的。后台大量打印如下类似日志{“severity”:“DEBUG”,“time”:“2026-08-04T03:14:10.987Z”,“message”:“/opt/gitlab/embedded/lib/ruby/gems/3.2.0/gems/prometheus-client-mmap-1.2.10-x86_64-linux-gnu/lib/prometheus/client/mmaped_dict.rb:46:inupsert_entry\n/opt/gitlab/embedded/lib/ruby/gems/3.2.0/gems/prometheus-client-mmap-1.2.10-x86_64-linux-gnu/lib/prometheus/client/mmaped_dict.rb:46:inwrite_value’\n/opt/gitlab/embedded/lib/ruby/gems/3.2.0/gems/prometheus-client-mmap-1.2.10-x86_64-linux-gnu/lib/prometheus/client/mmaped_value.rb:139:inwrite_value\n/opt/gitlab/embedded/lib/ruby/gems/3.2.0/gems/prometheus-client-mmap-1.2.10-x86_64-linux-gnu/lib/prometheus/client/mmaped_value.rb:48:inblock in set’\n/opt/gitlab/embedded/lib/ruby/gems/3.2.0/gems/prometheus-client-mmap-1.2.10-x86_64-linux-gnu/lib/prometheus/client/mmaped_value.rb:44:insynchronize\n/opt/gitlab/embedded/lib/ruby/gems/3.2.0/gems/prometheus-client-mmap-1.2.10-x86_64-linux-gnu/lib/prometheus/client/mmaped_value.rb:44:inset’\n/opt/gitlab/embedded/lib/ruby/gems/3.2.0/gems/prometheus-client-mmap-1.2.10-x86_64-linux-gnu/lib/prometheus/client/gauge.rb:28:inset\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/samplers/threads_sampler.rb:41:inset_running_threads’\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/samplers/threads_sampler.rb:33:inblock in sample\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/samplers/threads_sampler.rb:30:ineach’\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/samplers/threads_sampler.rb:30:insample\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/samplers/base_sampler.rb:30:insafe_sample’\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/samplers/base_sampler.rb:80:inblock in run_thread\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/samplers/base_sampler.rb:89:inblock in wrap_sampler’\n/opt/gitlab/embedded/lib/ruby/gems/3.2.0/gems/activesupport-7.1.5.1/lib/active_support/execution_wrapper.rb:92:inwrap\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/samplers/base_sampler.rb:89:inwrap_sampler’\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/metrics/samplers/base_sampler.rb:80:inrun_thread\n/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/daemon.rb:58:inblock (2 levels) in start’”}{“severity”:“WARN”,“time”:“2026-08-04T03:14:10.988Z”,“message”:“writing value to /dev/shm/gitlab/puma/gauge_all_puma_2-0.db failed with unmapped file”}问题分析writing value to /dev/shm/gitlab/puma/gauge_all_puma_2-0.db failed with unmapped file表明GitLab 尝试向 /dev/shm 目录写入文件时失败。/dev/shm 是Linux系统的共享内存tmpfs 目录Docker容器默认大小通常仅为 64MB。连锁反应当 /dev/shm 空间耗尽GitLab 的 prometheus-client-mmap 组件无法写入指标数据便会不断重试并产生大量 DEBUG 和 WARN 级别日志。解决方法清理宿主机磁盘占用情况并清理。增加 Docker 容器的共享内存大小–shm-size1g 或者 --shm-size512m二. 创建仓库初始化地址以及仓库链接地址都没带上8012端口使用的是默认的80端口无法访问和跳转。GitLab容器因端口映射宿主机8012→容器80导致生成的链接丢失:8012根源在于external_url未配置真实访问地址默认不含端口。解决方案修改gitlab.rb中的external_url为http://IP:8012解决方法停止容器docker stop gitlab删除容器docker rm gitlab新建容器sudo docker run -d–hostname 192.168.1.156–name gitlab–restart always–shm-size1g-p 8012:8012-v /etc/localtime:/etc/localtime:ro-v /usr/local/gitlab/config:/etc/gitlab-v /usr/local/gitlab/logs:/var/log/gitlab-v /usr/local/gitlab/data:/var/opt/gitlab-e GITLAB_OMNIBUS_CONFIG“external_url ‘http://192.168.1.156:8012’;”gitlab/gitlab-ce:latest插曲之前添加 -e GITLAB_OMNIBUS_CONFIG“external_url ‘http://192.168.1.156:8012’;” \后依然使用 -p 8012:80导致无法访问。GitLab Omnibus 的 external_url 会直接决定容器内 Nginx 的监听端口。配置了 external_url ‘http://…:8012’ 后容器内的 Nginx 便会监听 8012而不再监听 80。因此 -p 8012:80 将宿主机请求转发到了容器内无人监听的 80 端口导致无法连接。安全与运维建议密码与文件安全务必在首次登录后修改 root 密码并注意/usr/local/gitlab/config/initial_root_password文件的保密性。数据备份重点保护/usr/local/gitlab/data目录可使用tar或 GitLab 自带的gitlab-backup命令定期备份并传输至异地。网络与防火墙若只对内网服务建议在宿主机防火墙上仅开放需要的端口如 8012避免将 22 映射到公网。HTTPS 配置生产环境建议配合 Nginx 反向代理或直接在 GitLab 配置中启用 SSL此时需挂载证书文件并修改对应的external_url。时区一致性挂载/etc/localtime保证了日志时间正确对于排错和时间敏感型操作如 CI 定时触发很重要。总结通过 Docker 部署 GitLab 十分简便只需一条docker run命令就能获得一个全功能代码托管平台。关键点在于正确挂载数据卷尤其是data目录保证数据持久化。及时获取并修改 root 密码避免因密码文件 24 小时自动删除而无法登录。注意磁盘空间健康避免因空间耗尽导致服务异常。如果在部署过程中遇到其他问题欢迎在评论区交流讨论。愿你我都能在各自的领域里不断成长勇敢追求梦想同时也保持对世界的好奇与善意!
)
