gitlab-local-deployment

本机 GitLab 部署整理

整理时间：2026-05-05

1. 部署方式

本机 GitLab 不是直接安装在宿主机系统里的，而是通过 Docker 容器运行。

• 容器名：gitlab
• 当前运行镜像：gitlab/gitlab-ce:18.7.0-ce.0
• 容器状态：Up 5 days (healthy)

说明：

• /home/zbc/gitlab.sh 中的历史启动命令使用的是 gitlab/gitlab-ce:13.12.2-ce.0
• 当前实际运行容器版本已经是 18.7.0-ce.0
• 因此 gitlab.sh 可视为旧脚本，不能完全代表当前在线环境

2. 宿主机路径

GitLab 在宿主机上的主目录为：

/home/gitlab

主要子目录如下：

• 配置目录：/home/gitlab/data/etc
• 数据目录：/home/gitlab/data/opt
• 日志目录：/home/gitlab/logs
• 备份目录：/home/gitlab/压缩包/GitLab备份
• 旧配置备份目录：/home/gitlab/conf

相关文件：

• 活动配置文件：/home/gitlab/data/etc/gitlab.rb
• 活动密钥文件：/home/gitlab/data/etc/gitlab-secrets.json
• 历史配置备份：/home/gitlab/conf/gitlab.rb.20251225-18.6.1
• 历史密钥备份：/home/gitlab/conf/gitlab-secrets.json.20251225-18.6.1
• GitLab 备份脚本：/home/gitlab/backup.sh
• MinIO 备份脚本：/home/gitlab/minio_backup.sh

3. 容器挂载关系

当前运行容器的挂载关系如下：

• /home/gitlab/data/etc -> /etc/gitlab
• /home/gitlab/data/opt -> /var/opt/gitlab
• /home/gitlab/logs -> /var/log/gitlab

含义：

• 宿主机上的 /home/gitlab/data/etc 保存 GitLab 配置
• 宿主机上的 /home/gitlab/data/opt 保存 GitLab 业务数据
• 宿主机上的 /home/gitlab/logs 保存 GitLab 日志

4. 当前访问入口

本机 IP：

• 192.168.3.103

容器端口映射：

• 3322 -> 22/tcp
• 9980 -> 80/tcp

由此可得本机访问入口：

• Git SSH：ssh://git@192.168.3.103:3322/<group>/<repo>.git
• Web HTTP：http://192.168.3.103:9980

GitLab 活动配置中的关键设置：

external_url 'https://gitlab.898311.xyz'
 
nginx['listen_port'] = 80
nginx['listen_https'] = false

说明：

• GitLab 容器内部当前只监听 HTTP 80
• external_url 配置为 https://gitlab.898311.xyz
• 这说明 HTTPS 很可能由容器外部的反向代理或其他入口负责终止

5. 仓库远程地址

当前 GeneralAndroid 仓库远程地址为：

ssh://git@gitlab.898311.xyz:3322/zbc/GeneralAndroid.git

如果从本机局域网直连，也可按端口映射使用：

ssh://git@192.168.3.103:3322/zbc/GeneralAndroid.git

6. 空间占用

当前已确认的目录占用：

• /home/gitlab：约 358G
• /home/gitlab/data/etc：约 188K
• /home/gitlab/data/opt：约 336K
• /home/gitlab/logs：约 20M
• /home/gitlab/压缩包：约 358G

结论：

• 当前空间几乎都占用在 /home/gitlab/压缩包
• 主体是离线打包备份文件

7. 本地备份文件

目录：

/home/gitlab/压缩包/GitLab备份

当前已发现备份：

gitlab_backup_20260409_021936.tar.gz   60G
gitlab_backup_20260410_022116.tar.gz   60G
gitlab_backup_20260411_022246.tar.gz   60G
gitlab_backup_20260423_023546.tar.gz   60G
gitlab_backup_20260424_024142.tar.gz   60G
gitlab_backup_20260429_024524.tar.gz   62G

总量约：

• 358G

8. 其他已发现内容

/home/gitlab 下还存在以下与运维相关的内容：

• backup.lock
• minio_backup.lock
• minio_backup.status
• cleanup_remote_backups.py
• cleanup_remote_backups.cpython-312.pyc

说明这些备份流程可能已经配套了远端清理或状态记录脚本。

9. 结论

这台机器上的 GitLab 可以概括为：

1. 运行方式是 Docker 容器，不是宿主机原生安装。
2. 宿主机核心目录在 /home/gitlab。
3. 配置在 /home/gitlab/data/etc，数据在 /home/gitlab/data/opt，日志在 /home/gitlab/logs。
4. 本机 Web 入口是 http://192.168.3.103:9980，SSH 入口是 192.168.3.103:3322。
5. 当前最大磁盘占用来自 /home/gitlab/压缩包/GitLab备份 下的大体积备份文件。

10. 典型故障案例：push 被 pre-receive hook 拒绝

现象：

remote: Internal API unreachable
fatal: 无法读取远程仓库。

或：

remote: calling pre_receive endpoint: http post to gitlab api /pre_receive endpoint: Internal API error (500)
! [remote rejected] master -> master (pre-receive hook declined)

这类报错看起来像 Git 权限或仓库异常，但这次实际根因是 GitLab 容器内的 Rails/Puma 服务不可用，导致 pre-receive 依赖的内部 API 调用失败。

10.1 本次实际根因

排查结果：

• GitLab 运行在 Docker 容器 gitlab 中
• 容器内 /dev/shm 只有 64M
• /dev/shm 被 Puma 的 Prometheus mmap 指标文件打满，达到 100%
• GitLab Rails 日志出现：

exception.message: "unmapped file"

以及：

writing value to /dev/shm/gitlab/puma/gauge_all_puma_*.db failed with unmapped file

直接影响：

• POST /api/:version/internal/allowed 报错
• push 过程中 pre-receive hook 调 GitLab 内部 API 失败
• 最终表现为 Internal API unreachable 或 pre-receive hook declined

10.2 快速确认命令

检查容器服务状态：

docker exec gitlab gitlab-ctl status

检查 /dev/shm 是否打满：

docker exec gitlab df -h /dev/shm

检查 Puma 指标文件：

docker exec gitlab ls /dev/shm/gitlab/puma

检查日志关键词：

docker exec gitlab sh -lc "grep -RIn 'unmapped file\|Internal API error\|pre_receive' /var/log/gitlab/gitlab-rails /var/log/gitlab/gitaly /var/log/gitlab/gitlab-shell 2>/dev/null | tail -100"

10.3 临时恢复办法

如果已经卡住，最快恢复方式是重启容器：

docker restart gitlab

然后等待 Puma 恢复监听：

docker exec gitlab sh -lc 'tail -50 /var/log/gitlab/puma/current'

看到类似：

Listening on unix:///var/opt/gitlab/gitlab-rails/sockets/gitlab.socket
Listening on http://127.0.0.1:8080

说明 Rails/Puma 基本恢复，可以再重试 push。

10.4 长期修复办法

根因不是仓库内容，而是 Docker 默认 /dev/shm 太小。

建议把 GitLab 容器共享内存直接调到 1G：

docker run --shm-size=1g ...

本机脚本 /home/zbc/gitlab.sh 已调整为：

sudo docker run -itd --shm-size=1g -p 9980:80 -p 3322:22 -v /home/gitlab/logs/:/var/log/gitlab -v /home/gitlab/data/opt:/var/opt/gitlab -v /home/gitlab/data/etc:/etc/gitlab --privileged=true --name=gitlab --restart always gitlab/gitlab-ce:13.12.2-ce.0

注意：修改脚本后不会自动影响当前容器，必须重建容器才能生效：

docker stop gitlab
docker rm gitlab
bash /home/zbc/gitlab.sh

因为配置、数据、日志都已经挂载到 /home/gitlab/...，正常情况下重建容器不会丢仓库数据。

11. 运维手册

本节面向日常维护，默认操作者具备宿主机 sudo 权限，并可执行 Docker 命令。

11.1 常用路径速查

• GitLab 宿主机根目录：/home/gitlab
• 活动配置：/home/gitlab/data/etc/gitlab.rb
• 活动密钥：/home/gitlab/data/etc/gitlab-secrets.json
• GitLab 数据：/home/gitlab/data/opt
• GitLab 日志：/home/gitlab/logs
• 本地备份目录：/home/gitlab/压缩包/GitLab备份
• 旧配置备份：/home/gitlab/conf
• 启动脚本：/home/zbc/gitlab.sh

11.2 常用访问入口

• Web：http://192.168.3.103:9980
• SSH：ssh://git@192.168.3.103:3322/<group>/<repo>.git
• 域名远程地址：ssh://git@gitlab.898311.xyz:3322/<group>/<repo>.git

说明：

• external_url 当前配置是 https://gitlab.898311.xyz
• 但容器内部 Nginx 监听的是 HTTP 80
• 如果外部用户通过 HTTPS 正常访问，说明外层还有单独的 HTTPS 代理层

11.3 容器日常操作

查看容器状态：

docker ps -a --filter name=gitlab

查看容器详细端口：

docker inspect gitlab --format '{{json .HostConfig.PortBindings}}'

查看容器挂载：

docker inspect gitlab --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

启动容器：

docker start gitlab

停止容器：

docker stop gitlab

重启容器：

docker restart gitlab

进入容器 shell：

docker exec -it gitlab bash

11.4 GitLab 内部服务检查

检查 GitLab 各组件状态：

docker exec gitlab gitlab-ctl status

查看 GitLab 版本：

docker exec gitlab gitlab-rake gitlab:env:info

查看实时日志：

docker exec -it gitlab gitlab-ctl tail

只看 Puma 日志：

docker exec gitlab sh -lc 'tail -100 /var/log/gitlab/puma/current'

只看 Rails 日志：

docker exec gitlab sh -lc 'tail -100 /var/log/gitlab/gitlab-rails/production_json.log'

只看 Nginx 日志：

docker exec gitlab sh -lc 'tail -100 /var/log/gitlab/nginx/gitlab_access.log'
docker exec gitlab sh -lc 'tail -100 /var/log/gitlab/nginx/gitlab_error.log'

11.5 配置修改流程

宿主机配置文件：

/home/gitlab/data/etc/gitlab.rb

标准修改流程：

1. 备份当前配置
2. 修改 gitlab.rb
3. 执行 gitlab-ctl reconfigure
4. 检查服务状态和日志
5. 验证 Web / Git SSH 是否恢复正常

示例命令：

cp /home/gitlab/data/etc/gitlab.rb /home/gitlab/conf/gitlab.rb.$(date +%F-%H%M%S)

vim /home/gitlab/data/etc/gitlab.rb

docker exec gitlab gitlab-ctl reconfigure

docker exec gitlab gitlab-ctl status

docker exec gitlab sh -lc 'tail -100 /var/log/gitlab/reconfigure/current'

注意：

• gitlab.rb 修改后不会自动生效
• 必须执行 gitlab-ctl reconfigure
• 如果只是修改少量运行时配置，也建议至少执行一次 gitlab-ctl restart

11.6 常见配置项

当前确认的关键配置：

external_url 'https://gitlab.898311.xyz'
nginx['listen_port'] = 80
nginx['listen_https'] = false

常见调整方向：

• 站点访问域名：external_url
• Git SSH 对外域名：gitlab_rails['gitlab_ssh_host']
• SMTP 邮件：gitlab_rails['smtp_*']
• 备份相关参数
• 上传、超时、代理相关设置

修改前建议先保存一份时间戳备份。

11.7 备份操作

本机已存在备份脚本：

• /home/gitlab/backup.sh
• /home/gitlab/minio_backup.sh

本地 GitLab 备份目录：

/home/gitlab/压缩包/GitLab备份

如果使用 GitLab 自带备份命令，可在容器内执行：

docker exec -t gitlab gitlab-backup create

执行后通常会在容器内的：

/var/opt/gitlab/backups

也就是宿主机的：

/home/gitlab/data/opt/backups

生成备份文件。

建议备份后再统一转移或归档到：

/home/gitlab/压缩包/GitLab备份

11.8 备份校验

查看本地备份文件：

ls -lh /home/gitlab/压缩包/GitLab备份

查看容器内标准备份目录：

ls -lh /home/gitlab/data/opt/backups

检查最近备份时间：

ls -lt /home/gitlab/压缩包/GitLab备份 | head

