ubuntu中gitlab网络配置技巧

Ubuntu 下 GitLab 网络配置技巧

一 基础网络与防火墙

• 设置主机名与解析：使用命令设置稳定主机名，例如：sudo hostnamectl set-hostname gitlab.example.com，并确保域名 DNS 解析指向服务器 IP。
• 放行访问端口：开放 HTTP 80/HTTPS 443 与 SSH 22（Git 克隆常用 22）。Ubuntu 可使用 UFW：sudo ufw allow 80,443,22/tcp && sudo ufw enable；如使用云厂商安全组，也需同步放行。
• 端口与服务检查：确认 sshd 正常运行（sudo systemctl status ssh），并可用 ss -tlnp | grep -E ':(80|443|22)' 检查端口监听。

二 域名与端口映射

• 配置外部访问地址：编辑 /etc/gitlab/gitlab.rb，设置 external_url 'http://gitlab.example.com'（或带端口/HTTPS 的地址），保存后执行 sudo gitlab-ctl reconfigure 使配置生效。
• 避免端口冲突：若主机上已有服务占用 80/443，可让 GitLab 使用其他端口，例如：nginx['listen_port'] = 8080，并将外部访问改为 http://gitlab.example.com:8080。
• NAT/路由器端口转发：在网关将公网的 80/443 转发到内网 GitLab 主机的对应端口（如 192.168.1.10:80），确保外网可直达。

三 反向代理与内置 Nginx 协同

• 方案 A 使用外部 Nginx 反向代理（推荐与现有站点共存）
  1. 关闭内置 Nginx：nginx['enable'] = false；2) 允许外部 Web 服务用户：web_server['external_users'] = ['www-data']；3) 将外部用户加入 GitLab 组：sudo usermod -aG gitlab-www www-data；4) 配置外部 Nginx，反向代理到 Unix socket：unix:/var/opt/gitlab/gitlab-workhorse/socket，并设置关键请求头（Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto）；5) 重载 Nginx 与 GitLab。
• 方案 B 仅调整内置 Nginx 监听端口
  1. 保留 nginx['enable'] = true；2) 设置 nginx['listen_port'] = 8080（或 8443 用于 HTTPS）；3) 将 external_url 的端口与之匹配；4) 执行 gitlab-ctl reconfigure。
• 代理要点：反向代理需传递正确的 X-Forwarded-Proto，否则 GitLab 可能生成 HTTP 链接；大文件推送需设置 client_max_body_size 0 或较大值（如 500M）。

四 HTTPS 与证书部署

• 自签名证书（测试环境）
  1. 创建目录与证书：sudo mkdir -p /etc/gitlab/ssl && sudo chmod 700 /etc/gitlab/ssl；2) 生成 server.key 与 server.crt；3) 在 gitlab.rb 中设置 external_url 'https://gitlab.example.com'，并指定证书路径：nginx['ssl_certificate'] 与 nginx['ssl_certificate_key']；4) 可选：nginx['redirect_http_to_https'] = true；5) 执行 gitlab-ctl reconfigure。
• Let’s Encrypt 证书（生产环境）
  1. 安装 Certbot：sudo apt install -y certbot；2) 获取证书：sudo certbot certonly --standalone -d gitlab.example.com；3) 在 gitlab.rb 中配置证书路径：/etc/letsencrypt/live/gitlab.example.com/fullchain.pem 与 privkey.pem；4) 启用重定向并 gitlab-ctl reconfigure。
• 端口与协议一致性：证书路径、域名与 external_url 协议/端口需一致，避免浏览器与 Git 客户端出现 证书不匹配 或 重定向循环。

五 Docker 部署与端口规划

• 端口映射建议：运行容器时将主机端口与容器端口分离，避免与宿主机已有服务冲突，例如：-p 9080:80 -p 9022:22 -p 9443:443（分别对应 HTTP/SSH/HTTPS）。
• 数据持久化：挂载配置、日志与数据目录，例如：-v /home/docker/gitlab/config:/etc/gitlab -v /home/docker/gitlab/logs:/var/log/gitlab -v /home/docker/gitlab/data:/var/opt/gitlab。
• 外部 Nginx 代理 Docker：反向代理到容器内的 Workhorse socket 或映射的 HTTP 端口；若使用 Unix socket，需将宿主机的 socket 目录挂载进容器并在外部 Nginx 中指向该 socket。

六 常见问题快速排查

• 无法访问：依次检查 域名解析、UFW/安全组、端口监听（ss -tlnp）、以及 NAT 转发是否生效。
• 502/504 错误：多为反向代理与 GitLab 协议/头不一致或上游超时，核对 X-Forwarded-Proto、proxy_read_timeout 等；必要时查看 /var/log/gitlab/nginx/*.log。
• 页面或克隆地址错误：确认 external_url 与代理配置完全一致（协议、域名、端口）。
• 端口占用：修改 gitlab.rb 中的 nginx['listen_port'] 或相应服务端口，再 gitlab-ctl reconfigure。
• 服务状态与日志：gitlab-ctl status、gitlab-ctl tail 快速定位组件故障。