Featured image of post 『Blog』Dive Into System Proxy
Software Engineering

『Blog』Dive Into System Proxy

由浅入深地介绍 System Proxy 的工作原理，记录常用的系统代理配置。

代理服务器

核心概念

值得注意的是，即使在配置 clash-meta 代理路由后再设置国内镜像源（无论是 pip 还是 apt），也不会造成网络请求的额外绕路。这得益于 rules-group 的智能路由机制 —— 网络请求在离开本机之前就会被精确分流。对于国内主流镜像源的域名，系统会自动采用 DIRECT 出站策略，使设备与镜像服务器建立直连。这种分流设计不仅确保了对国内资源的低延迟访问，同时又能无缝处理需要代理的国际网络请求，实现了最优的网络访问体验。

mermaid-diagram-2025-03-04-154857

同样，rules-gruop 内置了开发常见的路由规则，不必担心局域网流量环回和内网域名解析错误等问题。

常用配置

本文均以 127.0.0.1:2088 指代局域网内（本机）系统代理的监听地址，你需要根据你的实际情况进行修改。

为了确保系统代理配置的完整性和精确控制，在设置任何代理变量（如 HTTP_PROXY 或 HTTPS_PROXY）时，都必须同时配置 NO_PROXY 环境变量。

NO_PROXY 作为最高优先级的代理过滤策略，会直接决定哪些域名或 IP 地址将绕过代理设置。

以下是一些常见的配置示例：

~/.bashrc

# 最全的写法，能够在不开启 tun 虚拟网卡的情况下覆盖绝大多数开发场景
export HTTPS_PROXY=http://127.0.0.1:2088
export HTTP_PROXY=http://127.0.0.1:2088
export https_proxy=http://127.0.0.1:2088
export http_proxy=http://127.0.0.1:2088
export GRPC_PROXY=http://127.0.0.1:2088
export GRPC_ENABLE_HTTP_PROXY=1
export ALL_PROXY=http://127.0.0.1:2088
export all_proxy=http://127.0.0.1:2088
export NO_PROXY=localhost,127.0.0.1
export no_proxy=localhost,127.0.0.1

./docker-compose.yaml

# 在 service 的 `environment` 中插入索引
# <<: *runtime_args
x-build-args: &runtime_args
    HTTPS_PROXY: http://127.0.0.1:2088
    HTTP_PROXY: http://127.0.0.1:2088
    https_proxy: http://127.0.0.1:2088
    http_proxy: http://127.0.0.1:2088
    GRPC_PROXY: http://127.0.0.1:2088
    GRPC_ENABLE_HTTP_PROXY: 1
    ALL_PROXY: http://127.0.0.1:2088
    all_proxy: http://127.0.0.1:2088
    NO_PROXY: localhost,127.0.0.1
    no_proxy: localhost,127.0.0.1

./Dockerfile

# 影响宿主机 docker build 时镜像内的网络行为，如 RUN yarn install
ENV HTTPS_PROXY=http://127.0.0.1:2088
ENV HTTP_PROXY=http://127.0.0.1:2088
ENV NO_PROXY=localhost,127.0.0.1

/etc/systemd/system/docker.service.d/http-proxy.conf

# 影响宿主机 docker pull 时拉取镜像的网络行为
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:2088"
Environment="HTTPS_PROXY=http://127.0.0.1:2088"
Environment="NO_PROXY=localhost,127.0.0.1"

在宿主机中可用如下指令检查当前 terminal 是否被代理影响：

env | grep -i proxy

代理客户端搭建

截至本文修改日期（2024-09-05）proxy_channel 以及 proxy_protocol 的最佳实践技术栈组合为：server/hysteria2 + client/clash.meta。

Hysteria2

快捷指令看 $hy2 部分，在 2081 端口部署。

  • Heyhy 一键部署脚本，在 Ubuntu 标准设备上一键部署 hysteria2 代理服务端
  • Hysteria2，下载预编译的 hysteria2 代理客户端

Clash.Meta

快捷指令看 $clash-meta 部分，在 2088 端口部署。

pip

pip 受环境变量影响。如果在宿主机内使用 pip 下载依赖，而 ~/.bashrc 环境变量中配置了代理，则可直接使用代理下载依赖。

