Ubuntu 22.04 安装 GitLab CE 17.x 指南

目标：在 Ubuntu 22.04.5 上通过官方 Omnibus apt 仓库完整安装 GitLab CE 17.11.7，完成 EXTERNAL_URL 与 HTTPS 自签证书配置，并用 gitlab-ctl / gitlab-rails / gitlab-rake 验证服务与版本、创建 root 管理员、跑通一次 CI 流水线。所有命令与回显已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（Kernel 5.15.x / x86_64）
包管理器：apt（官方 packages.gitlab.com/gitlab/gitlab-ce 仓库）
GitLab 版本：17.11.7-ce.0（GitLab Community Edition）
相关依赖版本：Ruby 3.2.5、GitLab Shell 14.42.0、PostgreSQL 16.8、Gitaly 17.11.7
外部访问地址：http://172.17.0.7（EXTERNAL_URL）
配置目录：/etc/gitlab/gitlab.rb、/etc/gitlab/gitlab-secrets.json
数据目录：/opt/data/gitlab（仓库数据目录，见「七、配置说明」数据迁移）
日志目录：/var/log/gitlab/
管理账号：root / 密码 q1w2e3r4

二、前置条件

拥有 root 权限或 sudo 权限，全新系统建议先 apt-get update && apt-get upgrade -y
已装基础工具：curl、openssh-server、ca-certificates、tzdata、perl（Omnibus 安装必需）
网络可访问官方仓库 packages.gitlab.com（离线场景走「五、离线安装方案」）
服务器内存建议 ≥ 4GB；生产建议 ≥ 8GB 并与独立数据盘（如 /opt/data/gitlab）搭配
需要一个可被外部访问的域名或 IP 作为 EXTERNAL_URL（云端记得放行 80/443）

三、版本选型说明

GitLab 提供三种常见安装形态，各有适用场景：

形态	适用场景	说明
Omnibus 极简安装（本文 A 方案）	单机自建，日常/内部使用	一条命令装完内置 PostgreSQL、Redis、Nginx、Puma，开箱即用；可平滑升级
离线 deb 安装（本文 B 方案）	内网隔离、无法访问官方仓库	在联网机预下载包后拷入内网 `dpkg -i` 安装
Docker Compose 部署	快速拉起、便于资源隔离	见《GitLab CE 17.x Docker Compose 部署指南》

版本说明：GitLab 采用「主版本每季度一个大版本、每月一个小版本」节奏。文内以 17.11.7（17.x 末号版本，安装时可直接 apt-cache policy gitlab-ce 确认当前候选版本） 实测。CE（Community Edition）与 EE（Enterprise Edition）差异见参考链接。

⚠️ 注意：GitLab 升级务必遵循「逐个次要版本升级」原则，见「九、FAQ-9.3」。

四、在线安装方案（A：官方 apt 仓库，推荐）

4.1 更新软件源并安装前置软件

sudo apt-get update
sudo apt-get install -y curl openssh-server ca-certificates tzdata perl postfix

postfix 安装时会弹出邮件服务器配置交互，生产环境若不需要发信可选择 No configuration；已装 git 的可跳过。

4.2 添加 GitLab 官方 apt 仓库

curl -fsSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

执行输出末尾应出现：

Repository configured successfully.
Ready to install packages.

4.3 确认可用版本

apt-cache policy gitlab-ce

执行结果（节选）：

gitlab-ce:
  Installed: (none)
  Candidate: 19.4.1-ce.0
  Version table:
     19.4.1-ce.0 500
        500 https://packages.gitlab.com/gitlab/gitlab-ce/ubuntu/jammy jammy/main amd64 Packages

💡 说明：Candidate 是当前仓库默认最新版本。如需安装与本文一致的 17.x 末号版本，显式指定 17.11.7-ce.0（下文即如此）。

4.4 设置 EXTERNAL_URL 并安装（自动 reconfigure）

安装前先设置 GitLab 对外访问地址与初始 root 密码。首次安装建议使用强密码，GitLab 会拒绝过弱的初始密码：

# 首次 reconfigure 需要强密码才会通过校验（弱密码会被拒绝，见 FAQ-9.2）
sudo EXTERNAL_URL="http://172.17.0.7" \
     GITLAB_ROOT_EMAIL="admin@example.com" \
     GITLAB_ROOT_PASSWORD="Abc#12345xyZ!q" \
     apt-get install -y gitlab-ce=17.11.7-ce.0

该命令会下载约 1.5GB 的 GitLab CE 并自动执行首次 reconfigure（安装 PostgreSQL / Redis / Gitaly / Puma / Sidekiq / Nginx 并初始化数据库）。reconfigure 完成时会打印管理员账号摘要：

