Privoxy 4.2.0 常用 CLI 命令与工具详解

Privoxy 4.2.0 常用 CLI 命令与工具详解：主命令 8 个旗标逐项实测、systemd 服务管理与 journalctl 排障、log-parser 与 regression-test 辅助工具，--help 全文照抄。

PrivoxyPrivoxyHTTP 代理网络配置安全2026/10/20

Privoxy 4.2.0 常用 CLI 命令与工具详解

目标：整理 Privoxy 4.2.0 的完整命令行操作面——主命令 privoxy 的全部启动旗标、systemd 服务管理命令、journalctl 与日志排障手法、两个官方辅助工具（privoxy-log-parser、privoxy-regression-test）的用法。全部命令与回显在 Ubuntu 22.04.4 LTS（x86_64）的 4.2.0 实装环境实测采集，实测日期 2026-10-20。

一、环境信息

  • 操作系统：Ubuntu 22.04.4 LTS（Jammy），架构 x86_64
  • Privoxy 版本：4.2.0 stable（源码编译安装，--with-openssl 编译，privoxy --version 实测 Privoxy version 4.2.0 (https://www.privoxy.org/)）
  • 主程序路径：/usr/local/sbin/privoxy（apt 安装为 /usr/sbin/privoxy，旗标一致；辅助工具 apt 安装在 /usr/bin/，源码安装在 /usr/local/bin/）
  • 服务管理：systemd 单元 /etc/systemd/system/privoxy.service（实测生效版本），Type=forking
  • 监听：127.0.0.1:8118（实测 ss -ltn 可见 LISTEN）
  • 执行身份：全文以 root 执行（普通用户请自行在命令前加 sudo）

二、工具概览

Privoxy 4.2.0 的命令行操作面由三部分组成：

组成内容用途
主命令 privoxy8 个启动旗标：--config-test、--chroot、--help、--no-daemon、--pidfile、--pre-chroot-nslookup、--user、--version配置校验、降权运行、前台调试
服务管理命令systemctl 的 start/stop/restart/status/is-active/is-enabled、journalctl日常启停与排障（生产推荐方式）
官方辅助工具privoxy-log-parser 0.9.8（日志解析/高亮）、privoxy-regression-test 0.7.6（规则回归测试）日志分析、规则验证

解读：Privoxy 没有子命令式 CLI，主命令只负责「按配置启动一次」；日常运维围绕 systemd 展开，两个辅助工具分别补日志与测试两块。

三、前置条件

  • 已按《Ubuntu 22.04 安装 Privoxy 指南》完成安装，privoxy --version 可正常执行
  • 方案 A（apt）用户注意路径差异：主程序 /usr/sbin/privoxy、配置 /etc/privoxy/config；本文回显来自方案 B（源码）环境，路径为 /usr/local 前缀，旗标用法完全一致
  • journalctl 排障需要 root 权限

四、主命令 privoxy 详解

4.1 --help：查看用法

privoxy --help

实测回显（全文照抄——Usage 行就是全部旗标清单；无配置参数时打印用法后退出，末行 Aborting 属正常输出而非报错）：

Privoxy version 4.2.0 (https://www.privoxy.org/)
Usage: /usr/local/sbin/privoxy [--config-test] [--chroot] [--help] [--no-daemon] [--pidfile pidfile] [--pre-chroot-nslookup hostname] [--user user[.group]] [--version] [configfile]
Aborting

4.2 --version：查看版本

privoxy --version

实测回显：

Privoxy version 4.2.0 (https://www.privoxy.org/)

4.3 --config-test：配置语法校验

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

合法配置时静默退出、退出码 0（实测回显）：

exit: 0

向 config 追加一行不存在的指令后再测（实测回显，注意退出码仍是 0）：

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 行、规则被忽略（见《Privoxy 4.2.0 配置参数详解》5.5 节实测）。

4.4 --no-daemon：前台运行（调试用）

privoxy --no-daemon /usr/local/etc/privoxy/config

实测启动输出（输出节选，实测启动段；进程驻留前台，Ctrl-C 结束）：

2026-10-20 10:13:43.940 759eaae40380 Info: Privoxy version 4.2.0
2026-10-20 10:13:43.940 759eaae40380 Info: Program name: /usr/local/sbin/privoxy

排障时配合 strace 观察文件打开行为非常有效（定位日志目录权限问题的实录见《Ubuntu 22.04 安装 Privoxy 指南》5.7 节：strace -f -e trace=setuid,setgroups,openat,unlink privoxy --no-daemon --user privoxy <config>）。

4.5 --pidfile 与 --user：守护运行的标准组合

生产启动形态（降权 + 指定 pidfile + 配置文件），实测启动后 ss -ltnp 与 ps 回显：

privoxy --pidfile /run/privoxy-test.pid --user privoxy /usr/local/etc/privoxy/config
ss -ltnp | grep 8118

实测回显：

LISTEN 0      128        127.0.0.1:8118      0.0.0.0:*    users:(("privoxy",pid=9359,fd=4))

9359 /usr/local/sbin/privoxy --pidfile /run/privoxy-test.pid --user privoxy /usr/local/etc/privoxy/config
  • --pidfile pidfile：把守护进程 PID 写入指定文件，systemd 单元靠它管理进程（单元里 PIDFile=/run/privoxy.pid）。
  • --user user[.group]：完成配置/日志文件打开后降权到指定用户运行（实测 strace 可见 setuid(105) 先于配置打开，因此 privoxy 用户必须读得了 config、写得了 logdir，否则启动失败，三连坑实录见安装指南 5.7 节）。

4.6 --chroot 与 --pre-chroot-nslookup

--chroot 切换根目录后运行、--pre-chroot-nslookup hostname 在切根前完成域名解析（解析依赖 /etc/resolv.conf，切根后不可读）。这两项涉及 chroot 环境整套文件布局（confdir/logdir 等都要落在新根内），本文环境未实测，参数语义以 --help Usage 行与官方手册为准；一般部署用 --user 降权已足够，不建议叠加 chroot 复杂度。

五、服务管理命令（systemd）

生产环境一律经 systemd 管理，直接手工 privoxy 起的进程不受单元约束。

5.1 日常启停与状态

systemctl start privoxy
systemctl stop privoxy
systemctl restart privoxy
systemctl status privoxy --no-pager
systemctl is-active privoxy
systemctl is-enabled privoxy

启动后实测回显（systemctl status 节选）：

● privoxy.service - Privoxy 4.2.0 Privacy enhancing HTTP Proxy
     Loaded: loaded (/etc/systemd/system/privoxy.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-20 10:19:06 UTC; 8ms ago
       Docs: man:privoxy(8)
             https://www.privoxy.org/user-manual/
    Process: 9436 ExecStart=/usr/local/sbin/privoxy --pidfile $PIDFILE --user $OWNER $CONFIGFILE (code=exited, status=0/SUCCESS)
   Main PID: 9437 (privoxy)
      Tasks: 1 (limit: 5753)
     Memory: 1.9M

is-active/is-enabled 实测分别回显 active、enabled。

5.2 修改配置后的正确生效方式

systemctl restart privoxy

restart 会完整重新加载 config/actions/filter（实测重启后新增的 +block 拦截与 +filter 内容改写规则立即生效，验证回显见《Privoxy 4.2.0 配置参数详解》六、七章）。

⚠️ 注意：不要用 kill -HUP 让 Privoxy 热重载。实测修改过滤器后向运行中进程发 HUP，journalctl 记录段错误（见 5.4 节回显）；受控复现还出现请求返回空响应体、再次 HUP 后服务 failed。规则加载一律 restart。

5.3 停用与取消自启

systemctl stop privoxy
systemctl disable privoxy

实测回显（disable 会同步移除 multi-user.target.wants 软链）：

Synchronizing state of privoxy.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install disable privoxy
Removed /etc/systemd/system/multi-user.target.wants/privoxy.service.

5.4 journalctl 与日志文件排障

服务崩溃/异常退出查 journal（实测实录——HUP 触发 SEGV 的记录）：

journalctl -u privoxy --no-pager | tail -5

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

Oct 20 10:19:05 systemd[1]: Starting Privoxy 4.2.0 Privacy enhancing HTTP Proxy...
Oct 20 10:19:06 systemd[1]: Started Privoxy 4.2.0 Privacy enhancing HTTP Proxy.
Oct 20 10:19:58 systemd[1]: privoxy.service: Main process exited, code=dumped, status=11/SEGV
Oct 20 10:19:58 systemd[1]: privoxy.service: Failed with result 'core-dump'.
Oct 20 10:20:29 systemd[1]: Starting Privoxy 4.2.0 Privacy enhancing HTTP Proxy...

请求级日志看 logfile（logdir/logfile 指定的文件，实测 /var/log/privoxy/logfile）。开启 debug 1 后每请求一行（实测回显）：

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

行内依次为毫秒时间戳、12 位线程标识、内容；线程标识用于串联同一请求的多条日志。

六、辅助工具详解

6.1 privoxy-log-parser：日志解析与高亮

官方日志分析器（本环境实测版本 0.9.8），读取（管道输入的）Privoxy 日志流，做语法高亮、压缩线程标识等渲染。

privoxy-log-parser --help

实测回显（全文照抄）：

Privoxy-Log-Parser 0.9.8
https://www.fabiankeil.de/sourcecode/privoxy-log-parser/

Options and their default values if they have any:
    [--detect-innactivity]
    [--inactivity-threshold 100]
    [--host-statistics-threshold 0]
    [--html-output]
    [--no-embedded-css]
    [--no-msecs]
    [--no-syntax-highlighting]
    [--shorten-thread-ids]

参数速读：--html-output 输出 HTML 页（配合 --no-embedded-css 可外挂样式）；--no-msecs 不显示毫秒；--no-syntax-highlighting 关闭高亮输出纯文本；--shorten-thread-ids 压缩长线程标识；--detect-innactivity 配合 --inactivity-threshold（默认 100）探测日志流空闲。传入不存在的选项会明确拒绝（实测误传 -c 回显）：

Unknown option: c

典型用法：tail -f /var/log/privoxy/logfile | privoxy-log-parser 实时高亮跟踪日志流。

6.2 privoxy-regression-test：规则回归测试

官方回归测试器（本环境实测版本 0.7.6），基于 regression-tests.action 中定义的「请求/期望」用例对规则集做批量回归，也支持对代理实例做探测。

privoxy-regression-test --help

实测回显（全文照抄）：

Privoxy-Regression-Test 0.7.6

Options and their default values if they have any:
    [--check-bad-ssl]
    [--curl curl]
    [--debug 35]
    [--forks 0]
    [--fuzzer-address]
    [--fuzzer-feeding]
    [--help]
    [--header-fuzzing]
    [--level]
    [--local-test-file]
    [--loops 1]

参数速读：--curl 指定 curl 路径（默认 curl）；--forks 并发进程数（默认 0 单进程）；--debug 调试等级（默认 35）；--loops 每用例重复次数（默认 1）；--local-test-file 指定本地测试文件；--fuzzer-address/--fuzzer-feeding/--header-fuzzing 用于模糊测试场景；--check-bad-ssl 针对坏证书站点做检查。deb 包自带用例集 /etc/privoxy/regression-tests.action（源码安装在 /usr/local/etc/privoxy/，实测两处均有该文件）。

七、注意事项

  • 退出码不可迷信：--config-test 无论发现未知指令与否都退出 0，审查输出才是可靠手段（4.3 节实测）。
  • --help 的 Aborting 不是错误：Usage 打印后正常退出（4.1 节全文回显）。
  • 改配置只走 restart：HUP 实测 SEGV（5.2/5.4 节），前台 --no-daemon 仅用于调试。
  • --user 降权有文件权限前提：privoxy 用户需可读配置、可写日志目录，否则静默退出或误导性报错（排障实录见《Ubuntu 22.04 安装 Privoxy 指南》5.7 与 8.2/8.3 节）。
  • 版本差异看 --help：主命令旗标集合以 privoxy --help 的 Usage 行为准（4.1 节），跨版本升级后先核对 Usage 再沿用旧启动参数。

八、常见问题（FAQ）

Q1：systemctl start 后 is-active 显示 failed，去哪找原因？ 答：先 journalctl -u privoxy --no-pager | tail -20 看 systemd 记录（崩溃会显示 code=dumped/SEGV 或 exit status），再查 /var/log/privoxy/logfile 与启动日志；权限类静默退出用 --no-daemon + strace 前台复现（4.4 节与安装指南 5.7 节实录）。

Q2：--config-test 通过但规则就是不生效？ 答：test 的「通过」不代表指令都被接受（9.1 陷阱见 4.3 节实测），逐条核对启动日志 Error 行；转发规则尤其注意参数个数（forward 2 参数、forward-socks5 3 参数）。

Q3：手工 privoxy 起的进程和 systemd 起的有什么区别？ 答：手工启动不受单元的 PIDFile/降权/退出码约定管理，systemd 无法正确 stop/status。生产一律 systemctl；手工方式仅限 --no-daemon 调试。

九、参考链接