检查备份总占用：

du -sh /home/gitlab/压缩包/GitLab备份

11.9 恢复操作注意事项

恢复前必须明确：

• 恢复的是哪一天的备份
• 当前线上数据是否需要先做一次新备份
• 是否允许覆盖当前 GitLab 数据

恢复的一般思路：

1. 停止可能写入 GitLab 的外部操作
2. 备份当前配置和当前数据
3. 将目标备份包放到 GitLab 可识别目录
4. 按 GitLab 官方恢复流程执行 gitlab-backup restore
5. 执行 gitlab-ctl reconfigure
6. 重启服务并验证

因为恢复属于高风险操作，正式执行前建议单独写恢复步骤确认单，不要直接在生产上临时操作。

11.10 空间治理

当前磁盘压力主要来自：

/home/gitlab/压缩包/GitLab备份

先看目录占用：

du -sh /home/gitlab /home/gitlab/压缩包 /home/gitlab/data/opt /home/gitlab/logs

看备份文件时间和大小：

ls -lh /home/gitlab/压缩包/GitLab备份

建议治理策略：

1. 先确认远端是否已有可靠副本
2. 保留最近 N 份本地完整备份
3. 删除超过保留期的离线归档
4. 删除前记录文件名、日期、大小
5. 删除后重新核对磁盘占用

删除前建议先做列表存档：

ls -lh /home/gitlab/压缩包/GitLab备份 > /home/gitlab/压缩包/gitlab-backup-list-$(date +%F).txt

11.11 升级或重建容器

当前线上容器版本：

gitlab/gitlab-ce:18.7.0-ce.0

如果要升级或重建，原则是：

• 不直接依赖旧脚本中的镜像版本
• 先核对当前运行版本
• 确保挂载目录不变
• 先做备份再重建

建议流程：

1. 备份 gitlab.rb 和 gitlab-secrets.json
2. 备份当前 GitLab 数据
3. 记录当前端口和挂载配置
4. 停容器
5. 删除旧容器
6. 用新镜像和相同挂载重建
7. 验证服务、日志、Web、SSH

基础命令：

docker stop gitlab
docker rm gitlab

然后按新的启动命令重建。

注意：

• 重建容器本身不应丢数据，前提是宿主机挂载目录没有变化
• 但跨大版本升级必须结合 GitLab 官方升级路径，不要跳版本乱升

11.12 HTTPS 反向代理核查

当前存在一个结构特征：

• GitLab 自身监听 HTTP 80
• external_url 却配置成 HTTPS 域名

这通常意味着外层还有反向代理。

建议核查项：

• 宿主机是否还有 Nginx
• 是否有 Caddy、Traefik 或其他反代
• 是否由网关设备或云负载均衡做 TLS 终止

排查方向：

ss -ltnp

docker ps -a

find /etc/nginx /etc/caddy -maxdepth 3 -type f 2>/dev/null

11.13 日常巡检建议

建议定期检查以下项目：

1. docker ps 中 gitlab 是否为 healthy
2. gitlab-ctl status 中关键服务是否都在运行
3. /home/gitlab/压缩包/GitLab备份 是否持续增长
4. 是否存在最新可用备份
5. production_json.log 中是否持续出现 500 错误
6. /dev/shm 是否再次接近打满

巡检命令示例：

docker ps -a --filter name=gitlab
docker exec gitlab gitlab-ctl status
docker exec gitlab df -h /dev/shm
du -sh /home/gitlab/压缩包/GitLab备份

11.14 变更前最小检查清单

在修改配置、重建容器、清理备份、做恢复前，至少确认：

1. 当前有可用备份
2. 关键配置文件已单独备份
3. 已记录当前镜像版本、端口映射、挂载目录
4. 已评估业务影响窗口
5. 已准备回滚方案

11.15 风险提示

当前环境至少有两个明确风险：

1. /home/zbc/gitlab.sh 仍写着旧版本镜像，直接拿它重建可能导致版本回退或不一致
2. 本地备份目录已达 358G，如果不做保留策略，磁盘压力会持续增长

建议后续至少补两件事：

1. 把当前线上真实启动参数整理成新的标准启动脚本
2. 建立本地备份保留策略和定期清理策略