GitLab 单机私有化部署文档（基于 Docker 环境）

本文档介绍了如何在独立的 Linux 服务器上，使用原生的 Docker 部署和运维单机版 GitLab (Omnibus)。

1. 核心架构与规划

项目	说明
容器运行时	Docker Engine
部署方式	单容器 Omnibus 镜像部署
数据目录	/data/gitlab
端口映射	80:80（HTTP）、443:443（HTTPS）、2222:22（SSH）

2. 环境准备 (安装 Docker)

在独立的服务器上，推荐使用官方的一键安装脚本快速部署 Docker 环境。

2.1 安装 Docker Engine

在 Ubuntu 系统上，执行以下命令安装 Docker 及其相关组件。我们提供了阿里云镜像源（推荐，国内速度快）和官方源两种选择，请根据您的服务器网络环境任选其一执行：

选项 A：使用阿里云镜像源安装 (国内服务器推荐)

# 1. 更新源并安装基础依赖工具
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

# 2. 添加 Docker 阿里云官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 3. 设置稳定版 Docker 阿里云仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 4. 安装 Docker Engine、CLI 和 Compose 插件
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

选项 B：使用官方源安装 (海外服务器推荐)

# 1. 更新源并安装基础依赖工具
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

# 2. 添加 Docker 官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 3. 设置稳定版 Docker 官方仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 4. 安装 Docker Engine、CLI 和 Compose 插件
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

2.2 配置 Docker 镜像加速 (推荐)

为了提升拉取 GitLab 官方镜像的速度，建议配置国内的镜像加速器：

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}
EOF

(注：同时配置了日志轮转，防止长时间运行后容器日志撑爆磁盘)

2.3 启动 Docker 并验证

# 启动并设置开机自启
sudo systemctl enable --now docker

# 验证安装
sudo docker version
sudo docker info

3. 部署 GitLab

3.1 创建数据挂载目录

为了保证数据持久化，需要将 GitLab 的配置、日志和数据挂载到宿主机：

sudo mkdir -p /data/gitlab/{config,logs,data}
sudo chmod 777 -R /data/gitlab

3.2 编写 docker-compose.yml

在 /data/gitlab 目录下创建 docker-compose.yml 文件：

cd /data/gitlab
sudo vi docker-compose.yml

填入以下内容：

version: '3.6'
services:
  gitlab:
    image: 'gitlab/gitlab-ce:17.4.6-ce.0'
    container_name: 'gitlab'
    restart: always
    hostname: 'gitlab.aioil.top' # 替换为您的实际域名或主机 IP
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        # 初始外部访问地址 (使用 https)
        external_url 'https://gitlab.aioil.top'
        # 强制将 HTTP (80) 请求重定向到 HTTPS (443)
        nginx['redirect_http_to_https'] = true
        # 因为是内网且外网不可达，关闭 Let's Encrypt 自动证书申请
        letsencrypt['enable'] = false
        # 开启容器镜像仓库 (Container Registry) - 使用独立域名，复用 443 端口
        registry_external_url 'https://registry.aioil.top'
        gitlab_rails['registry_enabled'] = true
        # 开启包管理功能 (支持 Helm, Maven, NPM 等包管理)
        gitlab_rails['packages_enabled'] = true
        # 设置 Nginx 客户端最大上传限制 (默认 0，表示不限制)
        nginx['client_max_body_size'] = '0'
    ports:
      - '80:80'
      - '443:443'
      - '2222:22'
    volumes:
      - './config:/etc/gitlab'
      - './logs:/var/log/gitlab'
      - './data:/var/opt/gitlab'
    # 增加共享内存大小到 256MB (Docker 默认仅 64MB)，防止内置 PostgreSQL 数据库等服务因共享内存不足而崩溃
    shm_size: '256m'

可选配置：使用 Host 网络模式

如果您希望 GitLab 容器直接使用宿主机网络（性能略好，但需注意端口冲突），可以使用以下配置代替上面的 docker-compose.yml：