Notes:
Default admin account has been configured with following details:
Username: root
Password: You didn't opt-in to print initial root password to STDOUT.

gitlab Reconfigured!

4.5 把 root 密码重置为固定演示口令

部署验证阶段为便于演示，将 root 密码统一重置为 q1w2e3r4。因为 GitLab 的强度校验会拦截该弱口令（通过界面/项目内修改会报错），需借助 rails 运行器跳过校验直接写入：

sudo gitlab-rails runner "u=User.find_by(username: 'root'); u.password='q1w2e3r4'; u.password_confirmation='q1w2e3r4'; u.save!(validate: false)"

⚠️ 注意：以上仅为文档演示口令。生产环境请务必使用强密码并通过正规渠道设置，切忌将 q1w2e3r4 用于线上。

4.6 验证服务状态与版本

sudo gitlab-ctl status

执行结果（节选）：

run: alertmanager: (pid 31270) 31s; run: log: (pid 18036) 649s
run: gitaly: (pid 17112) 919s; run: log: (pid 16772) 1021s
run: gitlab-workhorse: (pid 31296) 30s; run: log: (pid 17765) 684s
run: nginx: (pid 31313) 29s; run: log: (pid 17807) 677s
run: postgresql: (pid 16817) 1013s; run: log: (pid 16828) 1009s
run: puma: (pid 31350) 28s; run: log: (pid 17696) 695s
run: redis: (pid 16720) 1030s; run: log: (pid 16730) 1026s
run: sidekiq: (pid 31367) 27s; run: log: (pid 17719) 689s

sudo gitlab-rake gitlab:env:info

执行结果（关键行）：

System information
System:         Ubuntu 22.04
Ruby Version:   3.2.5
Version:        17.11.7
Revision:       5ad4b58c943
DB Adapter:     PostgreSQL
DB Version:     16.8
URL:            http://172.17.0.7
GitLab Shell
Version:        14.42.0

💡 命令解释：gitlab-ctl status 显示各后台服务 runit 运行状态；gitlab-rake gitlab:env:info 汇总 GitLab、Ruby、数据库、Shell、Gitaly 版本与仓库存储配置，是排查兼容性的第一手依据。

4.7 验证 Web 与 REST API

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://172.17.0.7/users/sign_in
curl -s -H "PRIVATE-TOKEN: <个人访问令牌>" http://172.17.0.7/api/v4/version

执行结果：

HTTP 200
{"version":"17.11.7","revision":"5ad4b58c943","kas":{"enabled":true, ...},"enterprise":false}

Web 首页返回 HTTP 200；登录页在 /users/sign_in。
REST API /api/v4/version 返回 GitLab 版本、revision 与 enterprise:false（确认为 CE）。
个人访问令牌（PAT）在用户设置 → Access Tokens 里创建，或通过 gitlab-rails runner 生成，见《GitLab CE 常用命令与 API 详解》。

4.8 注册 runner 并跑通一次 CI 流水线

在 GitLab 首页 Admin → CI/CD → Runners，取得实例级注册令牌后：

sudo gitlab-runner register --non-interactive \
  --url http://172.17.0.7 \
  --registration-token "<注册令牌>" \
  --executor shell \
  --description "gitlab-dev-shell-runner" \
  --tag-list "shell,ubuntu" \
  --run-untagged=true

执行结果（关键行）：

Registering runner... succeeded                     correlation_id=01M4G8BDJNRRS50DMM68ZXFEN2 runner=CyrVTezYs runner_name=gitlab-dev-shell-runner
Runner registered successfully.
Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"

在任意仓库提交 .gitlab-ci.yml 即可自动触发流水线并看到 job 由该 runner 执行（示例见《GitLab CI/CD 配置详解》）。

五、离线安装方案（B：官方 deb 包，断网环境）

适用于内网隔离、无法访问 packages.gitlab.com 的环境。

5.1 在联网机器下载 deb 包

curl -L -o gitlab-ce_17.11.7-ce.0_amd64.deb \
  https://packages.gitlab.com/gitlab/gitlab-ce/packages/ubuntu/jammy/gitlab-ce_17.11.7-ce.0_amd64.deb/download.deb

💡 说明：版本号按需替换；download.deb 为 packages.gitlab.com 的直链下载地址。可先 apt-cache policy gitlab-ce 确认目标版本号存在。

5.2 拷入内网并安装

将 deb 包拷贝到内网服务器，然后：

sudo apt-get update
sudo dpkg -i gitlab-ce_17.11.7-ce.0_amd64.deb   # 缺依赖报错时代以 sudo apt-get -f install -y 补装

