pac-proxy-cli

本机运行的 PAC / 全局代理 / 抓包工具，提供 Web 控制台与本地代理服务。支持内置代理客户端、系统代理自动设置、PAC 规则管理、HTTPS 抓包与流量记录。启用内置客户端后，全局 / PAC 流量由其直接转发，控制台只负责配置与开关。

功能特性

• 多种代理模式：全局代理、PAC 代理、抓包代理，一键切换
• 内置代理客户端：托管上游代理进程生命周期；全局 / PAC 模式下由其直接提供本机 HTTP 代理并按规则分流，无需再经控制台转发
• PAC 规则：按域名/URL 规则匹配，选择「代理」「直连」或「拦截」，支持优先级、搜索、导入/导出
• 上游代理：支持 SOCKS5 / HTTP 上游；未启用内置客户端时，将 SOCKS5 转为 HTTP 代理并按规则转发
• 流量记录：查看经本机转发层的请求；启用内置客户端直接转发时，连接明细请使用抓包代理；抓包模式下可查看解密后的请求/响应、搜索与筛选
• 抓包代理：HTTPS 解密、自动生成 CA 证书供下载安装；与普通转发分离，仅在选择抓包时启用
• 本地 / 远程模式：本地模式配置仅存本机；远程模式需登录（登录状态持久保持至手动退出），PAC 规则可同步云端

环境要求

• Node.js >= 18
• 系统代理自动设置支持：macOS、Windows、Linux（GNOME 桌面或 Debian/Ubuntu 无界面服务器）

启动

npx pac-proxy-cli serve

默认在后台拉起控制台（不占用当前终端），并输出访问地址。开发调试时在前台运行：

npx pac-proxy-cli serve --foreground
# 或简写
npx pac-proxy-cli serve -f

不指定 --port 时默认使用 5174；若端口被占用会自动在 5174–5274 范围内选取可用端口。前台模式启动后会输出：

控制台已启动: http://127.0.0.1:5174

在浏览器中打开该地址即可使用。如需长期使用，可全局安装：

npm install -g pac-proxy-cli
pac-proxy serve
pac-proxy status
pac-proxy -h          # 完整命令与选项参考

本地开发（源码）

# 仓库根目录：透传任意 CLI 子命令
bun run dev:cli -h
bun run dev:cli show
bun run dev:cli serve -f

# 前台启动控制台（等价于 serve --port 5174 --foreground）
bun run dev:cli:serve

serve 常用参数

| 参数 | 说明 | |------|------| | -p, --port <number> | 控制台端口，默认 5174 | | -f, --foreground | 在前台运行（占用终端） | | --stop | 结束已在后台运行的控制台，并清除由其设置的系统代理（即使控制台已不在运行，也会尝试关闭残留的系统代理）。若已开启登录自启，会先暂停其保活（如 macOS KeepAlive），避免结束后立刻被拉回；登录自启配置本身不会关闭，下次登录仍会自动启动 | | --autostart enable | 启用登录时自动启动控制台，并在未运行时后台拉起 | | --autostart disable | 关闭登录时自启（不结束当前已运行的控制台；结束请用 --stop） |

查看运行状态：

pac-proxy status
pac-proxy status --json

登录时自启也可在 Web 代理设置 页开关，或使用 pac-proxy autostart --enable / --disable。关闭自启（无论 CLI 还是 Web）都不会结束当前已打开的控制台；需要结束时使用 pac-proxy serve --stop。结束控制台时会先暂停自启保活（避免 macOS 等平台立刻重新拉起），再请求其自行退出并清除系统代理；若只要停掉当前进程、下次登录仍自启，仅用 --stop 即可。

命令行配置

与 Web 控制台读写同一目录（默认 macOS/Linux 为 ~/.pac-proxy，Windows 为 %USERPROFILE%\.pac-proxy，可用环境变量 PAC_PROXY_HOME 覆盖）。根级 pac-proxy -h 或 pac-proxy help 可查看全部命令与选项；各子命令亦支持 -h。

命令一览

| 命令 | 说明 | |------|------| | pac-proxy serve -h | 启动/停止控制台 | | pac-proxy status -h | 查看运行状态 | | pac-proxy show | 打印当前本地配置 JSON（敏感字段脱敏） | | pac-proxy set -h | 写入运行模式、代理、Shadowsocks 等 | | pac-proxy rules -h | 管理 PAC 规则（list / add / edit / remove / export） | | pac-proxy proxy-mode -h | 查看或设置代理模式 | | pac-proxy import -h <file> | 合并导入 PAC 规则 | | pac-proxy autostart -h | 登录自启（print / enable / disable） | | pac-proxy sslocal -h | Shadowsocks 配置与启停 |

pac-proxy set 可写参数

| 参数 | 说明 | |------|------| | --mode <local\|remote> | PAC 规则存储位置 | | --proxy-enabled <bool> | 是否启用本地代理 | | --proxy-mode <mode> | direct、global、pac、mitm | | --upstream <url> | 上游代理地址 | | --http-port | 本地代理端口（HTTP 与 HTTPS 共用；--https-port 已弃用并忽略） | | --apply-system-proxy <bool> | 是否应用系统代理 | | --sslocal-enable / --sslocal-disable | 内置 Shadowsocks 开关 | | --sslocal-server 等 | Shadowsocks 服务器、端口、密码、加密、超时 | | --no-sync | 仅写盘，不同步到运行中的 serve |

示例

pac-proxy show
pac-proxy set --mode local --proxy-mode pac --upstream socks5://127.0.0.1:1080
pac-proxy proxy-mode pac
pac-proxy rules add --pattern "*.google.com" --action proxy --priority 10
pac-proxy rules list --json
pac-proxy import rules.json
pac-proxy sslocal --enable --server example.com --password secret
pac-proxy autostart enable

set、proxy-mode、sslocal、rules（add/edit/remove）与 import 在写盘后会尝试向运行中的 pac-proxy serve 同步（与 Web 保存一致，等待最长约 30 秒）；加 --no-sync 可跳过（仅 set / proxy-mode / sslocal 支持）。非默认控制台端口可设环境变量 PAC_PROXY_CONSOLE_PORT（未指定时扫描 5174–5274）。

无桌面 Linux 上启用代理后，新开 SSH/终端会自动加载环境变量；当前已打开的终端可执行：

source ~/.pac-proxy/proxy-env.sh

登录自启

开启后，在用户登录本机时自动在后台运行 pac-proxy serve，并按 config.json 中的代理设置恢复服务（与手动启动控制台相同）。也可在 Web「代理设置」页底部开关配置。

| 平台 | 实现方式 | 日志 | |------|----------|------| | macOS | 用户 LaunchAgent（~/Library/LaunchAgents/com.pac-proxy.serve.plist） | ~/.pac-proxy/logs/serve.log | | Windows | 当前用户「启动」注册表项 + 启动脚本（%USERPROFILE%\.pac-proxy\pac-proxy-console-start.vbs） | 同上 | | Linux | systemd 用户服务 pac-proxy.service | journalctl --user -u pac-proxy |

说明：

• 登录自启会固定为开启时的安装路径。非全局安装（如项目 node_modules、源码目录）在删除依赖或移动文件夹后可能失效；建议使用 npm install -g pac-proxy-cli 后再开启。升级或迁移安装位置后，请关闭并重新开启一次自启。
• Linux 需已安装并启用 systemd 用户会话；无图形登录也需自启时，可执行 loginctl enable-linger $USER（高级用法）。
• Windows 依赖当前用户启动项。若组织关闭了 Windows 脚本宿主，后台启动会改为隐藏的 Node 进程。快速启动/睡眠唤醒后若未自动拉起，请重新登录或手动执行 pac-proxy serve。
• 自启仅负责拉起控制台进程；是否自动设置系统代理仍由「代理设置」中的模式与开关决定。
• 登录自启命令带 --foreground，以便系统在控制台异常退出后能可靠拉起，而不是短命的后台包装进程。
• pac-proxy serve --stop 在结束进程前会暂停当前会话中的自启托管（macOS 卸下 LaunchAgent 保活、Linux 停止用户服务），否则 KeepAlive / Restart 会把控制台立刻拉回，表现为「--stop 不生效」。这不会关闭「登录自启」配置；彻底关闭请用 --autostart disable。
• 控制台日志（serve.log）超过约 10MB 时会轮转为 serve.log.old。

