Linux 配置 HTTP 代理

在网络受限或需要统一出口的环境中，可以通过 HTTP 代理访问软件仓库、容器镜像仓库和 Python 包索引。下面以代理地址 http://127.0.0.1:7890 为例，请按实际地址和端口替换。

Linux 环境变量

临时配置

只对当前终端会话生效：

1
2
3
4
5
6
export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"
export no_proxy="localhost,127.0.0.1,::1"
export NO_PROXY="$no_proxy"

可以用 curl 验证代理是否能正常访问外网：

1
curl -x "http://127.0.0.1:7890" https://ipinfo.io/ip

持久配置

将上面的 export 命令写入当前用户的 shell 配置文件。Bash 通常使用 ~/.bashrc，Zsh 通常使用 ~/.zshrc：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
cat >> ~/.bashrc <<'EOF'
export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"
export no_proxy="localhost,127.0.0.1,::1"
export NO_PROXY="$no_proxy"
EOF

source ~/.bashrc

如果需要让通过 systemd 启动的服务使用代理，应在对应服务中设置环境变量，而不是只修改用户的 shell 配置。例如：

1
sudo systemctl edit your-service

加入：

1
2
3
4
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,::1"

然后重新加载并重启服务：

1
2
sudo systemctl daemon-reload
sudo systemctl restart your-service

Docker 使用 HTTP 代理

Docker 拉取镜像由 Docker daemon 执行，因此仅设置当前用户的环境变量通常不够。Linux 上可以通过 /etc/docker/daemon.json 为 Docker daemon 配置代理。下面以局域网代理地址 192.168.0.100:7890 为例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "proxies": {
    "http-proxy": "http://192.168.0.100:7890",
    "https-proxy": "http://192.168.0.100:7890",
    "no-proxy": "localhost,127.0.0.1,192.168.0.0/16"
  }
}
EOF

sudo systemctl restart docker

如果 /etc/docker/daemon.json 中已经存在 registry-mirrors 等配置，不要直接覆盖文件。请使用 sudo nano /etc/docker/daemon.json，将上面的 proxies 字段合并到已有 JSON 对象中，并确保 JSON 语法正确。

检查 Docker daemon 是否读取到配置：

1
docker info | grep -i proxy

确认代理配置生效后，拉取镜像：

1
docker pull vincentqin/image-matching-webui:latest

如果连接失败，请确认局域网机器 192.168.0.100 上的代理软件已开启“允许来自局域网的连接”（Allow LAN），并确认该机器的防火墙已放行 7890 端口。可以从当前 Linux 主机测试代理：

1
curl -x "http://192.168.0.100:7890" https://ipinfo.io/ip

仅为容器设置代理

如果只希望容器内的程序使用代理，可以在启动时传入环境变量，不修改 Docker daemon：

1
2
3
4
5
docker run --rm \
  -e HTTP_PROXY="http://127.0.0.1:7890" \
  -e HTTPS_PROXY="http://127.0.0.1:7890" \
  -e NO_PROXY="localhost,127.0.0.1,::1" \
  alpine sh -c 'wget -qO- https://example.com | head'

使用 Docker Compose 时，可以在服务的 environment 中配置同样的变量：

1
2
3
4
5
6
services:
  app:
    environment:
      HTTP_PROXY: http://127.0.0.1:7890
      HTTPS_PROXY: http://127.0.0.1:7890
      NO_PROXY: localhost,127.0.0.1,::1

注意：容器中的 127.0.0.1 指向容器自身。如果代理运行在宿主机上，Linux 容器通常需要使用宿主机可访问的地址，例如宿主机局域网 IP，并确保代理监听的地址允许容器访问。

pip 使用 HTTP 代理

单次安装

使用 --proxy 只影响当前命令：

1
python -m pip install requests --proxy http://127.0.0.1:7890

也可以通过环境变量配置当前 shell：

1
2
3
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
python -m pip install requests

持久配置

使用 pip config 写入当前用户配置：

1
python -m pip config set global.proxy http://127.0.0.1:7890

查看当前配置：

1
python -m pip config list

取消该配置：

1
python -m pip config unset global.proxy

也可以直接编辑用户级配置文件。Linux 上通常是 ~/.config/pip/pip.conf：

1
2
[global]
proxy = http://127.0.0.1:7890

代理需要用户名和密码时

代理地址格式为：

1
http://用户名:密码@代理地址:端口

如果用户名或密码包含 @、:、/ 等特殊字符，应先进行 URL 编码。不要把包含密码的命令写入公开脚本、文章或 shell 历史记录；更安全的做法是使用代理软件提供的本地无认证端口，或通过环境变量和权限受控的配置文件传递凭据。

排查方法

验证代理是否生效

执行以下命令查看出口 IP：

1
curl https://ipinfo.io/ip

如果命令返回的 IP 是代理服务器的公网 IP，说明请求已经通过代理；如果仍然是当前 Linux 主机的公网 IP，请检查代理环境变量、代理服务的 Allow LAN 设置以及防火墙规则。

用 curl -I https://pypi.org 验证基础代理连接。
用 env | grep -i proxy 检查当前 shell 的代理变量。
用 docker info | grep -i proxy 检查 Docker daemon 配置。
用 python -m pip config debug 查看 pip 实际读取的配置文件。
将不应经过代理的内网域名和地址加入 NO_PROXY，多个值用逗号分隔。

代理使用完毕后，可以在当前 shell 中取消临时变量：

1
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY