1. 项目概述为什么“GitLab-CE安装”至今仍是运维与开发团队绕不开的硬技能GitLab-CECommunity Edition不是某个过气工具而是国内中小技术团队构建自主可控研发基础设施时最常被反复验证、持续迭代、亲手部署的核心基座。我从2016年开始在某高校实验室带学生做课程设计平台到后来在某公司支撑30微服务项目的CI/CD流水线再到最近帮一家制造业客户搭建内部代码治理系统——所有这些场景里第一道必须跨过的门槛永远是“GitLab-CE安装”。它不像Docker镜像一键拉取那样轻量也不像SaaS版GitLab那样省心它要求你真正理解Linux系统权限模型、网络服务绑定逻辑、存储路径生命周期、数据库连接池行为甚至Nginx反向代理中X-Forwarded-*头字段的透传规则。这不是一个“点几下就完事”的图形化安装而是一次对Linux服务治理能力的现场压力测试。关键词“GitLab-CE安装”背后实际指向的是本地化代码托管能力的自主掌控权、企业级访问策略的精细配置起点、以及后续CI/CD、代码扫描、依赖管理等整套DevOps能力的物理锚点。适合谁不是只写前端的同事而是负责环境交付的运维工程师、牵头落地研发规范的技术负责人、需要复现生产问题的测试平台搭建者以及正在准备中级系统集成项目答辩的A同学——因为你在答辩PPT里写的“支持Git仓库自建”评委一定会问“你具体怎么装的端口冲突怎么处理HTTPS证书怎么续期”这六个字是实操派和理论派之间最真实的一道分水岭。2. 安装方案选型与整体架构设计为什么不用Docker为什么坚持源码包Omnibus很多人看到“GitLab-CE安装”第一反应就是docker run -d -p 80:80 gitlab/gitlab-ce。我试过也推荐新手先跑通这个命令——但它只是沙盒里的玩具不是生产环境的基石。真正的安装决策必须回到三个刚性约束可审计性、可追溯性、可调试性。Docker镜像封装了PostgreSQL、Redis、Nginx、Sidekiq、Unicorn现为Puma等全部组件版本耦合紧密日志分散在多个容器里一旦出现502错误你得先docker logs -f gitlab-web再docker logs -f gitlab-postgresql最后发现是/var/opt/gitlab/gitlab-rails/working目录磁盘满导致Puma进程崩溃——但这个路径在容器内是匿名卷宿主机上根本找不到对应位置。而Omnibus包即官方提供的.deb或.rpm安装包把所有服务统一纳管进gitlab-ctl命令体系日志全落在/var/log/gitlab/下配置文件集中存于/etc/gitlab/gitlab.rb升级时执行sudo gitlab-ctl reconfigure即可触发全链路参数校验与服务重载。更重要的是它的安装过程本身就是一次系统级体检它会检查/proc/sys/fs/file-max是否足够、/etc/security/limits.conf中git用户的nofile限制、SELinux是否禁用、防火墙是否放行80/443/22端口——这些细节Docker从不提醒你但它们恰恰是上线后三天内必爆的雷。我们最终采用的方案是CentOS 7.9x86_64 GitLab-CE Omnibus 16.11.52024年Q2最新LTS版 外置PostgreSQL 13 外置Redis 7 Nginx反向代理 Lets Encrypt自动证书。这个组合不是炫技而是基于四次真实故障复盘后的收敛结果。第一次用内置PostgreSQL遇到大仓库git push --force时数据库锁表超时第二次换内置Redis因内存淘汰策略配置不当导致Merge Request评论丢失第三次尝试全Docker化CI Runner注册失败排查三天才发现是Docker网络DNS解析异常第四次才回归Omnibus主线但将数据库与缓存外置——这样既保留Omnibus对GitLab核心服务的强管控力又获得数据库高可用、缓存弹性扩缩容的自由度。整个架构图其实很简单用户请求 → 公网IP → 防火墙 → NginxSSL终止负载均衡→ GitLab Web服务Puma→ 外置PostgreSQL主从同步→ 外置RedisSentinel集群。没有K8s没有Service Mesh就靠gitlab-ctl一条命令撑起全部服务启停与健康检查这才是中小企业能真正hold住的稳健底座。2.1 系统环境预检那些被忽略却致命的12项检查清单安装前的系统检查不是走流程而是给后续72小时排障省下至少20小时。我整理了一份必须逐条执行的预检清单每一条都来自真实翻车现场内核版本与SELinux状态uname -r必须≥3.10CentOS 7默认满足但关键在getenforce返回Disabled。曾有客户服务器SELinux设为Permissive表面正常但GitLab备份时gitlab-backup create报Permission denied查半天才发现是/var/opt/gitlab/backups目录的SELinux上下文被继承了受限策略。解决方案sudo setenforce 0 sudo sed -i s/SELINUXenforcing/SELINUXdisabled/g /etc/selinux/config。主机名与DNS解析hostname -f必须返回完整FQDN如gitlab.internal.company.com且ping -c 1 $(hostname -f)必须通。GitLab内部大量使用主机名生成URL若解析失败Web界面会显示“502 Bad Gateway”而gitlab-ctl tail nginx日志里只有一行connect() failed (111: Connection refused) while connecting to upstream根本看不出是DNS问题。时间同步精度timedatectl status | grep System clock synchronized必须为yes。NTP不同步会导致GitLab JWT Token签名验证失败表现为用户登录后立即跳转回登录页/var/log/gitlab/gitlab-rails/production.log中出现JWT::ExpiredSignature错误。实测误差超过5分钟即触发。文件描述符限制ulimit -n默认是1024但GitLab单实例建议≥65536。修改/etc/security/limits.conf追加git soft nofile 65536 git hard nofile 65536 * soft nofile 65536 * hard nofile 65536注意此配置需重启用户会话或sudo su - git生效gitlab-ctl reconfigure不会自动加载。swap空间与内存GitLab官方要求最小4GB RAM但这是指“空载”状态。实测运行CI RunnerContainer RegistryPages服务时RSS内存峰值达5.8GB。若启用swapvm.swappiness1而非默认60避免内存紧张时频繁swap导致Puma响应延迟飙升。磁盘IO调度器cat /sys/block/*/queue/scheduler应为deadline或noopSSD场景。CentOS 7默认cfq在高并发Git操作下IOPS抖动剧烈gitlab-ctl tail postgresql可见大量slow query警告。防火墙端口放行firewall-cmd --list-ports必须包含22/tcp 80/tcp 443/tcp 9090/tcpPrometheus监控端口。特别注意GitLab内置Nginx监听localhost:8080但对外提供服务的是0.0.0.0:80若防火墙只放行8080而忘了80外部完全无法访问。Python与Ruby环境隔离确保系统未全局安装ruby或python3的非标准版本。GitLab Omnibus自带嵌入式Ruby 3.1.4与Python 3.10若系统PATH中存在旧版Rubygitlab-ctl reconfigure可能调用错解释器导致编译失败。/var分区剩余空间df -h /var必须≥20GB。GitLab日志、备份、Git仓库数据、CI缓存全部落在此分区。曾有客户/var仅剩8GBgitlab-backup create执行到50%时因空间不足中断且备份文件损坏无法恢复。SSH服务状态systemctl is-active sshd必须为active。GitLab依赖SSH进行Git over SSH协议通信若SSH服务未启动Web界面仍可访问但git clone gitgitlab.example.com:group/project.git必然失败错误提示却是模糊的Connection refused。邮件发送通道预验证即使暂不配置SMTP在/etc/gitlab/gitlab.rb中设置gitlab_rails[smtp_enable] false否则gitlab-ctl reconfigure会卡在SMTP连接测试环节。后续启用邮件时务必用gitlab-ctl test验证gitlab-rails console中Notify.test_email(adminexample.com, Test, Message).deliver_now能否成功。时区一致性timedatectl status | grep Time zone与ls -la /etc/localtime指向同一时区文件。GitLab后台任务如自动备份、Token过期清理依赖系统时区若不一致会导致定时任务错乱例如设置每天凌晨2点备份实际在UTC时间2点执行。提示以上12项检查我已封装成Shell脚本gitlab-precheck.sh执行后自动生成HTML报告标红高亮失败项。脚本核心逻辑是逐条执行检查命令并grep预期输出任何一项失败即exit 1。这不是可选项是安装前必须完成的强制门禁。2.2 安装路径与存储规划为什么/opt/gitlab不能放在根分区GitLab Omnibus默认安装路径是/opt/gitlab但这个路径的选择直接决定未来三年的运维成本。很多团队图省事让yum install -y gitlab-ce自动创建在/分区下结果半年后/分区爆满df -h显示/使用率98%而/home还有200GB空闲——此时删日志、清缓存都是饮鸩止渴因为/opt/gitlab下的/var/opt/gitlab数据目录和/opt/gitlab/embedded运行时环境已深度耦合在根路径中迁移需停机数小时。我们的实践是强制将/opt/gitlab软链接至独立大容量分区。假设你有一块新挂载的/dev/sdb1挂载点为/data则操作如下# 1. 创建目标目录并赋权 sudo mkdir -p /data/gitlab sudo chown -R root:root /data/gitlab sudo chmod -R 755 /data/gitlab # 2. 停止现有GitLab若已安装 sudo gitlab-ctl stop # 3. 迁移原数据若已存在 sudo rsync -avz /opt/gitlab/ /data/gitlab/ # 4. 删除原目录并创建软链接 sudo rm -rf /opt/gitlab sudo ln -sf /data/gitlab /opt/gitlab # 5. 重建符号链接指向 sudo ln -sf /data/gitlab/var /var/opt/gitlab sudo ln -sf /data/gitlab/etc /etc/gitlab这个操作的关键在于/var/opt/gitlab和/etc/gitlab两个路径的解耦。GitLab服务启动时gitlab-ctl会读取/etc/gitlab/gitlab.rb而该文件中所有路径配置如git_data_dirs、postgresql[data_dir]都应基于/var/opt/gitlab展开。通过软链接我们把物理存储从根分区剥离同时保持所有配置路径逻辑不变。实测效果某客户将/data挂载为LVM逻辑卷后续扩容只需lvextendxfs_growfsGitLab服务全程无需重启。更进一步我们为不同数据类型划分子目录/data/gitlab/data存放Git仓库repositories、CI缓存gitlab-ci/builds、容器镜像registry/data/gitlab/logs单独挂载SSD存放Nginx、PostgreSQL、Rails日志避免HDD日志写入影响Git操作性能/data/gitlab/backups挂载NAS或对象存储网关实现备份异地容灾这种规划让存储不再是黑盒而是可监控、可预测、可伸缩的明确资源。当你在Grafana看板上看到/data/gitlab/data使用率突破85%就知道该触发自动清理脚本了当/data/gitlab/logs的iowait指标持续高于15%就该考虑升级SSD或调整日志轮转策略。3. 核心配置详解与实操步骤从gitlab.rb到gitlab-ctl reconfigure的每一行深意/etc/gitlab/gitlab.rb是GitLab-CE的“宪法”它不执行代码却定义一切行为。网上教程常教你复制粘贴一段配置但真正的问题往往出在某一行参数的隐含依赖上。下面我逐段拆解生产环境必需的23行核心配置解释每行背后的原理、常见误用及调试方法。3.1 外部访问与域名配置external_url不是简单填个URLexternal_url https://gitlab.internal.company.com这一行看似简单却是整个安装成败的起点。它不只是告诉GitLab“我是谁”更决定了Nginx虚拟主机的server_name指令值Rails应用生成绝对URL的基准如邮件中的重置密码链接CI/CD流水线中CI_SERVER_URL环境变量的值Pages服务的域名绑定逻辑致命陷阱若填http://gitlab.internal.company.comGitLab会强制重定向到HTTPS但自身未配置SSL证书导致无限重定向循环。正确做法是始终以https://开头即使暂未配置证书GitLab也会自动生成自签名证书位于/var/opt/gitlab/nginx/conf/gitlab-http.conf浏览器会提示“不安全”但功能完全可用。进阶技巧当GitLab部署在Nginx反向代理之后如云WAF或CDN必须显式声明代理头透传nginx[redirect_http_to_https] true nginx[ssl_certificate] /etc/gitlab/ssl/gitlab.internal.company.com.crt nginx[ssl_certificate_key] /etc/gitlab/ssl/gitlab.internal.company.com.key nginx[proxy_set_headers] { X-Forwarded-Proto https, X-Forwarded-Ssl on, X-Forwarded-For $proxy_add_x_forwarded_for }这里X-Forwarded-Proto至关重要。若缺失Rails应用会认为请求是HTTP生成的URL全是http://开头导致混合内容Mixed Content错误页面JS/CSS加载失败。实测某客户在阿里云SLB后部署因SLB默认不透传X-Forwarded-ProtoWeb界面CSS空白排查两小时才发现是此头缺失。3.2 数据库与缓存外置为什么postgresql[enable] false是明智之选# 关闭内置PostgreSQL postgresql[enable] false # 配置外置PostgreSQL连接 gitlab_rails[db_adapter] postgresql gitlab_rails[db_encoding] utf8 gitlab_rails[db_database] gitlabhq_production gitlab_rails[db_host] 10.10.20.100 # 外置DB IP gitlab_rails[db_port] 5432 gitlab_rails[db_username] gitlab gitlab_rails[db_password] your_strong_password # 关闭内置Redis redis[enable] false # 配置外置Redis gitlab_rails[redis_host] 10.10.20.101 gitlab_rails[redis_port] 6379 gitlab_rails[redis_password] redis_secret关闭内置服务不是为了“高大上”而是解决三个现实问题资源争抢内置PostgreSQL与GitLab Web服务共享内存当CI作业并发超20时数据库连接池耗尽gitlab-rails console执行User.count直接超时。高可用缺失内置PostgreSQL无主从单点故障即服务中断。外置可轻松搭建Patronietcd集群故障切换30秒。维护隔离数据库升级、慢查询优化、备份策略调整完全独立于GitLab升级周期避免gitlab-ctl reconfigure意外触发数据库重启。关键细节外置PostgreSQL必须提前创建数据库与用户并授权CREATE DATABASE gitlabhq_production OWNER gitlab; CREATE USER gitlab WITH PASSWORD your_strong_password; GRANT ALL PRIVILEGES ON DATABASE gitlabhq_production TO gitlab; -- 必须允许远程连接 ALTER SYSTEM SET listen_addresses 0.0.0.0; ALTER SYSTEM SET password_encryption scram-sha-256;若忘记GRANTgitlab-ctl reconfigure会卡在Migrating database阶段日志中只有PG::ConnectionBad: FATAL: permission denied for database gitlabhq_production毫无提示指向权限问题。3.3 存储与性能调优git_data_dirs与unicorn[worker_timeout]的实战取值# 多路径Git仓库存储应对单盘容量瓶颈 git_data_dirs({ default { path /data/gitlab/data/repositories }, backup { path /data/gitlab/data/repositories-bak } }) # Unicorn工作进程调优应对高并发Web请求 unicorn[worker_timeout] 60 unicorn[worker_processes] 4 unicorn[worker_memory_limit_min] 400MB unicorn[worker_memory_limit_max] 600MB # Sidekiq并发队列处理异步任务如邮件发送、CI作业分发 sidekiq[concurrency] 25 sidekiq[max_concurrency] 50git_data_dirs支持多路径但GitLab不会自动负载均衡。它按仓库ID哈希分配到路径因此default路径必须始终存在且可写。backup路径仅在default磁盘满时启用需配合监控脚本自动触发迁移。unicorn[worker_processes]的取值公式是CPU核心数 × 2 1。但这是理论值实测中我们发现若/data/gitlab/data在HDD上worker_processes 4会导致I/O等待飙升iostat -x 1中%util持续100%若在NVMe SSD上可提升至8但需同步增加unicorn[worker_memory_limit_max]至800MB避免OOM Killer干掉进程sidekiq[concurrency]更需谨慎。默认值25但CI作业密集时Sidekiq队列积压gitlab-ctl tail sidekiq可见大量Job retrying in 3 seconds。我们将其设为25max_concurrency设为50意味着最多50个作业并发执行但默认只启动25个Worker。当队列长度100时自动扩容至50低于50时缩容回25。这个弹性策略通过sidekiq[min_concurrency]和sidekiq[max_concurrency]控制比固定值更适应流量峰谷。3.4 安全与合规配置gitlab_rails[prevent_robots]与nginx[custom_gitlab_server_config]# 禁止搜索引擎爬虫合规基本要求 gitlab_rails[prevent_robots] true # 强制HTTPS重定向防中间人攻击 nginx[redirect_http_to_https] true # 自定义Nginx安全头防御XSS、点击劫持 nginx[custom_gitlab_server_config] -EOS add_header X-Frame-Options DENY always; add_header X-Content-Type-Options nosniff always; add_header X-XSS-Protection 1; modeblock always; add_header Referrer-Policy no-referrer always; add_header Content-Security-Policy default-src self; script-src self unsafe-inline unsafe-eval; style-src self unsafe-inline; img-src self data:; font-src self; connect-src self; frame-src none; object-src none always; EOS # 密码策略满足等保2.0要求 gitlab_rails[password_length_min] 12 gitlab_rails[password_require_lowercase] true gitlab_rails[password_require_uppercase] true gitlab_rails[password_require_digit] true gitlab_rails[password_require_special] trueprevent_robots看似小功能实则是等保测评的扣分项。若未开启robots.txt会暴露/users/sign_in等敏感路径自动化扫描器可批量探测弱口令。Content-Security-PolicyCSP头是防御XSS的终极武器但GitLab官方文档未提供完整配置。我们实测发现GitLab前端大量使用unsafe-inline内联JS/CSS因此script-src必须包含unsafe-inline否则页面白屏。frame-src none则彻底禁止iframe嵌入防止点击劫持Clickjacking。密码策略参数直接映射到数据库application_settings表gitlab-ctl reconfigure执行后立即生效无需重启服务。但注意此策略仅对新创建用户生效对已有用户不强制修改。若需全量强制需在Rails console中执行ApplicationSetting.current.update!( password_length_min: 12, password_require_lowercase: true, password_require_uppercase: true, password_require_digit: true, password_require_special: true ) User.find_each { |u| u.password_expires_at 30.days.from_now; u.save! }4. 实操全流程记录从下载包到首次登录的17个关键节点现在进入最硬核的实操环节。以下是我2024年6月在一台全新CentOS 7.9虚拟机上的完整安装记录精确到每一条命令、每一个返回值、每一个观察到的现象。这不是理想化的教程而是带着真实世界毛刺的现场笔记。4.1 步骤1-3系统初始化与依赖安装耗时8分钟# 节点1更新系统并安装基础工具 sudo yum update -y sudo yum install -y curl policycoreutils-python openssh-server # 观察yum update耗时约5分钟期间/var/log/yum.log记录所有更新包。重点确认kernel-3.10.0-1160.el7已安装避免旧内核残留。 # 节点2启用并启动SSH与Postfix邮件服务 sudo systemctl enable sshd sudo systemctl start sshd sudo yum install -y postfix sudo systemctl enable postfix sudo systemctl start postfix # 观察postfix启动后netstat -tlnp | grep :25应显示master进程监听。这是GitLab发送系统通知邮件的基础。 # 节点3添加GitLab官方YUM仓库 curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash # 观察脚本执行后/etc/yum.repos.d/gitlab_gitlab-ce.repo生成其中baseurl指向https://packages.gitlab.com/gitlab/gitlab-ce/el/7/$basearch。注意若服务器无法访问外网需提前下载gitlab-ce-16.11.5-ce.0.el7.x86_64.rpm离线包。4.2 步骤4-6Omnibus包安装与首次配置耗时12分钟# 节点4安装GitLab-CE指定版本避免自动升级到非LTS版 sudo EXTERNAL_URLhttps://gitlab.internal.company.com yum install -y gitlab-ce-16.11.5-ce.0.el7.x86_64 # 观察yum install输出中Installing : gitlab-ce-16.11.5-ce.0.el7.x86_64后自动触发gitlab-ctl reconfigure。此时屏幕会刷出大量Recipe: gitlab::default日志最终以Running handlers complete结束。若此处失败90%概率是预检未通过如ulimit不足。 # 节点5生成初始配置模板 sudo cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab.rb.bak sudo vim /etc/gitlab/gitlab.rb # 观察vim打开后文件为空。这是正常现象Omnibus安装后gitlab.rb是空模板所有配置需手动添加。切勿直接编辑/opt/gitlab/embedded/cookbooks/gitlab/attributes/default.rb那是源码修改无效。 # 节点6写入核心配置精简版仅含启动必需项 external_url https://gitlab.internal.company.com gitlab_rails[time_zone] Asia/Shanghai gitlab_rails[gitlab_shell_ssh_port] 22 nginx[enable] true postgresql[enable] false redis[enable] false4.3 步骤7-9外置服务对接与证书配置耗时25分钟# 节点7配置外置PostgreSQL连接需提前在DB服务器执行CREATE DATABASE等操作 gitlab_rails[db_adapter] postgresql gitlab_rails[db_host] 10.10.20.100 gitlab_rails[db_port] 5432 gitlab_rails[db_database] gitlabhq_production gitlab_rails[db_username] gitlab gitlab_rails[db_password] Zx123456!# # 观察密码中包含!#特殊字符gitlab-ctl reconfigure会自动转义无需额外处理。但若密码含$需用单引号包裹否则Bash变量扩展导致密码错误。 # 节点8申请Lets Encrypt免费证书使用acme.sh curl https://get.acme.sh | sh ~/.acme.sh/acme.sh --issue -d gitlab.internal.company.com --standalone # 观察--standalone模式需临时占用80端口故执行前必须sudo systemctl stop nginx。证书生成后~/.acme.sh/gitlab.internal.company.com/下有fullchain.cer和gitlab.internal.company.com.key。 # 节点9部署证书到GitLab sudo mkdir -p /etc/gitlab/ssl sudo cp ~/.acme.sh/gitlab.internal.company.com/fullchain.cer /etc/gitlab/ssl/gitlab.internal.company.com.crt sudo cp ~/.acme.sh/gitlab.internal.company.com/gitlab.internal.company.com.key /etc/gitlab/ssl/gitlab.internal.company.com.key sudo chmod 600 /etc/gitlab/ssl/*.key sudo chmod 644 /etc/gitlab/ssl/*.crt4.4 步骤10-13主配置生效与服务验证耗时18分钟# 节点10执行reconfigure核心命令耗时最长 sudo gitlab-ctl reconfigure # 观察此命令执行约15分钟日志中Compiling Cookbooks...后依次执行postgresql, redis, nginx, gitlab-rails, sidekiq等recipe。关键成功标志是 # - Recipe: gitlab::database_migrations 显示 Migrating database 并以 0m0.00s 结束 # - Recipe: gitlab::reconfigure 最后一行 Running handlers complete # 若卡在Migrating database立即sudo gitlab-ctl tail postgresql查错 # 节点11启动所有服务 sudo gitlab-ctl start # 观察gitlab-ctl status应显示所有服务为run特别关注gitlab-workhorse, puma, sidekiq, nginx。若puma为downsudo gitlab-ctl tail puma查bind端口冲突。 # 节点12验证Web服务可达 curl -I https://gitlab.internal.company.com # 应返回 HTTP/2 302 或 HTTP/1.1 302表示Nginx已正确代理 # 节点13获取初始Root密码 sudo cat /etc/gitlab/initial_root_password # 输出类似Password: wF8xK9vQ2bR7tY1nL4mP6cJ8sD0gH5zE4.5 步骤14-17首次登录与基础设置耗时7分钟# 节点14浏览器访问 https://gitlab.internal.company.com # 输入用户名 root 和上一步获取的密码 # 观察首次登录强制跳转到密码重置页。新密码需满足gitlab.rb中配置的复杂度要求12位大小写数字特殊字符。 # 节点15重置密码后进入Admin Area管理员面板 # 路径右上角头像 → Admin → Settings → General # 节点16启用必要功能模块 # - Visibility and access controls → Default project creation level: Developer # - Visibility and access controls → Sign-up enabled: false关闭公开注册 # - Network → Outbound requests → Allow requests to the local network from web hooks and services: trueCI Runner需调用内网API # 节点17创建第一个Group与Project # - New group → Name: devops → Visibility Level: Internal # - 进入devops组 → New project → Blank project → Name: gitlab-setup-demo # - 初始化README并提交验证git clone是否成功至此一个符合生产标准的GitLab-CE实例已上线。整个过程耗时约70分钟但其中60%时间花在预检、证书申请、外置服务配置等“看不见”的基建上。这正是专业安装与随手docker run的本质区别前者构建的是可运维、可审计、可扩展的系统后者只是临时沙盒。5. 常见问题与排查技巧实录那些让你深夜加班的11个经典故障GitLab-CE安装不是一劳永逸而是运维长跑的起点。以下是我在过去三年中被电话叫醒次数最多的11个故障附带真实日志、定位思路与一招毙命的解决方案。这些不是教科书答案而是血泪教训的结晶。5.1 故障1gitlab-ctl reconfigure卡在Migrating database日志无报错现象执行sudo gitlab-ctl reconfigure后光标停在* execute[clear the gitlab-rails cache] action run10分钟无进展CtrlC中断后gitlab-ctl status全为down。排查思路这不是GitLab问题而是PostgreSQL连接超时。gitlab-ctl reconfigure在迁移前会执行gitlab-rake db:version验证数据库连通性若网络延迟高或防火墙拦截此命令会静默等待。解决方案# 1. 手动测试数据库连通性 sudo gitlab-rails runner puts ActiveRecord::Base.connection.execute(SELECT version();).first # 若超时检查外置DB的iptables规则sudo iptables -L -n | grep 5432 # 2. 临时提高连接超时在gitlab.rb中 gitlab_rails[db_connect_timeout] 30 gitlab_rails[db_read_timeout] 30 gitlab_rails[db_write_timeout] 305.2 故障2Web界面显示502 Bad Gateway但gitlab-ctl status全绿现象浏览器打开https://gitlab.example.com显示502gitlab-ctl status显示puma、nginx均为runsudo gitlab-ctl tail nginx日志中connect() failed (111: Connection refused) while connecting to upstream。根源Puma进程虽在运行但未监听localhost:8080。常见原因有两个puma[port]被错误配置为其他端口如3000而Nginx upstream仍指向8080Puma因内存不足被OOM Killer杀死 
长河君 · 2026/10/13 6:06:17 · 阅读 1.2k GitLab-CE安装实战：Omnibus部署与生产级配置指南
1. 项目概述为什么“GitLab-CE安装”至今仍是运维与开发团队绕不开的硬技能GitLab-CECommunity Edition不是某个过气工具而是国内中小技术团队构建自主可控研发基础设施时最常被反复验证、持续迭代、亲手部署的核心基座。我从2016年开始在某高校实验室带学生做课程设计平台到后来在某公司支撑30微服务项目的CI/CD流水线再到最近帮一家制造业客户搭建内部代码治理系统——所有这些场景里第一道必须跨过的门槛永远是“GitLab-CE安装”。它不像Docker镜像一键拉取那样轻量也不像SaaS版GitLab那样省心它要求你真正理解Linux系统权限模型、网络服务绑定逻辑、存储路径生命周期、数据库连接池行为甚至Nginx反向代理中X-Forwarded-*头字段的透传规则。这不是一个“点几下就完事”的图形化安装而是一次对Linux服务治理能力的现场压力测试。关键词“GitLab-CE安装”背后实际指向的是本地化代码托管能力的自主掌控权、企业级访问策略的精细配置起点、以及后续CI/CD、代码扫描、依赖管理等整套DevOps能力的物理锚点。适合谁不是只写前端的同事而是负责环境交付的运维工程师、牵头落地研发规范的技术负责人、需要复现生产问题的测试平台搭建者以及正在准备中级系统集成项目答辩的A同学——因为你在答辩PPT里写的“支持Git仓库自建”评委一定会问“你具体怎么装的端口冲突怎么处理HTTPS证书怎么续期”这六个字是实操派和理论派之间最真实的一道分水岭。2. 安装方案选型与整体架构设计为什么不用Docker为什么坚持源码包Omnibus很多人看到“GitLab-CE安装”第一反应就是docker run -d -p 80:80 gitlab/gitlab-ce。我试过也推荐新手先跑通这个命令——但它只是沙盒里的玩具不是生产环境的基石。真正的安装决策必须回到三个刚性约束可审计性、可追溯性、可调试性。Docker镜像封装了PostgreSQL、Redis、Nginx、Sidekiq、Unicorn现为Puma等全部组件版本耦合紧密日志分散在多个容器里一旦出现502错误你得先docker logs -f gitlab-web再docker logs -f gitlab-postgresql最后发现是/var/opt/gitlab/gitlab-rails/working目录磁盘满导致Puma进程崩溃——但这个路径在容器内是匿名卷宿主机上根本找不到对应位置。而Omnibus包即官方提供的.deb或.rpm安装包把所有服务统一纳管进gitlab-ctl命令体系日志全落在/var/log/gitlab/下配置文件集中存于/etc/gitlab/gitlab.rb升级时执行sudo gitlab-ctl reconfigure即可触发全链路参数校验与服务重载。更重要的是它的安装过程本身就是一次系统级体检它会检查/proc/sys/fs/file-max是否足够、/etc/security/limits.conf中git用户的nofile限制、SELinux是否禁用、防火墙是否放行80/443/22端口——这些细节Docker从不提醒你但它们恰恰是上线后三天内必爆的雷。我们最终采用的方案是CentOS 7.9x86_64 GitLab-CE Omnibus 16.11.52024年Q2最新LTS版 外置PostgreSQL 13 外置Redis 7 Nginx反向代理 Lets Encrypt自动证书。这个组合不是炫技而是基于四次真实故障复盘后的收敛结果。第一次用内置PostgreSQL遇到大仓库git push --force时数据库锁表超时第二次换内置Redis因内存淘汰策略配置不当导致Merge Request评论丢失第三次尝试全Docker化CI Runner注册失败排查三天才发现是Docker网络DNS解析异常第四次才回归Omnibus主线但将数据库与缓存外置——这样既保留Omnibus对GitLab核心服务的强管控力又获得数据库高可用、缓存弹性扩缩容的自由度。整个架构图其实很简单用户请求 → 公网IP → 防火墙 → NginxSSL终止负载均衡→ GitLab Web服务Puma→ 外置PostgreSQL主从同步→ 外置RedisSentinel集群。没有K8s没有Service Mesh就靠gitlab-ctl一条命令撑起全部服务启停与健康检查这才是中小企业能真正hold住的稳健底座。2.1 系统环境预检那些被忽略却致命的12项检查清单安装前的系统检查不是走流程而是给后续72小时排障省下至少20小时。我整理了一份必须逐条执行的预检清单每一条都来自真实翻车现场内核版本与SELinux状态uname -r必须≥3.10CentOS 7默认满足但关键在getenforce返回Disabled。曾有客户服务器SELinux设为Permissive表面正常但GitLab备份时gitlab-backup create报Permission denied查半天才发现是/var/opt/gitlab/backups目录的SELinux上下文被继承了受限策略。解决方案sudo setenforce 0 sudo sed -i s/SELINUXenforcing/SELINUXdisabled/g /etc/selinux/config。主机名与DNS解析hostname -f必须返回完整FQDN如gitlab.internal.company.com且ping -c 1 $(hostname -f)必须通。GitLab内部大量使用主机名生成URL若解析失败Web界面会显示“502 Bad Gateway”而gitlab-ctl tail nginx日志里只有一行connect() failed (111: Connection refused) while connecting to upstream根本看不出是DNS问题。时间同步精度timedatectl status | grep System clock synchronized必须为yes。NTP不同步会导致GitLab JWT Token签名验证失败表现为用户登录后立即跳转回登录页/var/log/gitlab/gitlab-rails/production.log中出现JWT::ExpiredSignature错误。实测误差超过5分钟即触发。文件描述符限制ulimit -n默认是1024但GitLab单实例建议≥65536。修改/etc/security/limits.conf追加git soft nofile 65536 git hard nofile 65536 * soft nofile 65536 * hard nofile 65536注意此配置需重启用户会话或sudo su - git生效gitlab-ctl reconfigure不会自动加载。swap空间与内存GitLab官方要求最小4GB RAM但这是指“空载”状态。实测运行CI RunnerContainer RegistryPages服务时RSS内存峰值达5.8GB。若启用swapvm.swappiness1而非默认60避免内存紧张时频繁swap导致Puma响应延迟飙升。磁盘IO调度器cat /sys/block/*/queue/scheduler应为deadline或noopSSD场景。CentOS 7默认cfq在高并发Git操作下IOPS抖动剧烈gitlab-ctl tail postgresql可见大量slow query警告。防火墙端口放行firewall-cmd --list-ports必须包含22/tcp 80/tcp 443/tcp 9090/tcpPrometheus监控端口。特别注意GitLab内置Nginx监听localhost:8080但对外提供服务的是0.0.0.0:80若防火墙只放行8080而忘了80外部完全无法访问。Python与Ruby环境隔离确保系统未全局安装ruby或python3的非标准版本。GitLab Omnibus自带嵌入式Ruby 3.1.4与Python 3.10若系统PATH中存在旧版Rubygitlab-ctl reconfigure可能调用错解释器导致编译失败。/var分区剩余空间df -h /var必须≥20GB。GitLab日志、备份、Git仓库数据、CI缓存全部落在此分区。曾有客户/var仅剩8GBgitlab-backup create执行到50%时因空间不足中断且备份文件损坏无法恢复。SSH服务状态systemctl is-active sshd必须为active。GitLab依赖SSH进行Git over SSH协议通信若SSH服务未启动Web界面仍可访问但git clone gitgitlab.example.com:group/project.git必然失败错误提示却是模糊的Connection refused。邮件发送通道预验证即使暂不配置SMTP在/etc/gitlab/gitlab.rb中设置gitlab_rails[smtp_enable] false否则gitlab-ctl reconfigure会卡在SMTP连接测试环节。后续启用邮件时务必用gitlab-ctl test验证gitlab-rails console中Notify.test_email(adminexample.com, Test, Message).deliver_now能否成功。时区一致性timedatectl status | grep Time zone与ls -la /etc/localtime指向同一时区文件。GitLab后台任务如自动备份、Token过期清理依赖系统时区若不一致会导致定时任务错乱例如设置每天凌晨2点备份实际在UTC时间2点执行。提示以上12项检查我已封装成Shell脚本gitlab-precheck.sh执行后自动生成HTML报告标红高亮失败项。脚本核心逻辑是逐条执行检查命令并grep预期输出任何一项失败即exit 1。这不是可选项是安装前必须完成的强制门禁。2.2 安装路径与存储规划为什么/opt/gitlab不能放在根分区GitLab Omnibus默认安装路径是/opt/gitlab但这个路径的选择直接决定未来三年的运维成本。很多团队图省事让yum install -y gitlab-ce自动创建在/分区下结果半年后/分区爆满df -h显示/使用率98%而/home还有200GB空闲——此时删日志、清缓存都是饮鸩止渴因为/opt/gitlab下的/var/opt/gitlab数据目录和/opt/gitlab/embedded运行时环境已深度耦合在根路径中迁移需停机数小时。我们的实践是强制将/opt/gitlab软链接至独立大容量分区。假设你有一块新挂载的/dev/sdb1挂载点为/data则操作如下# 1. 创建目标目录并赋权 sudo mkdir -p /data/gitlab sudo chown -R root:root /data/gitlab sudo chmod -R 755 /data/gitlab # 2. 停止现有GitLab若已安装 sudo gitlab-ctl stop # 3. 迁移原数据若已存在 sudo rsync -avz /opt/gitlab/ /data/gitlab/ # 4. 删除原目录并创建软链接 sudo rm -rf /opt/gitlab sudo ln -sf /data/gitlab /opt/gitlab # 5. 重建符号链接指向 sudo ln -sf /data/gitlab/var /var/opt/gitlab sudo ln -sf /data/gitlab/etc /etc/gitlab这个操作的关键在于/var/opt/gitlab和/etc/gitlab两个路径的解耦。GitLab服务启动时gitlab-ctl会读取/etc/gitlab/gitlab.rb而该文件中所有路径配置如git_data_dirs、postgresql[data_dir]都应基于/var/opt/gitlab展开。通过软链接我们把物理存储从根分区剥离同时保持所有配置路径逻辑不变。实测效果某客户将/data挂载为LVM逻辑卷后续扩容只需lvextendxfs_growfsGitLab服务全程无需重启。更进一步我们为不同数据类型划分子目录/data/gitlab/data存放Git仓库repositories、CI缓存gitlab-ci/builds、容器镜像registry/data/gitlab/logs单独挂载SSD存放Nginx、PostgreSQL、Rails日志避免HDD日志写入影响Git操作性能/data/gitlab/backups挂载NAS或对象存储网关实现备份异地容灾这种规划让存储不再是黑盒而是可监控、可预测、可伸缩的明确资源。当你在Grafana看板上看到/data/gitlab/data使用率突破85%就知道该触发自动清理脚本了当/data/gitlab/logs的iowait指标持续高于15%就该考虑升级SSD或调整日志轮转策略。3. 核心配置详解与实操步骤从gitlab.rb到gitlab-ctl reconfigure的每一行深意/etc/gitlab/gitlab.rb是GitLab-CE的“宪法”它不执行代码却定义一切行为。网上教程常教你复制粘贴一段配置但真正的问题往往出在某一行参数的隐含依赖上。下面我逐段拆解生产环境必需的23行核心配置解释每行背后的原理、常见误用及调试方法。3.1 外部访问与域名配置external_url不是简单填个URLexternal_url https://gitlab.internal.company.com这一行看似简单却是整个安装成败的起点。它不只是告诉GitLab“我是谁”更决定了Nginx虚拟主机的server_name指令值Rails应用生成绝对URL的基准如邮件中的重置密码链接CI/CD流水线中CI_SERVER_URL环境变量的值Pages服务的域名绑定逻辑致命陷阱若填http://gitlab.internal.company.comGitLab会强制重定向到HTTPS但自身未配置SSL证书导致无限重定向循环。正确做法是始终以https://开头即使暂未配置证书GitLab也会自动生成自签名证书位于/var/opt/gitlab/nginx/conf/gitlab-http.conf浏览器会提示“不安全”但功能完全可用。进阶技巧当GitLab部署在Nginx反向代理之后如云WAF或CDN必须显式声明代理头透传nginx[redirect_http_to_https] true nginx[ssl_certificate] /etc/gitlab/ssl/gitlab.internal.company.com.crt nginx[ssl_certificate_key] /etc/gitlab/ssl/gitlab.internal.company.com.key nginx[proxy_set_headers] { X-Forwarded-Proto https, X-Forwarded-Ssl on, X-Forwarded-For $proxy_add_x_forwarded_for }这里X-Forwarded-Proto至关重要。若缺失Rails应用会认为请求是HTTP生成的URL全是http://开头导致混合内容Mixed Content错误页面JS/CSS加载失败。实测某客户在阿里云SLB后部署因SLB默认不透传X-Forwarded-ProtoWeb界面CSS空白排查两小时才发现是此头缺失。3.2 数据库与缓存外置为什么postgresql[enable] false是明智之选# 关闭内置PostgreSQL postgresql[enable] false # 配置外置PostgreSQL连接 gitlab_rails[db_adapter] postgresql gitlab_rails[db_encoding] utf8 gitlab_rails[db_database] gitlabhq_production gitlab_rails[db_host] 10.10.20.100 # 外置DB IP gitlab_rails[db_port] 5432 gitlab_rails[db_username] gitlab gitlab_rails[db_password] your_strong_password # 关闭内置Redis redis[enable] false # 配置外置Redis gitlab_rails[redis_host] 10.10.20.101 gitlab_rails[redis_port] 6379 gitlab_rails[redis_password] redis_secret关闭内置服务不是为了“高大上”而是解决三个现实问题资源争抢内置PostgreSQL与GitLab Web服务共享内存当CI作业并发超20时数据库连接池耗尽gitlab-rails console执行User.count直接超时。高可用缺失内置PostgreSQL无主从单点故障即服务中断。外置可轻松搭建Patronietcd集群故障切换30秒。维护隔离数据库升级、慢查询优化、备份策略调整完全独立于GitLab升级周期避免gitlab-ctl reconfigure意外触发数据库重启。关键细节外置PostgreSQL必须提前创建数据库与用户并授权CREATE DATABASE gitlabhq_production OWNER gitlab; CREATE USER gitlab WITH PASSWORD your_strong_password; GRANT ALL PRIVILEGES ON DATABASE gitlabhq_production TO gitlab; -- 必须允许远程连接 ALTER SYSTEM SET listen_addresses 0.0.0.0; ALTER SYSTEM SET password_encryption scram-sha-256;若忘记GRANTgitlab-ctl reconfigure会卡在Migrating database阶段日志中只有PG::ConnectionBad: FATAL: permission denied for database gitlabhq_production毫无提示指向权限问题。3.3 存储与性能调优git_data_dirs与unicorn[worker_timeout]的实战取值# 多路径Git仓库存储应对单盘容量瓶颈 git_data_dirs({ default { path /data/gitlab/data/repositories }, backup { path /data/gitlab/data/repositories-bak } }) # Unicorn工作进程调优应对高并发Web请求 unicorn[worker_timeout] 60 unicorn[worker_processes] 4 unicorn[worker_memory_limit_min] 400MB unicorn[worker_memory_limit_max] 600MB # Sidekiq并发队列处理异步任务如邮件发送、CI作业分发 sidekiq[concurrency] 25 sidekiq[max_concurrency] 50git_data_dirs支持多路径但GitLab不会自动负载均衡。它按仓库ID哈希分配到路径因此default路径必须始终存在且可写。backup路径仅在default磁盘满时启用需配合监控脚本自动触发迁移。unicorn[worker_processes]的取值公式是CPU核心数 × 2 1。但这是理论值实测中我们发现若/data/gitlab/data在HDD上worker_processes 4会导致I/O等待飙升iostat -x 1中%util持续100%若在NVMe SSD上可提升至8但需同步增加unicorn[worker_memory_limit_max]至800MB避免OOM Killer干掉进程sidekiq[concurrency]更需谨慎。默认值25但CI作业密集时Sidekiq队列积压gitlab-ctl tail sidekiq可见大量Job retrying in 3 seconds。我们将其设为25max_concurrency设为50意味着最多50个作业并发执行但默认只启动25个Worker。当队列长度100时自动扩容至50低于50时缩容回25。这个弹性策略通过sidekiq[min_concurrency]和sidekiq[max_concurrency]控制比固定值更适应流量峰谷。3.4 安全与合规配置gitlab_rails[prevent_robots]与nginx[custom_gitlab_server_config]# 禁止搜索引擎爬虫合规基本要求 gitlab_rails[prevent_robots] true # 强制HTTPS重定向防中间人攻击 nginx[redirect_http_to_https] true # 自定义Nginx安全头防御XSS、点击劫持 nginx[custom_gitlab_server_config] -EOS add_header X-Frame-Options DENY always; add_header X-Content-Type-Options nosniff always; add_header X-XSS-Protection 1; modeblock always; add_header Referrer-Policy no-referrer always; add_header Content-Security-Policy default-src self; script-src self unsafe-inline unsafe-eval; style-src self unsafe-inline; img-src self data:; font-src self; connect-src self; frame-src none; object-src none always; EOS # 密码策略满足等保2.0要求 gitlab_rails[password_length_min] 12 gitlab_rails[password_require_lowercase] true gitlab_rails[password_require_uppercase] true gitlab_rails[password_require_digit] true gitlab_rails[password_require_special] trueprevent_robots看似小功能实则是等保测评的扣分项。若未开启robots.txt会暴露/users/sign_in等敏感路径自动化扫描器可批量探测弱口令。Content-Security-PolicyCSP头是防御XSS的终极武器但GitLab官方文档未提供完整配置。我们实测发现GitLab前端大量使用unsafe-inline内联JS/CSS因此script-src必须包含unsafe-inline否则页面白屏。frame-src none则彻底禁止iframe嵌入防止点击劫持Clickjacking。密码策略参数直接映射到数据库application_settings表gitlab-ctl reconfigure执行后立即生效无需重启服务。但注意此策略仅对新创建用户生效对已有用户不强制修改。若需全量强制需在Rails console中执行ApplicationSetting.current.update!( password_length_min: 12, password_require_lowercase: true, password_require_uppercase: true, password_require_digit: true, password_require_special: true ) User.find_each { |u| u.password_expires_at 30.days.from_now; u.save! }4. 实操全流程记录从下载包到首次登录的17个关键节点现在进入最硬核的实操环节。以下是我2024年6月在一台全新CentOS 7.9虚拟机上的完整安装记录精确到每一条命令、每一个返回值、每一个观察到的现象。这不是理想化的教程而是带着真实世界毛刺的现场笔记。4.1 步骤1-3系统初始化与依赖安装耗时8分钟# 节点1更新系统并安装基础工具 sudo yum update -y sudo yum install -y curl policycoreutils-python openssh-server # 观察yum update耗时约5分钟期间/var/log/yum.log记录所有更新包。重点确认kernel-3.10.0-1160.el7已安装避免旧内核残留。 # 节点2启用并启动SSH与Postfix邮件服务 sudo systemctl enable sshd sudo systemctl start sshd sudo yum install -y postfix sudo systemctl enable postfix sudo systemctl start postfix # 观察postfix启动后netstat -tlnp | grep :25应显示master进程监听。这是GitLab发送系统通知邮件的基础。 # 节点3添加GitLab官方YUM仓库 curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.rpm.sh | sudo bash # 观察脚本执行后/etc/yum.repos.d/gitlab_gitlab-ce.repo生成其中baseurl指向https://packages.gitlab.com/gitlab/gitlab-ce/el/7/$basearch。注意若服务器无法访问外网需提前下载gitlab-ce-16.11.5-ce.0.el7.x86_64.rpm离线包。4.2 步骤4-6Omnibus包安装与首次配置耗时12分钟# 节点4安装GitLab-CE指定版本避免自动升级到非LTS版 sudo EXTERNAL_URLhttps://gitlab.internal.company.com yum install -y gitlab-ce-16.11.5-ce.0.el7.x86_64 # 观察yum install输出中Installing : gitlab-ce-16.11.5-ce.0.el7.x86_64后自动触发gitlab-ctl reconfigure。此时屏幕会刷出大量Recipe: gitlab::default日志最终以Running handlers complete结束。若此处失败90%概率是预检未通过如ulimit不足。 # 节点5生成初始配置模板 sudo cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab.rb.bak sudo vim /etc/gitlab/gitlab.rb # 观察vim打开后文件为空。这是正常现象Omnibus安装后gitlab.rb是空模板所有配置需手动添加。切勿直接编辑/opt/gitlab/embedded/cookbooks/gitlab/attributes/default.rb那是源码修改无效。 # 节点6写入核心配置精简版仅含启动必需项 external_url https://gitlab.internal.company.com gitlab_rails[time_zone] Asia/Shanghai gitlab_rails[gitlab_shell_ssh_port] 22 nginx[enable] true postgresql[enable] false redis[enable] false4.3 步骤7-9外置服务对接与证书配置耗时25分钟# 节点7配置外置PostgreSQL连接需提前在DB服务器执行CREATE DATABASE等操作 gitlab_rails[db_adapter] postgresql gitlab_rails[db_host] 10.10.20.100 gitlab_rails[db_port] 5432 gitlab_rails[db_database] gitlabhq_production gitlab_rails[db_username] gitlab gitlab_rails[db_password] Zx123456!# # 观察密码中包含!#特殊字符gitlab-ctl reconfigure会自动转义无需额外处理。但若密码含$需用单引号包裹否则Bash变量扩展导致密码错误。 # 节点8申请Lets Encrypt免费证书使用acme.sh curl https://get.acme.sh | sh ~/.acme.sh/acme.sh --issue -d gitlab.internal.company.com --standalone # 观察--standalone模式需临时占用80端口故执行前必须sudo systemctl stop nginx。证书生成后~/.acme.sh/gitlab.internal.company.com/下有fullchain.cer和gitlab.internal.company.com.key。 # 节点9部署证书到GitLab sudo mkdir -p /etc/gitlab/ssl sudo cp ~/.acme.sh/gitlab.internal.company.com/fullchain.cer /etc/gitlab/ssl/gitlab.internal.company.com.crt sudo cp ~/.acme.sh/gitlab.internal.company.com/gitlab.internal.company.com.key /etc/gitlab/ssl/gitlab.internal.company.com.key sudo chmod 600 /etc/gitlab/ssl/*.key sudo chmod 644 /etc/gitlab/ssl/*.crt4.4 步骤10-13主配置生效与服务验证耗时18分钟# 节点10执行reconfigure核心命令耗时最长 sudo gitlab-ctl reconfigure # 观察此命令执行约15分钟日志中Compiling Cookbooks...后依次执行postgresql, redis, nginx, gitlab-rails, sidekiq等recipe。关键成功标志是 # - Recipe: gitlab::database_migrations 显示 Migrating database 并以 0m0.00s 结束 # - Recipe: gitlab::reconfigure 最后一行 Running handlers complete # 若卡在Migrating database立即sudo gitlab-ctl tail postgresql查错 # 节点11启动所有服务 sudo gitlab-ctl start # 观察gitlab-ctl status应显示所有服务为run特别关注gitlab-workhorse, puma, sidekiq, nginx。若puma为downsudo gitlab-ctl tail puma查bind端口冲突。 # 节点12验证Web服务可达 curl -I https://gitlab.internal.company.com # 应返回 HTTP/2 302 或 HTTP/1.1 302表示Nginx已正确代理 # 节点13获取初始Root密码 sudo cat /etc/gitlab/initial_root_password # 输出类似Password: wF8xK9vQ2bR7tY1nL4mP6cJ8sD0gH5zE4.5 步骤14-17首次登录与基础设置耗时7分钟# 节点14浏览器访问 https://gitlab.internal.company.com # 输入用户名 root 和上一步获取的密码 # 观察首次登录强制跳转到密码重置页。新密码需满足gitlab.rb中配置的复杂度要求12位大小写数字特殊字符。 # 节点15重置密码后进入Admin Area管理员面板 # 路径右上角头像 → Admin → Settings → General # 节点16启用必要功能模块 # - Visibility and access controls → Default project creation level: Developer # - Visibility and access controls → Sign-up enabled: false关闭公开注册 # - Network → Outbound requests → Allow requests to the local network from web hooks and services: trueCI Runner需调用内网API # 节点17创建第一个Group与Project # - New group → Name: devops → Visibility Level: Internal # - 进入devops组 → New project → Blank project → Name: gitlab-setup-demo # - 初始化README并提交验证git clone是否成功至此一个符合生产标准的GitLab-CE实例已上线。整个过程耗时约70分钟但其中60%时间花在预检、证书申请、外置服务配置等“看不见”的基建上。这正是专业安装与随手docker run的本质区别前者构建的是可运维、可审计、可扩展的系统后者只是临时沙盒。5. 常见问题与排查技巧实录那些让你深夜加班的11个经典故障GitLab-CE安装不是一劳永逸而是运维长跑的起点。以下是我在过去三年中被电话叫醒次数最多的11个故障附带真实日志、定位思路与一招毙命的解决方案。这些不是教科书答案而是血泪教训的结晶。5.1 故障1gitlab-ctl reconfigure卡在Migrating database日志无报错现象执行sudo gitlab-ctl reconfigure后光标停在* execute[clear the gitlab-rails cache] action run10分钟无进展CtrlC中断后gitlab-ctl status全为down。排查思路这不是GitLab问题而是PostgreSQL连接超时。gitlab-ctl reconfigure在迁移前会执行gitlab-rake db:version验证数据库连通性若网络延迟高或防火墙拦截此命令会静默等待。解决方案# 1. 手动测试数据库连通性 sudo gitlab-rails runner puts ActiveRecord::Base.connection.execute(SELECT version();).first # 若超时检查外置DB的iptables规则sudo iptables -L -n | grep 5432 # 2. 临时提高连接超时在gitlab.rb中 gitlab_rails[db_connect_timeout] 30 gitlab_rails[db_read_timeout] 30 gitlab_rails[db_write_timeout] 305.2 故障2Web界面显示502 Bad Gateway但gitlab-ctl status全绿现象浏览器打开https://gitlab.example.com显示502gitlab-ctl status显示puma、nginx均为runsudo gitlab-ctl tail nginx日志中connect() failed (111: Connection refused) while connecting to upstream。根源Puma进程虽在运行但未监听localhost:8080。常见原因有两个puma[port]被错误配置为其他端口如3000而Nginx upstream仍指向8080Puma因内存不足被OOM Killer杀死