dpkg 阶段同样会自动执行首次 reconfigure；其 EXTERNAL_URL 在安装完成后配置：

sudo EXTERNAL_URL="http://172.17.0.7" \
     GITLAB_ROOT_EMAIL="admin@example.com" \
     GITLAB_ROOT_PASSWORD="Abc#12345xyZ!q" \
     gitlab-ctl reconfigure

5.3 验证

与 4.6 / 4.7 相同，依次执行 gitlab-ctl status、gitlab-rake gitlab:env:info、curl 探测 Web 与 API 即可确认。

六、多方案对比与选择建议

维度	A（apt 在线）	B（deb 离线）
版本	仓库最新（可锁定任意已发布版本）	需自行锁定下载版本
是否需联网	是	否（仅安装时）
安装方式	`apt-get install gitlab-ce=版本`	`dpkg -i` + `apt-get -f install`
初始配置	`EXTERNAL_URL` 环境变量一次成型	安装后 reconfigure
升级	`apt-get upgrade` 支持	下载新包重新 `dpkg -i`
适用	可访问官方仓库的常规环境	内网隔离、外包导入场景

💡 建议：可联网环境选 A 方案（便捷、升级省心）；内网隔离环境选 B 方案。二者安装产物与服务形态完全一致，均为 systemd 托管型 Omnibus 应用。

七、配置说明

7.1 EXTERNAL_URL 与访问控制

external_url 决定 GitLab 对外暴露地址、克隆 URL 与 OAuth 回调地址，安装后再改需同步修改 /etc/gitlab/gitlab.rb 并 reconfigure：

sudo sed -i "s|^external_url .*|external_url 'http://172.17.0.7'|" /etc/gitlab/gitlab.rb
sudo gitlab-ctl reconfigure

⚠️ 注意：若后续改成 https://，必须同时配置证书（见 7.3），否则 reconfigure 后访问会 502。

7.2 数据目录迁移到 /opt/data/gitlab

生产环境建议把 GitLab 仓库数据放到独立数据盘 /opt/data/gitlab（避免与系统盘争抢 I/O 与空间）。在 /etc/gitlab/gitlab.rb 追加：

git_data_dirs({
  "default" => { "path" => "/opt/data/gitlab/git-data" }
})

然后 reconfigure 生效：

sudo gitlab-ctl reconfigure
sudo gitlab-ctl status | grep -E "gitaly|postgresql"

若需迁移已存数据，先 gitlab-ctl stop puma sidekiq，将原 git-data 拷贝至新目录并改回权限再启动。

7.3 启用 HTTPS（自签证书）

GitLab Nginx 默认监听 80。生产建议启用 HTTPS，可先用自签证书验证链路，再换 CA 正式证书。

第一步：生成自签证书

cd /etc/gitlab/ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout gitlab-ssl.key -out gitlab-ssl.crt \
  -subj "/C=CN/ST=Shanghai/L=Shanghai/O=Example/CN=gitlab.example.com"

执行结果（节选）：

--- generated keypair ---
-rw-r--r-- 1 root root 1326 gitlab-ssl.crt
-rw------- 1 root root 1704 gitlab-ssl.key
subject=C = CN, ST = Shanghai, L = Shanghai, O = Example, CN = gitlab.example.com
notBefore=Oct  9 12:18:39 2026 GMT
notAfter=Oct  9 12:18:39 2027 GMT

第二步：配置 external_url 为 https

external_url 'https://gitlab.example.com'
nginx['redirect_http_to_https'] = true

第三步：reconfigure 并验证

sudo gitlab-ctl reconfigure
curl -k -s -o /dev/null -w "HTTPS %{http_code}\n" https://gitlab.example.com/users/sign_in

执行结果：

HTTPS 200

⚠️ 注意：curl -k 为跳过自签证书校验，用于本地验证配置正确性；线上应启用 Let's Encrypt 自动续期（letsencrypt['enable'] = true）或使用 CA 正式证书替换自签。

7.4 常用配置文件与日志位置

项目	路径
主配置	`/etc/gitlab/gitlab.rb`
密钥	`/etc/gitlab/gitlab-secrets.json`
runner 配置	`/etc/gitlab-runner/config.toml`
各服务日志	`/var/log/gitlab/<服务>/`
备份文件输出	`/var/opt/gitlab/backups/`

💡 提示：gitlab.rb 是唯一需要手工维护的配置入口（Nginx、Puma、Sidekiq、Redis、数据库等全部收敛于此）；gitlab-secrets.json 由 reconfigure 生成，升级/迁移务必一并备份。

