【Linux】在树莓派上搭建自建 Git 服务（基于 GitLab）- 实战笔记与运维清单

前言

2025 年结束了才发现自己已经很久没有更新文章了。但最近都在忙其他的事情，实在没有多余的精力去写新的分享了（但笔记还是会记录，看看什么时候再分享出来吧）。于是我在重新整理以前的笔记发现，其实有很多都还没有分享过，不如趁此机会都给大家分享一下吧。

也许分享的内容有点旧了，但还是希望自己的经验能够帮到更多的人。

2020 年我做过一阵子"独立开发者"，并选择将 GitLab Community Edition（CE）部署在树莓派上作为首个尝试。下面是我按实际操作整理出的步骤、陷阱、维护命令与改进建议一次性分享给大家，希望大家也能够少走点弯路。

1. 为什么考虑在树莓派上部署 GitLab？

优点：成本低、能在内网长期托管、对中小团队够用（尤其是当代码量/并发不高时）。我可以在局域网中快速搭建 CI/CD 流程（若需要，也可以只把 Git 服务放在树莓派，CI 用其他更强的机器）。
约束与现实：GitLab 资源占用不小（尤其是旧版本的 omnibus 包包含很多服务），树莓派（尤其是 1/2/3 代）CPU 与内存非常有限。若只是轻量需求，Gitea 或 Gogs 更轻量、更易运行在低配设备上（社区评论也经常推荐用 Gitea）。

2. 准备的硬件/系统与依赖

硬件：Raspberry Pi 4；1GB RAM（但我建议最好有 2GB+），SSD 或高速 SD 卡（推荐用 USB SSD 以提高 I/O）。
操作系统：Raspbian / Raspberry Pi OS（版本差异会影响可用的 deb 包）。
网络：安装时如果采用在线安装，下载 GitLab 包需要稳定链路；若网络受限，建议先在别的机器上下载 .deb 并离线传到 Pi。
依赖包：

bash 复制代码

sudo apt-get update
sudo apt-get install -y curl openssh-server ca-certificates postfix apt-transport-https

安装 postfix 会要求配置邮箱相关项，若不需要邮件功能，可以选择"Local only"或不做特殊配置。

3. 安装步骤

获取合适的 GitLab 包（建议离线安装以避免网络问题）

我使用的操作系统版本是 jessie，因此我会选择 gitlab-ce_8.13.0-ce.0_armhf.deb 作为我的安装包。我先下载到本地，再通过 scp 上传到树莓派。

在树莓派上安装 deb 包：

bash 复制代码

sudo dpkg -i gitlab-ce_8.13.0-ce.0_armhf.deb

这个包很大，可能包含上万文件，安装时会比较慢，耐心等候。若中途依赖缺失，运行 sudo apt-get -f install 来修复。

运行 reconfigure：

bash 复制代码

sudo gitlab-ctl reconfigure

这一步会把 omnibus 配置写入并启动各组件，可能花较长时间。完成后会提示访问地址。

首次登录/管理员设置

首次访问会提示设置密码。若邮件未配置，用户创建后的密码可能不会发送到邮箱，我通常在 Admin Area 手动为用户设置初始密码或由管理员重置。

4. 遇到的问题与解决办法

内存不足 / 安装卡住：GitLab 包含很多 Ruby / Puma / Redis / PostgreSQL 组件，内存消耗较大。我的解决办法是增加 swap（创建 2~4GB swapfile）：

bash 复制代码

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

并把 /swapfile none swap sw 0 0 写入 /etc/fstab 以开机启用。

注意：推荐用外接 SSD 并把 swapfile 放在 SSD 上。

安装失败或依赖问题：用 sudo apt-get -f install 修复依赖，然后重试 dpkg -i 。
启动后 Web 界面卡顿和 502 错误：检查 GitLab 服务状态 sudo gitlab-ctl status，查看 gitlab-rails 和 puma logs（位于 /var/log/gitlab/）以定位问题。
邮件不发 / 无法发送初始密码：可以在 Admin Area 手动设置用户密码，或配置 SMTP（postfix 或外部 SMTP）。若仅供内网使用且不需要邮件，直接跳过邮件设置。

5. 日常维护命令

使修改生效：

bash 复制代码

sudo gitlab-ctl reconfigure

清除缓存：

bash 复制代码

sudo gitlab-rake cache:clear RAILS_ENV=production

启停重启：

bash 复制代码

sudo gitlab-ctl start
sudo gitlab-ctl stop
sudo gitlab-ctl restart

开机自启：

bash 复制代码

sudo systemctl enable gitlab-runsvdir
sudo systemctl disable gitlab-runsvdir

查看组件状态 / 日志（排错必用）：

bash 复制代码

sudo gitlab-ctl status
sudo tail -f /var/log/gitlab/gitlab-rails/production.log

6. 网络与配套

DNS 缓存

我在另一台 Pi 上运行 DNS 缓存（如 dnsmasq 或 unbound），把路由器的 DNS 指向该 Pi，从而加速常用域名解析并减轻外部 DNS 查询压力。

内网穿透

有时候人在外面，我希望在外网也能暂时访问内网的 GitLab，于是使用了 ngrok 做映射服务。我倾向于只在必要时开放，并通过 SSH 隧道或反向代理加认证来保护服务。若你对安全要求高，建议通过 VPN（例如 WireGuard）连接，而不是长期使用 ngrok 做穿透服务。

7. 备份策略

仓库数据（裸仓库）：GitLab 的仓库一般在 /var/opt/gitlab/git-data/repositories，我会定期 rsync 到 NAS 进行存储（按项目/按日期分目录）。
数据库与配置：

bash 复制代码

sudo gitlab-backup create

把生成的备份文件传到离线存储；同时备份 /etc/gitlab/gitlab.rb（配置文件）与 SSL 密钥。

8. 总结

以上就是我的实战总结了，下面是我的检查清单，大致上就归纳到这些点上面了。

硬件推荐使用 Pi 4 + SSD。
系统要确保 OS 与安装包兼容，建议先测试一次完整安装演练。
安装依赖并离线上传 .deb文件，避免安装失败。
配置 swap 并放在 SSD 上，时刻监控内存压力。
配置 DNS 缓存，提高解析稳定性。
内外网穿透，若短期可用 ngrok，长期用 VPN。
建立自动备份（仓库 + gitlab-backup + configs）。
配置 HTTPS 与访问控制，最小化暴露面。