بروكسي لـ PyPI: كيفية تثبيت حزم بايثون في المناطق المحجوبة عبر pip

```html

PyPI — المستودع الرئيسي لحزم Python — يتم حظره بشكل دوري في عدد من الدول والشبكات المؤسسية. إذا كان pip install يتوقف أو يظهر خطأ في الاتصال، فإن المشكلة تكمن هنا. في هذه المقالة، سنستعرض جميع الطرق الفعالة: من متغيرات البيئة إلى المرآة وحاويات Docker.

لماذا PyPI غير متاح: أسباب الحظر

قبل إعداد البروكسي، من المهم فهم نوع الحظر الذي تواجهه. يعتمد اختيار الحل على ذلك.

حظر إقليمي

في عدد من الدول (إيران، الصين، بعض مناطق روسيا خلال فترات القيود العقابية) يتم حظر الوصول إلى pypi.org و files.pythonhosted.org على مستوى مزود الخدمة أو جدار الحماية الحكومي. الأمر الذي يجعل الأمر يتوقف أو يظهر ConnectionError.

بروكسي الشركات وجدران الحماية

تقوم العديد من الشركات بتوجيه كل حركة المرور الصادرة عبر خادم بروكسي مؤسسي. إذا لم يكن pip على علم بهذا البروكسي، فإنه يحاول الاتصال مباشرة ويتلقى رفضًا. الخطأ الشائع في هذه الحالة هو: ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

خوادم بدون اتصال بالإنترنت (مفصولة)

غالبًا ما تكون الخوادم الإنتاجية، وخوادم البنوك، والهياكل الحكومية، أو في VPC السحابية المعزولة لا تحتوي على وصول مباشر إلى الإنترنت. هنا تحتاج إلى إما خادم بروكسي داخل الشبكة أو مرآة محلية لـ PyPI.

انقطاعات مؤقتة وتحديد المعدل

أحيانًا يقوم PyPI بتحديد عدد الطلبات من عنوان IP واحد — خاصة إذا كنت تقوم بنشر عشرات حاويات Docker في نفس الوقت. في هذه الحالة، يحل البروكسي مع تدوير IP المشكلة.

كيف تتحقق مما إذا كان PyPI محظورًا؟

نفذ في الطرفية: curl -v https://pypi.org/simple/. إذا كان الاتصال يتوقف أو يظهر خطأ SSL/timeout — PyPI غير متاح من عنوان IP الخاص بك. إذا كان الخطأ يحتوي على كلمة 407 Proxy Authentication Required — أنت خلف بروكسي مؤسسي.

متغيرات البيئة: أسرع طريقة

أسهل وأبسط طريقة هي تعيين متغيرات البيئة القياسية HTTP_PROXY و HTTPS_PROXY. يقوم pip، مثل معظم مكتبات Python (requests، urllib3)، بالتقاطها تلقائيًا دون إعداد إضافي.

Linux و 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.

Windows (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")

Windows (cmd)

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

لاحظ: إذا كانت كلمة المرور تحتوي على رموز خاصة (@، #، %)، يجب ترميزها في URL. على سبيل المثال، @ يتحول إلى %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 في Docker و CI/CD

عند بناء صور Docker، يتم تشغيل 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

# الملف: ~/.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

# الخطأ:
# 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 مطلوب مصادقة البروكسي

# الخطأ:
# ProxyError: 407 مطلوب مصادقة البروكسي

# السبب: البروكسي يتطلب مصادقة، ولكن لم يتم تمرير اسم المستخدم/كلمة المرور
# الحل: تأكد من أن بيانات الاعتماد مشفرة بشكل صحيح

# إذا كانت كلمة المرور تحتوي على رموز خاصة، قم بترميزها:
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  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# تحقق من أولوية تكوين pip
pip config debug

# السبب المحتمل: البيئة الافتراضية لا ترى المتغيرات النظامية
# الحل: قم بتنشيط venv وأعد تعيين المتغيرات مرة أخرى
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

الخطأ 4: انتهاء مهلة الاتصال حتى عبر البروكسي

# تحقق من توفر البروكسي
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 في Docker.

يعتمد الاختيار بين البروكسي والمرآة على السياق: المرايا أسرع وأسهل في الإعداد، لكنها تتطلب الثقة في مشغل المرآة. البروكسي أكثر تنوعًا — فهو يعمل ليس فقط مع PyPI، ولكن أيضًا مع أي موارد محظورة أخرى (npm، Docker Hub، GitHub).

إذا كنت بحاجة إلى بروكسي موثوق للعمل مع PyPI و GitHub و Docker Hub وغيرها من الموارد المحظورة في منطقتك، انتبه إلى بروكسي مركز البيانات — حيث توفر سرعة عالية عند تنزيل الحزم الثقيلة وتعمل بشكل مستقر في بيئات CI/CD. إذا كانت IP مركز البيانات محظورة حتى في منطقتك، فكر في استخدام بروكسي سكنية مع IP لمستخدمين حقيقيين في المنازل — فهي أقل عرضة بكثير للحظر الإقليمي.