پروکسی برای گیت‌هاب و npm: چگونه به مخازن و بسته‌ها از کشورهایی که گیت‌هاب مسدود شده یا به آرامی کار می‌کند دسترسی پیدا کنیم

GitHub مسدود شده، با تأخیر 10–30 ثانیه‌ای کار می‌کند یا npm install در میانه راه متوقف می‌شود — این یک وضعیت آشنا برای توسعه‌دهندگان از روسیه، ایران، چین و چندین کشور دیگر است. راه‌حلی وجود دارد و آن ساده‌تر از آن چیزی است که به نظر می‌رسد: پروکسی به درستی تنظیم شده دسترسی پایدار به مخازن، بسته‌ها و API GitHub را بدون VPN و بدون نیاز به کارهای اضافی فراهم می‌کند.

چرا GitHub و npm مسدود یا کند می‌شوند

قبل از تنظیم پروکسی، مهم است که بفهمید دقیقاً با چه چیزی مواجه هستید. مشکلات دسترسی به GitHub و npm سه نوع هستند و هر یک نیاز به رویکرد خاص خود دارد.

مسدودیت کامل در سطح دولت

تعدادی از کشورها — چین، ایران، کره شمالی و از سال 2022 به طور دوره‌ای روسیه — GitHub را در سطح DNS یا بر اساس IP مسدود می‌کنند. این بدان معناست که درخواست‌ها به github.com یا اصلاً نمی‌گذرند یا خطای اتصال برمی‌گردانند. در این حین، مخزن npm (registry.npmjs.org) ممکن است به درستی کار کند — یا نیز مسدود باشد.

فایروال‌های شرکتی و محدودیت‌های شبکه

حتی بدون مسدودیت دولتی، شبکه‌های شرکتی اغلب دسترسی به مخازن خارجی را محدود می‌کنند. این یک عمل استاندارد در بانک‌ها، نهادهای دولتی و شرکت‌های بزرگ است: بخش IT اتصالات خروجی را به پورت‌های 443 مسدود می‌کند یا دامنه‌های خاصی را مسدود می‌کند. یک توسعه‌دهنده در چنین شبکه‌ای نمی‌تواند git clone یا npm install را بدون یک مسیر دور بزند.

سرعت کند به دلیل جغرافیا

از نظر فنی GitHub در دسترس است، اما کلون کردن یک مخزن 500 مگابایتی 40 دقیقه طول می‌کشد و نصب وابستگی‌ها از طریق npm — یک عمر. این مشکل مسیریابی است: بسته‌ها از طریق گره‌های شلوغ یا مسیرهای طولانی می‌روند. یک سرور پروکسی واقع در ایالات متحده یا اروپا مسیر را کوتاه می‌کند و افزایش واقعی سرعت 3–10 برابری را فراهم می‌کند.

پروکسی vs VPN: چه چیزی برای کار با کد انتخاب کنیم

بسیاری از توسعه‌دهندگان به طور عادت به VPN روی می‌آورند. این قابل درک است — VPN تنظیم آن ساده است و بلافاصله برای کل سیستم کار می‌کند. اما برای کار با GitHub و npm، پروکسی اغلب راحت‌تر است. بیایید تفاوت را بررسی کنیم.

نتیجه ساده است: اگر هدف شما این است که به تیم دسترسی به GitHub و npm بدهید، پروکسی یک بار در پیکربندی تنظیم می‌شود و بدون نیاز به دخالت در تنظیمات سیستمی هر دستگاه کار می‌کند. این به ویژه برای پایپ‌لاین‌های CI/CD مهم است که در آن‌ها راه‌اندازی VPN به طور فیزیکی دشوار است.

کدام نوع پروکسی برای GitHub و npm مناسب است

همه پروکسی‌ها به یک اندازه با Git و npm کار نمی‌کنند. انتخاب بستگی به هدف شما دارد: دور زدن مسدودیت، تسریع بارگذاری یا کار از شبکه شرکتی.

پروکسی HTTP/HTTPS

ساده‌ترین گزینه. Git و npm به طور بومی پروکسی HTTP را از طریق متغیرهای محیطی استاندارد پشتیبانی می‌کنند. برای اکثر وظایف مناسب است: کلون کردن مخازن، نصب بسته‌ها، کار با API GitHub. اگر ارائه‌دهنده پروکسی شما آدرس HTTP می‌دهد — از آن شروع کنید.

پروکسی SOCKS5

پروتکل انعطاف‌پذیرتری است که در سطح TCP کار می‌کند. از هر نوع ترافیکی پشتیبانی می‌کند، از جمله اتصالات SSH با GitHub (پورت 22). اگر از Git از طریق SSH استفاده می‌کنید و نه HTTPS — SOCKS5 ترجیح داده می‌شود. Git SOCKS5 را از طریق پارامتر socks5:// در پیکربندی پشتیبانی می‌کند.

