Proxy cho PyPI: cài đặt gói Python vượt qua các khối.

```html

PyPI — kho lưu trữ chính của các gói Python — thỉnh thoảng bị chặn ở một số quốc gia và mạng doanh nghiệp. Nếu pip install bị treo hoặc báo lỗi kết nối, vấn đề chính là ở đây. Trong bài viết, chúng ta sẽ xem xét tất cả các cách làm việc: từ biến môi trường đến gương và các container Docker.

Tại sao PyPI không khả dụng: nguyên nhân chặn

Trước khi cấu hình proxy, điều quan trọng là hiểu rõ bạn đang gặp phải loại chặn nào. Điều này sẽ ảnh hưởng đến sự lựa chọn giải pháp.

Chặn theo khu vực

Ở một số quốc gia (Iran, Trung Quốc, một số khu vực của Nga trong thời gian bị trừng phạt), truy cập vào pypi.org và files.pythonhosted.org bị chặn ở cấp độ nhà cung cấp hoặc tường lửa nhà nước. Lệnh pip install requests chỉ đơn giản là bị treo hoặc báo lỗi ConnectionError.

Proxy doanh nghiệp và tường lửa

Nhiều công ty chuyển toàn bộ lưu lượng truy cập ra ngoài qua máy chủ proxy doanh nghiệp. Nếu pip không biết về proxy này, nó sẽ cố gắng kết nối trực tiếp và bị từ chối. Lỗi điển hình trong trường hợp này là: ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

Máy chủ không có kết nối internet (air-gapped)

Các máy chủ sản xuất, máy chủ trong ngân hàng, cơ quan nhà nước hoặc trong các VPC đám mây cách ly thường không có quyền truy cập trực tiếp vào internet. Ở đây cần một máy chủ proxy trong mạng hoặc một gương PyPI cục bộ.

Sự cố tạm thời và giới hạn tốc độ

Đôi khi PyPI tự giới hạn số lượng yêu cầu từ một IP — đặc biệt nếu bạn triển khai hàng chục container Docker cùng một lúc. Trong trường hợp này, proxy với việc xoay vòng IP giải quyết vấn đề.

Làm thế nào để kiểm tra xem PyPI có bị chặn không?

Thực hiện trong terminal: curl -v https://pypi.org/simple/. Nếu kết nối bị treo hoặc báo lỗi SSL/timeout — PyPI không khả dụng từ IP của bạn. Nếu lỗi chứa từ 407 Proxy Authentication Required — bạn đang ở sau proxy doanh nghiệp.

Biến môi trường: cách nhanh nhất

Cách đơn giản và phổ biến nhất là thiết lập các biến môi trường tiêu chuẩn HTTP_PROXY và HTTPS_PROXY. Pip, giống như hầu hết các thư viện Python (requests, urllib3), tự động nhận chúng mà không cần cấu hình thêm.

Linux và macOS

# Không cần xác thực
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# Với tên đăng nhập và mật khẩu
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"

# Proxy SOCKS5
export HTTP_PROXY="socks5://user:[email protected]:1080"
export HTTPS_PROXY="socks5://user:[email protected]:1080"

# Bây giờ cài đặt gói
pip install requests

Để không phải nhập lệnh mỗi lần, hãy thêm các dòng vào ~/.bashrc hoặc ~/.zshrc.

Windows (PowerShell)

# Tạm thời (chỉ cho phiên hiện tại)
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# Vĩnh viễn (cho tất cả các phiên)
[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

Lưu ý: nếu mật khẩu có ký tự đặc biệt (@, #, %), chúng cần được mã hóa URL. Ví dụ, @ trở thành %40.

Cờ --proxy trực tiếp trong pip

Nếu cần sử dụng proxy chỉ cho một lệnh, mà không thay đổi cấu hình toàn cầu:

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

# Đối với SOCKS5 cần gói pysocks
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

Cấu hình proxy qua pip.conf và pip.ini

Nếu bạn muốn proxy được sử dụng tự động mỗi khi chạy pip — mà không cần xuất biến thủ công — hãy ghi nó vào tệp cấu hình pip.

Vị trí của các tệp cấu hình

Hệ điều hành	Đường dẫn đến tệp	Phạm vi
Linux / macOS	`~/.config/pip/pip.conf`	Người dùng hiện tại
Linux / macOS	`/etc/pip.conf`	Tất cả người dùng trong hệ thống
Windows	`%APPDATA%\pip\pip.ini`	Người dùng hiện tại
Bất kỳ hệ điều hành nào	`./pip.conf` (trong thư mục dự án)	Chỉ cho dự án hiện tại

Nội dung của tệp pip.conf

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

# Nếu cần bỏ qua xác thực SSL (không khuyến nghị trong sản xuất)
# trusted-host = pypi.org
#                files.pythonhosted.org

Sau khi lưu tệp, tất cả các lệnh pip install tiếp theo sẽ tự động sử dụng proxy đã chỉ định. Kiểm tra cấu hình hiện tại có thể thực hiện bằng lệnh:

pip config list
pip config debug  # hiển thị tất cả các tệp cấu hình và ưu tiên của chúng

Loại proxy nào nên chọn cho PyPI

Không phải tất cả các proxy đều phù hợp cho việc làm việc với PyPI. Sự lựa chọn phụ thuộc vào nguyên nhân chặn và cơ sở hạ tầng của bạn.

Loại proxy	Tốc độ	Độ tin cậy	Kịch bản tốt nhất
Datacenter	⚡ Cao	Trung bình	Mạng doanh nghiệp, CI/CD, tải xuống các gói lớn
Residential	Trung bình	⭐ Cao	Chặn theo khu vực, khi IP datacenter cũng bị chặn
Mobile	Trung bình	⭐ Cao	Chặn theo khu vực nghiêm ngặt, khi cần vượt qua tối đa
SOCKS5	⚡ Cao	Cao	Khi cần proxy cho toàn bộ lưu lượng, bao gồm DNS

Đối với hầu hết các nhà phát triển gặp phải việc chặn PyPI do các hạn chế theo khu vực, lựa chọn tối ưu sẽ là proxy datacenter — chúng cung cấp tốc độ tải xuống cao cho các gói và kết nối ổn định. Tốc độ đặc biệt quan trọng khi cần cài đặt các gói nặng như PyTorch hoặc TensorFlow (vài gigabyte).

Nếu IP datacenter cũng bị chặn ở khu vực của bạn (điều này xảy ra trong các hạn chế nhà nước nghiêm ngặt), bạn nên xem xét proxy residential — chúng sử dụng IP của người dùng thực và hiếm khi bị chặn.

HTTP vs HTTPS vs SOCKS5: pip hỗ trợ gì?

Pip hỗ trợ proxy HTTP và HTTPS một cách tự nhiên. Đối với SOCKS5, cần cài đặt gói bổ sung:

# Để hỗ trợ SOCKS5 trong pip cần pysocks
# Nhưng có một vấn đề: pip cần để cài đặt pysocks, mà pip không hoạt động mà không có proxy
# Giải pháp: trước tiên cài đặt qua proxy HTTP, sau đó chuyển sang SOCKS5

pip install pysocks --proxy http://1.2.3.4:8080
# Sau đó có thể sử dụng SOCKS5
pip install requests --proxy socks5://user:[email protected]:1080

Gương PyPI như một sự thay thế cho proxy

Nếu cấu hình proxy có vẻ phức tạp hoặc bạn không có máy chủ proxy đáng tin cậy, bạn có thể sử dụng các gương PyPI chính thức và không chính thức. Điều này đặc biệt quan trọng đối với các nhà phát triển ở Trung Quốc, nơi có một số gương địa phương nhanh chóng.

Các gương PyPI phổ biến

Gương	URL	Khu vực / Nhà điều hành
Tsinghua	`https://pypi.tuna.tsinghua.edu.cn/simple`	Trung Quốc (Đại học Tsinghua)
Aliyun	`https://mirrors.aliyun.com/pypi/simple`	Trung Quốc (Alibaba Cloud)
USTC	`https://pypi.mirrors.ustc.edu.cn/simple`	Trung Quốc (USTC)
Huawei Cloud	`https://repo.huaweicloud.com/repository/pypi/simple`	Trung Quốc (Huawei)