请避免同时使用 –proxy 和 –index-url 参数。

如果 –index-url 指定了国内或局域网内的镜像源，且未配置相应的 DIRECT 分流规则，可能会导致程序通过远程代理访问这些镜像源，从而引发连接错误。

Download from Open Source Mirror

pypi | 镜像站使用帮助 | 清华大学开源软件镜像站 | Tsinghua Open Source Mirror

临时使用

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple some-package

设为默认，永久设置，如下操作会把配置写入到 /root/.config/pip/pip.conf

python3 -m pip install --upgrade pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

查看当前python环境的 pip 配置

pip config list

移除镜像源

pip config unset global.index-url

Download from JFrog

缓存常用的、体积巨大的 .whl，此时主要矛盾转移到了“下载速度”上。尽管是 client proxy 直连 pypi 下载，下载速度也受 client 和 pypi 的上下行速度限制（PyPI 镜像的下行极值在 200Mbps 左右），但内网文件互传的速度远比这要快（瓶颈在网卡和硬盘 4k 读写，pull 指令下行均值可达 3000Mbps）。

你可以查看 JFrog 官网，判断是否必要本地部署。

Conda

建议用 miniconda 而非 Anaconda

conda config --set proxy_servers.http http://127.0.0.1:2088
conda config --set proxy_servers.https http://127.0.0.1:2088

调整默认启动的虚拟环境 dev：

conda config --set auto_activate_base false
conda config --set default_python 3.10
# /root/.bashrc
# 需要提前创建
conda activate dev

调整后的配置文件：

# vim /root/.condarc
channels:
  # - https://mirrors.ustc.edu.cn/anaconda/cloud/menpo/
  # - https://mirrors.ustc.edu.cn/anaconda/cloud/bioconda/
  # - https://mirrors.ustc.edu.cn/anaconda/cloud/msys2/
  # - https://mirrors.ustc.edu.cn/anaconda/cloud/conda-forge/
  # - https://mirrors.ustc.edu.cn/anaconda/pkgs/free/
  # - https://mirrors.ustc.edu.cn/anaconda/pkgs/main/
  - defaults
show_channel_urls: true
proxy_servers:
  https: http://127.0.0.1:2088
  http: http://127.0.0.1:2088
default_python: '3.10'
auto_activate_base: false

Docker

如下配置仅影响镜像拉取下载的网络行为，例如 docker pull 和 docker compose pull，不影响容器正常运行时的网络通信。

创建配置文件目录

mkdir -p /etc/systemd/system/docker.service.d

修改配置

vim /etc/systemd/system/docker.service.d/http-proxy.conf

将 Docker pull 指向宿主机系统代理

# Add content below
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:2088"
Environment="HTTPS_PROXY=http://127.0.0.1:2088"
Environment="NO_PROXY=localhost,127.0.0.1"

修改代理配置后，需要重启相关容器服务以使新的配置生效，可以通过以下命令完成重启操作：

systemctl daemon-reload
systemctl restart docker

完事后可以检查 docker 的环境变量

docker info
重启容器服务之前，确保配置文件内的设定是正确的，否则可能导致宿主机的容器网络炸穿。

Reference

Docker Compose

在 docker-compose.yaml 文件中添加公用的环境变量，然后引用插入，或在 environment 中直接插入，以下是样例写法：

x-build-args: &runtime_args
  http_proxy: http://127.0.0.1:2088
  https_proxy: http://127.0.0.1:2088
  HTTP_PROXY: http://127.0.0.1:2088
  HTTPS_PROXY: http://127.0.0.1:2088
  LOG_LEVEL: DEBUG
  
services:
  jygs-crawler:
    image: alpine
    environment:
      <<: *runtime_args
      SERVER_HOST: "${SERVER_HOST:-}"
      TZ: Asia/Shanghai
x-build-args: &runtime_args
  - http_proxy=http://127.0.0.1:2088
  - https_proxy=http://127.0.0.1:2088
  - HTTP_PROXY=http://127.0.0.1:2088
  - HTTPS_PROXY=http://127.0.0.1:2088
  - LOG_LEVEL=DEBUG
  
services:
  jygs-crawler:
    image: alpine
    environment:
      <<: *runtime_args
      - SERVER_HOST:="${SERVER_HOST:-}"
      - TZ=Asia/Shanghai
docker-compose.yaml 中，environment 的优先级比 env_file (.env) 要更高。

Git

参考链接

一次性指令：

git clone -c http.proxy="http://127.0.0.1:2088" [repo_url]

设置 Git 全局代理：

git config --global http.proxy http://127.0.0.1:2088
git config --global https.proxy http://127.0.0.1:2088

# check configuration
vim ~/.gitconfig

移除 Git 全局代理：

git config --global --unset http.proxy
git config --global --unset https.proxy

Wget

wget 默认使用环境变量中的 http_proxy/https_proxy（小写） 访问互联网资源，你可以参照上文 常用配置 设置环境变量，或使用一次性指令：

wget -e use_proxy=yes -e https_proxy=http://127.0.0.1:2088 [TARGET_HTTPS_URL]

或：

wget -e use_proxy=yes -e http_proxy=http://127.0.0.1:2088 [TARGET_HTTP_URL]

也即，wget 会使用 http_proxy 去访问 http 链接，使用 https_proxy 去访问 https 链接。以上指令的代理是临时生效的的，不会作用到后续 wget 的操作。

cURL

概述

curl 作为一个广泛使用的类Unix网络请求工具，在某些场景下需要配置代理来访问网络。本文将详细介绍配置curl代理的多种方法。

命令行参数配置

基本语法：