使用说明

1. 选择运行模式

首次访问会进入「选择运行模式」：

• 本地模式：无需登录，所有配置保存在本机（默认目录 macOS/Linux 为 ~/.pac-proxy，Windows 为 %USERPROFILE%\.pac-proxy）
• 远程模式：需注册/登录，登录成功后会话会持久保持，直至在控制台点击「退出登录」；仅分流规则与云端同步。代理端口、上游与客户端配置仍保存在本机。

选择后进入控制台。下次打开控制台会自动恢复上次模式；远程模式在未退出登录前无需再次输入账号密码。可在侧边栏底部「切换模式」中更改。

2. 代理设置

在 代理设置 页可进行：

| 操作 | 说明 | |------|------| | 全局代理 | 系统代理指向本机。macOS / Linux 在启用内置客户端时走 SOCKS5（避免浏览器 HTTP 代理把 GitHub 等多主机站点排队）；Windows 系统代理不支持 SOCKS5，始终走本机 HTTP 代理端口。未启用内置客户端时各平台均走本机 HTTP 代理 | | PAC 代理 | 系统使用自动代理配置（PAC），按规则决定代理或直连。可直接转发时 PAC 返回 SOCKS5（Windows 浏览器可识别；系统「手动代理」仍不使用 SOCKS） | | 抓包代理 | 流量经本机解密，可查看请求/响应内容；需安装 CA 证书；与普通转发分离，仅在选择抓包时启用 | | 清除代理 | 关闭系统代理并停止本地代理服务 |

• 上游代理地址：如 socks5://127.0.0.1:1080 或 http://proxy.example.com:8080
• 本机代理端口：HTTP 与 HTTPS 共用，默认 5175
• 同时修改本机系统代理：可关闭，改为自行在系统或浏览器中填写代理
• 若启用了内置代理客户端，上游代理地址会自动托管，无需手动填写
• 关闭控制台或点击「清除代理」时会去掉已设置的系统代理，避免指向已停止的端口

3. 代理客户端

在 代理客户端 页可配置并托管上游代理进程：

• 填写服务器地址、端口、密码、加密方式、超时、本地 SOCKS5 端口
• 启用后，控制台会自动启动代理进程。macOS / Linux 上全局 / PAC 模式下，浏览器可走 SOCKS5 直连该进程（同时保留本机 HTTP 端口供 curl 等使用）。Windows 全局模式使用本机 HTTP 端口，因为系统代理不支持 SOCKS5。
• 页面实时显示进程状态（运行中 / 已停止）、PID 及最近日志
• 可手动启动 / 停止进程

代理客户端二进制按平台按需安装（仅下载当前平台对应的 ~10MB 文件）：

| 平台 | 对应包 | |------|--------| | Windows x64 | pac-proxy-sslocal-win32-x64 | | macOS x64 / arm64 | pac-proxy-sslocal-darwin-x64 / pac-proxy-sslocal-darwin-arm64 | | Linux x64 / arm64 | pac-proxy-sslocal-linux-x64 / pac-proxy-sslocal-linux-arm64 |

也可单独安装对应平台包，在命令行直接使用 shadowsocks-libev sslocal（与包内二进制一致）：

# 示例：macOS Apple Silicon
npm install -g pac-proxy-sslocal-darwin-arm64

sslocal --help
cp config.example.json config.json   # 编辑 config.json 填入你的服务器信息（勿提交到 Git）
sslocal -c config.json

# 别名
pac-proxy-sslocal -c /path/to/config.json

各平台包名中的 darwin / linux / win32 与 x64 / arm64 需与本机一致；npm 会根据 os / cpu 字段跳过不匹配的平台包。

4. PAC 规则

在 PAC 规则 页管理「代理 / 直连」规则：

• 每条规则包含：匹配模式（如 *.google.com）、动作（代理 / 直连 / 拦截）、优先级
• 按优先级从高到低匹配，命中则按该条动作执行
• 域名、主机类规则在启用内置客户端时可直接由该进程分流；含路径的通配规则会回退为本机转发层
• 支持搜索、导入 JSON 文件（合并模式）、导出、复制规则列表
• 本地模式下规则保存在本机；远程模式下规则与云端同步

5. 流量记录

在 流量记录 页可查看经本机代理的请求：

• 非抓包模式：列表展示时间、类型、方法、URL、动作，最多保留 500 条；支持自动刷新与清空。若已启用内置客户端直接转发，则不记录每条连接，可改用抓包代理查看详情
• 抓包模式：支持按 URL 搜索、按方法/状态码/类型筛选、排序与分页、自动刷新与清空；点击行可查看请求/响应头与正文。音视频等大体积内容不保存正文

6. 抓包代理与 CA 证书

选择「抓包代理」并保存后：

1. 系统代理指向本机抓包代理端口
2. 首次产生 HTTPS 请求后，在数据目录下自动生成根 CA
3. 在代理设置页点击 下载 CA 证书，安装到系统或浏览器「受信任的根证书」
   • Windows：双击证书 → 当前用户 → 「受信任的根证书颁发机构」（不要放到「个人」）。Firefox 需在浏览器内单独导入。
   • macOS / Linux：按系统提示添加到受信任的根证书。
4. 安装后可在「流量记录」中查看解密后的请求/响应

CA 仅限本机抓包使用，请勿安装到他人设备或生产环境。

无论全局或 PAC 模式，本机回环（127.0.0.1 / localhost / ::1）、链路本地与 RFC1918 私网（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）以及 *.local 均强制直连，不会进入上游代理。

系统代理支持

| 平台 | 说明 | |------|------| | macOS | 通过 networksetup 设置；自动写入绕过列表（localhost、回环、RFC1918 私网、*.local）。遇权限问题可手动在「系统设置 → 网络 → 代理」中配置 | | Windows | 写入当前用户 Internet 设置（关闭自动检测；绕过 localhost / 回环 / 私网 / <local>），并同步当前用户的 HTTP_PROXY / HTTPS_PROXY 与 NO_PROXY 供命令行工具使用。全局模式使用本机 HTTP 代理（系统不支持 SOCKS5）。失败时可手动在「设置 → 网络和 Internet → 代理」中配置。若内置客户端被安全软件拦截，请在安全软件中允许 sslocal.exe。微软商店应用默认不能访问本机代理。 | | Linux | 有 GNOME 桌面时使用 gsettings（含 ignore-hosts 私网绕过）；无桌面 Debian/Ubuntu 等自动写入 ~/.pac-proxy/proxy-env.sh（含完整 NO_PROXY）并注入 ~/.profile、~/.bashrc，同时配置 wget/curl。若已配置 sudo 免密，会尝试写入 /etc/apt/apt.conf.d/99pac-proxy-cli |

环境变量

| 变量 | 说明 | |------|------| | PAC_PROXY_HOME | 数据与配置根目录，默认 macOS/Linux 为 ~/.pac-proxy，Windows 为 %USERPROFILE%\.pac-proxy | | PAC_PROXY_CONSOLE_PORT | 指定控制台探测/同步端口（未指定时扫描 5174–5274） |

许可证

MIT