部署gitlab社区版

飞牛OS Docker 部署 GitLab 完整指南

飞牛OS（debian）是基于Linux的NAS系统，核心部署逻辑与标准Docker部署GitLab一致，需重点适配NAS的存储路径、端口占用、硬件资源限制，以下是可直接落地的完整步骤。

一、前置准备

1. 开启飞牛OS Docker服务

登录飞牛OS Web管理后台，进入应用市场，搜索「Docker」，点击安装并启动服务。
确认Docker服务正常运行：可在Docker应用的「服务状态」页查看，或SSH登录NAS执行 docker --version 验证。

2. 硬件与环境校验

最低配置要求：CPU≥4核，内存≥4G（强烈推荐8G及以上，低于4G会频繁卡死/重启），存储空间预留≥30G（GitLab运行后数据会持续增长）。
端口规划与冲突检查：
GitLab默认占用80(HTTP)、443(HTTPS)、22(SSH)，飞牛OS自身已占用80/22端口，必须做端口映射，推荐规划：

宿主机端口容器端口用途

2080 80 HTTP访问

2443 443 HTTPS访问

2222 22 SSH代码克隆

执行以下命令检查端口是否被占用，无输出即为可用：
1
2
netstat -tulpn | grep 2080 netstat -tulpn | grep 2222

3. 创建持久化目录（数据不丢失核心）

GitLab容器删除/重建后，数据需通过宿主机目录挂载保留，需提前创建3个核心目录。

方法1

ssh连接飞牛
一开始就用管理员权限创建目录

sudo su
cd /vol2
mkdir -p gitlab_data/etc
mkdir -p gitlab_data/log
mkdir -p gitlab_data/opt
cd gitlab_data
pwd
ll

！！！注意：切记千万不要进入 /vol2/1000 等用户目录创建 gitlab_data 目录，会导致权限问题！

方法2

在飞牛OS的存储池（如vol2）中，在其下创建 gitlab_data 目录。
进入gitlab_data目录，创建3个子目录：etc、log、opt。
最终路径示例（需替换为实际存储路径）：
1
2
3
/vol2/gitlab_data/etc /vol2/gitlab_data/log /vol2/gitlab_data/opt
权限配置：给目录设置读写权限，避免容器启动报错，执行命令：
1
chmod -R 775 /vol2/gitlab_data

！！！注意：切记千万不要进入 /vol2/1000 等用户目录创建 gitlab_data 目录，会导致权限问题！

二、部署方案（2选1，推荐docker-compose）

方案1：docker-compose 部署（推荐，易维护、易修改）

适合长期使用，配置可留存，一键启停/更新。

SSH登录飞牛OS，进入gitlab目录：
1
cd /vol2/gitlab_data
创建 docker-compose.yml 配置文件：
1
vi docker-compose.yml

粘贴以下配置，必须修改2处核心内容：external_url 中的IP改为飞牛OS局域网IP，宿主机路径改为实际路径。

services:
  gitlab:
    image: gitlab/gitlab-ce:18.0.0-ce.0
    container_name: gitlab
    restart: always
    hostname: gitlab
    # 端口映射 宿主机端口:容器端口
    ports:
      - "2080:80"
      - "2443:443"
      - "2222:22"
    # 目录持久化挂载
    volumes:
      - /vol2/gitlab_data/etc:/etc/gitlab
      - /vol2/gitlab_data/log:/var/log/gitlab
      - /vol2/gitlab_data/opt:/var/opt/gitlab
    # 共享内存配置，必加，否则页面500报错
    shm_size: '256m'
    # 核心环境配置
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
        gitlab_rails['time_zone'] = 'Asia/Shanghai'
        # 直接禁用 gitlab-kas，解决报错
        gitlab_kas['enable'] = false
        # 个人使用建议关闭公开注册，避免陌生人访问
        gitlab_rails['gitlab_signup_enabled'] = false

后台启动容器：
1
docker-compose up -d

方案2：docker run 快速部署

适合临时测试，一键启动，无需额外配置文件。
执行以下命令，必须替换路径和IP为实际信息：