-x, --proxy [protocol://]host[:port]

示例配置，以下几种方式都是有效的：

curl -x "http://127.0.0.1:2088" "http://httpbin.org/ip"

或

curl --proxy "http://127.0.0.1:2088" "http://httpbin.org/ip"

由于默认协议为http，因此也可以简写为：

curl --proxy "127.0.0.1:2088" "http://httpbin.org/ip"

环境变量配置

可以通过设置环境变量来全局配置代理：

# 设置 http 代理
export http_proxy="http://127.0.0.1:2088"
# 设置 https 代理
export https_proxy="http://127.0.0.1:2088"

如需取消代理配置：

unset http_proxy
unset https_proxy

配置文件设置

proxy="http://127.0.0.1:2088"

忽略代理

当需要临时使用其他代理时：

curl --proxy "http://127.0.0.1:2088" "http://httpbin.org/ip"

当需要忽略所有代理设置时：

curl --noproxy "*" "http://httpbin.org/ip"

注意事项

  • 命令行参数的优先级最高，其次是 ~/.curlrc，最后才是 ~/.bashrc
  • 环境变量配置可以是临时的也可以是永久的（需要添加到 ~/.bashrc 或 ~/.zshrc）
  • 配置文件方式的修改是永久性的

apt-get

代理设置

apt-get 和 apt 受环境变量控制，理论上在镜像构建阶段可以通过环境变量控制代理行为。而在宿主机内，通常可以修改 ~/.bashrc 或临时环境变量来控制代理行为，或修改 apt 的配置文件持久化。

  1. 查看环境代理
env | grep -i proxy
  1. 设置环境代理
vim ~/.bashrc
# >>> SYSTEM_PROXY >>>
export HTTP_PROXY=http://127.0.0.1:2088
export HTTPS_PROXY=http://127.0.0.1:2088
export ALL_PROXY=http://127.0.0.1:2088
export NO_PROXY=localhost
export https_proxy=http://127.0.0.1:2088
# <<< SYSTEM_PROXY <<<
source ~/.bashrc
  1. 修改持久化配置
vim /etc/apt/apt.conf.d/proxy.conf
Acquire {
  HTTP::proxy "http://127.0.0.1:2088";
  HTTPS::proxy "http://127.0.0.1:2088";
}

镜像源设置

vim /etc/apt/sources.list
# See http://help.ubuntu.com/community/UpgradeNotes for how to upgrade to
# newer versions of the distribution.
deb http://archive.ubuntu.com/ubuntu/ jammy main restricted
deb-src http://archive.ubuntu.com/ubuntu/ jammy main restricted

## Major bug fix updates produced after the final release of the
## distribution.
deb http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted
deb-src http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted

## N.B. software from this repository is ENTIRELY UNSUPPORTED by the Ubuntu
## team. Also, please note that software in universe WILL NOT receive any
## review or updates from the Ubuntu security team.
deb http://archive.ubuntu.com/ubuntu/ jammy universe
deb-src http://archive.ubuntu.com/ubuntu/ jammy universe
deb http://archive.ubuntu.com/ubuntu/ jammy-updates universe
deb-src http://archive.ubuntu.com/ubuntu/ jammy-updates universe

## N.B. software from this repository is ENTIRELY UNSUPPORTED by the Ubuntu
## team, and may not be under a free licence. Please satisfy yourself as to
## your rights to use the software. Also, please note that software in
## multiverse WILL NOT receive any review or updates from the Ubuntu
## security team.
deb http://archive.ubuntu.com/ubuntu/ jammy multiverse
deb-src http://archive.ubuntu.com/ubuntu/ jammy multiverse
deb http://archive.ubuntu.com/ubuntu/ jammy-updates multiverse
deb-src http://archive.ubuntu.com/ubuntu/ jammy-updates multiverse

## N.B. software from this repository may not have been tested as
## extensively as that contained in the main release, although it includes
## newer versions of some applications which may provide useful features.
## Also, please note that software in backports WILL NOT receive any review
## or updates from the Ubuntu security team.
deb http://archive.ubuntu.com/ubuntu/ jammy-backports main restricted universe multiverse
deb-src http://archive.ubuntu.com/ubuntu/ jammy-backports main restricted universe multiverse

deb http://security.ubuntu.com/ubuntu jammy-security main restricted
deb-src http://security.ubuntu.com/ubuntu jammy-security main restricted
deb http://security.ubuntu.com/ubuntu jammy-security universe
deb-src http://security.ubuntu.com/ubuntu jammy-security universe
deb http://security.ubuntu.com/ubuntu jammy-security multiverse
deb-src http://security.ubuntu.com/ubuntu jammy-security multiverse

更新软件包列表

sudo apt update

pnpm/bun/npm/yarn

包管理器均受环境变量影响。非特殊情况不建议单独设置。

以下是各个包管理器设置代理的方法：

  1. npm
# 设置代理
npm config set proxy http://127.0.0.1:2088
npm config set https-proxy http://127.0.0.1:2088

# 查看代理设置
npm config list

# 删除代理
npm config delete proxy
npm config delete https-proxy

# 临时使用代理
HTTP_PROXY=http://127.0.0.1:2088 HTTPS_PROXY=http://127.0.0.1:2088 npm install
  1. yarn
# 设置代理
yarn config set proxy http://127.0.0.1:2088
yarn config set https-proxy http://127.0.0.1:2088

# 查看代理设置
yarn config list

# 删除代理
yarn config delete proxy
yarn config delete https-proxy

# 临时使用代理
HTTP_PROXY=http://127.0.0.1:2088 HTTPS_PROXY=http://127.0.0.1:2088 yarn install
  1. pnpm
# 设置代理
pnpm config set proxy http://127.0.0.1:2088
pnpm config set https-proxy http://127.0.0.1:2088

# 查看代理设置
pnpm config list

# 删除代理
pnpm config delete proxy
pnpm config delete https-proxy

# 临时使用代理
HTTP_PROXY=http://127.0.0.1:2088 HTTPS_PROXY=http://127.0.0.1:2088 pnpm install
  1. bun
# bun 主要依赖系统环境变量
export HTTP_PROXY=http://127.0.0.1:2088
export HTTPS_PROXY=http://127.0.0.1:2088

# 或者临时使用代理
HTTP_PROXY=http://127.0.0.1:2088 HTTPS_PROXY=http://127.0.0.1:2088 bun install

配置文件位置：

  • npm: ~/.npmrc
  • yarn: ~/.yarnrc 或 .yarnrc.yml
  • pnpm: ~/.npmrc
  • bun: 主要使用环境变量
Licensed under CC BY-NC-SA 4.0
comments powered by Disqus
© 2020 - 2025 Echosec @QIN2DIM
You will to enjoy grander sight / By climing to a greater height.