Proxy cho GitHub và npm: Cách truy cập vào kho lưu trữ và gói từ các quốc gia nơi GitHub bị chặn hoặc hoạt động chậm

GitHub bị chặn, hoạt động với độ trễ từ 10–30 giây hoặc npm install bị treo giữa chừng — tình huống quen thuộc với các nhà phát triển từ Nga, Iran, Trung Quốc và một số quốc gia khác. Có giải pháp, và nó đơn giản hơn bạn nghĩ: một proxy được cấu hình đúng cách cung cấp quyền truy cập ổn định vào các kho lưu trữ, gói và API GitHub mà không cần VPN và không cần phải thực hiện các bước phức tạp.

Tại sao GitHub và npm bị chặn hoặc chậm lại

Trước khi thiết lập proxy, điều quan trọng là phải hiểu chính xác bạn đang gặp phải vấn đề gì. Các vấn đề với quyền truy cập vào GitHub và npm có ba loại, và mỗi loại yêu cầu một cách tiếp cận khác nhau.

Bị chặn hoàn toàn ở cấp độ quốc gia

Một số quốc gia — Trung Quốc, Iran, Bắc Triều Tiên, và từ năm 2022, thỉnh thoảng là Nga — chặn GitHub ở cấp độ DNS hoặc theo IP. Điều này có nghĩa là các yêu cầu đến github.com hoặc không qua được hoặc trả về lỗi kết nối. Trong khi đó, kho npm (registry.npmjs.org) có thể hoạt động bình thường — hoặc cũng bị chặn.

Tường lửa doanh nghiệp và hạn chế mạng

Ngay cả khi không có sự chặn của nhà nước, các mạng doanh nghiệp thường hạn chế quyền truy cập vào các kho lưu trữ bên ngoài. Đây là thực tiễn tiêu chuẩn trong các ngân hàng, cơ quan nhà nước và các doanh nghiệp lớn: bộ phận IT chặn các kết nối ra ngoài trên các cổng 443 hoặc chặn các miền cụ thể. Một nhà phát triển trong một mạng như vậy không thể thực hiện git clone hoặc npm install mà không có một con đường vòng.

Tốc độ chậm do địa lý

Về mặt kỹ thuật, GitHub có thể truy cập được, nhưng việc sao chép một kho lưu trữ 500 MB mất 40 phút, và việc cài đặt các phụ thuộc qua npm — mất rất nhiều thời gian. Đây là vấn đề định tuyến: các gói đi qua các nút quá tải hoặc các tuyến đường dài. Một máy chủ proxy đặt tại Mỹ hoặc châu Âu rút ngắn đường đi và mang lại sự gia tăng tốc độ thực tế từ 3–10 lần.

Proxy vs VPN: chọn cái nào để làm việc với mã

Nhiều nhà phát triển theo thói quen thường chọn VPN. Điều này là dễ hiểu — VPN dễ thiết lập và hoạt động ngay lập tức cho toàn bộ hệ thống. Nhưng để làm việc với GitHub và npm, proxy thường tiện lợi hơn. Hãy cùng phân tích sự khác biệt.

Kết luận đơn giản: nếu nhiệm vụ của bạn là cung cấp cho đội ngũ quyền truy cập vào GitHub và npm, proxy chỉ cần được thiết lập một lần trong cấu hình và hoạt động mà không cần can thiệp vào cài đặt hệ thống của từng máy. Điều này đặc biệt quan trọng cho các pipeline CI/CD, nơi mà việc thiết lập VPN là rất khó khăn.

Loại proxy nào phù hợp cho GitHub và npm

Không phải tất cả các proxy đều hoạt động tốt với Git và npm. Lựa chọn phụ thuộc vào nhiệm vụ của bạn: vượt qua sự chặn, tăng tốc độ tải xuống hoặc làm việc từ mạng doanh nghiệp.

Proxy HTTP/HTTPS