پروکسی‌های مسکونی

پروکسی‌های مسکونی از آدرس‌های IP کاربران واقعی خانگی استفاده می‌کنند. برای GitHub این به ویژه مهم است، اگر از کشوری با مسدودیت شدید کار می‌کنید: این نوع IP‌ها به ندرت در لیست سیاه قرار می‌گیرند و مانند ترافیک کاربران عادی به نظر می‌رسند. برای مواقعی که IP‌های دیتاسنتری قبلاً در سطح ارائه‌دهنده مسدود شده‌اند مناسب است.

پروکسی‌های دیتاسنتر

پروکسی‌های دیتاسنتر — انتخاب بهینه برای اکثر توسعه‌دهندگان. آن‌ها سریع‌تر از پروکسی‌های مسکونی هستند، هزینه کمتری دارند و اتصال پایداری را فراهم می‌کنند. اگر GitHub فقط کند است و نه مسدود — پروکسی دیتاسنتری در ایالات متحده یا اروپا بیشترین افزایش سرعت را در کلون کردن و بارگذاری بسته‌ها فراهم می‌کند.

تنظیم پروکسی برای Git: دستورالعمل مرحله به مرحله

Git از طریق پیکربندی داخلی و از طریق متغیرهای محیطی از پروکسی پشتیبانی می‌کند. هر دو روش را نشان می‌دهیم — روش مناسب برای فرآیند کاری خود را انتخاب کنید.

روش 1: از طریق git config (توصیه می‌شود)

این یک تنظیم دائمی است که به تمام عملیات Git در دستگاه اعمال می‌شود. ترمینال را باز کنید و اجرا کنید:

# برای پروکسی HTTP/HTTPS
git config --global http.proxy http://username:password@proxy-host:port
git config --global https.proxy http://username:password@proxy-host:port

# برای پروکسی SOCKS5
git config --global http.proxy socks5://username:password@proxy-host:port
git config --global https.proxy socks5://username:password@proxy-host:port

# بررسی کنید که تنظیمات اعمال شده‌اند
git config --global --list | grep proxy

username:password@proxy-host:port را با اطلاعات پروکسی خود جایگزین کنید. اگر پروکسی بدون احراز هویت است — username:password@ را حذف کنید.

روش 2: از طریق متغیرهای محیطی

برای استفاده موقت یا در اسکریپت‌ها مناسب است. Git به طور خودکار متغیرهای استاندارد HTTP_PROXY و HTTPS_PROXY را شناسایی می‌کند:

# Linux / macOS — اضافه کنید به ~/.bashrc یا ~/.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"

# ویندوز (PowerShell)
$env:HTTP_PROXY="http://username:password@proxy-host:port"
$env:HTTPS_PROXY="http://username:password@proxy-host:port"

# اعمال بدون راه‌اندازی مجدد ترمینال (Linux/macOS)
source ~/.bashrc

تنظیم پروکسی فقط برای GitHub

اگر می‌خواهید فقط درخواست‌ها به GitHub از طریق پروکسی هدایت شوند و نه به تمام مخازن، از تنظیمات بخش استفاده کنید:

# پروکسی فقط برای github.com
git config --global http.https://github.com.proxy http://username:password@proxy-host:port

# بررسی کلون کردن از طریق پروکسی
git clone https://github.com/username/repo.git

Git از طریق SSH از طریق SOCKS5

اگر از GitHub از طریق SSH (نه HTTPS) استفاده می‌کنید، تنظیم کمی متفاوت است. باید فایل ~/.ssh/config را ویرایش کنید:

# ~/.ssh/config

Host github.com
    HostName github.com
    User git
    # در Linux/macOS از nc (netcat) استفاده کنید
    ProxyCommand nc -X 5 -x proxy-host:port %h %p
    
    # یا از طریق connect-proxy (نیاز به نصب دارد)
    # ProxyCommand connect -S proxy-host:port %h %p
    
    # در ویندوز از طریق Git Bash
    # ProxyCommand connect -S proxy-host:port %h %p

پس از این، دستورات git clone [email protected]:user/repo.git و git push به طور خودکار از طریق پروکسی SOCKS5 انجام خواهند شد.

چگونه تنظیمات پروکسی را بازنشانی کنیم

# حذف پروکسی از پیکربندی جهانی
git config --global --unset http.proxy
git config --global --unset https.proxy

تنظیم پروکسی برای npm، yarn و pnpm

هر مدیر بسته روش خاص خود را برای تنظیم پروکسی دارد. همه سه مورد — npm، yarn و pnpm — را با دستورات خاص بررسی می‌کنیم.

npm

npm از طریق تنظیمات داخلی پیکربندی از پروکسی پشتیبانی می‌کند:

# تنظیم پروکسی برای npm
npm config set proxy http://username:password@proxy-host:port
npm config set https-proxy http://username:password@proxy-host:port

# بررسی تنظیمات
npm config get proxy
npm config get https-proxy

# تست: نصب بسته از طریق پروکسی
npm install lodash

# بازنشانی پروکسی
npm config delete proxy
npm config delete https-proxy

تنظیمات در فایل ~/.npmrc ذخیره می‌شوند. شما می‌توانید آن را به طور مستقیم ویرایش کنید:

# ~/.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

# بررسی
yarn config get proxy

# بازنشانی
yarn config delete proxy
yarn config delete https-proxy

Yarn Berry (v2+)

# Yarn Berry از متغیرهای محیطی استفاده می‌کند
# اضافه کنید به .yarnrc.yml در ریشه پروژه:
httpProxy: "http://username:password@proxy-host:port"
httpsProxy: "http://username:password@proxy-host:port"

# یا از طریق متغیرهای محیطی
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"

pnpm

# pnpm از همان .npmrc که npm استفاده می‌کند استفاده می‌کند
# تنظیمات به طور خودکار اعمال می‌شوند، اگر npm قبلاً تنظیم شده باشد

# یا به طور صریح از طریق pnpm config
pnpm config set proxy http://username:password@proxy-host:port
pnpm config set https-proxy http://username:password@proxy-host:port

جایگزین: آینه‌های مخزن npm

اگر مخزن npm کند است، اما GitHub در دسترس است — می‌توانید به آینه تغییر دهید. گزینه‌های محبوب: Taobao (برای چین)، Verdaccio (خود میزبانی). اما آینه‌ها اغلب در نسخه‌های بسته‌ها عقب می‌مانند، بنابراین پروکسی قابل اعتمادتر است:

# تغییر مخزن به آینه (فقط برای تسریع، نه برای مسدودیت‌ها)
npm config set registry https://registry.npmmirror.com

# بازگشت به مخزن رسمی
npm config set registry https://registry.npmjs.org

پروکسی در CI/CD: GitHub Actions، Docker، Jenkins

تنظیم پروکسی در دستگاه محلی — این نیمه کار است. درد واقعی زمانی شروع می‌شود که باید دسترسی به GitHub و npm را در پایپ‌لاین CI/CD که در یک شبکه ایزوله کار می‌کند، فراهم کنید. سه سناریوی رایج را بررسی می‌کنیم.

GitHub Actions

در GitHub Actions پروکسی از طریق متغیرهای محیطی در فایل workflow تنظیم می‌شود. اسرار را در تنظیمات مخزن اضافه کنید (Settings → Secrets)، سپس از آن‌ها در 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

در Docker پروکسی در دو سطح نیاز است: هنگام ساخت تصویر (در docker build) و داخل کانتینر. این‌ها تنظیمات متفاوتی هستند:

# ارسال پروکسی هنگام ساخت از طریق --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 .

# در Dockerfile از ARG برای پروکسی استفاده کنید
# Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN npm ci

# پس از نصب وابستگی‌ها — پروکسی را بازنشانی کنید (در تصویر ذخیره نکنید!)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

تنظیم جهانی پروکسی برای دیمون Docker (برای 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"
  }
}

# پس از تغییرات Docker را دوباره راه‌اندازی کنید
sudo systemctl restart docker

Jenkins

در Jenkins پروکسی در سطح عامل از طریق متغیرهای محیطی در Jenkinsfile یا به طور جهانی در تنظیمات سیستم تنظیم می‌شود:

// 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'
            }
        }
    }
}

خطاهای رایج و نحوه رفع آن‌ها

حتی با تنظیم صحیح پروکسی، ممکن است چیزی اشتباه پیش برود. رایج‌ترین خطاها و راه‌حل‌های آن‌ها را جمع‌آوری کرده‌ایم.

خطا: ECONNREFUSED یا Connection refused

پروکسی پاسخ نمی‌دهد. دلایل: آدرس یا پورت نادرست، سرور پروکسی در دسترس نیست، اعتبارنامه‌ها منقضی شده‌اند.

راه‌حل: با دستور زیر دسترسی پروکسی را بررسی کنید:

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

خطا: مشکل گواهی SSL / UNABLE_TO_VERIFY_LEAF_SIGNATURE

پروکسی ترافیک SSL را ره‌گیری کرده و گواهی خود را قرار می‌دهد که Git یا npm به آن اعتماد ندارند.

راه‌حل برای Git:

git config --global http.sslVerify false
# یا گواهی ریشه پروکسی را اضافه کنید:
git config --global http.sslCAInfo /path/to/proxy-ca.crt

خطا: npm ERR! code ENOTFOUND