Cách sử dụng gương

# Một lần, qua cờ -i
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

# Vĩnh viễn, qua pip.conf
# [global]
# index-url = https://pypi.tuna.tsinghua.edu.cn/simple
# trusted-host = pypi.tuna.tsinghua.edu.cn

# Nhiều nguồn (fallback)
pip install pandas \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --extra-index-url https://pypi.org/simple/

⚠️ Quan trọng về an toàn của các gương

Chỉ sử dụng các gương đã được xác minh từ các tổ chức lớn (trường đại học, nhà cung cấp đám mây). Các gương không rõ nguồn gốc có thể chứa các gói đã được sửa đổi với mã độc — điều này được gọi là tấn công chuỗi cung ứng (supply chain attack). Đối với các dự án quan trọng, tốt hơn hết là thiết lập gương riêng thông qua devpi hoặc bandersnatch.

Proxy cho pip trong Docker và CI/CD

Khi xây dựng các hình ảnh Docker, pip chạy bên trong container, có thể không có quyền truy cập vào PyPI. Đây là một vấn đề thường gặp trong các pipeline CI/CD doanh nghiệp (GitLab CI, GitHub Actions, Jenkins).

Truyền proxy qua ARG trong Dockerfile

FROM python:3.11-slim

# Khai báo ARG cho proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY

# Truyền vào ENV cho pip và các công cụ khác
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

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

# Đặt lại proxy sau khi cài đặt (an toàn)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

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

Xây dựng với việc truyền proxy:

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

Cấu hình proxy toàn cầu cho Docker daemon

# Tệp: ~/.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

Quan trọng: không bao giờ mã hóa thông tin xác thực proxy trực tiếp trong các tệp YAML. Sử dụng bí mật (Secrets) của dịch vụ CI/CD của bạn.

Cấu hình proxy cho Poetry, conda và uv

Các dự án Python hiện đại ngày càng sử dụng nhiều trình quản lý gói thay thế. Hãy xem xét cấu hình proxy cho từng loại.

Poetry

Poetry sử dụng các biến môi trường giống như pip. Nhưng có một điểm khác — Poetry sử dụng một HTTP client riêng dựa trên requests, vì vậy các biến tiêu chuẩn hoạt động:

# Hoạt động cho Poetry
export HTTPS_PROXY=http://user:[email protected]:8080
poetry install

# Hoặc cấu hình nguồn trong pyproject.toml
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

Conda có hệ thống cấu hình riêng:

# Qua lệnh
conda config --set proxy_servers.http http://user:[email protected]:8080
conda config --set proxy_servers.https http://user:[email protected]:8080

# Hoặc trực tiếp trong ~/.condarc
# proxy_servers:
#   http: http://user:[email protected]:8080
#   https: http://user:[email protected]:8080

# Gương conda cho Trung Quốc
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes

uv (trình quản lý gói nhanh mới)

uv từ Astral — một trong những trình quản lý gói nhanh nhất cho Python. Nó cũng hỗ trợ các biến môi trường tiêu chuẩn:

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

# Hoặc với cờ index
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv kế thừa các biến môi trường từ pip
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

# Thay đổi nguồn trong Pipfile
# [[source]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# verify_ssl = true
# name = "tsinghua"

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

Chúng ta sẽ xem xét những vấn đề phổ biến nhất mà các nhà phát triển gặp phải khi cấu hình proxy cho pip.

Lỗi 1: SSL Certificate Verification Failed

# Lỗi:
# SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate

# Nguyên nhân: proxy doanh nghiệp thay thế các chứng chỉ SSL (MITM)
# Giải pháp 1: thêm chứng chỉ CA doanh nghiệp
pip install requests --cert /path/to/corporate-ca.crt