Đây là lựa chọn đơn giản nhất. Git và npm hỗ trợ natively proxy HTTP thông qua các biến môi trường tiêu chuẩn. Phù hợp cho hầu hết các nhiệm vụ: sao chép các kho lưu trữ, cài đặt các gói, làm việc với API GitHub. Nếu nhà cung cấp proxy của bạn cung cấp địa chỉ HTTP — hãy bắt đầu từ đó.

Proxy SOCKS5

Giao thức linh hoạt hơn, hoạt động ở cấp độ TCP. Hỗ trợ mọi loại lưu lượng, bao gồm cả kết nối SSH với GitHub (cổng 22). Nếu bạn sử dụng Git qua SSH thay vì HTTPS — SOCKS5 là lựa chọn tốt hơn. Git hỗ trợ SOCKS5 thông qua tham số socks5:// trong cấu hình.

Proxy cư dân

Proxy cư dân sử dụng địa chỉ IP của người dùng thực tế. Đối với GitHub, điều này đặc biệt quan trọng nếu bạn làm việc từ một quốc gia có sự chặn nghiêm ngặt: những IP này rất hiếm khi bị đưa vào danh sách đen và trông giống như lưu lượng của người dùng bình thường. Phù hợp cho các tình huống khi IP của các trung tâm dữ liệu đã bị chặn ở cấp độ nhà cung cấp.

Proxy trung tâm dữ liệu

Proxy trung tâm dữ liệu là lựa chọn tối ưu cho hầu hết các nhà phát triển. Chúng nhanh hơn các proxy cư dân, rẻ hơn và cung cấp kết nối ổn định. Nếu GitHub chỉ chậm mà không bị chặn — một proxy trung tâm dữ liệu ở Mỹ hoặc châu Âu sẽ mang lại sự gia tăng tốc độ tối đa khi sao chép và tải xuống các gói.

Cấu hình proxy cho Git: hướng dẫn từng bước

Git hỗ trợ proxy thông qua cấu hình tích hợp và thông qua các biến môi trường. Chúng tôi sẽ chỉ cho bạn cả hai cách — hãy chọn cách nào thuận tiện hơn cho quy trình làm việc của bạn.

Cách 1: Qua git config (được khuyến nghị)

Đây là cấu hình vĩnh viễn, áp dụng cho tất cả các hoạt động Git trên máy. Mở terminal và thực hiện:

# Đối với proxy HTTP/HTTPS
git config --global http.proxy http://username:password@proxy-host:port
git config --global https.proxy http://username:password@proxy-host:port

# Đối với proxy SOCKS5
git config --global http.proxy socks5://username:password@proxy-host:port
git config --global https.proxy socks5://username:password@proxy-host:port

# Kiểm tra xem cấu hình đã được áp dụng
git config --global --list | grep proxy

Thay thế username:password@proxy-host:port bằng thông tin của proxy của bạn. Nếu proxy không yêu cầu xác thực — hãy bỏ qua username:password@.

Cách 2: Qua biến môi trường

Tiện lợi cho việc sử dụng tạm thời hoặc trong các script. Git tự động nhận các biến tiêu chuẩn HTTP_PROXY và HTTPS_PROXY:

# Linux / macOS — thêm vào ~/.bashrc hoặc ~/.zshrc
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"
export NO_PROXY="localhost,127.0.0.1,::1"

# Windows (PowerShell)
$env:HTTP_PROXY="http://username:password@proxy-host:port"
$env:HTTPS_PROXY="http://username:password@proxy-host:port"

# Áp dụng mà không cần khởi động lại terminal (Linux/macOS)
source ~/.bashrc

Cấu hình proxy chỉ cho GitHub

Nếu bạn muốn chỉ định hướng qua proxy cho các yêu cầu đến GitHub, mà không phải cho tất cả các kho lưu trữ, hãy sử dụng cấu hình theo phần:

# Proxy chỉ cho github.com
git config --global http.https://github.com.proxy http://username:password@proxy-host:port

# Kiểm tra sao chép qua proxy
git clone https://github.com/username/repo.git

