پروکسی برای PyPI: چگونه بسته‌های پایتون را در مناطق مسدود شده از طریق pip نصب کنیم

```html

PyPI — مخزن اصلی بسته‌های Python — به طور دوره‌ای در تعدادی از کشورها و شبکه‌های شرکتی مسدود می‌شود. اگر pip install متوقف می‌شود یا خطای اتصال می‌دهد، مشکل دقیقاً در همین جاست. در این مقاله تمام روش‌های کارآمد را بررسی خواهیم کرد: از متغیرهای محیطی تا آینه‌ها و کانتینرهای داکر.

چرا PyPI در دسترس نیست: دلایل مسدودیت‌ها

قبل از تنظیم پروکسی، مهم است که بفهمید با کدام نوع مسدودیت مواجه هستید. این موضوع بر انتخاب راه‌حل تأثیر می‌گذارد.

مسدودیت‌های منطقه‌ای

در تعدادی از کشورها (ایران، چین، برخی مناطق روسیه در دوره‌های تحریم) دسترسی به pypi.org و files.pythonhosted.org در سطح ارائه‌دهنده یا فایروال دولتی مسدود می‌شود. دستور pip install requests به سادگی متوقف می‌شود یا خطای ConnectionError را می‌دهد.

پروکسی‌های شرکتی و فایروال‌ها

بسیاری از شرکت‌ها تمام ترافیک خروجی را از طریق یک سرور پروکسی شرکتی هدایت می‌کنند. اگر pip از این پروکسی مطلع نباشد، سعی می‌کند به طور مستقیم متصل شود و با رد درخواست مواجه می‌شود. خطای معمول در این حالت: ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

سرورهای بدون دسترسی به اینترنت (air-gapped)

سرورهای تولید، سرورهای بانکی، سازمان‌های دولتی یا در VPC‌های ابری ایزوله معمولاً هیچ دسترسی مستقیمی به اینترنت ندارند. در اینجا به یک سرور پروکسی درون شبکه یا یک آینه محلی PyPI نیاز است.

اختلالات موقتی و محدودیت نرخ

گاهی اوقات PyPI خود تعداد درخواست‌ها را از یک IP محدود می‌کند — به ویژه اگر شما ده‌ها کانتینر داکر را به طور همزمان راه‌اندازی کنید. در این صورت، پروکسی با چرخش IP مشکل را حل می‌کند.

چگونه بررسی کنیم که آیا PyPI مسدود شده است؟

در ترمینال اجرا کنید: curl -v https://pypi.org/simple/. اگر اتصال متوقف شود یا خطای SSL/timeout را بدهد — PyPI از IP شما در دسترس نیست. اگر خطا شامل کلمه 407 Proxy Authentication Required باشد — شما پشت پروکسی شرکتی هستید.

متغیرهای محیطی: سریع‌ترین روش

ساده‌ترین و عمومی‌ترین روش — تنظیم متغیرهای محیطی استاندارد HTTP_PROXY و HTTPS_PROXY. Pip، مانند اکثر کتابخانه‌های Python (requests، urllib3)، به طور خودکار آن‌ها را بدون تنظیمات اضافی شناسایی می‌کند.

لینوکس و macOS

# بدون احراز هویت
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# با نام کاربری و رمز عبور
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"

# پروکسی SOCKS5
export HTTP_PROXY="socks5://user:[email protected]:1080"
export HTTPS_PROXY="socks5://user:[email protected]:1080"

# حالا بسته را نصب می‌کنیم
pip install requests

برای اینکه هر بار نیاز به وارد کردن دستورات نباشد، خطوط را به ~/.bashrc یا ~/.zshrc اضافه کنید.

ویندوز (PowerShell)

# موقتی (فقط برای جلسه جاری)
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# دائمی (برای تمام جلسات)
[System.Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://user:[email protected]:8080", "User")
[System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://user:[email protected]:8080", "User")

ویندوز (cmd)

set HTTP_PROXY=http://user:[email protected]:8080
set HTTPS_PROXY=http://user:[email protected]:8080
pip install numpy

توجه داشته باشید: اگر در رمز عبور کاراکترهای خاصی وجود دارد (@, #, %)، باید آن‌ها را URL-encode کنید. به عنوان مثال، @ به %40 تبدیل می‌شود.

پرچم --proxy به طور مستقیم در pip

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

pip install pandas --proxy http://user:[email protected]:8080

# برای SOCKS5 به بسته pysocks نیاز دارید
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

تنظیم پروکسی از طریق pip.conf و pip.ini

اگر می‌خواهید که پروکسی به طور خودکار در هر بار اجرای pip استفاده شود — بدون نیاز به صادرات دستی متغیرها — آن را در فایل پیکربندی pip بنویسید.

محل فایل‌های پیکربندی

محتوای فایل pip.conf

[global]
proxy = http://user:[email protected]:8080

# اگر نیاز به نادیده گرفتن بررسی SSL دارید (در تولید توصیه نمی‌شود)
# trusted-host = pypi.org
#                files.pythonhosted.org

پس از ذخیره فایل، تمام فراخوانی‌های بعدی pip install به طور خودکار از پروکسی مشخص شده استفاده خواهند کرد. برای بررسی پیکربندی فعلی می‌توانید از دستور زیر استفاده کنید:

pip config list
pip config debug  # نشان می‌دهد که تمام فایل‌های پیکربندی و اولویت‌های آن‌ها چیست

کدام نوع پروکسی را برای PyPI انتخاب کنیم

همه پروکسی‌ها به یک اندازه برای کار با PyPI مناسب نیستند. انتخاب بستگی به دلیل مسدودیت و زیرساخت شما دارد.

برای اکثر توسعه‌دهندگانی که با مسدودیت PyPI به دلیل محدودیت‌های منطقه‌ای مواجه هستند، انتخاب بهینه پروکسی‌های مرکز داده خواهد بود — آن‌ها سرعت بالایی در دانلود بسته‌ها و اتصال پایدار ارائه می‌دهند. سرعت به ویژه زمانی مهم است که نیاز به نصب بسته‌های سنگینی مانند PyTorch یا TensorFlow (چند گیگابایت) دارید.

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

HTTP در مقابل HTTPS در مقابل SOCKS5: چه چیزی توسط pip پشتیبانی می‌شود؟

Pip به طور بومی از پروکسی‌های HTTP و HTTPS پشتیبانی می‌کند. برای SOCKS5 نیاز به نصب بسته اضافی دارید:

# برای پشتیبانی از SOCKS5 در pip به pysocks نیاز دارید
# اما یک مشکل وجود دارد: pip برای نصب pysocks نیاز دارد، و pip بدون پروکسی کار نمی‌کند
# راه‌حل: ابتدا از طریق پروکسی HTTP نصب کنید، سپس به SOCKS5 سوئیچ کنید

pip install pysocks --proxy http://1.2.3.4:8080
# پس از آن می‌توانید از SOCKS5 استفاده کنید
pip install requests --proxy socks5://user:[email protected]:1080

آینه‌های PyPI به عنوان جایگزینی برای پروکسی

اگر تنظیم پروکسی به نظر پیچیده می‌رسد یا شما یک سرور پروکسی قابل اعتماد ندارید، می‌توانید از آینه‌های رسمی و غیررسمی PyPI استفاده کنید. این موضوع به ویژه برای توسعه‌دهندگان در چین که چندین آینه محلی سریع دارند، بسیار مهم است.

آینه‌های محبوب PyPI

چگونه از آینه استفاده کنیم

# یک‌بار، از طریق پرچم -i
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

# دائمی، از طریق pip.conf
# [global]
# index-url = https://pypi.tuna.tsinghua.edu.cn/simple
# trusted-host = pypi.tuna.tsinghua.edu.cn

# چندین منبع (fallback)
pip install pandas \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --extra-index-url https://pypi.org/simple/

پروکسی برای pip در داکر و CI/CD

هنگام ساخت تصاویر داکر، pip درون کانتینری اجرا می‌شود که ممکن است به PyPI دسترسی نداشته باشد. این موضوع به ویژه یک مشکل رایج در خطوط لوله CI/CD شرکتی (GitLab CI، GitHub Actions، Jenkins) است.

انتقال پروکسی از طریق ARG در Dockerfile

FROM python:3.11-slim

# اعلام ARG برای پروکسی
ARG HTTP_PROXY
ARG HTTPS_PROXY

# انتقال به ENV برای pip و سایر ابزارها
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# پس از نصب پروکسی را ریست کنید (امنیت)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

COPY . .
CMD ["python", "app.py"]

ساخت با انتقال پروکسی:

docker build \
  --build-arg HTTP_PROXY=http://user:[email protected]:8080 \
  --build-arg HTTPS_PROXY=http://user:[email protected]:8080 \
  -t myapp .

تنظیم جهانی پروکسی برای Docker daemon

# فایل: ~/.docker/config.json
{
  "proxies": {
    "default": {
      "httpProxy": "http://user:[email protected]:8080",
      "httpsProxy": "http://user:[email protected]:8080",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

GitLab CI / GitHub Actions

# .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://user:[email protected]:8080"
  HTTPS_PROXY: "http://user:[email protected]:8080"
  PIP_INDEX_URL: "https://pypi.tuna.tsinghua.edu.cn/simple"

install:
  script:
    - pip install -r requirements.txt

# .github/workflows/ci.yml
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{ secrets.HTTP_PROXY }}
      HTTPS_PROXY: ${{ secrets.HTTP_PROXY }}
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: pip install -r requirements.txt

مهم است: هرگز اطلاعات حساب کاربری پروکسی را به طور سخت‌افزاری در فایل‌های YAML قرار ندهید. از رازها (Secrets) سرویس CI/CD خود استفاده کنید.

تنظیم پروکسی برای Poetry، conda و uv

پروژه‌های مدرن Python به طور فزاینده‌ای از مدیران بسته جایگزین استفاده می‌کنند. بیایید تنظیم پروکسی را برای هر یک از آن‌ها بررسی کنیم.

Poetry

Poetry از متغیرهای محیطی به همان شیوه‌ای که pip استفاده می‌کند، بهره می‌برد. اما یک نکته وجود دارد — Poetry از یک کلاینت HTTP اختصاصی مبتنی بر requests استفاده می‌کند، بنابراین متغیرهای استاندارد کار می‌کنند:

# برای Poetry کار می‌کند
export HTTPS_PROXY=http://user:[email protected]:8080
poetry install

# یا تنظیم منبع در pyproject.toml
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

conda سیستم پیکربندی خاص خود را دارد:

# از طریق دستور
conda config --set proxy_servers.http http://user:[email protected]:8080
conda config --set proxy_servers.https http://user:[email protected]:8080

# یا به طور مستقیم در ~/.condarc
# proxy_servers:
#   http: http://user:[email protected]:8080
#   https: http://user:[email protected]:8080

# آینه conda برای چین
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes

uv (مدیر بسته سریع جدید)

uv از Astral — یکی از سریع‌ترین مدیران بسته برای Python است. او همچنین از متغیرهای محیطی استاندارد پشتیبانی می‌کند:

export HTTPS_PROXY=http://user:[email protected]:8080
uv pip install numpy

# یا با پرچم index
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv متغیرهای محیطی را از pip به ارث می‌برد
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

# تغییر منبع در Pipfile
# [[source]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# verify_ssl = true
# name = "tsinghua"

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

بیایید به بررسی رایج‌ترین مشکلاتی بپردازیم که توسعه‌دهندگان هنگام تنظیم پروکسی برای pip با آن‌ها مواجه می‌شوند.

خطا 1: SSL Certificate Verification Failed

# خطا:
# SSL: CERTIFICATE_VERIFY_FAILED] گواهی تأیید نشد: قادر به دریافت گواهی صادرکننده محلی نیست

# دلیل: پروکسی شرکتی گواهی‌های SSL را تغییر می‌دهد (MITM)
# راه‌حل 1: افزودن گواهی CA شرکتی
pip install requests --cert /path/to/corporate-ca.crt

# راه‌حل 2: مشخص کردن مسیر گواهی در pip.conf
# [global]
# cert = /path/to/corporate-ca.crt

# راه‌حل 3 (برای تولید توصیه نمی‌شود): غیر فعال کردن بررسی SSL
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

خطا 2: 407 Proxy Authentication Required

# خطا:
# ProxyError: 407 Proxy Authentication Required

# دلیل: پروکسی نیاز به احراز هویت دارد، اما نام کاربری/رمز عبور ارسال نشده است
# راه‌حل: اطمینان حاصل کنید که اطلاعات حساب کاربری به درستی کدگذاری شده‌اند

# اگر رمز عبور شامل کاراکترهای خاص است، آن‌ها را کدگذاری کنید:
python3 -c "from urllib.parse import quote; print(quote('my@pass#word'))"
# خروجی: my%40pass%23word

export HTTPS_PROXY="http://user:my%40pass%[email protected]:8080"

خطا 3: pip متغیرهای محیطی را نادیده می‌گیرد

# بررسی کنید که متغیرها به درستی تنظیم شده‌اند
echo $HTTPS_PROXY  # لینوکس/macOS
echo %HTTPS_PROXY%  # ویندوز cmd

# بررسی کنید که اولویت پیکربندی pip چیست
pip config debug

# دلیل ممکن: محیط مجازی نمی‌تواند متغیرهای سیستمی را ببیند
# راه‌حل: venv را فعال کنید و متغیرها را دوباره تنظیم کنید
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

خطا 4: Connection timeout حتی از طریق پروکسی

# بررسی کنید که آیا پروکسی در دسترس است
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# اگر پروکسی در دسترس نیست — مشکل از خود سرور پروکسی است
# یک پورت یا پروتکل دیگر را امتحان کنید

# زمان‌بندی pip را افزایش دهید
pip install package-name --timeout 120

# یا در pip.conf:
# [global]
# timeout = 120

خطا 5: بسته نصب شده، اما وارد نمی‌شود

این موضوع به پروکسی مربوط نمی‌شود — احتمالاً بسته در Python سیستم نصب شده است، نه در محیط مجازی فعال. بررسی کنید:

which pip      # باید به pip درون venv اشاره کند
which python   # باید به python درون venv اشاره کند
pip show requests  # نشان می‌دهد که بسته کجا نصب شده است

چک‌لیست عیب‌یابی پروکسی برای pip

نتیجه‌گیری

مسدودیت PyPI — یک مشکل قابل حل است و راه‌حل‌های قابل اعتمادی برای آن وجود دارد. برای شروع سریع، کافی است متغیر HTTPS_PROXY را تنظیم کرده و pip را به طور معمول اجرا کنید. برای کارکرد دائمی — پروکسی را در pip.conf بنویسید. برای CI/CD — از رازها و ARG در داکر استفاده کنید.

انتخاب بین پروکسی و آینه بستگی به زمینه دارد: آینه‌ها سریع‌تر و ساده‌تر در تنظیم هستند، اما به اعتماد به اپراتور آینه نیاز دارند. پروکسی‌ها عمومی‌تر هستند — آن‌ها نه تنها با PyPI، بلکه با هر منبع مسدود شده دیگری (npm، Docker Hub، GitHub) کار می‌کنند.

اگر به یک پروکسی قابل اعتماد برای کار با PyPI، GitHub، Docker Hub و سایر منابع مسدود شده در منطقه خود نیاز دارید، به پروکسی‌های مرکز داده توجه کنید — آن‌ها سرعت بالایی در دانلود بسته‌های سنگین ارائه می‌دهند و در محیط‌های CI/CD به طور پایدار کار می‌کنند. اگر در منطقه شما حتی IP مرکز داده‌ها نیز مسدود شده است، به پروکسی‌های مسکونی با IP کاربران واقعی خانگی فکر کنید — آن‌ها به طور قابل توجهی کمتر تحت مسدودیت‌های منطقه‌ای قرار می‌گیرند.