本文详细介绍如何在 NAS（飞牛 OS、群晖、TrueNAS）上通过 Docker 安装 GitLab，解决权限报错并恢复备份数据。涵盖挂载配置、版本匹配与迁移经验，让你轻松搭建私有 DevOps 平台。
一、为什么要在 NAS 上安装 GitLab？
在开发团队中，代码托管通常依赖 GitHub 或 GitLab.com 的云服务，但越来越多开发者希望掌控自己的数据与构建环境。
在 NAS 上部署 GitLab，可以带来以下优势：
- 数据主权：代码与配置完全掌握在自己手中。
- 高速访问：局域网内访问速度快，减少延迟。
- 成本可控：无需额外订阅云服务。
- 自动备份：结合 NAS 自带快照、RAID 等功能，安全可靠。
然而，由于 NAS 的系统架构与传统 Linux 服务器略有差异，GitLab 的安装与备份恢复常常会遇到权限或版本问题。本文将详细讲解如何在 NAS 上 通过 Docker 部署 GitLab，并安全地 恢复已有备份数据。
二、常见安装问题：权限报错与原因分析
在首次启动 GitLab 容器时，很多用户会遇到类似下面的错误：
Errno::EACCES: Permission denied @ rb_sysopen - /opt/gitlab/embedded/service/gitlab-rails/config/database.yml
/opt/gitlab/embedded/service/gitlab-rails/Rakefile:18:in `<top (required)>'/opt/gitlab/embedded/bin/bundle:25:in `<main>'
(See full trace by running task with --trace)
---- End output of /opt/gitlab/bin/gitlab-rake cache:clear ----
Ran /opt/gitlab/bin/gitlab-rake cache:clear returned 1
这类问题通常是因为：
- 容器挂载目录的权限不足；
- NAS 的文件系统（如 btrfs、ext4）默认限制了容器的写入；
- 使用非 root 用户启动 Docker，导致 GitLab 无法创建配置文件。
下图就是在 fnos 下自定义容器存储目录，导致容器启动失败：
解决思路是：
让系统自动分配挂载位置 ，或者 使用 root 权限启动容器。下面是完整的解决方案。
三、在 NAS 中正确创建 GitLab 容器的方式
1. 启用 SSH 并连接到 NAS
在飞牛 OS 或群晖 DSM 上，先开启 SSH 功能。
通过命令行连接 NAS：
ssh [email protected]
sudo su # 切换至 root 用户
提示：root 权限在容器挂载及文件写入时至关重要。
2. 创建 GitLab 数据存储目录
建议将容器数据统一放在专用卷中，方便后期备份与迁移。
df -h # 查看可用存储空间
cd /vol2
mkdir -p docker-apps/gitlab
cd docker-apps/gitlab
3. 编写 docker-compose 配置文件
创建文件：
nano docker-compose.yml
写入以下配置（推荐使用 EE 版本镜像以获得更丰富功能）：
services:
gitlab:
image: gitlab/gitlab-ee:16.7.0-ee.0
container_name: gitlab
restart: unless-stopped
privileged: true
volumes:
- ./etc/gitlab:/etc/gitlab
- ./var/log/gitlab:/var/log/gitlab
- ./var/opt/gitlab:/var/opt/gitlab
ports:
- "40022:22"
- "40443:443"
- "40080:80"
networks:
- gitlab
networks:
gitlab:
external: false
⚠️ 重要提示：
备份恢复时，GitLab 镜像版本必须与备份文件版本一致。
例如：备份来自16.7.0-ee，则容器必须使用相同版本。
4. 启动容器并访问 GitLab
运行：
docker compose up -d
容器启动后，在浏览器访问：
http://NAS_IP:40080
第一次启动需要几分钟初始化，请耐心等待。
初始化完成后，可通过以下命令查看管理员密码：
docker exec -it gitlab grep 'Password:' /etc/gitlab/initial_root_password
输出示例：
Password: yqOc3nsM73QBnpO8/9BDUu5DpMl2lNpoSiMw4KgKQ5k=
然后使用账号 root 登录即可。
四、GitLab 备份恢复与数据迁移
假设你之前在旧设备或服务器上做过 GitLab 备份，文件名类似于：
1758614821_2025_09_23_16.7.0-ee_gitlab_backup.tar
现在我们要将它恢复到新部署的 NAS GitLab 环境。
1. 将备份文件复制到容器目录
在宿主机执行：
cp /vol1/1000/backup/1758614821_2025_09_23_16.7.0-ee_gitlab_backup.tar /vol2/docker-apps/gitlab/var/opt/gitlab/backups/
2. 进入容器执行恢复命令
进入容器：
docker exec -it gitlab /bin/bash
执行恢复命令（注意 BACKUP 参数无需后缀）：
gitlab-rake gitlab:backup:restore BACKUP=1758614821_2025_09_23_16.7.0-ee
如遇“权限不足”提示，添加可读权限即可：
chmod +r /var/opt/gitlab/backups/1758614821_2025_09_23_16.7.0-ee_gitlab_backup.tar
恢复完成后，GitLab 会自动解压数据库、仓库文件、Artifacts、CI 文件等内容。
3. 版本不匹配错误的解决
如果出现如下报错：
root@1605c1408116:/var/opt/gitlab/backups# gitlab-rake gitlab:backup:restore BACKUP=1758614821_2025_09_23_16.7.0-ee
2025-11-08 04:45:19 UTC -- Unpacking backup ...
2025-11-08 04:45:26 UTC -- Unpacking backup ... done
2025-11-08 04:45:26 UTC -- GitLab version mismatch:
Your current GitLab version (18.5.1) differs from the GitLab version in the backup!
Please switch to the following version and try again:
version: 16.7.0-ee
2025-11-08 04:45:26 UTC -- Hint: git checkout v16.7.0-ee
2025-11-08 04:45:26 UTC -- Deleting tar staging files ...
2025-11-08 04:45:26 UTC -- Cleaning up /var/opt/gitlab/backups/backup_information.yml
2025-11-08 04:45:26 UTC -- Cleaning up /var/opt/gitlab/backups/db
2025-11-08 04:45:26 UTC -- Cleaning up /var/opt/gitlab/backups/repositories
2025-11-08 04:45:27 UTC -- Cleaning up /var/opt/gitlab/backups/uploads.tar.gz
2025-11-08 04:45:27 UTC -- Cleaning up /var/opt/gitlab/backups/builds.tar.gz
2025-11-08 04:45:27 UTC -- Cleaning up /var/opt/gitlab/backups/artifacts.tar.gz
2025-11-08 04:45:27 UTC -- Cleaning up /var/opt/gitlab/backups/pages.tar.gz
2025-11-08 04:45:27 UTC -- Cleaning up /var/opt/gitlab/backups/lfs.tar.gz
2025-11-08 04:45:27 UTC -- Cleaning up /var/opt/gitlab/backups/terraform_state.tar.gz
2025-11-08 04:45:27 UTC -- Cleaning up /var/opt/gitlab/backups/packages.tar.gz
2025-11-08 04:45:27 UTC -- Cleaning up /var/opt/gitlab/backups/ci_secure_files.tar.gz
2025-11-08 04:45:27 UTC -- Deleting tar staging files ... done
2025-11-08 04:45:27 UTC -- Deleting backups/tmp ...
2025-11-08 04:45:27 UTC -- Deleting backups/tmp ... done
2025-11-08 04:45:27 UTC -- Deleting backup and restore PID file at [/opt/gitlab/embedded/service/gitlab-rails/tmp/backup_restore.pid] ... done
说明你使用的镜像版本与备份版本不一致。
解决方案：
# 修改镜像版本为与备份一致
docker compose down
nano docker-compose.yml
# 将 image 改为 gitlab/gitlab-ee:16.7.0-ee.0
docker compose up -d
然后重新执行恢复命令即可。
五、实战经验与最佳实践
1. 保持版本一致性
GitLab 的备份格式与版本紧密关联，不同版本间不可直接恢复。
2. 合理规划挂载目录
建议统一在 /vol2/docker-apps/ 下，便于迁移和备份。
3. 启用自动备份计划
使用 GitLab 内置任务或 cron 定期执行：
gitlab-rake gitlab:backup:create
4. 定期验证备份有效性
可使用 tar -tvf 检查备份包内容是否完整。
5. 使用企业版镜像（EE）gitlab-ee 版本提供更多权限与安全特性，非常适合私有部署。
六、常见问题（FAQ）
Q1：恢复时一直提示“Permission denied”，怎么办？
A：确保容器使用 root 用户运行，且挂载目录权限为 755 或 777。
Q2：为什么恢复失败后 GitLab 无法启动？
A：可能因为版本不一致或中途中断，建议重新删除容器目录后重新部署。
Q3：可以用群晖 Docker 部署 GitLab 吗？
A：可以，群晖 DSM 的 Docker 界面可直接导入相同的 docker-compose.yml，路径挂载保持一致即可。
Q4：如何备份配置文件？
A：GitLab 所有配置均在 /etc/gitlab、日志在 /var/log/gitlab，可通过 rsync 定期同步。
七、总结
在 NAS 上安装 GitLab 并非复杂的黑科技，但确实需要理解容器的权限与版本逻辑。
通过本文的方法，你可以在飞牛 OS、群晖或任何支持 Docker 的 NAS 上，快速搭建属于自己的 GitLab 平台，实现高效、安全、可控的 DevOps 环境。
