Privoxy 4.2.0 配置参数详解

目标：讲清 Privoxy 4.2.0 的配置体系——主配置 config 的全部生效指令、actions 动作系统与 filter 内容过滤器三层结构的用法与实战，全部参数默认值与行号取自实测安装的 4.2.0（Ubuntu 22.04.4 LTS，x86_64），拦截、过滤、转发等示例均带真实回显，查询/实测日期 2026-10-20。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（Jammy），架构 x86_64
• Privoxy 版本：4.2.0 stable（源码编译安装，privoxy --version 实测回显 Privoxy version 4.2.0 (https://www.privoxy.org/)，编译期 --with-openssl 启用 https inspection）
• 主配置：/usr/local/etc/privoxy/config（源码安装默认布局；apt 安装为 /etc/privoxy/config，指令体系相同，路径前缀换成 /etc/privoxy）
• 配置文件规模：config 共约 2900 行，其中实际生效的非注释指令 25 行（实测 grep 导出，见第四章总览）
• 监听：127.0.0.1:8118（实测 ss -ltn 可见 LISTEN）
• 服务管理：systemd（systemctl restart privoxy 生效配置）
• 实测日期：2026-10-20

二、前置条件

• 已按《Ubuntu 22.04 安装 Privoxy 指南》完成安装且服务运行中（systemctl is-active privoxy 回显 active）
• 能修改配置文件（root 权限）并重启服务
• 验证工具：curl（走代理发请求）、ss（查端口）；内容过滤示例需要一个本地测试页（第七章给出搭建方法）

三、配置查看与修改方式

Privoxy 的配置全部是纯文本文件，查看与修改方法如下。

查看实际生效的指令：config 里绝大多数内容是注释文档，真正的生效指令可以用 grep 一条命令列出（实测命令与回显）：

grep -nE '^[a-z][a-z-]+[ ]' /usr/local/etc/privoxy/config

实测回显（4.2.0 全部 25 行生效指令，含行号）：

130:user-manual /usr/local/share/doc/privoxy/user-manual/
262:confdir /usr/local/etc/privoxy
347:logdir /var/log/privoxy
385:actionsfile match-all.action # Actions that are applied to all sites and maybe overruled later on.
386:actionsfile default.action   # Main actions file
387:actionsfile user.action      # User customizations
432:filterfile default.filter
433:filterfile user.filter      # User customizations
481:logfile logfile
794:listen-address  127.0.0.1:8118
822:toggle  1
864:enable-remote-toggle  0
902:enable-remote-http-toggle  0
942:enable-edit-actions 0
990:enforce-blocks 0
1138:buffer-limit 4096
1179:enable-proxy-authentication-forwarding 0
1530:forwarded-connect-retries  0
1579:accept-intercepted-requests 0
1616:allow-cgi-request-crunching 0
1658:split-large-forms 0
1714:keep-alive-timeout 5
1757:tolerate-pipelining 1
1919:socket-timeout 300
2692:elliptic-curve-keys 1

修改后校验：改完先做语法校验再重启（合法配置时校验命令静默、退出码 0，实测回显 exit: 0）：

privoxy --config-test /usr/local/etc/privoxy/config
echo exit: $?

修改后生效：一律用 restart（实测 restart 加载新规则正常；kill -HUP 热重载实测会触发 SEGV 崩溃，排障实录见《Ubuntu 22.04 安装 Privoxy 指南》8.4 节）：

systemctl restart privoxy

运行时核对：经代理访问 http://config.privoxy.org/show-status 可查看当前加载的配置文件与动作明细（实测页面标题 Privoxy@localhost: Proxy Status）。

四、参数总览

按功能把 4.2.0 的 25 条生效指令分为七类（行号/默认值均为实测）：

解读：默认配置是「最小安全集」——只听回环、开着官方规则库的过滤、网页编辑与远程开关全关。需要改的通常只有 listen-address、转发和自定义 actions/filter 加载三类。

五、核心参数分类详解

5.1 目录与文件类

• confdir /usr/local/etc/privoxy（262 行）：配置文件根目录，actions/filter/templates 都从这里找。
• logdir /var/log/privoxy（347 行）：日志目录。⚠️ 源码安装的坑：make install 只建 /usr/local/var/log/privoxy，并不会创建这里写的 /var/log/privoxy，需手工 mkdir -p /var/log/privoxy && chown -R privoxy:privoxy /var/log/privoxy，否则服务启动即静默退出（strace 排障实录见安装指南 5.7 节）。
• logfile logfile（481 行）：日志文件名，实际路径 = logdir/logfile，实测为 /var/log/privoxy/logfile。
• user-manual /usr/local/share/doc/privoxy/user-manual/（130 行）：内置手册路径，CGI 页面的手册链接指向此处。

5.2 规则加载类

• actionsfile（385-387 行）：按 match-all.action → default.action → user.action 顺序加载动作文件，后加载的可覆盖先加载的；match-all 打底、default 是官方广告拦截规则库（约 136 KB，实测文件大小 135724 字节）、user.action 留给用户定制。
• filterfile（432-433 行）：加载 default.filter（官方过滤器集）与 user.filter（用户自定义），加载顺序同理。

💡 说明：升级时只动 default.* 文件，用户定制全放 user.*，既不丢配置也不冲突。

5.3 监听与超时类

• listen-address（794 行）：默认 127.0.0.1:8118 仅听回环。给局域网用可改成内网 IP（如 192.168.1.10:8118，绑定内网地址即天然与公网隔离）。改完 ss -ltn | grep 8118 验证。
• keep-alive-timeout 5（1714 行）：客户端空闲连接保活秒数，超时关闭。
• socket-timeout 300（1919 行）：套接字读写超时秒数。
• tolerate-pipelining 1（1757 行）：容忍客户端流水线请求（4.2.0 默认开启）。
• buffer-limit 4096（1138 行）：单请求缓冲上限（KB），内容过滤大页面时相关。
• forwarded-connect-retries 0（1530 行）：上游连接失败重试次数，默认不重试。

5.4 功能开关类（均为 0/1 型）

5.5 转发类（forward 家族）

默认无生效行。常用指令：forward（HTTP 父代理）、forward-socks5（SOCKS5 上游）等，语法均为「URL 模式 + 上游地址」，实测要点：

语法陷阱：forward 只接受 2 个参数。写成三个参数（模式 + 父代理 + 直接标记 .——这是 socks 系指令的写法）会报错（实测启动日志）：

2026-10-20 10:22:20.055 7e274dc74380 Error: Wrong number of parameters for forward directive in configuration file.

且出错规则被忽略、其余配置照常加载——之后请求会直连目标并返回 200，极易误判为「转发生效」（实测 via bogus parent -> 200，实际没走父代理）。

正确写法与实测效果：

# 错误：forward / 127.0.0.1:9999 .      ← 3 参数，规则被忽略
# 正确：forward / 127.0.0.1:9999        ← 2 参数：URL模式 + 父代理

配置不可达父代理后（重启服务生效），实测请求返回 503 与标题 <title>503 - Connect failed (Privoxy@localhost)</title>，证明请求确实经过父代理路由。配置真实内网 Squid 父代理（实测 10.0.0.1:3128）后返回 403——请求已真实转发给父代理并由其 ACL 拦截。撤销转发规则重启后恢复 200。

forward-socks5：forward-socks5 / 127.0.0.1:1080 .（socks 系才是 3 参数：模式 + socks 上游 + HTTP 父代理，. 表示直达）。上游不可达时实测返回 503 与 <title>503 - Forwarding failure (Privoxy@localhost)</title>。

5.6 HTTPS 检查类（4.x 新增）

https inspection 需编译期启用（--with-openssl，实测 configure 输出 Detected OpenSSL-compatible library. Enabling https inspection.；--with-mbedtls 在 Ubuntu 22.04 因系统 mbed TLS 2.28 过旧编译失败）。运行期相关指令在 4.2.0 config 中默认全部处于注释状态，例如 2486 行注释示例 ca-directory /usr/local/etc/privoxy/CA（CA 证书目录）、2237 行说明受 https-inspection 影响的指令范围、2317 行 client-specific-tag 与 https inspection 的联动示例。开启 HTTPS 检查需按注释指引生成 CA、配置 ca-directory/ca-cert-file 等指令并向客户端分发信任，属进阶部署。

六、动作系统（actions）详解

6.1 三级 action 文件与覆盖顺序

动作决定「对某个请求做什么」。三级文件按 match-all.action（全局打底）→ default.action（官方规则库）→ user.action（用户定制）顺序加载，URL 逐个匹配规则、动作集逐步叠加，后加载的设置覆盖先加载的。用户所有定制写 user.action，不改官方文件。

6.2 常用动作

6.3 实战：添加一条拦截规则并验证

在 /usr/local/etc/privoxy/user.action 末尾追加：

{ +block{test-block} }
blocked.example.com

重启生效并请求被拦截域名：

systemctl restart privoxy
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' -x http://127.0.0.1:8118 http://blocked.example.com/
curl -sS -x http://127.0.0.1:8118 http://blocked.example.com/ | grep '<title>'

实测回显：

HTTP 403
<title>Request blocked (Privoxy@localhost)</title>

6.4 用 show-url-info 核对动作命中

curl -sS -x http://127.0.0.1:8118 'http://config.privoxy.org/show-url-info?url=blocked.example.com' | grep -A3 'Final results'

实测回显（输出节选，实测关键段）：

        <h2>Final results:</h2>
        <b>
<br>+<a href="http://config.privoxy.org/user-manual/actions-file.html#BLOCK">block</a>{test-block}

+block{test-block} 出现在 Final results 即规则已命中。对放行域名（如 www.baidu.com）同样可查，实测返回其 Matches for 与 Final results 小节。

七、内容过滤器（filter）详解

7.1 filter 语法与 user.filter 写法

过滤器定义在 filterfile 指定的文件里：FILTER: 名称 起头，其下每行是一条 pcrs（Perl 兼容正则）替换规则，运行时对响应体流式逐条应用。在 /usr/local/etc/privoxy/user.filter 末尾追加两个实测用的过滤器：

FILTER: replace-old
s/OLDWORD/NEWWORD/g

FILTER: drop-ad
s|<p>ADSPOT banner</p>||g

• replace-old：把页面里的 OLDWORD 全部替换为 NEWWORD
• drop-ad：删除 <p>ADSPOT banner</p> 整个片段（分隔符用 |，避免与标签里的 / 冲突）

7.2 实战：内容替换与片段删除

准备本地测试页（端口 8009 空闲时）：

mkdir -p /var/tmp/privoxy-test && cd /var/tmp/privoxy-test
printf '<html><body><h1>OLDWORD hello</h1><p>ADSPOT banner</p></body></html>' > test.html
python3 -m http.server 8009 &

在 user.action 末尾追加（对发往 127.0.0.1 的请求启用两个过滤器，实测可匹配 8009 端口请求）：

{ +filter{replace-old} +filter{drop-ad} }
127.0.0.1

重启并拉取（经代理访问测试页）：

systemctl restart privoxy
systemctl is-active privoxy
curl -sS -x http://127.0.0.1:8118 http://127.0.0.1:8009/test.html

实测回显：

active
<html><body><h1>NEWWORD hello</h1></body></html>

对比基线（未启用过滤器时拉取同页，实测回显）：

<html><body><h1>OLDWORD hello</h1><p>ADSPOT banner</p></body></html>

OLDWORD 已被替换为 NEWWORD，<p>ADSPOT banner</p> 片段被整体删除——两个过滤器一次 restart 同时生效。

7.3 生效方式与撤销

撤销验证：删除/注释上述 user.action 与 user.filter 追加内容后再次 restart，实测回显 active，页面复原为基线内容（与上方基线一致）。切记改 filter/action 后走 systemctl restart privoxy，不要用 kill -HUP（实测 HUP 会段错误崩溃，实录见安装指南 8.4 节）。

八、生产配置模板

以下模板均在实测 4.2.0 上核验过指令语法，按场景直接取用。Privoxy 资源占用极低（实测 systemd status 显示 Memory: 1.9M），1GB 内存/普通磁盘即可，无需按大内存规格调参。

模板一：桌面/本机过滤（最小改动）——默认配置直接用，只按需加自定义规则：

listen-address  127.0.0.1:8118
toggle  1
logfile logfile

模板二：局域网网关（内网设备共用）——绑定内网网卡地址，物理上不暴露公网：

listen-address  192.168.1.10:8118
toggle  1
logfile logfile
enable-remote-toggle  0
enable-edit-actions 0

模板三：带上游链路（过滤后转父代理/SOCKS5）：

forward / 10.0.0.1:3128
# 或走 SOCKS5 上游：
# forward-socks5 / 10.0.0.1:1080 .

每份模板的共同要点：自定义规则只进 user.action/user.filter；改完先 privoxy --config-test 校验再 systemctl restart privoxy；ss -ltn | grep 8118 与 curl -x http://127.0.0.1:8118 http://www.baidu.com/（实测回显 HTTP 200）做最终验证。

九、常见问题（FAQ）

9.1 --config-test 返回 0，但配置明明写错了

实测：向 config 追加一行不存在的指令后校验（回显照抄）：

2026-10-20 10:23:06.291 7dffb5081380 Error: Ignoring unrecognized directive 'this-is-not-a-valid-directive 123' (2964355450U) in line 2891 in configuration file (/usr/local/etc/privoxy/config).
exit: 0

结论：config-test 对未知指令只「忽略 + 打 Error 日志」、退出码仍为 0，不能只看退出码，必须看输出。同类问题也出现在 forward 参数写错时（Error 后规则被忽略，请求直连返回 200 造成误判，见 5.5 节）。

9.2 网页编辑器打不开，提示 Actions file not found

enable-edit-actions 默认 0，CGI 编辑功能关闭，实测访问编辑页返回 <title>Privoxy: Actions file not found</title>。这是安全默认值，生产环境建议保持关闭，规则用文件方式管理。

9.3 日志里看不到每个请求访问了哪里

默认日志不记请求目标。在 config 中开启 debug 1（取消第 571 行附近该注释行的行首 #）并 restart 后，实测日志行：

2026-10-20 10:24:17.831 7ad09bf2a640 Request: www.baidu.com/

行首 12 位十六进制是处理线程标识，可用来串联同一请求的多条日志。debug 等级调整属排障手段，长期开启会放大日志量。

9.4 改了规则却不生效

三步排查：① 确认规则写进了 user.action/user.filter（不是 default.*，也不要加错文件）；② 确认执行过 systemctl restart privoxy（HUP 不可靠）；③ 用 show-url-info 查目标 URL 的 Final results 是否出现预期动作（方法见 6.4 节）。若 forward 类规则不生效，回看启动日志有没有 Wrong number of parameters 的 Error 行（5.5 节语法陷阱）。

十、参考链接

• Privoxy 官网：https://www.privoxy.org/
• 官方用户手册（actions/filter 完整语法）：https://www.privoxy.org/user-manual/
• 官方 FAQ：https://www.privoxy.org/faq/
• 站内系列：《Privoxy 4.2.0 介绍与选型指南》（定位与选型）、《Ubuntu 22.04 安装 Privoxy 指南》（安装与排障实录）、《Privoxy 4.2.0 常用 CLI 命令与工具详解》（命令行参数与辅助工具）