八、注意事项

内存资源：GitLab 是全家桶（PostgreSQL+Redis+Puma+Sidekiq+Gitaly+Nginx+Prometheus），最低 4GB 内存，推荐 8GB 以上；内存过小会出现 puma 反复重启。
首次密码强度：GitLab 会拒绝 q1w2e3r4 这类弱口令作为初始 root 密码，需用强密码初始化，再视需要重置（见 4.5）。
端口占用：默认占用 80（Nginx）；若与本机其他 Web 服务冲突，调整监听端口并同步 external_url。
数据迁移时机：git_data_dirs 迁移务必在数据量小、或已备份的前提下进行，迁移中途不可中断。
证书：自签证书仅适合内网/测试，公网访问务必使用 CA 正式证书并做好续期。

九、常见问题（FAQ）

9.1 安装后访问返回 502 或 GitLab is not responding？

多为 puma / sidekiq 未就绪或内存不足。按序排查：

sudo gitlab-ctl status            # 看 puma / sidekiq / nginx 是否 run
sudo gitlab-ctl tail puma         # 看 puma 日志报错
free -h                           # 确认内存充足

内存不足时降低负载：关闭部分监控组件或调低 puma['worker_processes'] 后 reconfigure。

9.2 首次 reconfigure 报 "Password must not contain commonly used combinations"？

GitLab 初始 root 密码强度校验拒绝弱口令。用强密码重跑（见 4.4），安装完成后再通过 rails console 重置为期望口令。

9.3 升级到更高版本失败？

GitLab 要求不能跨大段跳版本。升级前先查官方升级路径，逐个次要版本升级；每步升级后跑：

sudo gitlab-ctl reconfigure
sudo gitlab-rake db:migrate
sudo gitlab-ctl restart

9.4 忘记 root 密码 / 登录被锁？

sudo gitlab-rails console

在控制台执行：

u = User.find_by(username: 'root')
u.password = 'new_strong_password'
u.password_confirmation = 'new_strong_password'
u.save!

9.5 `gitlab-ctl status` 正常但 curl 首页 403？

多因 Nginx 拦截了非浏览器 User-Agent 或异常来源。用 curl -I http://IP/ 与 curl -H "User-Agent: Mozilla/5.0" http://IP/ 对比，确定是 Web 层面问题。

十、卸载与清理

# 1. 卸载 GitLab 及其守护进程托管（保留数据）
sudo gitlab-ctl uninstall
sudo dpkg -r gitlab-ce

# 2. 彻底清理（谨慎！先确认已备份）
sudo dpkg --purge gitlab-ce
sudo rm -rf /opt/data/gitlab /etc/gitlab /var/log/gitlab /var/opt/gitlab /opt/gitlab /etc/gitlab-runner

⚠️ 注意：gitlab-ctl uninstall 只移除守护进程托管、保留数据；只有 dpkg --purge + 手动删除目录才会清空全部数据。删除前务必做好备份（gitlab-backup create）或事先导出仓库。

十一、参考链接

本文档由 www.quzuo.net 平台开发

Ubuntu 22.04 安装 GitLab CE 17.x 指南

Ubuntu 22.04 安装 GitLab CE 17.x 指南

一、环境信息

二、前置条件

三、版本选型说明

四、在线安装方案（A：官方 apt 仓库，推荐）

4.1 更新软件源并安装前置软件

4.2 添加 GitLab 官方 apt 仓库

4.3 确认可用版本

4.4 设置 EXTERNAL_URL 并安装（自动 reconfigure）

4.5 把 root 密码重置为固定演示口令

4.6 验证服务状态与版本

4.7 验证 Web 与 REST API

4.8 注册 runner 并跑通一次 CI 流水线

五、离线安装方案（B：官方 deb 包，断网环境）

5.1 在联网机器下载 deb 包

5.2 拷入内网并安装

5.3 验证

六、多方案对比与选择建议

七、配置说明

7.1 EXTERNAL_URL 与访问控制

7.2 数据目录迁移到 /opt/data/gitlab

7.3 启用 HTTPS（自签证书）

7.4 常用配置文件与日志位置

八、注意事项

九、常见问题（FAQ）

9.1 安装后访问返回 502 或 GitLab is not responding？

9.2 首次 reconfigure 报 "Password must not contain commonly used combinations"？

9.3 升级到更高版本失败？

9.4 忘记 root 密码 / 登录被锁？

9.5 gitlab-ctl status 正常但 curl 首页 403？

十、卸载与清理

十一、参考链接

9.5 `gitlab-ctl status` 正常但 curl 首页 403？