Git qua SSH qua SOCKS5

Nếu bạn làm việc với GitHub qua SSH (không phải HTTPS), cấu hình sẽ hơi khác. Bạn cần chỉnh sửa tệp ~/.ssh/config:

# ~/.ssh/config

Host github.com
    HostName github.com
    User git
    # Trên Linux/macOS sử dụng nc (netcat)
    ProxyCommand nc -X 5 -x proxy-host:port %h %p
    
    # Hoặc qua connect-proxy (cần cài đặt)
    # ProxyCommand connect -S proxy-host:port %h %p
    
    # Trên Windows qua Git Bash
    # ProxyCommand connect -S proxy-host:port %h %p

Sau đó, các lệnh git clone [email protected]:user/repo.git và git push sẽ tự động đi qua proxy SOCKS5.

Cách đặt lại cấu hình proxy

# Xóa proxy khỏi cấu hình toàn cầu
git config --global --unset http.proxy
git config --global --unset https.proxy

Cấu hình proxy cho npm, yarn và pnpm

Mỗi trình quản lý gói có cách thiết lập proxy riêng. Chúng ta sẽ phân tích cả ba — npm, yarn và pnpm — với các lệnh cụ thể.

npm

npm hỗ trợ proxy thông qua các cài đặt tích hợp trong cấu hình:

# Thiết lập proxy cho npm
npm config set proxy http://username:password@proxy-host:port
npm config set https-proxy http://username:password@proxy-host:port

# Kiểm tra cài đặt
npm config get proxy
npm config get https-proxy

# Kiểm tra: cài đặt gói qua proxy
npm install lodash

# Đặt lại proxy
npm config delete proxy
npm config delete https-proxy

Các cài đặt được lưu trong tệp ~/.npmrc. Bạn có thể chỉnh sửa nó trực tiếp:

# ~/.npmrc
proxy=http://username:password@proxy-host:port
https-proxy=http://username:password@proxy-host:port
strict-ssl=false

Yarn (v1 Classic)

# Yarn Classic (v1)
yarn config set proxy http://username:password@proxy-host:port
yarn config set https-proxy http://username:password@proxy-host:port

# Kiểm tra
yarn config get proxy

# Đặt lại
yarn config delete proxy
yarn config delete https-proxy

Yarn Berry (v2+)

# Yarn Berry sử dụng các biến môi trường
# Thêm vào .yarnrc.yml ở thư mục gốc của dự án:
httpProxy: "http://username:password@proxy-host:port"
httpsProxy: "http://username:password@proxy-host:port"

# Hoặc qua các biến môi trường
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"

pnpm

# pnpm sử dụng cùng .npmrc như npm
# Các cài đặt được áp dụng tự động nếu npm đã được cấu hình

# Hoặc rõ ràng qua pnpm config
pnpm config set proxy http://username:password@proxy-host:port
pnpm config set https-proxy http://username:password@proxy-host:port

Giải pháp thay thế: gương của kho npm

Nếu kho npm chậm, nhưng GitHub có thể truy cập — bạn có thể chuyển sang gương. Các tùy chọn phổ biến: Taobao (cho Trung Quốc), Verdaccio (tự lưu trữ). Nhưng các gương thường bị chậm hơn về phiên bản gói, vì vậy proxy đáng tin cậy hơn:

# Chuyển kho sang gương (chỉ để tăng tốc, không để vượt qua sự chặn)
npm config set registry https://registry.npmmirror.com

# Trở lại kho chính thức
npm config set registry https://registry.npmjs.org

Proxy trong CI/CD: GitHub Actions, Docker, Jenkins

Thiết lập proxy trên máy cục bộ chỉ là một phần của công việc. Cơn đau thực sự bắt đầu khi cần đảm bảo quyền truy cập vào GitHub và npm trong pipeline CI/CD, hoạt động trong một mạng bị cô lập. Chúng ta sẽ phân tích ba kịch bản phổ biến nhất.

GitHub Actions