version: '3.6'
services:
  gitlab:
    image: 'gitlab/gitlab-ce:17.4.6-ce.0'
    container_name: 'gitlab'
    restart: always
    hostname: 'gitlab.aioil.top'
    network_mode: 'host' # 开启 host 模式
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.aioil.top'
        # 强制将 HTTP (80) 请求重定向到 HTTPS (443)
        nginx['redirect_http_to_https'] = true
        letsencrypt['enable'] = false
        registry_external_url 'https://registry.aioil.top'
        gitlab_rails['registry_enabled'] = true
        gitlab_rails['packages_enabled'] = true
        nginx['client_max_body_size'] = '0'
        # 【重要】由于使用了 host 模式，必须修改容器内的 SSH 端口，以防与宿主机本身的 22 端口冲突
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
        gitlab_sshd['enable'] = true
        gitlab_sshd['listen_address'] = '[::]:2222'
    # 注意：Host 模式下，ports 映射无效，无需配置
    volumes:
      - './config:/etc/gitlab'
      - './logs:/var/log/gitlab'
      - './data:/var/opt/gitlab'
    # 增加共享内存大小到 256MB (Docker 默认仅 64MB)，防止内置 PostgreSQL 数据库等服务因共享内存不足而崩溃
    shm_size: '256m'

可选配置：出于安全考虑禁止 SSH 访问

如果您希望在网络层面上彻底禁止外部通过 SSH 克隆或访问 GitLab 代码（仅允许 HTTP/HTTPS），您可以使用以下配置。该配置在原有的基础上移除了 2222:22 的端口映射，并通过配置 gitlab_sshd['enable'] = false 主动禁用了容器内部的 SSHD 进程：

version: '3.6'
services:
  gitlab:
    image: 'gitlab/gitlab-ce:17.4.6-ce.0'
    container_name: 'gitlab'
    restart: always
    hostname: 'gitlab.aioil.top'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.aioil.top'
        nginx['redirect_http_to_https'] = true
        letsencrypt['enable'] = false
        registry_external_url 'https://registry.aioil.top'
        gitlab_rails['registry_enabled'] = true
        gitlab_rails['packages_enabled'] = true
        nginx['client_max_body_size'] = '0'
        # 出于安全考虑，主动禁用内置的 sshd 服务进程
        gitlab_sshd['enable'] = false
    ports:
      - '80:80'
      - '443:443'
      # 不映射 22 端口，阻断外部 SSH 连接
    volumes:
      - './config:/etc/gitlab'
      - './logs:/var/log/gitlab'
      - './data:/var/opt/gitlab'
    shm_size: '256m'

3.3 准备内网 HTTPS 证书

由于域名解析到内网且外网不可达，GitLab 无法通过 Let’s Encrypt 自动获取证书。您需要手动提供证书文件：

1. 在 docker-compose.yml 所在的目录下，创建用于存放证书的目录：

   mkdir -p ./config/ssl
   

2. 将您的证书和私钥文件分别重命名为与域名相同的名称，并放入该目录。注意：由于 GitLab 和 Registry 使用了不同的域名，您需要准备两套证书（或使用通配符证书 *.aioil.top）：

   • GitLab 证书：./config/ssl/gitlab.aioil.top.crt 和 ./config/ssl/gitlab.aioil.top.key
   • Registry 证书：./config/ssl/registry.aioil.top.crt 和 ./config/ssl/registry.aioil.top.key

提示： 如果您没有企业内网 CA 签发的证书，可以临时生成有效期为 10 年的自签名证书供测试使用：

# 生成 GitLab 证书
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout ./config/ssl/gitlab.aioil.top.key -out ./config/ssl/gitlab.aioil.top.crt -subj "/CN=gitlab.aioil.top"
# 生成 Registry 证书
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout ./config/ssl/registry.aioil.top.key -out ./config/ssl/registry.aioil.top.crt -subj "/CN=registry.aioil.top"

提示 2：复用 K8s 集群中已存在的证书（推荐）
如果您的 Kubernetes 集群中（例如通过 Cert-Manager）已经签发了该域名（或泛域名 *.aioil.top）的 TLS 证书，可以直接从 K8s Secret 中导出并复制给 GitLab 使用：

# 假设您的泛域名证书 Secret 名称为 aioil-top-tls，位于 default 命名空间
SECRET_NAME="aioil-top-tls"
NAMESPACE="default"

# 提取 crt 和 key 并保存到 GitLab 的 ssl 目录
kubectl get secret ${SECRET_NAME} -n ${NAMESPACE} -o jsonpath='{.data.tls\.crt}' | base64 -d > ./config/ssl/gitlab.aioil.top.crt
kubectl get secret ${SECRET_NAME} -n ${NAMESPACE} -o jsonpath='{.data.tls\.key}' | base64 -d > ./config/ssl/gitlab.aioil.top.key

