附录

GitLab Omnibus 运维命令与配置速查。所有命令默认在 GitLab 服务器上以 root 或 sudo 执行。

1. gitlab-ctl常用命令

命令	说明
gitlab-ctl status	查看所有服务状态
gitlab-ctl start	启动所有服务
gitlab-ctl stop	停止所有服务
gitlab-ctl restart	重启所有服务
gitlab-ctl restart puma	重启单个服务
gitlab-ctl reconfigure	应用 gitlab.rb 配置
gitlab-ctl tail [service]	实时日志
gitlab-ctl diff-config	对比配置变更
gitlab-ctl show-config	输出渲染后的配置
gitlab-ctl deploy-page up	启用维护页
gitlab-ctl deploy-page down	关闭维护页
gitlab-ctl backup-etc	备份 /etc/gitlab
gitlab-ctl registry-garbage-collect	Registry 垃圾回收
gitlab-ctl prometheus reload	热加载 Prometheus 规则
gitlab-ctl reset-permissions	修复数据目录权限

服务列表：

gitlab-ctl status | awk '{print $1}' | sort
# 常见：nginx, puma, sidekiq, postgresql, redis, gitaly, gitlab-workhorse

2. gitlab-rake常用命令

命令	说明
gitlab-rake gitlab:check SANITIZE=true	全面健康检查
gitlab-rake gitlab:env:info	环境信息汇总
gitlab-rake gitlab:gitaly:check	Gitaly 连通性检查
gitlab-rake gitlab:shell:setup	修复 gitlab-shell 配置
gitlab-rake cache:clear	清除 Rails 缓存
gitlab-rake db:migrate	执行数据库迁移
gitlab-rake db:migrate:status	迁移状态
gitlab-rake gitlab:backup:verify PARTS=...	验证备份组件
gitlab-rake gitlab:password_reset[root]	重置 root 密码
gitlab-rake gitlab:incoming_email:check	检查邮件接收
gitlab-rake gitlab:cleanup:repos	清理孤立仓库（谨慎）
gitlab-rake gitlab:db:reindex	重建数据库索引
gitlab-rake stats	统计用户数/项目数

Rails console（高级调试）：

sudo gitlab-rails console
# 示例：查找用户
# User.find_by(username: 'admin')

3. GitLab日志路径

组件	路径
Rails 应用	/var/log/gitlab/gitlab-rails/production.log
Nginx 访问	/var/log/gitlab/nginx/gitlab_access.log
Nginx 错误	/var/log/gitlab/nginx/error.log
Puma	/var/log/gitlab/puma/
Sidekiq	/var/log/gitlab/sidekiq/current
Gitaly	/var/log/gitlab/gitaly/current
PostgreSQL	/var/log/gitlab/postgresql/current
Redis	/var/log/gitlab/redis/current
GitLab Shell	/var/log/gitlab/gitlab-shell/
Reconfigure	/var/log/gitlab/reconfigure/reconfigure.log
Backup	输出至 cron logger 或 production.log

快速搜索错误：

sudo grep -i error /var/log/gitlab/gitlab-rails/production.log | tail -20
sudo grep ' 5[0-9][0-9] ' /var/log/gitlab/nginx/gitlab_access.log | tail -20

4. 常用配置参数

/etc/gitlab/gitlab.rb 高频参数：

# 基础
external_url 'https://gitlab.example.com'
gitlab_rails['time_zone'] = 'Asia/Shanghai'

# 邮件
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.example.com"
gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'

# 资源
puma['worker_processes'] = 4
puma['min_threads'] = 4
puma['max_threads'] = 4
sidekiq['max_concurrency'] = 25
postgresql['shared_buffers'] = "256MB"

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

# 备份
gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"
gitlab_rails['backup_keep_time'] = 604800
gitlab_rails['backup_upload_connection'] = {
  'provider' => 'AWS',
  'region' => 'cn-north-1',
  'aws_access_key_id' => 'ACCESSKEY',
  'aws_secret_access_key' => 'SECRETKEY'
}
gitlab_rails['backup_upload_remote_directory'] = 'gitlab-backups'

# 外部 PostgreSQL
postgresql['enable'] = false
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_host'] = 'pg.example.com'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_database'] = 'gitlabhq_production'
gitlab_rails['db_username'] = 'gitlab'
gitlab_rails['db_password'] = 'secret'

# LDAP
gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'Company LDAP',
    'host' => 'ldap.example.com',
    'port' => 389,
    'uid' => 'uid',
    'bind_dn' => 'cn=gitlab,ou=services,dc=example,dc=com',
    'password' => 'bind_password',
    'base' => 'ou=people,dc=example,dc=com'
  }
}

修改后执行：sudo gitlab-ctl reconfigure。

5. CI YAML示例

5.1 标准 Docker 构建推送

variables:
  IMAGE: registry.example.com/$CI_PROJECT_PATH

stages:
  - test
  - build
  - deploy

unit-test:
  stage: test
  image: node:20-alpine
  script:
    - npm ci
    - npm test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

build-image:
  stage: build
  image: docker:24-cli
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" registry.example.com
  script:
    - docker build -t $IMAGE:$CI_COMMIT_SHA -t $IMAGE:latest .
    - docker push $IMAGE:$CI_COMMIT_SHA
    - docker push $IMAGE:latest
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

deploy-prod:
  stage: deploy
  image: bitnami/kubectl:latest
  script:
    - kubectl set image deployment/app app=$IMAGE:$CI_COMMIT_SHA -n production
  environment:
    name: production
  when: manual
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

5.2 含缓存的多阶段 Java 构建

cache:
  key:
    files:
      - pom.xml
  paths:
    - .m2/repository

build:
  image: maven:3.9-eclipse-temurin-17
  script:
    - mvn -B package -Dmaven.test.skip=true
  artifacts:
    paths:
      - target/*.jar
    expire_in: 1 week

6. 常见问题汇总

问题	原因	处理
502 Bad Gateway	Puma/Workhorse 未运行	gitlab-ctl restart puma workhorse
413 Request Entity Too Large	上传限制	调大 nginx['client_max_body_size'] 和 gitlab_rails['max_attachment_size']
500 + PG 错误	数据库连接/迁移	gitlab-psql -c "SELECT 1;"，检查 migration
CI job 一直 pending	无可用 Runner	检查 Runner tags 与 online 状态
git push 被拒	分支 protected	走 MR 流程或调整保护规则
备份 tar 很小	跳过了 repos	检查 SKIP 参数，确认 repositories_storages
升级后页面空白	迁移未完成	gitlab-rake db:migrate，查看 production.log
Redis OOM	内存不足	调大 maxmemory 或扩容
Registry push 401	凭证/token 错误	重新 docker login，检查 token scope
LDAP 用户无法登录	bind_dn 错误或 base 不匹配	gitlab-rake gitlab:ldap:check

健康检查端点

curl http://127.0.0.1/-/health      # 存活
curl http://127.0.0.1/-/readiness   # 就绪（含依赖）
curl http://127.0.0.1/-/liveness    # 存活（K8s probe）

紧急联系信息模板

GitLab 实例：https://gitlab.example.com
版本：gitlab-rake gitlab:env:info | grep Version
On-call：<团队联系方式>
备份位置：/var/opt/gitlab/backups + S3 bucket
Runbook：本手册 14-troubleshooting.md