Trong GitHub Actions, proxy được thiết lập thông qua các biến môi trường trong tệp workflow. Thêm các bí mật vào cài đặt kho (Cài đặt → Bí mật), sau đó sử dụng chúng trong workflow:

# .github/workflows/build.yml
name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    
    env:
      HTTP_PROXY: ${{ secrets.PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.PROXY_URL }}
      NO_PROXY: "localhost,127.0.0.1"
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Configure npm proxy
        run: |
          npm config set proxy ${{ secrets.PROXY_URL }}
          npm config set https-proxy ${{ secrets.PROXY_URL }}
      
      - name: Install dependencies
        run: npm ci

Docker

Trong Docker, proxy cần thiết ở hai cấp độ: khi xây dựng hình ảnh (trong docker build) và bên trong container. Đây là các cài đặt khác nhau:

# Truyền proxy khi xây dựng qua --build-arg
docker build \
  --build-arg HTTP_PROXY=http://user:pass@proxy-host:port \
  --build-arg HTTPS_PROXY=http://user:pass@proxy-host:port \
  -t myapp .

# Trong Dockerfile sử dụng ARG cho proxy
# Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN npm ci

# Sau khi cài đặt các phụ thuộc — đặt lại proxy (không lưu trong hình ảnh!)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

Cấu hình toàn cầu cho proxy cho daemon Docker (cho docker pull):

# /etc/docker/daemon.json
{
  "proxies": {
    "http-proxy": "http://user:pass@proxy-host:port",
    "https-proxy": "http://user:pass@proxy-host:port",
    "no-proxy": "localhost,127.0.0.1"
  }
}

# Khởi động lại Docker sau khi thay đổi
sudo systemctl restart docker

Jenkins

Trong Jenkins, proxy được thiết lập ở cấp độ agent thông qua các biến môi trường trong Jenkinsfile hoặc toàn cầu trong cài đặt hệ thống:

// Jenkinsfile
pipeline {
    agent any
    
    environment {
        HTTP_PROXY  = credentials('proxy-url')
        HTTPS_PROXY = credentials('proxy-url')
        NO_PROXY    = 'localhost,127.0.0.1'
    }
    
    stages {
        stage('Install') {
            steps {
                sh 'npm config set proxy $HTTP_PROXY'
                sh 'npm config set https-proxy $HTTPS_PROXY'
                sh 'npm ci'
            }
        }
        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }
    }
}

Các lỗi thường gặp và cách khắc phục

Ngay cả khi cấu hình proxy đúng, vẫn có thể có điều gì đó không ổn. Chúng tôi đã tổng hợp những lỗi phổ biến nhất và cách khắc phục.

Lỗi: ECONNREFUSED hoặc Connection refused

Proxy không phản hồi. Nguyên nhân: địa chỉ hoặc cổng không đúng, máy chủ proxy không khả dụng, thời gian hiệu lực của thông tin đăng nhập đã hết.

Giải pháp: Kiểm tra khả năng truy cập của proxy bằng lệnh:

curl -v --proxy http://user:pass@proxy-host:port https://github.com

Lỗi: Vấn đề chứng chỉ SSL / UNABLE_TO_VERIFY_LEAF_SIGNATURE

Proxy chặn lưu lượng SSL và chèn chứng chỉ của riêng mình, mà Git hoặc npm không tin tưởng.

Giải pháp cho Git:

git config --global http.sslVerify false
# Hoặc thêm chứng chỉ gốc của proxy:
git config --global http.sslCAInfo /path/to/proxy-ca.crt

Lỗi: npm ERR! code ENOTFOUND

npm không thể giải quyết tên DNS của kho. Proxy đã được cấu hình, nhưng các yêu cầu DNS không đi qua nó.

Giải pháp: Sử dụng SOCKS5 thay vì proxy HTTP — nó định tuyến các yêu cầu DNS:

npm config set proxy socks5://user:pass@proxy-host:port
npm config set https-proxy socks5://user:pass@proxy-host:port

Lỗi: 407 Proxy Authentication Required