# 因为是泛域名证书，Registry 也可以直接复用这两个文件
cp ./config/ssl/gitlab.aioil.top.crt ./config/ssl/registry.aioil.top.crt
cp ./config/ssl/gitlab.aioil.top.key ./config/ssl/registry.aioil.top.key

3.4 启动 GitLab 容器

在 docker-compose.yml 所在的目录执行启动命令：

sudo docker compose up -d 

注：GitLab 启动初始化较慢，通常需要等待 3-5 分钟，期间可通过 sudo docker compose logs -f 查看启动日志。

3.5 配置或证书更新后如何生效

根据您修改的内容不同，生效的方式也有所区别：

场景一：修改了 docker-compose.yml（如环境变量、端口映射等）
由于我们在 docker-compose.yml 中通过环境变量 GITLAB_OMNIBUS_CONFIG 注入了配置，当您修改了该文件后，需要重建容器才能使新环境变量生效：

cd /data/gitlab
# 重新应用 compose 文件并重建容器（Docker 会自动检测变更）
sudo docker compose up -d

场景二：仅更新了 SSL 证书（docker-compose.yml 未修改）
如果您只是替换了 ./config/ssl/ 目录下的证书文件，执行 up -d 不会触发任何操作。您需要直接重启容器使证书生效：

cd /data/gitlab
# 重启容器加载最新证书
sudo docker compose restart

(注意：容器重启后，GitLab 内部的启动和重载配置过程通常需要 1-3 分钟，期间访问网页可能会提示 502，请耐心等待。)

4. 初始配置与登录

4.1 获取初始密码

GitLab 首次启动时会生成一个随机的 root 密码，可通过以下命令查看：

# 注意：如果您的容器名称不是 gitlab（可通过 docker ps 查看 NAMES 列），请将下面命令中的 gitlab 替换为实际的容器名
sudo docker exec -it gitlab cat /etc/gitlab/initial_root_password

(密码文件会在 24 小时后自动删除，请尽快登录并修改密码)

4.2 访问系统

• 浏览器访问：https://gitlab.aioil.top （如果您在前面配置了 HTTPS）或 http://<宿主机IP>
• 默认账号：root
• 密码：上一步获取的初始密码

4.3 修改配置（可选）

虽然我们在 docker-compose.yml 中通过环境变量注入了初始配置，但在日常运维中，修改复杂的配置项更推荐直接编辑挂载出来的配置文件。

1. 编辑挂载到宿主机的配置文件：

sudo vi /data/gitlab/config/gitlab.rb

2. 找到需要修改的配置项（例如邮件服务等）并取消注释修改。

3. 重载配置使其生效：

sudo docker exec -it gitlab gitlab-ctl reconfigure

5. 运维指南

5.1 数据备份

手动触发全量备份：

sudo docker exec -it gitlab gitlab-backup create

备份文件默认会存放在容器内的 /var/opt/gitlab/backups 目录中，对应宿主机的 /data/gitlab/data/backups。

定时备份 (Crontab)：
可以通过宿主机的 crontab 设置每日凌晨 2 点自动备份：

0 2 * * * /usr/bin/docker exec gitlab gitlab-backup create CRON=1

5.2 版本升级

使用 Docker Compose 升级 GitLab 非常简单（注意：大版本升级需遵循 GitLab 官方升级路径，不能跨大版本强升）：

cd /data/gitlab

# 1. 修改版本号
# 编辑 docker-compose.yml，将 image: 'gitlab/gitlab-ce:17.4.6-ce.0' 修改为新版本

# 2. 拉取新镜像并重启容器
sudo docker compose pull
sudo docker compose up -d

5.3 忘记 root 密码怎么办

如果在日常使用中忘记了 GitLab 的管理员 (root) 密码，且无法通过邮箱找回，可以通过进入容器内部执行交互式命令来强制重置密码。

操作步骤：

1. 在部署了 GitLab 的宿主机上，执行以下命令进入重置密码的交互模式：

   # 注意：如果您的容器名称不是 gitlab，请替换为实际容器名
   sudo docker exec -it gitlab gitlab-rake "gitlab:password:reset[root]"
   

2. 执行后，系统会提示您输入新密码：

   Enter password: 
   Confirm password: 
   

   (输入密码时屏幕不会显示字符，属于正常现象)
3. 密码要求至少 8 个字符。输入完成后，系统会更新密码并提示成功：

   Password successfully updated for user with username root.
   

4. 此时，您就可以使用 root 账号和刚刚设置的新密码登录 GitLab 网页端了。