# Giải pháp 2: chỉ định đường dẫn đến chứng chỉ trong pip.conf
# [global]
# cert = /path/to/corporate-ca.crt

# Giải pháp 3 (KHÔNG khuyến nghị cho sản xuất): tắt xác thực SSL
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

Lỗi 2: 407 Proxy Authentication Required

# Lỗi:
# ProxyError: 407 Proxy Authentication Required

# Nguyên nhân: proxy yêu cầu xác thực, nhưng tên đăng nhập/mật khẩu không được truyền
# Giải pháp: đảm bảo rằng thông tin xác thực được mã hóa chính xác

# Nếu mật khẩu chứa ký tự đặc biệt, hãy mã hóa chúng:
python3 -c "from urllib.parse import quote; print(quote('my@pass#word'))"
# Đầu ra: my%40pass%23word

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

Lỗi 3: pip bỏ qua các biến môi trường

# Kiểm tra xem các biến đã được thiết lập chính xác
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# Kiểm tra ưu tiên cấu hình pip
pip config debug

# Nguyên nhân có thể: môi trường ảo không nhìn thấy các biến hệ thống
# Giải pháp: kích hoạt venv và thiết lập lại các biến
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

Lỗi 4: Connection timeout ngay cả qua proxy

# Kiểm tra khả năng truy cập của proxy
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# Nếu proxy không khả dụng — vấn đề nằm ở chính máy chủ proxy
# Thử một cổng hoặc giao thức khác

# Tăng thời gian chờ của pip
pip install package-name --timeout 120

# Hoặc trong pip.conf:
# [global]
# timeout = 120

Lỗi 5: Gói đã được cài đặt, nhưng import không hoạt động

Điều này không liên quan đến proxy — có thể gói đã được cài đặt vào Python hệ thống, không phải vào môi trường ảo đang hoạt động. Kiểm tra:

which pip      # phải chỉ vào pip bên trong venv
which python   # phải chỉ vào python bên trong venv
pip show requests  # sẽ hiển thị nơi gói đã được cài đặt

Danh sách kiểm tra khắc phục sự cố proxy cho pip

Chẩn đoán từng bước:

Kiểm tra khả năng truy cập PyPI mà không cần proxy: curl https://pypi.org
Đảm bảo rằng máy chủ proxy hoạt động: curl --proxy http://1.2.3.4:8080 https://pypi.org
Kiểm tra các biến môi trường: env | grep -i proxy
Xem cấu hình pip: pip config debug
Thử cờ trực tiếp: pip install pkg --proxy http://... -v
Nếu có lỗi SSL — kiểm tra chứng chỉ CA doanh nghiệp
Nếu vẫn không hoạt động — thử gương thay vì proxy

Kết luận

Việc chặn PyPI là một vấn đề có thể giải quyết và có một số giải pháp đáng tin cậy. Để bắt đầu nhanh chóng, chỉ cần thiết lập biến HTTPS_PROXY và chạy pip như thường lệ. Để hoạt động liên tục — ghi proxy vào pip.conf. Đối với CI/CD — sử dụng bí mật và ARG trong Docker.

Sự lựa chọn giữa proxy và gương phụ thuộc vào ngữ cảnh: gương nhanh hơn và dễ cấu hình hơn, nhưng đòi hỏi sự tin tưởng vào nhà điều hành gương. Proxy đa năng hơn — nó không chỉ hoạt động với PyPI mà còn với bất kỳ tài nguyên nào khác bị chặn (npm, Docker Hub, GitHub).

Nếu bạn cần một proxy đáng tin cậy để làm việc với PyPI, GitHub, Docker Hub và các tài nguyên bị chặn khác trong khu vực của bạn, hãy xem xét proxy datacenter — chúng cung cấp tốc độ cao khi tải xuống các gói nặng và hoạt động ổn định trong các môi trường CI/CD. Nếu IP datacenter cũng bị chặn ở khu vực của bạn, hãy xem xét proxy residential với IP của người dùng thực — chúng hiếm khi bị chặn theo khu vực.