GitLab CE 常用命令与 API 详解

详解 GitLab CE 17.11.7 的 gitlab-ctl、gitlab-rails/console、gitlab-rake、gitlab-runner 与 REST API 五类运维工具，每类给出真实命令与完整回显、按版本节整理的 CLI 帮助，已在 Ubuntu 22.04 真实环境实测

GitLabGitLabDevOpsGit服务CICD2026/10/09

GitLab CE 常用命令与 API 详解

目标：详解 GitLab CE 17.11.7 运维最常用的三类命令行工具与 REST API——gitlab-ctl（服务/备份）、gitlab-rails / gitlab-rails console / gitlab-rails runner（数据库与对象操作）、gitlab-rake（内置任务）、gitlab-runner（Runner 运维），以及 curl /api/v4/* REST 接口。每条命令的真实回显均已在本机 Ubuntu 22.04 真实环境逐条实测，按版本节整理。管理账号 root / 密码 q1w2e3r4。

一、环境信息

  • GitLab 版本：17.11.7（CE），Revision 5ad4b58c943
  • Nginx 监听：http://172.17.0.7
  • 数据目录：/opt/data/gitlab（仓库数据），配置 /etc/gitlab/gitlab.rb
  • GitLab Runner：19.4.1（system 模式，shell 执行器）
  • REST API：http://172.17.0.7/api/v4/，私有令牌鉴权 PRIVATE-TOKEN
  • 实测用个人访问令牌（PAT）方式调用 API（见「五、5.1」）
  • root 密码：q1w2e3r4

二、工具概览

工具类型主要作用
gitlab-ctl系统运维服务启停/状态、reconfigure、日志、备份、支持检查
gitlab-rails应用运维进入 Rails 环境，runner 跑脚本、console 进控制台、dbconsole 进数据库
gitlab-rake应用运维执行内置任务（环境信息、自检、数据库迁移等）
gitlab-runnerCI 工具注册/验证/执行 Runner 任务
curl /api/v4/*REST程序化操作项目、用户、runner、流水线等

💡 说明：前四个都在服务器本机执行；REST API 可以用 curl 或任何 HTTP 客户端调用，是最适合自动化与对接其他系统的方式。

三、前置条件

  • 已部署 GitLab CE 17.11.7（见《Ubuntu 22.04 安装 GitLab CE 17.x 指南》）
  • 拥有本机 root / sudo 权限，能执行 gitlab-ctl、gitlab-rails 等 Omnibus 命令
  • 调用 REST API 需一个个人访问令牌（PAT）或 Runner/管理员令牌（见「五、5.1」）
  • 已注册 GitLab Runner（CI 场景，见「四、gitlab-runner」）

四、gitlab-ctl

gitlab-ctl 是 Omnibus GitLab 的服务/系统运维入口，gitlab-ctl help 会列出全部子命令。

4.1 服务管理：status / start / stop / restart

sudo gitlab-ctl status

实测回显（节选，服务 run 表示正在运行）：

run: alertmanager: (pid 31270) 8054s; run: log: (pid 18036) 8672s
run: gitaly: (pid 17112) 8942s; run: log: (pid 16772) 9044s
run: gitlab-kas: (pid 31284) 8054s; run: log: (pid 17001) 9025s
run: gitlab-workhorse: (pid 31296) 8053s; run: log: (pid 17765) 8707s
run: nginx: (pid 34097) 6922s; run: log: (pid 17807) 8700s
run: postgresql: (pid 16817) 9036s; run: log: (pid 16828) 9032s
run: prometheus: (pid 31338) 8051s; run: log: (pid 17915) 8676s
run: puma: (pid 33882) 6981s; run: log: (pid 17696) 8718s
run: redis: (pid 16720) 9053s; run: log: (pid 16730) 9049s
run: redis-exporter: (pid 31356) 8050s; run: log: (pid 17887) 8684s
run: sidekiq: (pid 31367) 8050s; run: log: (pid 17719) 8712s

常用服务管理命令：

sudo gitlab-ctl start            # 启动所有服务
sudo gitlab-ctl stop             # 停止所有服务
sudo gitlab-ctl stop puma        # 只停止 puma
sudo gitlab-ctl restart          # 重启所有服务
sudo gitlab-ctl restart sidekiq  # 只重启 sidekiq

4.2 service-list：列出全部服务

sudo gitlab-ctl service-list

实测回显：

alertmanager*
gitaly*
gitlab-exporter*
gitlab-kas*
gitlab-workhorse*
logrotate*
nginx*
node-exporter*
postgres-exporter*
postgresql*
prometheus*
puma*
redis*
redis-exporter*
sidekiq*

💡 说明：带 * 表示该服务已启用并随系统自启。未列出的（如 gitlab-pages）说明未启用。

4.3 reconfigure 与 show-config

sudo gitlab-ctl reconfigure        # 应用配置并重跑食谱（装完/改 gitlab.rb 后必跑）
sudo gitlab-ctl show-config | head # 预览即将生成的配置

4.4 日志查看：tail / 定位特定服务

sudo gitlab-ctl tail puma          # 跟踪(实时) puma 日志
sudo gitlab-ctl tail nginx -f      # 跟踪 nginx 日志

4.5 reconfigure 期间自动执行的检查

sudo gitlab-ctl check-config       # 检查 gitlab.rb 是否有被移除的过时配置
sudo gitlab-ctl diff-config        # 对比用户配置与包默认配置差异
sudo gitlab-ctl deploy-page        # 运维期间显示部署占位页

4.6 其他常用子命令（来自 help）

General Commands:
  cleanse              删除所有 gitlab 数据并从零开始
  reconfigure          重新配置应用
  show-config          预览 reconfigure 将生成的配置
  uninstall            杀掉全部进程并卸载进程托管（保留数据）

Service Management Commands:
  start / stop / status / restart    # 见 4.1
  service-list                          # 见 4.2
  tail                                  # 见 4.4

Backup Commands:
  backup-etc            备份 GitLab 配置

Database Commands:
  pg-password-md5       生成 PostgreSQL 格式的用户密码哈希
  pg-upgrade            升级 PostgreSQL 到最新支持版本

Container Registry / Gitaly / Let's Encrypt 等分类子命令见 `gitlab-ctl help` 完整清单。

五、REST API（curl /api/v4）

GitLab 提供完整的 REST API。鉴权最常用的是个人访问令牌（PAT），通过请求头 PRIVATE-TOKEN 传递。

5.1 创建个人访问令牌（PAT）

进入「用户 Settings → Access Tokens」，或直接在服务器上用 runner 生成（实测）：

sudo gitlab-rails runner "tok=PersonalAccessToken.create!(\
  name:'demo', scopes:['api','read_repository','read_api'], \
  expires_at: 1.year.from_now, user: User.find_by(username:'root')); puts tok.token"

输出类似（示例令牌，请勿直接使用）：

glpat-8JorMfyMRgrCx6gQWBoH

⚠️ 注意：PAT 是敏感凭据，只显示一次，切勿提交进仓库或写死到脚本；可按需用 rbac 收紧 scopes 与过期时间。

5.2 获取版本信息

curl -s -H "PRIVATE-TOKEN: <PAT>" http://172.17.0.7/api/v4/version

实测回显：

{"version":"17.11.7","revision":"5ad4b58c943","kas":{"enabled":true,"externalUrl":"ws://172.17.0.7/-/kubernetes-agent/","externalK8sProxyUrl":"http://172.17.0.7/-/kubernetes-agent/k8s-proxy/","version":"17.11.7"},"enterprise":false}

💡 说明：enterprise:false 确认当前为社区版 CE。

5.3 查询当前用户

curl -s -H "PRIVATE-TOKEN: <PAT>" http://172.17.0.7/api/v4/user

实测回显（节选）：

{
  "id": 1,
  "username": "root",
  "name": "Administrator",
  "state": "active",
  "web_url": "http://172.17.0.7/root",
  "confirmed_at": "2026-10-09T11:40:09.420Z",
  "last_activity_on": "2026-10-09"
}

5.4 列出项目

curl -s -H "PRIVATE-TOKEN: <PAT>" "http://172.17.0.7/api/v4/projects?simple=true"

实测回显（节选，本机有 hello-ci 与 ci-demo 两个项目）：

[
  {"id":2,"name":"ci-demo","path_with_namespace":"root/ci-demo",
   "default_branch":"main","visibility":"private",
   "http_url_to_repo":"http://172.17.0.7/root/ci-demo.git",
   "web_url":"http://172.17.0.7/root/ci-demo"},
  {"id":1,"name":"hello-ci","path_with_namespace":"root/hello-ci",
   "default_branch":"main","visibility":"private",
   "http_url_to_repo":"http://172.17.0.7/root/ci-demo.git"}
]

5.5 查询单个项目与流水线

curl -s -H "PRIVATE-TOKEN: <PAT>" http://172.17.0.7/api/v4/projects/2
curl -s -H "PRIVATE-TOKEN: <PAT>" http://172.17.0.7/api/v4/projects/2/pipelines

架构关键字段（实测）：

projects/2    -> default_branch=main  visibility=private
projects/2/pipelines -> [{"id":4,"status":"success","ref":"main"}]

5.6 查询与操作 Runner

# 列出全部 Runner
curl -s -H "PRIVATE-TOKEN: <PAT>" http://172.17.0.7/api/v4/runners/all

实测回显：

[{"id":1,"description":"gitlab-dev-shell-runner","active":true,
  "is_shared":true,"runner_type":"instance_type","name":"gitlab-runner",
  "online":true,"status":"online"}]

5.7 用户与待办等

curl -s -H "PRIVATE-TOKEN: <PAT>" http://172.17.0.7/api/v4/users
curl -s -H "PRIVATE-TOKEN: <PAT>" http://172.17.0.7/api/v4/groups
curl -s -H "PRIVATE-TOKEN: <PAT>" http://172.17.0.7/api/v4/todos      # 空数组 = 无待办

💡 说明：groups、todos 在无数据时返回 []，属正常。

⚠️ 注意：/api/v4/runners/all 需 admin 权限；只读操作可用含 read_api scope 的 PAT。

六、gitlab-rails 与 console

gitlab-rails 把 rails 命令接入 GitLab 应用环境，runner 直接在服务器上执行 Ruby 代码、console 进入交互式控制台。

6.1 gitlab-rails runner：批量执行 Ruby 脚本

# 打印 GitLab 应用版本
sudo gitlab-rails runner "puts Gitlab::VERSION"

实测回显：

17.11.7

# 统计项目与用户数
sudo gitlab-rails runner "puts Project.count"
sudo gitlab-rails runner "puts User.count"

实测回显：

2
1

6.2 重置 / 修改 root 密码（跳过强度校验）

GitLab 强度校验会拦截 q1w2e3r4 这类弱口令，需用 runner 跳过校验写入：

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

⚠️ 注意：此为文档演示口令。生产环境务必使用强密码，切忌 q1w2e3r4 用于线上。

6.3 gitlab-rails console：交互式控制台

sudo gitlab-rails console

进入后是 Ruby + GitLab 对象环境，可直接操作模型：

u = User.find_by(username: 'root')
u.username            # => "root"
p = Project.first
p.path                # => "ci-demo"（本机第一个项目）
p.pipelines.count     # => 1

输入 quit 或 exit 退出。

💡 说明：控制台改动走 ORM，! 方法才会真正保存；适合一次性数据修复、批量建用户等运维场景，但操作生产数据务必谨慎。

七、gitlab-rake

gitlab-rake 执行 GitLab 内置运维任务。

7.1 查看环境信息

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

7.2 自检

sudo gitlab-rake gitlab:check

实测回显（节选）：

Checking Environment ...
Checking GitLab Shell ... Finished

Ruby version >= 3.0.6 ? ... yes (3.2.5)
Git user has default SSH configuration? ... yes
Active users: ... 1
Is authorized keys file accessible? ... yes
GitLab configured to store new projects in hashed storage? ... yes
All projects are in hashed storage? ... yes

Checking GitLab App ... Finished

Checking GitLab subtasks ... Finished

💡 说明：gitlab:check 会逐项校验运行环境（Ruby 版本、SSH 配置、存储格式等），yes/Finished 表示通过；是排查「页面 502 / 功能异常」的第一道体检。

7.3 数据迁移（升级后）

sudo gitlab-rake db:migrate        # 升级后执行迁移

八、gitlab-runner

gitlab-runner 管理 Runner 的注册、校验与状态。本文环境为 system 模式（shell 执行器）。

8.1 version 与运行状态

sudo gitlab-runner --version

实测回显：

Version:      19.4.1
Git revision: 3c39fceb
Git branch:   19-4-stable
GO version:   go1.26.5
Built:        2026-09-24T03:56:12Z
OS/Arch:      linux/amd64

sudo gitlab-runner list        # 列出已注册 Runner

8.2 注册 Runner

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"

8.3 校验已达到的 Runner

sudo gitlab-runner verify

实测回显：

Runtime platform                                    arch=amd64 os=linux pid=39050 revision=3c39fceb version=19.4.1
Running in system-mode.

Verifying runner... is alive                        correlation_id=01M4GFG5ACHMFFY416F9NR3BNM runner=eE8RRXHCA runner_name=gitlab-dev-shell-runner

💡 说明：is alive 表示该 Runner 仍能被 GitLab 连接；--delete 可移除已不存在的 Runner（见 verify --help）。

8.4 register / verify 常用 --help 速查

register（节选关键项）：

NAME:   gitlab-runner register
USAGE:  gitlab-runner register [command options] [arguments...]
OPTIONS:
  --template-config value       模板配置文件
  --tag-list value              标签列表
  -n, --non-interactive         非交互注册
  -r value, --registration-token value   Runner 注册令牌(deprecated, 可用 --token)
  --run-untagged                注册执行未打标签的 job(默认: tag-list 为空时 true)
  --locked                      是否锁定到当前项目(默认 true)
  --access-level value          权限级别: not_protected / ref_protected(默认 not_protected)
  --name value, --description value  Runner 名(默认: 主机名)
  -u value, --url value         GitLab 实例地址
  -t value, --token value       Runner token
  --executor value            执行器类型（本文使用的本机 shell 执行器）
  --shell value               选择 bash / sh / cmd / pwsh / powershell
  --cache-type value          缓存方式
  （其余 S3/GCS/Azure 缓存、代理、超时等参数见完整 help）

verify：

NAME:   gitlab-runner verify - verify all registered runners
USAGE:  gitlab-runner verify [command options] [arguments...]
OPTIONS:
  -c value, --config value  Config file (default: "/etc/gitlab-runner/config.toml")
  -n value, --name value    Name of the runner you wish to verify
  -u value, --url value     GitLab instance URL
  -t value, --token value   Runner token
  --delete                  是否删除已不存在的 runner

8.5 运行与守护

sudo gitlab-runner run --config /etc/gitlab-runner/config.toml   # 前台执行
sudo gitlab-runner start                                         # 后台守护（system 模式）

💡 说明：system 模式下 Runner 可作为 systemd 服务托管。Runner 执行 CI 的详细配置见《GitLab CI/CD 配置详解》。

九、注意事项

  • 善用 gitlab-ctl status / gitlab-rake gitlab:check：先做体检再动手术，少走弯路。
  • 改完 gitlab.rb 必须 reconfigure：gitlab-ctl reconfigure 是 Omnibus 的「配置生效」唯一入口。
  • PAT 是敏感值：生产环境用环境变量注入或密钥管理，禁止明文写死；参考 5.1 按需收紧 scopes。
  • 控制台/runner 改动需重启对应服务才兜底生效：部分配置（如某些功能开关）改完需 gitlab-ctl restart。
  • 备份优先：执行 cleanse 等破坏性命令前务必先 gitlab-ctl backup-etc 或按《GitLab CE 17.x Docker Compose 部署指南》做好数据卷备份。

十、常见问题（FAQ）

10.1 gitlab-ctl status 显示 down: puma？

puma 未就绪或内存不足。看 sudo gitlab-ctl tail puma 报错，确认内存充足后 sudo gitlab-ctl restart puma；持续 down 再查 free -h 与 puma worker 配置。

10.2 curl API 返回 401？

未带有效 PAT 或 token 权限不足。确认请求头 PRIVATE-TOKEN: <有效PAT>（或 Authorization: Bearer <token>），并检查 PAT 含 api / read_api scope。

10.3 gitlab-rails runner 很慢或超时？

首次加载 Rails 环境需要几十秒属正常；避免在 runner 里执行重量级任务，可改用后台 job 或分批处理。

10.4 gitlab-runner register 报校验失败？

实例级注册令牌在 Admin → CI/CD → Runners 中获取，令牌过期或复制出错会失败；确认 --url 与 --registration-token 一一对应。

10.5 忘记 root 密码？

用「六、6.2」的 runner 命令绕过强度校验重置，或 gitlab-rails console 中执行 u.password = '新强密码'; u.save!。

十一、参考链接

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