docker run -d \
  --hostname gitlab \
  --publish 2080:80 --publish 2443:443 --publish 2222:22 \
  --name gitlab \
  --restart always \
  --volume /vol2/gitlab_data/etc:/etc/gitlab \
  --volume /vol2/gitlab_data/log:/var/log/gitlab \
  --volume /vol2/gitlab_data/opt:/var/opt/gitlab \
  --shm-size 256m \
  --env GITLAB_OMNIBUS_CONFIG="external_url 'http://192.168.1.201:2080'; gitlab_rails['gitlab_shell_ssh_port'] = 2222; gitlab_rails['time_zone'] = 'Asia/Shanghai'; gitlab_rails['gitlab_signup_enabled'] = false; gitlab_kas['enable'] = false;" \
  gitlab/gitlab-ce:18.0.0-ce.0

三、初始化与登录

关键提醒：GitLab首次启动初始化时间极长，根据NAS性能，通常需要5分钟，请勿反复重启容器，否则会导致初始化失败。

查看启动状态与日志：

1 2	`# 实时查看日志，出现 gitlab Reconfigured! 即为初始化完成 docker logs -f gitlab`

获取初始管理员密码：
GitLab默认管理员账号为 root，初始密码仅保留24小时，需尽快查看：
1
docker exec -it gitlab cat /etc/gitlab/initial_root_password
复制 Password: 后的字符串，即为初始密码。
访问与登录：
浏览器输入 http://192.168.1.201:2080，打开GitLab登录页，账号 root，粘贴初始密码登录，登录后会强制要求修改管理员密码，请设置强密码并妥善保存。

四、常见问题与解决方案

1. 页面无法访问/打不开

排查1：初始化未完成，通过日志确认启动状态，等待初始化完成。
排查2：端口冲突，更换未被占用的宿主机端口，重新启动容器。
排查3：防火墙未放行，在飞牛OS防火墙设置中，放开2080、2222端口的访问权限。
排查4：external_url 配置错误，地址中的端口必须与映射的宿主机HTTP端口完全一致。

2. 容器频繁重启/卡死

核心原因：内存不足，优先升级NAS内存至8G及以上。

优化方案：关闭GitLab非必要服务，减少内存占用。
编辑 config/gitlab.rb，添加以下配置：

prometheus['enable'] = false
node_exporter['enable'] = false
grafana['enable'] = false
alertmanager['enable'] = false

执行重载配置生效：

1	`docker exec -it gitlab gitlab-ctl reconfigure`

3. SSH无法克隆代码

核心原因：未配置SSH端口，GitLab生成的克隆地址仍使用默认22端口。
解决方案：确认 gitlab_rails['gitlab_shell_ssh_port'] 已设置为映射的宿主机SSH端口（如2222），重载配置后生效。
补充排查：飞牛OS防火墙放开2222端口，SSH密钥已正确添加到GitLab账号中。

4. 初始密码过期/找不到

执行以下命令直接重置root管理员密码：

1	`docker exec -it gitlab gitlab-rake "gitlab:password:reset[root]"`

按提示输入新密码，确认后即可使用新密码登录。

五、可选配置

1. 数据备份

执行以下命令创建完整备份，备份文件默认存放在 data/backups/ 目录（宿主机）：

1	`docker exec -it gitlab gitlab-backup create`

2. 外网访问

优先使用飞牛OS自带的VPN远程访问、内网穿透服务；如需公网访问，建议配置HTTPS证书+域名，通过DDNS解析到公网IP，并做好防火墙策略限制。

3. 邮箱配置

如需开启邮件通知（找回密码、合并请求提醒），在 gitlab.rb 中添加SMTP配置（以QQ邮箱为例），重载配置后生效：

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.qq.com"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "你的QQ邮箱@qq.com"
gitlab_rails['smtp_password'] = "你的邮箱授权码"
gitlab_rails['smtp_domain'] = "qq.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_tls'] = true
gitlab_rails['gitlab_email_from'] = "你的QQ邮箱@qq.com"

宿主机端口	容器端口	用途
2080	80	HTTP访问
2443	443	HTTPS访问
2222	22	SSH代码克隆