Proxy yêu cầu xác thực, nhưng thông tin đăng nhập không được cung cấp hoặc được cung cấp không đúng.

# Đảm bảo rằng tên đăng nhập và mật khẩu trong URL được mã hóa đúng
# Nếu mật khẩu có ký tự đặc biệt (@, :, #) — hãy mã hóa chúng:
# @ → %40, : → %3A, # → %23

# Ví dụ: mật khẩu "p@ss:word" → "p%40ss%3Aword"
npm config set proxy http://user:p%40ss%3Aword@proxy-host:port

Git clone hoạt động, nhưng git push thì không

Clone (đọc) và push (ghi) có thể sử dụng các giao thức khác nhau. Đảm bảo rằng proxy được cấu hình cho cả HTTP và HTTPS. Nếu bạn sử dụng SSH để push — cần có một cấu hình riêng trong ~/.ssh/config như đã mô tả ở trên.

Danh sách kiểm tra: kiểm tra xem mọi thứ hoạt động

Sau khi thiết lập proxy, hãy kiểm tra danh sách kiểm tra này để đảm bảo mọi thứ hoạt động chính xác.

Chẩn đoán nhanh bằng một lệnh

Nếu có điều gì đó không hoạt động và không rõ vấn đề ở đâu — hãy chạy script chẩn đoán này:

#!/bin/bash
# Chẩn đoán proxy cho GitHub/npm

PROXY="http://user:pass@proxy-host:port"

echo "=== 1. Truy cập trực tiếp vào GitHub ==="
curl -s -o /dev/null -w "%{http_code}" https://github.com && echo " OK" || echo " FAIL"

echo "=== 2. Truy cập qua proxy ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://github.com && echo " OK" || echo " FAIL"

echo "=== 3. Truy cập vào kho npm qua proxy ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://registry.npmjs.org && echo " OK" || echo " FAIL"

echo "=== 4. Cấu hình proxy Git hiện tại ==="
git config --global --list | grep proxy || echo "Proxy Git chưa được thiết lập"

echo "=== 5. Cấu hình proxy npm hiện tại ==="
npm config get proxy
npm config get https-proxy

Kết luận

Thiết lập proxy cho GitHub và npm không phải là nhiệm vụ khó khăn nếu biết đúng thứ tự các bước. Hãy tóm tắt lại:

• Để tăng tốc GitHub chậm — hãy sử dụng proxy trung tâm dữ liệu ở Mỹ hoặc châu Âu: chúng nhanh, ổn định và rẻ.
• Để vượt qua sự chặn — proxy cư dân với IP của người dùng thực tế đảm bảo độ tin cậy tối đa.
• Đối với Git qua HTTPS — hãy thiết lập http.proxy trong git config.
• Đối với Git qua SSH — sử dụng ProxyCommand trong ~/.ssh/config.
• Đối với npm/yarn/pnpm — hãy thiết lập proxy qua config hoặc biến môi trường.
• Đối với CI/CD — hãy truyền dữ liệu proxy qua bí mật, không mã hóa trong mã.

Một lần dành 10–15 phút để thiết lập, bạn sẽ có quyền truy cập ổn định vào GitHub và npm mà không phụ thuộc vào trạng thái của kênh internet hoặc chính sách chặn. Đội ngũ không còn mất thời gian chờ đợi tải xuống chậm, các pipeline CI/CD chạy mà không có lỗi mạng, và các nhà phát triển ở các quốc gia khác nhau làm việc trong cùng một điều kiện.

Nếu bạn đang tìm kiếm một proxy ổn định để làm việc với GitHub và npm từ các quốc gia có quyền truy cập hạn chế, 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 độ cao và độ ổn định kết nối, điều này rất quan trọng khi sao chép các kho lưu trữ và cài đặt các phụ thuộc. Đối với các khu vực có sự chặn nghiêm ngặt, proxy cư dân sẽ là lựa chọn tốt hơn — IP của chúng hầu như không bị đưa vào hạn chế.