npm نمی‌تواند نام DNS مخزن را حل کند. پروکسی تنظیم شده است، اما درخواست‌های DNS از طریق آن نمی‌روند.

راه‌حل: از SOCKS5 به جای پروکسی HTTP استفاده کنید — این DNS را تونل می‌کند:

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

خطا: 407 نیاز به احراز هویت پروکسی

پروکسی نیاز به احراز هویت دارد، اما اعتبارنامه‌ها ارسال نشده‌اند یا نادرست ارسال شده‌اند.

# اطمینان حاصل کنید که نام کاربری و رمز عبور در URL به درستی کدگذاری شده‌اند
# اگر در رمز عبور کاراکترهای خاصی وجود دارد (@، :، #) — آن‌ها را کدگذاری کنید:
# @ → %40، : → %3A، # → %23

# مثال: رمز عبور "p@ss:word" → "p%40ss%3Aword"
npm config set proxy http://user:p%40ss%3Aword@proxy-host:port

Git clone کار می‌کند، اما git push نه

Clone (خواندن) و push (نوشتن) می‌توانند از پروتکل‌های مختلفی استفاده کنند. اطمینان حاصل کنید که پروکسی برای HTTP و HTTPS تنظیم شده است. اگر از SSH برای push استفاده می‌کنید — نیاز به تنظیم جداگانه در ~/.ssh/config دارید همانطور که در بالا توضیح داده شد.

چک‌لیست: بررسی می‌کنیم که همه چیز کار می‌کند

پس از تنظیم پروکسی، از این چک‌لیست عبور کنید تا اطمینان حاصل کنید که همه چیز به درستی کار می‌کند.

تشخیص سریع با یک دستور

اگر چیزی کار نمی‌کند و مشخص نیست مشکل کجاست — این اسکریپت تشخیص را اجرا کنید:

#!/bin/bash
# تشخیص پروکسی برای GitHub/npm

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

echo "=== 1. دسترسی مستقیم به GitHub ==="
curl -s -o /dev/null -w "%{http_code}" https://github.com && echo " OK" || echo " FAIL"

echo "=== 2. دسترسی از طریق پروکسی ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://github.com && echo " OK" || echo " FAIL"

echo "=== 3. دسترسی به مخزن npm از طریق پروکسی ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://registry.npmjs.org && echo " OK" || echo " FAIL"

echo "=== 4. تنظیمات فعلی پروکسی Git ==="
git config --global --list | grep proxy || echo "پروکسی Git تنظیم نشده است"

echo "=== 5. تنظیمات فعلی پروکسی npm ==="
npm config get proxy
npm config get https-proxy

نتیجه‌گیری

تنظیم پروکسی برای GitHub و npm — این یک کار دشوار نیست، اگر ترتیب صحیح اقدامات را بدانید. بیایید خلاصه کنیم:

• برای تسریع GitHub کند — پروکسی‌های دیتاسنتر در ایالات متحده یا اروپا مناسب هستند: آن‌ها سریع، پایدار و ارزان هستند.
• برای دور زدن مسدودیت‌ها — پروکسی‌های مسکونی با IP کاربران واقعی حداکثر اطمینان را فراهم می‌کنند.
• برای Git از طریق HTTPS — http.proxy را در پیکربندی Git تنظیم کنید.
• برای Git از طریق SSH — از ProxyCommand در ~/.ssh/config استفاده کنید.
• برای npm/yarn/pnpm — پروکسی را از طریق پیکربندی یا متغیرهای محیطی تنظیم کنید.
• برای CI/CD — داده‌های پروکسی را از طریق اسرار منتقل کنید، در کد هاردکد نکنید.

یک بار 10–15 دقیقه برای تنظیم وقت بگذارید، شما دسترسی پایدار به GitHub و npm را بدون وابستگی به وضعیت کانال اینترنت یا سیاست‌های مسدودیت دریافت می‌کنید. تیم دیگر وقت خود را برای انتظار بارگذاری‌های کند هدر نمی‌دهد، پایپ‌لاین‌های CI/CD بدون خطاهای شبکه عبور می‌کنند و توسعه‌دهندگان در کشورهای مختلف در شرایط یکسان کار می‌کنند.

اگر به دنبال پروکسی پایدار برای کار با GitHub و npm از کشورهای با دسترسی محدود هستید، توصیه می‌کنیم به پروکسی‌های دیتاسنتر توجه کنید — آن‌ها سرعت بالا و ثبات اتصال را فراهم می‌کنند که در کلون کردن مخازن و نصب وابستگی‌ها حیاتی است. برای مناطق با مسدودیت‌های شدید، پروکسی‌های مسکونی بهترین گزینه هستند — IP‌های آن‌ها به ندرت تحت محدودیت‌ها قرار می‌گیرند.