GitLab là nền tảng phổ biến để lưu trữ mã nguồn và quản lý quy trình DevOps, được hàng ngàn đội ngũ trên toàn thế giới sử dụng. Nhưng phải làm gì nếu việc truy cập vào GitLab bị chặn ở cấp độ nhà cung cấp, mạng công ty hoặc toàn quốc? Còn tệ hơn nữa — khi pipeline CI/CD bị sập giữa đêm chỉ vì runner không thể kết nối với kho lưu trữ.
Trong bài viết này, chúng ta sẽ tìm hiểu cách cấu hình proxy cho GitLab ở cấp độ Git client, GitLab Runner và máy chủ công ty — để toàn bộ đội ngũ làm việc ổn định từ bất kỳ đâu trên thế giới.
Tại sao cần proxy cho GitLab: các kịch bản thực tế
Trước khi cấu hình proxy, điều quan trọng là hiểu vấn đề cụ thể mà bạn đang giải quyết. Các tình huống có thể khác nhau, và từ đó sẽ ảnh hưởng đến việc lựa chọn loại proxy và cách kết nối của nó.
Kịch bản 1: GitLab bị chặn bởi nhà cung cấp hoặc ở cấp độ quốc gia
Ở một số quốc gia và mạng công ty, việc truy cập vào gitlab.com bị hạn chế. Nhà phát triển mở terminal, gõ git pull — và nhận được timeout. Proxy trong trường hợp này hoạt động như một trung gian: lưu lượng không đi trực tiếp đến gitlab.com, mà thông qua một máy chủ trung gian ở quốc gia không có hạn chế.
Kịch bản 2: Đội ngũ phân tán ở các quốc gia khác nhau
Hãy tưởng tượng: một phần đội ngũ làm việc từ Nga, một phần từ Kazakhstan, một phần từ châu Âu. Mỗi người có điều kiện mạng khác nhau, các hạn chế khác nhau. Để mọi người làm việc ổn định và với tốc độ giống nhau, các công ty triển khai một máy chủ proxy công ty, qua đó toàn bộ lưu lượng đến GitLab đi qua một kênh duy nhất.
Kịch bản 3: CI/CD runner không thể kết nối đến các phụ thuộc bên ngoài
GitLab Runner khởi động một pipeline, và ở bước npm install hoặc pip install mọi thứ bị sập — bởi vì máy chủ mà runner đang chạy nằm trong một mạng kín không có quyền truy cập trực tiếp vào internet. Proxy cho phép runner nhận các phụ thuộc bên ngoài mà không cần mở quyền truy cập hoàn toàn vào internet cho toàn bộ máy chủ.
Kịch bản 4: GitLab tự lưu trữ sau tường lửa công ty
Công ty giữ một máy chủ GitLab riêng trong mạng nội bộ. Các nhà phát triển làm việc từ xa cần kết nối với nó. Thay vì sử dụng VPN cho toàn bộ lưu lượng, có thể cấu hình proxy chỉ cho lưu lượng GitLab — điều này nhanh hơn và dễ quản lý hơn.
Kịch bản 5: Giám sát và kiểm toán lưu lượng
Các công ty lớn chuyển toàn bộ lưu lượng đến các kho lưu trữ qua proxy công ty, để ghi lại hoạt động, kiểm soát ai và cái gì được push, và chặn các hoạt động không mong muốn. Đây là yêu cầu về an ninh, không phải để vượt qua các khối.
Điều quan trọng là hiểu trước khi cấu hình:
Proxy cho GitLab có thể cần thiết ở ba cấp độ cùng một lúc: trên máy của nhà phát triển (Git client), trên máy chủ với GitLab Runner (CI/CD), và trên chính máy chủ GitLab (nếu tự lưu trữ). Mỗi cấp độ được cấu hình riêng biệt.
Loại proxy nào phù hợp cho GitLab
GitLab hoạt động trên các giao thức HTTPS và SSH. Điều này ngay lập tức xác định các loại proxy nào có thể áp dụng và loại nào không. Hãy cùng xem xét các tùy chọn.
| Loại proxy | Giao thức | Phù hợp cho GitLab | Khi nào sử dụng |
|---|---|---|---|
| Proxy HTTP/HTTPS | HTTP, HTTPS | ✓ Có | Git qua HTTPS, giao diện web GitLab |
| Proxy SOCKS5 | TCP (bất kỳ) | ✓ Có (tùy chọn tốt nhất) | Git qua HTTPS và SSH, CI/CD |
| Proxy SOCKS4 | TCP | ~ Một phần | Chỉ khi không có SOCKS5 |
| Proxy trong suốt | HTTP | ✗ Không | Không phù hợp — không vượt qua các khối |
Để làm việc với GitLab, lựa chọn tối ưu là SOCKS5. Nó hoạt động ở cấp độ TCP, vì vậy nó có thể proxy tốt cả kết nối HTTPS (giao diện web, git clone qua HTTPS) và kết nối SSH (git push/pull qua SSH trên cổng 22 hoặc 443).
Proxy cư trú vs proxy trung tâm dữ liệu cho GitLab
Tất cả phụ thuộc vào nhiệm vụ. Nếu mục tiêu là vượt qua các khối theo GeoIP hoặc có được IP ổn định cho việc xác thực, thì proxy trung tâm dữ liệu là lựa chọn tốt — chúng nhanh hơn, rẻ hơn và cung cấp độ trễ thấp, điều này rất quan trọng khi làm việc với các kho lưu trữ lớn.
Nếu IP công ty của bạn bị đưa vào danh sách chặn của GitLab (thường xảy ra khi quét một cách quyết liệt hoặc sau các sự cố an ninh), thì bạn nên xem xét proxy cư trú — các địa chỉ IP của chúng thuộc về người dùng thực và rất hiếm khi bị các nền tảng chặn.
Cấu hình proxy cho Git client (toàn cầu)
Đây là kịch bản phổ biến nhất: nhà phát triển trên máy của mình không thể kết nối với GitLab. Cấu hình được thực hiện thông qua cấu hình của chính Git — một lần, và nó hoạt động cho tất cả các kho lưu trữ.
Tùy chọn A: Proxy HTTPS cho Git
Nếu bạn làm việc với GitLab qua HTTPS (địa chỉ kho lưu trữ bắt đầu bằng https://), hãy thực hiện trong terminal:
# Cấu hình proxy HTTP toàn cầu git config --global http.proxy http://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT # Nếu proxy yêu cầu xác thực git config --global http.proxy http://TÊN_NGƯỜI_DÙNG:MẬT_KHẨU@ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT # Đối với proxy SOCKS5 (được khuyến nghị) git config --global http.proxy socks5://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT # Kiểm tra xem cấu hình đã được áp dụng git config --global --get http.proxy
Tùy chọn B: Proxy chỉ cho gitlab.com (không ảnh hưởng đến các kho lưu trữ khác)
Nếu bạn không muốn proxy áp dụng cho tất cả các thao tác Git (ví dụ, GitHub hoặc Bitbucket hoạt động bình thường), bạn có thể cấu hình proxy chỉ cho miền cụ thể:
# Proxy chỉ cho gitlab.com git config --global http.https://gitlab.com.proxy socks5://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT # Hoặc cho GitLab tự lưu trữ của bạn git config --global http.https://git.yourcompany.com.proxy socks5://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT
Tùy chọn C: SSH qua proxy (cho những ai làm việc qua SSH)
Nếu bạn sao chép các kho lưu trữ qua SSH ([email protected]:...), cấu hình proxy được thực hiện trong cấu hình SSH, không phải trong Git. Mở tệp ~/.ssh/config và thêm:
# Đối với Linux/macOS — qua nc (netcat)
Host gitlab.com
HostName gitlab.com
User git
ProxyCommand nc -X 5 -x ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT %h %p
# Đối với Windows — qua connect.exe (Git for Windows)
Host gitlab.com
HostName gitlab.com
User git
ProxyCommand connect -S ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT %h %p
Sau khi cấu hình, hãy kiểm tra kết nối bằng lệnh ssh -T [email protected]. Nếu mọi thứ được cấu hình đúng, bạn sẽ thấy thông điệp chào mừng từ GitLab.
Cách tắt proxy khi không còn cần thiết
# Xóa proxy toàn cầu git config --global --unset http.proxy # Xóa proxy cho miền cụ thể git config --global --unset http.https://gitlab.com.proxy
Proxy cho GitLab Runner và các pipeline CI/CD
GitLab Runner là một agent thực hiện các nhiệm vụ từ .gitlab-ci.yml. Nếu runner nằm trong một mạng kín hoặc trên máy chủ có quyền truy cập internet hạn chế, cần phải cấu hình proxy riêng. Cấu hình Git client của nhà phát triển ở đây sẽ không giúp ích — runner hoạt động trên một máy khác.
Cách 1: Biến môi trường trong cấu hình runner
Mở tệp cấu hình GitLab Runner (thường là /etc/gitlab-runner/config.toml) và thêm các biến môi trường vào phần [runners.env]:
[[runners]]
name = "my-runner"
url = "https://gitlab.com/"
token = "MÃ_TOKEN_CỦA_BẠN"
executor = "shell"
environment = [
"HTTP_PROXY=http://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT",
"HTTPS_PROXY=http://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT",
"NO_PROXY=localhost,127.0.0.1,miền-nội-bộ-của-bạn.com"
]
Sau khi thay đổi cấu hình, hãy khởi động lại runner: sudo gitlab-runner restart
Cách 2: Biến trong .gitlab-ci.yml (ở cấp độ pipeline)
Nếu bạn không phải là quản trị viên của runner hoặc muốn cấu hình proxy chỉ cho một dự án cụ thể, hãy thêm các biến trực tiếp vào tệp pipeline:
variables:
HTTP_PROXY: "http://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT"
HTTPS_PROXY: "http://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT"
NO_PROXY: "localhost,127.0.0.1,.internal.company.com"
stages:
- build
- test
- deploy
build:
stage: build
script:
- npm install # giờ sẽ đi qua proxy
- npm run build
Cách 3: Biến trong cài đặt dự án GitLab (không cần commit vào kho lưu trữ)
Cách tốt nhất cho dữ liệu nhạy cảm (proxy có xác thực): hãy vào Cài đặt → CI/CD → Biến của dự án của bạn và thêm các biến HTTP_PROXY, HTTPS_PROXY, NO_PROXY như các biến bảo mật (masked). Chúng sẽ tự động có sẵn trong tất cả các pipeline, nhưng sẽ không hiển thị trong nhật ký.
Về NO_PROXY — đừng quên!
Biến NO_PROXY cực kỳ quan trọng. Bạn cần thêm tất cả các miền và IP nội bộ mà runner phải kết nối trực tiếp, bỏ qua proxy. Nếu không, runner sẽ cố gắng đi qua proxy ngay cả với các dịch vụ nội bộ — và pipeline sẽ bị sập.
Proxy cho Docker executor
Nếu runner sử dụng Docker executor, các container theo mặc định không kế thừa các cài đặt proxy của máy chủ. Bạn cần thêm các biến vào config.toml trong phần [runners.docker], hoặc tạo tệp /etc/systemd/system/docker.service.d/proxy.conf trên máy chủ có runner:
[Service] Environment="HTTP_PROXY=http://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT" Environment="HTTPS_PROXY=http://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT" Environment="NO_PROXY=localhost,127.0.0.1"
Sau đó: sudo systemctl daemon-reload && sudo systemctl restart docker
Proxy cho máy chủ GitLab tự lưu trữ
Nếu bạn quản lý máy chủ GitLab riêng của mình (cài đặt qua Omnibus hoặc Helm), proxy cần thiết để GitLab có thể truy cập các dịch vụ bên ngoài: gửi thông báo, kết nối với các hệ thống CI bên ngoài, tải lên ảnh đại diện người dùng, tích hợp với Jira hoặc Slack.
Cấu hình trong gitlab.rb (cài đặt Omnibus)
Mở tệp /etc/gitlab/gitlab.rb và thêm hoặc bỏ chú thích các dòng sau:
# Proxy cho GitLab (Omnibus)
gitlab_rails['env'] = {
"http_proxy" => "http://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT",
"https_proxy" => "http://ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT",
"no_proxy" => "localhost,127.0.0.1,MIỀN_NỘI_BỘ_CỦA_BẠN"
}
# Nếu proxy có xác thực:
gitlab_rails['env'] = {
"http_proxy" => "http://TÊN_NGƯỜI_DÙNG:MẬT_KHẨU@ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT",
"https_proxy" => "http://TÊN_NGƯỜI_DÙNG:MẬT_KHẨU@ĐỊA_CHỈ_PROXY_CỦA_BẠN:PORT",
"no_proxy" => "localhost,127.0.0.1"
}
Sau khi thay đổi cấu hình, hãy áp dụng các cài đặt: sudo gitlab-ctl reconfigure
Cấu hình kết nối ra ngoài qua Admin Area
Trong GitLab 15.0+, đã có khả năng cấu hình proxy ngay qua giao diện web: hãy vào Khu vực quản trị → Cài đặt → Mạng → Yêu cầu ra ngoài. Tại đây, bạn có thể chỉ định proxy cho các webhook ra ngoài và giới hạn các dải IP mà GitLab có thể truy cập. Điều này hữu ích cho an ninh — ngăn chặn các cuộc tấn công SSRF qua webhook.
Tổ chức quyền truy cập cho toàn bộ đội ngũ qua proxy
Khi cần đảm bảo quyền truy cập ổn định vào GitLab cho một đội ngũ từ 5–50 người, việc cấu hình riêng lẻ trên mỗi máy không phải là cách tiếp cận tốt nhất. Hãy xem xét các giải pháp quy mô hơn.
Cách tiếp cận 1: Máy chủ proxy công ty
Triển khai một máy chủ proxy duy nhất (ví dụ, Squid hoặc 3proxy) với quyền truy cập internet. Tất cả các nhà phát triển cấu hình Git để sử dụng máy chủ này. Lợi ích: quản lý tập trung, một điểm kiểm soát duy nhất, có thể ghi lại lưu lượng. Nhược điểm: máy chủ trở thành điểm thất bại duy nhất.
Cách tiếp cận 2: Gương (mirror) kho lưu trữ
GitLab hỗ trợ việc gương các kho lưu trữ. Bạn có thể cấu hình GitLab tự lưu trữ trong mạng nội bộ như một gương cho gitlab.com. Các nhà phát triển làm việc với máy chủ nội bộ, và nó đồng bộ hóa với bên ngoài qua proxy. Điều này giảm sự phụ thuộc vào chất lượng kết nối proxy cho từng nhà phát triển.
Cách tiếp cận 3: Cấu hình tự động qua dotfiles hoặc script onboarding
Đối với các đội ngũ mà mỗi nhà phát triển tự cấu hình môi trường, việc tạo một script onboarding tự động ghi lại các cài đặt Git cần thiết là rất tiện lợi. Script được lưu trữ trong kho lưu trữ công ty và được chạy khi thiết lập nơi làm việc mới.
#!/bin/bash
# setup-git-proxy.sh — chạy khi thiết lập nơi làm việc mới
PROXY_HOST="proxy.company.com"
PROXY_PORT="3128"
echo "Cấu hình proxy Git để truy cập GitLab..."
git config --global http.https://gitlab.com.proxy "socks5://${PROXY_HOST}:${PROXY_PORT}"
git config --global http.sslVerify true
echo "Hoàn tất! Kiểm tra: git config --global --list | grep proxy"
Danh sách kiểm tra cho việc triển khai đội ngũ
- Xác định xem có cần proxy ở cấp độ nhà phát triển, runner hoặc máy chủ GitLab (hoặc cả ba)
- Chọn loại proxy: SOCKS5 cho khả năng tương thích tối đa
- Cấu hình
NO_PROXYcho tất cả các miền và dịch vụ nội bộ - Kiểm tra hoạt động của các khóa SSH qua proxy (một bước riêng biệt!)
- Ghi lại các cài đặt trong wiki công ty
- Tạo script onboarding cho nhân viên mới
- Cấu hình giám sát tính khả dụng của máy chủ proxy
Các vấn đề thường gặp và cách giải quyết
Ngay cả sau khi cấu hình đúng, đôi khi mọi thứ không diễn ra như mong đợi. Dưới đây là những vấn đề phổ biến nhất và cách chẩn đoán chúng.
Vấn đề 1: Vấn đề chứng chỉ SSL: không thể lấy chứng chỉ phát hành cục bộ
Lỗi này xảy ra khi máy chủ proxy (đặc biệt là máy chủ proxy công ty) thực hiện kiểm tra SSL — thay thế chứng chỉ GitLab bằng chứng chỉ của mình. Git không tin tưởng chứng chỉ này. Giải pháp: thêm chứng chỉ gốc của công ty vào danh sách tin cậy.
# Giải pháp tạm thời (cho việc gỡ lỗi, không cho sản xuất!) git config --global http.sslVerify false # Giải pháp đúng: thêm chứng chỉ công ty git config --global http.sslCAInfo /đường/dẫn/đến/corporate-ca-bundle.crt
Vấn đề 2: Proxy hoạt động cho HTTPS, nhưng SSH không hoạt động
Đây là tình huống cổ điển: đã cấu hình http.proxy trong Git, việc sao chép qua HTTPS hoạt động, nhưng các thao tác SSH vẫn không thành công. Nguyên nhân: lưu lượng SSH không đi qua proxy HTTP. Cần cấu hình riêng ~/.ssh/config như đã mô tả trong phần về Git client.
Giải pháp thay thế: chuyển sang làm việc với GitLab qua HTTPS thay vì SSH. Để làm điều này, hãy thay đổi URL từ xa:
# Kiểm tra remote hiện tại git remote -v # Thay đổi từ SSH sang HTTPS git remote set-url origin https://gitlab.com/tên_người_dùng/repo.git
Vấn đề 3: Pipeline CI/CD bị treo ở bước sao chép kho lưu trữ
Runner sao chép kho lưu trữ trực tiếp từ GitLab, sử dụng token. Nếu runner nằm sau proxy, việc sao chép này cũng phải đi qua proxy. Đảm bảo rằng các biến HTTP_PROXY và HTTPS_PROXY được thiết lập trong config.toml, không chỉ trong .gitlab-ci.yml — các biến từ tệp CI được áp dụng sau khi sao chép, không phải trước.
Vấn đề 4: Proxy hoạt động, nhưng rất chậm
Nếu push/pull hoạt động, nhưng mất gấp 5–10 lần thời gian bình thường, vấn đề có thể nằm ở băng thông của máy chủ proxy hoặc vị trí địa lý của nó. Để làm việc với các kho lưu trữ lớn (trên 100 MB), việc chọn proxy có độ trễ thấp và băng thông cao là rất quan trọng. Proxy trung tâm dữ liệu trong trường hợp này thường được ưu tiên hơn proxy cư trú — chúng cung cấp kênh ổn định hơn.
Vấn đề 5: Xác thực qua proxy yêu cầu nhập lại mật khẩu
Nếu proxy yêu cầu xác thực Basic, và Git mỗi lần đều yêu cầu mật khẩu, hãy cấu hình credential helper:
# macOS — sử dụng Keychain git config --global credential.helper osxkeychain # Windows — sử dụng Windows Credential Manager git config --global credential.helper manager # Linux — lưu vào bộ nhớ cache trong 1 giờ git config --global credential.helper "cache --timeout=3600"
Cách nhanh chóng chẩn đoán vấn đề với proxy:
Sử dụng GIT_TRACE=1 GIT_CURL_VERBOSE=1 git clone https://gitlab.com/... — điều này sẽ xuất ra nhật ký chi tiết của tất cả các yêu cầu và phản hồi HTTP, bao gồm thông tin về proxy.
Kết luận và khuyến nghị
Cấu hình proxy cho GitLab là một nhiệm vụ cần được giải quyết ở nhiều cấp độ cùng một lúc. Nhà phát triển trên máy làm việc chỉ cần ghi lại một vài dòng trong cấu hình Git hoặc SSH. Đối với CI/CD, cần thêm các biến môi trường vào cấu hình của runner hoặc cài đặt dự án. Còn đối với GitLab tự lưu trữ — cần cập nhật gitlab.rb và tái cấu hình.
Những quy tắc chính sẽ giúp bạn tránh hầu hết các vấn đề:
- Sử dụng SOCKS5 — nó hoạt động với cả HTTPS và SSH
- Luôn cấu hình
NO_PROXYcho các dịch vụ nội bộ - Không tắt xác thực SSL trong môi trường sản xuất — hãy thêm chứng chỉ công ty
- Đối với CI/CD, hãy cài đặt proxy trong
config.toml, không chỉ trong.gitlab-ci.yml - Ghi lại các cài đặt — nhà phát triển mới trong đội sẽ cảm ơn bạn
Nếu bạn đang tìm kiếm một proxy đáng tin cậy để tổ chức quyền truy cập ổn định vào GitLab từ bất kỳ đâu trên thế giới, chúng tôi khuyên bạn nên xem xét proxy trung tâm dữ liệu — chúng cung cấp tốc độ truyền dữ liệu cao và độ trễ thấp, điều này đặc biệt quan trọng khi làm việc với các kho lưu trữ lớn và các pipeline CI/CD cường độ cao. Đối với các đội ngũ mà sự ẩn danh tối đa hoặc vượt qua các khối GeoIP là quan trọng, các proxy cư trú với IP của người dùng thực là lựa chọn phù hợp.
```