接到这个需求的时候，我第一反应其实是找现成的安装包。GitLab 官方 Omnibus 安装包用起来多省事，一条命令装完。可等我看清目标机器的架构是 ARM64、系统是统信UOS 的时候，这条路基本断了一半。官方 Omnibus 仓库对 ARM64 的覆盖本来就有限，对统信UOS这种发行版更是没有现成的内置包。于是只能老老实实走源码编译的路子：在 UOS 上把 GitLab CE 从源码一步步搭起来。这篇文章是我整个过程的实操记录，内容包括版本选择、依赖准备、源码编译、数据库初始化、服务启动，以及一堆我在 ARM64 环境下反复踩过的坑，适合准备在国产化环境里自建代码托管平台的同学参考，也给要维护 ARM64 服务器的人避避雷。
1. 需求剖析与方案选型
1.1 为什么非要用源码方式搭
先交代一下背景。这个项目所在的机器是一台 ARM64 架构的服务器，操作系统是统信UOS。彼时手头要搭建企业内部代码托管平台，既要支持 SSH 克隆，又要接 CI 流水线，还要能跑项目权限管理，GitLab 在这些能力上比较完整，所以选型几乎没犹豫。
但真正操作起来就发现，问题全在安装环节。官方 Omnibus 安装包虽然支持 Debian / Ubuntu 等系统，但对统信UOS这种国产发行版并没有内置包，对 ARM64 的支持更是有限。有人可能会想：那我直接去 GitHub 下载一个通用二进制包不就行了？实际操作下来，Omnibus 包内部把 Ruby、PostgreSQL、Redis 这些运行时全部打包在了一起，而且把路径固定到了/opt/gitlab/embedded这种目录里。在不匹配的发行版上，glibc 版本、库文件路径一有差异，启动就是一连串的undefined symbol或者cannot open shared object file，排查起来非常折磨。
源码安装的好处就是完全绕开这种"内置运行时"的依赖，所有组件都跟随你用系统包管理器和源码编译的版本走，路径、版本、编译参数都可以自己控制。在统信UOS这种相对小众的环境里，这种方式兼容性最好。代价也很明显：编译时间长，依赖多，中间容易出错，但一旦跑通，后面扩展和定制组件版本也方便。
1.2 源码安装相比安装包的取舍
我在方案评审的时候列过一张对比表，基本可以代表源码安装和 Omnibus 安装的差异：
| 对比维度 | Omnibus 安装包 | 源码安装 |
|---|---|---|
| 安装速度 | 快，一条命令+依赖检查 | 很慢，光编译 Assets 可能就要半小时以上 |
| 对发行版要求 | 严格，只支持少数主流发行版 | 宽松，只要依赖能装齐就能编 |
| 路径控制 | 固定/opt/gitlab | 自己定义，如/home/git/gitlab |
| 组件版本 | 官方锁定 | 自己选，但要匹配 GitLab 依赖要求 |
| 二次开发 | 不方便改内部代码 | 直接在源码里改，改完重新 Rails 启动 |
| 升级维护 | 官方重建包，操作简单 | 需要自己重新走编译流程，工作量偏大 |
| 排障难度 | 内置组件黑盒 | 组件都是系统库和服务，排查路径清晰 |
当时的结论很简单：既然目标是统信UOS + ARM64 这种官方没有预编译包的组合，就没什么可纠结的，源码安装是唯一能让所有组件版本可控、后续能维护下去的方式。下面进入正题。
2. 环境准备与版本规划
2.1 确认环境信息
动手前先花五分钟把机器环境核对清楚，这一步省得后面反复改路径。我在服务器上执行了下面几条命令：
uname -m # 确认是否为 aarch64 cat /etc/os-release # 确认系统发行版和版本号 lscpu # 确认 CPU 核数和架构 free -h # 确认内存大小 df -h /home # 确认磁盘剩余空间我这边输出的架构是aarch64，系统是统信UOS V20，内存 16G，磁盘剩余 80G。GitLab 源码编译对磁盘和内存的要求都不低，磁盘建议至少预留 40G，内存建议 8G 以上，内存不够的话编译到前端 Assets 阶段大概率会触发 OOM。如果目标机器内存不够，至少把 swap 调大，我后面在排障章节会专门说。
2.2 安装系统依赖
统信UOS 社区版基于 Debian 体系，包管理器是 apt。如果你的 UOS 版本是服务器版且衍生自 CentOS 体系，那把 apt 换成 yum 即可，包名可以通过 yum 搜索确认。
安装编译工具链和基础依赖库的命令如下：
sudo apt update sudo apt install -y build-essential \ curl wget rsync \ libssl-dev libkrb5-dev \ libxml2-dev libxslt1-dev \ libicu-dev libpq-dev \ zlib1g-dev libreadline-dev \ libsqlite3-dev \ libssh2-1-dev \ libcurl4-openssl-dev \ pkg-config cmake \ graphviz这里面有一个特别容易忽略的：libicu-dev。GitLab 的国际化处理依赖 ICU，缺失的话后面编译nokogiri或rugged会直接报错。还有libssh2-1-dev，编译rugged需要它。graphviz是生成文档图表用的，GitLab 里部分 Rake 任务会调用。
2.3 创建专用用户与目录规划
GitLab 官方强烈不建议直接用 root 跑。我创建了一个git用户，所有服务和代码都装在这个用户下面：
sudo useradd --create-home --shell /bin/bash git sudo passwd git然后规划目录结构。我采用的是官方手动安装文档推荐的布局，方便后续升级和备份：
/home/git/ ├── gitlab/ # GitLab 主源码目录 ├── gitlab-shell/ # SSH 访问仓库的配套组件 ├── gitaly/ # Git RPC 服务组件 ├── repositories/ # 实际仓库存储目录 └── .gitlab_shell/ # Shell 配置目录这些目录先不急着创建，后面每一步用到时再建。源码目录的属主要记得给git用户。很多新手容易在这个环节踩坑，后面启动 Rails 时会遇到 permission denied，原因全是目录属主不对。
3. 核心组件安装与版本匹配
3.1 GitLab 与依赖组件的版本对应关系
这是整个搭建过程里我最想强调的一点：GitLab 的源码安装对组件版本要求很严格，Ruby 大版本、Node 大版本、Go 版本、PostgreSQL 版本、Redis 版本都有上下限。不同版本 GitLab 之间的依赖差异很大，不要随便拿一个最新版 Ruby 就去编。
我这里拿 GitLab CE 14.10 系列为例，这是我实际采用的版本组合：
| 组件 | 版本要求 | 我实际使用的版本 |
|---|---|---|
| GitLab CE | 14.10.x | 14.10.5 |
| Ruby | 2.7.x | 2.7.5 |
| Bundler | 2.x | 2.3.11 |
| PostgreSQL | 12.x 或 13.x | 13.4 |
| Redis | 4.0 以上 | 6.0.16 |
| Node.js | 14.x | 14.18.2 |
| Yarn | 1.22.x | 1.22.19 |
| Go | 1.16 ~ 1.17 | 1.17.7 |
如果你要用 GitLab 15 或更高的版本，Ruby 至少要 3.0，Node 要 16，Go 要 1.19 以上，对应的编译参数和配置文件也可能变化。我的建议是：选定一个版本组合后，严格按照官方该版本的依赖说明来安装，不要混搭。
3.2 Ruby 与 Bundler 安装
UOS 系统仓库自带的 Ruby 版本通常很低，满足不了 GitLab 的要求。我从源码编译的方式安装指定版本的 Ruby：
sudo apt install -y autoconf bison libyaml-dev libgdbm-dev libncurses-dev cd /usr/local/src sudo curl -L -o ruby-2.7.5.tar.gz https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.5.tar.gz sudo tar xzf ruby-2.7.5.tar.gz cd ruby-2.7.5 sudo ./configure --prefix=/usr/local/ruby sudo make -j$(nproc) sudo make install编译完成后把路径写进git用户的.bashrc：
export PATH="/usr/local/ruby/bin:$PATH" export GEM_HOME="/usr/local/ruby/lib/ruby/gems/2.7.0"然后验证：
ruby -v gem -v bundle -vbundle -v如果提示找不到，说明本机还没装 Bundler，执行gem install bundler -v 2.3.11即可。这里提醒一句：Ruby 源码编译在 ARM64 上比较慢，实测大概十分钟左右，如果中途报错，优先看是不是缺了 libyaml-dev 这类依赖。
3.3 Go、Node 与 Yarn 安装
GitLab 里负责 Git 操作的核心组件 Gitaly 是用 Go 写的，必须装 Go。我从官方下载了 go1.17.7 的 ARM64 包，解压到/usr/local/go：
cd /usr/local sudo curl -L -o go1.17.7.linux-arm64.tar.gz https://go.dev/dl/go1.17.7.linux-arm64.tar.gz sudo tar xzf go1.17.7.linux-arm64.tar.gz export PATH="/usr/local/go/bin:$PATH" go version前端资源编译需要 Node.js 和 Yarn。因为 GitLab 14 前端构建要求 Node 14，所以我装的是 Node 14.18.2：
curl -L -o node-v14.18.2-linux-arm64.tar.xz https://nodejs.org/dist/v14.18.2/node-v14.18.2-linux-arm64.tar.xz sudo tar xJf node-v14.18.2-linux-arm64.tar.xz -C /usr/local/ export PATH="/usr/local/node-v14.18.2-linux-arm64/bin:$PATH"Yarn 用npm install -g yarn@1.22.19安装即可。这里我要特别提醒：不要图省事用系统自带的 Node 或者最新版 Node，前端依赖里sass等包的编译对 Node ABI 版本敏感，Version 不匹配会直接编译失败。
3.4 PostgreSQL 与 Redis 准备
GitLab 的元数据全部存储在 PostgreSQL 里，仓库引用和任务队列依赖 Redis。这一步我更推荐直接用 UOS 仓库里的包，省去编译数据库的时间。
sudo apt install -y postgresql-13 redis-server sudo systemctl enable --now postgresql sudo systemctl enable --now redis-server然后给 GitLab 创建数据库和用户。GitLab 会要求一个单独的用户，不能使用 postgres 超级用户直接跑：
sudo -u postgres psql -c "CREATE USER gitlab CREATEDB;" sudo -u postgres psql -c "CREATE DATABASE gitlabhq_production OWNER gitlab;"Redis 这边有一个关键配置：GitLab 通过 unix socket 连接 Redis 在性能上更好，但也容易出权限问题。我采用的方案是让 Redis 监听本地 TCP 端口，简单直接，后面配置gitlab.yml时写redis://127.0.0.1:6379即可。
4. 源码编译与配置落地
4.1 准备 GitLab 源码和配套组件
主源码我直接从 GitLab 官方仓库拉取指定 tag：
sudo -u git -H git clone --branch v14.10.5 --depth 1 https://gitlab.com/gitlab-org/gitlab.git /home/git/gitlab cd /home/git/gitlab这里建议用--depth 1只拉一个 tag，不要全量 clone，否则历史提交会占掉很多磁盘空间和时间。拉完代码后，还要准备两个配套组件：gitlab-shell和gitaly。它们和 GitLab 主版本有严格对应关系，特别是 Gitaly 的版本必须跟主版本匹配：
sudo -u git -H git clone --branch v14.10.5 --depth 1 https://gitlab.com/gitlab-org/gitlab-shell.git /home/git/gitlab-shell sudo -u git -H git clone --branch v14.10.5 --depth 1 https://gitlab.com/gitlab-org/gitaly.git /home/git/gitaly配置文件的起点是官方自带的模板。在/home/git/gitlab下：
cd /home/git/gitlab sudo -u git cp config/gitlab.yml.example config/gitlab.yml编辑gitlab.yml里的核心配置项，重点包括host、port、repositories路径以及gitlab-shell的secret_token。secret_token要在/home/git/gitlab-shell下单独生成并复制到主配置中：
sudo -u git -H /home/git/gitlab-shell/bin/install这条命令会自动生成secret_token并完成 shell 组件的初始化。如果没有执行这一步，后面通过 SSH 访问仓库时会报 key 验证失败。
4.2 后端依赖安装踩坑实录
GitLab 主目录下执行 bundle 安装：
cd /home/git/gitlab sudo -u git -H bundle install --without development test --jobs 4这个过程在 ARM64 上会经历大量 native extension 编译，比如nokogiri、json、rugged、bcrypt、eventmachine等。我实际遇到的两个高频报错：
第一个是nokogiri编译失败，提示找不到 libxml2 或 libxslt。原因是系统里虽然装了基础库，但缺少开发头文件。解决方式就是回到 2.2 节把libxml2-dev libxslt1-dev libicu-dev装齐。
第二个是rugged编译失败，它依赖 libgit2，而且需要 libssh2 支持。只装libssh2-1-dev还不够，有时候还会提示libssh2.h找不到，此时可以用：
sudo apt install -y libssh2-1-dev libgit2-dev装完后不需要清理整个 bundle，直接重跑一次bundle install即可，已编译成功的 gem 会被缓存。
这里还要补充一个我踩了很久的坑：不要在 root 下执行bundle install。GitLab 的很多文件属主要和运行用户一致，如果你用 root 装了 bundle，后面切换成git用户跑 Rails 时，会遇到Gem::FilePermissionError，到时候再 chown 一堆目录会很麻烦。
4.3 前端资源编译
后端依赖装完之后，开始编译前端静态资源。命令如下：
cd /home/git/gitlab sudo -u git -H yarn install --frozen-lockfile sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production NODE_ENV=production这一步是耗时最长的环节，在 ARM64 上实测接近四十分钟，期间 CPU 会长时间满载，风扇起飞属于正常现象。我的建议是不要全程盯着屏幕，改用后台执行并把日志写入文件：
sudo -u git -H nohup bundle exec rake assets:precompile RAILS_ENV=production NODE_ENV=production > /tmp/assets.log 2>&1 & tail -f /tmp/assets.log如果日志里出现Command failed或者Sass::CompilationFailed，原因通常是系统缺少graphviz或者内存不足导致node子进程被杀。前者安装 graphviz 包即可，后者就要参考排障章节调整 swap。
4.4 Gitaly、Puma 与 Sidekiq 配置
Gitaly 是 GitLab 内部所有 Git 操作的实际执行者，源码装好后需要单独编译：
cd /home/git/gitaly sudo -u git -H make allGitaly 的配置在/home/git/gitaly/config.toml。我使用的是最简单的socket模式：
socket_path = "/home/git/gitaly/gitaly.sock" token = "your-secret-token" [storage] name = "default" path = "/home/git/repositories"这个 token 要和gitlab.yml里 gitaly 相关的token保持一致，不然 Rails 和 Gitaly 之间握手失败，页面会一直转圈。
Puma 的配置在config/puma.rb，源码包自带模板，直接复制：
sudo -u git cp config/puma.rb.example config/puma.rb模板默认绑定tcp://127.0.0.1:8080，端口冲突可以改。我建议把 worker 数调低一点，在 2~4 之间，ARM64 机器上太高的话内存很容易吃紧。Sidekiq 是 GitLab 的异步任务队列，启动命令可以在源码自带的lib/support目录下找 service 模板，也可以直接用下面的方式启动：
cd /home/git/gitlab sudo -u git -H nohup bundle exec sidekiq -e production -C config/sidekiq.yml > /tmp/sidekiq.log 2>&1 &5. 初始化数据库与启动联调
5.1 初始化数据库
在启动服务之前，要先让 Rails 读取配置文件并初始化数据库结构：
cd /home/git/gitlab sudo -u git -H bundle exec rake db:create RAILS_ENV=production sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=productionrake db:create会根据gitlab.yml里的数据库配置连接 PostgreSQL。如果创建失败，八成是 3.4 节里创建的数据库用户和密码没有正确写入config/database.yml。
这一步执行完后，控制台会输出 GitLab 的初始管理员账号，一般是root@local.host，系统会提示你设置密码。如果忘记设置，可以用：
sudo -u git -H bundle exec rails console -e production u = User.find(1) u.password = '新密码' u.password_confirmation = '新密码' u.save! exit这种方式重置管理员密码，比直接改数据库要安全，Rails 会自动做密码哈希和验证规则处理。
5.2 服务启动顺序与维护命令
源码安装模式下，没有gitlab-ctl这种统一管理命令，所以必须手动控制服务启动顺序。我推荐的顺序是：
- Redis
- PostgreSQL
- Gitaly
- Sidekiq
- Puma
- GitLab Workhorse
前两个由 systemd 管理，直接systemctl start即可。Gitaly 需要在/home/git/gitaly目录下编译并启动：
cd /home/git/gitaly sudo -u git -H nohup ./gitaly config.toml > /tmp/gitaly.log 2>&1 &GitLab Workhorse 是反向代理，负责把 HTTP 请求转发给 Puma 和 Gitaly。它的源码在/home/git/gitlab/workhorse子目录下，编译并启动：
cd /home/git/gitlab/workhorse sudo -u git -H make build sudo -u git -H nohup ./gitlab-workhorse -listenNetwork tcp -listenAddr "127.0.0.1:8181" -authBackend "http://127.0.0.1:8080" > /tmp/workhorse.log 2>&1 &最后启动 Puma：
cd /home/git/gitlab sudo -u git -H nohup bundle exec puma -C config/puma.rb -e production > /tmp/puma.log 2>&1 &这里要注意：源码安装里 Puma 默认监听 8080，Workhorse 监听 8181，如果你只想访问原始 Rails 端口，可以直接用http://服务器IP:8080。但我建议把 Nginx 或 Workhorse 放在前面做入口，这样静态资源处理和 SSH 转发都更自然。
5.3 功能验证清单
服务起来之后，我按下面的清单验证：
| 验证项 | 验证方式 | 预期结果 |
|---|---|---|
| Puma 存活 | curl -I http://127.0.0.1:8080 | 返回 HTTP 302 |
| 页面入口 | 浏览器访问http://服务器IP:8080 | 显示 GitLab 登录页 |
| 注册登录 | 使用 root 登录 | 能进入管理后台 |
| SSH 验证 | ssh -T git@服务器IP | 提示 Welcome to GitLab |
| 仓库创建 | 新建项目并初始化 README | 能显示文件列表 |
| 仓库克隆 | git clone git@服务器IP:/project.git | 能正常克隆 |
| 提交推送 | 修改文件并 push | 页面能刷新出提交记录 |
| CI 检查 | 项目里创建.gitlab-ci.yml并启用 Runner | Pipeline 能创建任务 |
其中 SSH 验证这一步非常关键。如果提示Permission denied (publickey)，先确认用户的公钥已经添加到 GitLab 的 SSH Keys 里，再看gitlab-shell的authorized_keys配置是否正确。源码安装模式下，authorized_keys一般是git用户下的~/.ssh/authorized_keys，要注意目录权限必须是 700，文件权限必须是 600。
6. 常见问题速查与避坑技巧
6.1 ARM64 编译问题
在 ARM64 环境里，最普遍的问题是某些 gem 没有预编译的 ARM64 版本，必须现场编译，但现场编译经常缺依赖。这里把所有高频问题汇总成一张表：
| 症状 | 可能原因 | 处置方法 |
|---|---|---|
nokogiri编译失败 | 缺少 libxml2/libxslt 开发头文件 | 安装libxml2-dev libxslt1-dev |
rugged编译失败 | 缺少 libssh2/libgit2 | 安装libssh2-1-dev libgit2-dev |
eventmachine编译失败 | 缺少libssl-dev | 安装libssl-dev后重新 bundle |
Gitalygo build拉取依赖失败 | Go module 下载受限 | 提前在能访问软件源的环境里下载依赖，或用内网 Go module 缓存 |
| Assets 编译时 node OOM | 内存不足 | 调整 swap 或减少 Yarn 并发 |
关于 Go module 依赖，我要多说一句：Gitaly 的依赖很多，离线环境下非常痛苦。最稳妥的方式是在有网络的环境中先把 Gitaly 仓库 clone 下来，然后执行go mod vendor把依赖打进 vendor 目录，再把整个目录拷到目标机上。这样后续就算目标机器不能访问外部的 Go module 源，也能正常编译。
6.2 运行时与运维问题
| 症状 | 可能原因 | 处置方法 |
|---|---|---|
| 页面 502 Gateway Timeout | Puma 没起来，或 Workhorse 转发失败 | 查/tmp/puma.log/tmp/workhorse.log |
| 页面一直加载，Gitaly rpc 超时 | Gitaly 没启动，或 token 不一致 | 检查 Gitaly 进程和gitlab.ymltoken |
| 创建仓库失败 | repositories目录属主不是 git 用户 | 执行chown -R git:git /home/git/repositories |
| Sidekiq 队列积压 | Sidekiq 进程退出 | 查看/tmp/sidekiq.log，确认 Redis 连接 |
| SSH 克隆提示无法连接 | gitlab-shell 初始化失败 | 重新执行bin/install，确认secret_token |
源码安装没有统一的进程守护，进程很容易在服务器重启后丢失。我给所有服务都写了 systemd 单元文件，这里贴一个 Sidekiq 的示例：
[Unit] Description=GitLab Sidekiq After=network.target redis-server.service postgresql.service [Service] User=git WorkingDirectory=/home/git/gitlab ExecStart=/usr/local/ruby/bin/bundle exec sidekiq -e production -C config/sidekiq.yml Restart=always [Install] WantedBy=multi-user.targetPuma、Gitaly、Workhorse 都可以按同样的思路写成 systemd 服务，这样重启机器后服务能自动拉起，不再需要手动 nohup。
6.3 关于内存与 swap 的调整建议
整个搭建过程中，内存是我遇到的最大瓶颈。16G 内存的机器编译前端资源时，node进程经常被 OOM Killer 干掉，现象就是assets:precompile跑到一半没有任何报错就退出，查看/var/log/kern.log才发现进程被杀了。
解决办法是增加 swap。对 ARM64 开发机来说，swap 分区大小可以设为内存的 1~2 倍。我用一个 swap 文件解决：
sudo fallocate -l 16G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile写进/etc/fstab后重启也会自动挂载。这个操作对编译大项目非常有用，不只是 GitLab，编译 Chromium 或大体积 Node 工程时都能用上。
结尾
算上配置、编译和排障，我在统信UOS ARM64 环境里前前后后折腾了三天才把 GitLab 完整跑起来。最大的感受是：这东西不是靠一条命令装完就结束，而是要把每个组件都当成一个独立服务去对待。源码安装虽然累，但它逼着你去理解 GitLab 内部的组件关系，后面做二次开发、做容灾备份，心里都是有底的。
最后再分享一个小技巧：源码装完 GitLab 后，先别急着设置一堆复杂配置，应该立刻打一个完整的/home/git目录快照。这样后续如果再调试坏，可以直接把快照解压回来，省去重新编译几小时的等待。我在项目里就是靠这个快照，后来升级测试时把系统环境备份了一遍，整个过程顺畅了很多。
