Tinyproxy 常用 CLI 命令与验证方法详解

Tinyproxy 常用 CLI 命令与验证方法详解：tinyproxy -v/-h/-d/-c 四选项、systemd 服务管理、日志与端口诊断，及 curl 实测代理行为主线（普通代理、CONNECT 隧道、Basic 认证、Via/X-Tinyproxy 头、上游链式与故障态 500/404 区分），回显全部实测。

TinyproxyTinyproxyHTTP 代理Linux2026/10/22

Tinyproxy 常用 CLI 命令与验证方法详解

目标：以「命令 + 实测回显」的方式梳理 Tinyproxy 的日常命令面——tinyproxy 自身的四个命令行选项、systemd 服务管理、日志与端口诊断，以及以 curl 为主线验证代理行为（普通正向代理、CONNECT 隧道、Basic 认证、Via/X-Tinyproxy 头、上游链式转发）的完整实操手册，全部命令与回显已在 Ubuntu 22.04.5 LTS（x86_64）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Tinyproxy：1.11.0-1（apt 安装，/usr/bin/tinyproxy）
  • 代理服务器：10.89.65.10（主机名 proxy1.example.local，服务监听 0.0.0.0:8888）
  • 客户端/靶机：10.89.65.11（主机名 node2.example.local，同内网 10.89.65.0/24）
  • 配置文件：/etc/tinyproxy/tinyproxy.conf；日志：/var/log/tinyproxy/tinyproxy.log
  • 客户端工具：curl 7.81.0（Ubuntu 22.04 自带版本）

二、工具概览

工具/命令用途典型场景
tinyproxy -v查看版本装完先确认版本
tinyproxy -h查看用法与编译特性确认 XTinyproxy/Upstream 等特性是否编入
tinyproxy -d [-c FILE]前台运行配置排障（直接看报错）、临时多实例
systemctl start/stop/restart ...服务生命周期改配置后重启、启停服务
systemctl status/is-active/is-enabled/cat服务状态核查巡检、看主 PID 与最近日志
journalctl -u tinyproxy读 journald 日志文件日志不可用时的兜底
tail/grep /var/log/tinyproxy/tinyproxy.log读文件日志看连接、拒绝、过滤事件
ss -ltnp端口与进程核对确认监听、排查端口占用
curl -x/-U/--proxytunnel代理行为验证功能与链路验收

💡 说明：Tinyproxy 没有类似 nginx -t 的配置检查选项，-h/-v/-d/-c 是全部命令行选项；配置正确性验证依赖「前台 -d 试跑」与 systemctl 启动结果。

三、前置条件

  • 已完成安装并托管（见《Ubuntu 22.04 安装 Tinyproxy 指南》），systemctl is-active tinyproxy 为 active；
  • 代理已放行客户端来源（Allow 配置），本机验证用 127.0.0.1（默认放行）；
  • 客户端已安装 curl（apt-get install -y curl）。

四、tinyproxy 自身命令行选项详解

4.1 -h：用法与编译特性

tinyproxy -h

实测输出：

Usage: tinyproxy [options]

Options are:
  -d        Do not daemonize (run in foreground).
  -c FILE   Use an alternate configuration file.
  -h        Display this usage information.
  -v        Display version information.

Features compiled in:
    XTinyproxy header
    Filtering
    Transparent proxy support
    Reverse proxy support
    Upstream proxy support

For support and bug reporting instructions, please visit
<https://tinyproxy.github.io/>.

Features compiled in 一栏很关键：发行版包把 XTinyproxy、过滤、透明代理、反向代理、上游转发五大特性全部编入，配置文件里对应指令都能用。

4.2 -v：版本信息

tinyproxy -v

实测输出：

tinyproxy 1.11.0

注意选项是短格式 -v（写 --version 会报 tinyproxy: invalid option -- '-' 并打印同样用法，如下为实测）：

tinyproxy: invalid option -- '-'
Usage: tinyproxy [options]

4.3 -d：前台运行（排障利器）

-d 不守护化、日志直接打到终端。配置排障时先停服务再前台试跑，错误一目了然。实测一：配置语法错误时：

systemctl stop tinyproxy
/usr/bin/tinyproxy -d

实测输出（Timeout 行写成非法值时）：

ERROR: Syntax error on line 49

实测二：端口被占用时（8888 已被服务实例监听，再前台启动一个）：

/usr/bin/tinyproxy: Could not create listening sockets.

实测三：源码版在 Ubuntu 上使用上游默认配置时的身份报错：

/usr/local/bin/tinyproxy: Unable to find group "nobody".

排障完毕 Ctrl+C 退出前台进程，再用 systemd 正常托管。

4.4 -c：指定配置文件（多实例）

Tinyproxy 支持「一台机器多个实例」：复制主配置、改端口，用 -c 指定启动。实测（副本配置 Port 18128）：

cp /etc/tinyproxy/tinyproxy.conf /root/d1-instance.conf
sed -i "s/^Port 8888/Port 18128/" /root/d1-instance.conf
/usr/bin/tinyproxy -d -c /root/d1-instance.conf &

ss -ltn | grep 18128

实测输出：

LISTEN 0      1024         0.0.0.0:18128      0.0.0.0:*

curl -s -m 8 -x http://127.0.0.1:18128 -o /dev/null -w "second-instance:%{http_code}\n" http://example.com

实测输出：

second-instance:200

临时实例用 kill %1（或 pkill -f d1-instance）结束；长期多实例建议为每个实例各写一个 systemd unit（写法见安装指南 5.5 节的自建 unit 模板）。注意同一配置下 LogFile/PidFile 路径必须错开，否则两实例争抢同一文件。

五、systemd 服务管理命令

apt 包自带 tinyproxy.service（Type=forking，PID 文件 /run/tinyproxy/tinyproxy.pid）。先看 unit 全貌：

systemctl cat tinyproxy

实测输出：

# /lib/systemd/system/tinyproxy.service
[Unit]
Description=Tinyproxy lightweight HTTP Proxy
After=network.target
Documentation=man:tinyproxy(8) man:tinyproxy.conf(5)

[Service]
EnvironmentFile=-/etc/default/tinyproxy
Type=forking
ExecStart=/usr/bin/tinyproxy $FLAGS
PIDFile=/run/tinyproxy/tinyproxy.pid
PrivateDevices=yes
KillMode=process
KillSignal=SIGTERM
TimeoutStopSec=20

[Install]
WantedBy=multi-user.target

日常管理命令与实测回显：

systemctl is-enabled tinyproxy

enabled

systemctl is-active tinyproxy

active

systemctl restart tinyproxy

（成功时无输出；失败时输出 Job for tinyproxy.service failed ...，用 journalctl -u tinyproxy 看原因。）

systemctl status tinyproxy --no-pager -l | head -8

实测输出：

● tinyproxy.service - Tinyproxy lightweight HTTP Proxy
     Loaded: loaded (/lib/systemd/system/tinyproxy.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 11:12:48 UTC; 1min 14s ago
       Docs: man:tinyproxy(8)
             man:tinyproxy.conf(5)
    Process: 5881 ExecStart=/usr/bin/tinyproxy $FLAGS (code=exited, status=0/SUCCESS)
   Main PID: 5883 (tinyproxy)
      Tasks: 1 (limit: 94371)

改配置后重启并确认生效的标准组合：

systemctl restart tinyproxy && systemctl is-active tinyproxy

实测输出：

active

六、curl 代理行为实测（功能验证主线）

以下验证均在放行内网的基线配置上执行（Allow 含 127.0.0.1、::1、10.89.65.0/24）。

6.1 普通正向代理：-x

本机走代理访问 HTTP 站点：

curl -s -x http://127.0.0.1:8888 -o /dev/null -w "%{http_code}\n" http://example.com

实测输出：

200

远程客户端（10.89.65.11）走代理：

curl -s -m 10 -x http://10.89.65.10:8888 -o /dev/null -w "%{http_code}\n" http://example.com

实测输出：

200

代理端文件日志同步出现连接记录（tail 实测节选）：

INFO      Oct 22 11:39:11.636 [6880]: opensock: opening connection to example.com:80
INFO      Oct 22 11:39:11.637 [6880]: opensock: getaddrinfo returned for example.com:80
CONNECT   Oct 22 11:39:11.773 [6880]: Established connection to host "example.com" using file descriptor 4.

6.2 CONNECT 隧道：https 目标与 --proxytunnel

https 目标经代理自动走 CONNECT 隧道：

curl -s -m 10 -x http://127.0.0.1:8888 https://example.com -o /dev/null -w "https:%{http_code}\n"

实测输出：

https:200

加 -v 观察隧道握手全过程：

curl -s -m 10 -x http://127.0.0.1:8888 https://example.com -v -o /dev/null 2>&1 | grep -E "CONNECT|replied|completed" | head -4

实测输出：

* Establish HTTP proxy tunnel to example.com:443
> CONNECT example.com:443 HTTP/1.1
* Proxy replied 200 to CONNECT request
* CONNECT phase completed!

要点：Proxy replied 200 表示代理接受了 CONNECT（需目标端口在 ConnectPort 白名单内）；对非白名单端口发起 CONNECT 会被直接拒绝（隧道建立不起来，curl 返回码非 0），配置为 ConnectPort 0 时返回 HTTP/1.0 403 Access violation。

6.3 Basic 代理认证：-U

在配置中加入演示账号（用户 root、密码 q1w2e3r4）：

BasicAuth root q1w2e3r4

systemctl restart tinyproxy

不带凭据访问，收到 407 要求认证：

curl -s -m 8 -x http://127.0.0.1:8888 -o /dev/null -w "noauth:%{http_code}\n" http://example.com

实测输出：

noauth:407

带凭据访问（-U 用户:密码）：

curl -s -m 8 -U root:q1w2e3r4 -x http://127.0.0.1:8888 -o /dev/null -w "withauth:%{http_code}\n" http://example.com

实测输出：

withauth:200

⚠️ 注意：407 响应头为 Proxy-Authenticate: Basic realm="Tinyproxy"，realm 由代码内置；上游 1.11.3 模板里的 BasicAuthRealm 指令在 1.11.0 上无法解析（ERROR: Syntax error），版本差异详见《Tinyproxy 配置参数详解》5.8 节实测。演示账号验证后从配置中删除。

6.4 观察代理注入的头：Via 与 X-Tinyproxy

Tinyproxy 转发请求时会追加 Via 头（HTTP 规范要求）。验证方法：在靶机 10.89.65.11 上起一个裸 TCP 监听抓原始请求，代理服务器对其发请求：

# 靶机（10.89.65.11）执行
nc -l 9999 > /tmp/req.txt

# 代理服务器执行
curl -s -m 5 -x http://127.0.0.1:8888 http://10.89.65.11:9999/via-check -o /dev/null

靶机抓到的原始请求实测：

GET /via-check HTTP/1.0
Host: 10.89.65.11:9999
Connection: close
Via: 1.1 tinyproxy (tinyproxy/1.11.0)
User-Agent: curl/7.81.0
Accept: */*

Via: 1.1 tinyproxy (tinyproxy/1.11.0) 即代理痕迹（名字来自 ViaProxyName）。开启 XTinyproxy Yes 后再抓一次，请求末尾多出客户端 IP 行（实测）：

X-Tinyproxy: 127.0.0.1

（值为发起请求的客户端地址；远程客户端场景下显示其真实 IP。）配套的隐身开关 DisableViaHeader Yes 可去掉 Via 头，但违反 RFC 2616，慎用。

6.5 内置统计页与错误页

请求主机名 tinyproxy.stats（StatHost 默认值）返回运行统计页：

curl -s -m 8 -x http://127.0.0.1:8888 http://tinyproxy.stats/ | grep "<title>" | head -1

实测输出：

<title>tinyproxy version 1.11.0 run-time statistics</title>

被 Allow 拒绝的客户端拿到 403 错误页（default.html 渲染，实测正文节选）：

<h1>Access denied</h1>

<p>The administrator of this proxy has not configured it to service requests from your host.</p>

6.6 上游链式转发验证（Upstream）

配置 upstream http 10.89.65.11:8889（上游为 10.89.65.11 上的另一 tinyproxy 实例，端口 8889，其配置需放行来源网段）后：

curl -s -m 10 -x http://127.0.0.1:8888 -o /dev/null -w "chain:%{http_code}\n" http://example.com

实测输出：

chain:200

链路生效证据在上游机日志——连接是它建立的（journalctl 实测）：

Oct 22 11:32:37 node2.example.local tinyproxy[3357]: Established connection to host "example.com" using file descriptor 4.
Oct 22 11:32:38 node2.example.local tinyproxy[3357]: Closed connection between local client (fd:3) and remote client (fd:4)

把上游实例 systemctl stop 停掉再测：

curl -s -m 8 -x http://127.0.0.1:8888 -o /tmp/502.html -w "code:%{http_code}\n" http://example.com
grep -oE "<title>[^<]+" /tmp/502.html

实测输出：

code:404
<title>404 Unable to connect to upstream proxy

💡 说明：Tinyproxy 对「上游代理不可达」返回 404（标题含 upstream proxy），对「目标站点本身不可达」返回 500（标题 500 Unable to connect），排障时先看标题区分故障层级。

七、日志与端口诊断命令

7.1 文件日志读取与关键字检索

tail -5 /var/log/tinyproxy/tinyproxy.log

实测输出节选：

INFO      Oct 22 11:39:11.636 [6880]: opensock: opening connection to example.com:80
INFO      Oct 22 11:39:11.637 [6880]: opensock: getaddrinfo returned for example.com:80
CONNECT   Oct 22 11:39:11.773 [6880]: Established connection to host "example.com" using file descriptor 4.
INFO      Oct 22 11:39:11.864 [6880]: Closed connection between local client (fd:3) and remote client (fd:4)

常用检索模式（均为实测出现过的日志行样式）：

目的命令命中行样式（实测）
查访问被拒来源grep Unauthorized /var/log/tinyproxy/tinyproxy.logUnauthorized connection from "10.89.65.11".
查过滤拦截grep "filtered domain" /var/log/tinyproxy/tinyproxy.logProxying refused on filtered domain "example.com"
查连接建立grep Established /var/log/tinyproxy/tinyproxy.logEstablished connection to host "example.com" using file descriptor 4.
查上游/目标不通grep -E "Unable" /var/log/tinyproxy/tinyproxy.log错误页标题对应事件

7.2 journald 兜底

文件日志不可用（目录属主不对或 Syslog 模式）时，日志在 journald：

journalctl -u tinyproxy --no-pager -n 5

实测输出节选：

Oct 22 11:07:42 proxy1.example.local tinyproxy[464]: Connect (file descriptor 5): 10.89.65.11
Oct 22 11:07:42 proxy1.example.local tinyproxy[464]: Unauthorized connection from "10.89.65.11".
Oct 22 11:07:42 proxy1.example.local tinyproxy[464]: Read request entity of 123 bytes

7.3 端口与进程核对

ss -ltnp | grep 8888

实测输出：

LISTEN 0      1024         0.0.0.0:8888       0.0.0.0:*    users:(("tinyproxy",pid=5883,fd=0))
LISTEN 0      1024            [::]:8888          [::]:*    users:(("tinyproxy",pid=5883,fd=1))

ps aux | grep [t]inyproxy | grep -v grep

实测输出：

tinypro+     464  0.0  0.0 135488  3024 ?        Sl   10:56   0:00 /usr/bin/tinyproxy

日志轮转由包自带的 /etc/logrotate.d/tinyproxy 负责，无需手工干预。

八、注意事项

  • 选项只有 -d/-c/-h/-v 四个短格式，不存在 --version/--test 等长选项；
  • 没有配置预检查命令：改配置一律「备份 → 修改 → systemctl restart → systemctl is-active 验证」，失败时用 tinyproxy -d 前台跑出错误行号；
  • Timeout 单位是秒且只管空闲连接；MaxClients 超额连接排队而非拒绝；
  • ConnectPort 白名单是防滥用的第一道闸，对外开放代理时务必收紧；
  • DisableViaHeader Yes 属于隐身行为，破坏 RFC 2616 兼容性，仅在明确需要时使用；
  • 命令行验证涉及密码时，-U root:q1w2e3r4 会留在 shell 历史，生产环境验证后及时清理或改用交互输入。

九、常见问题（FAQ）

Q1：curl 报 000 或 Connection refused？ 代理没起来或端口/地址不对。先 systemctl is-active tinyproxy，再 ss -ltnp | grep 8888 核对监听；若配置了 Listen，确认客户端访问的是被绑定的那个地址。

Q2：curl 返回 403 Access denied？ 客户端来源不在 Allow 白名单，代理日志有 Unauthorized connection from "来源IP".；按网段追加 Allow 行并重启。

Q3：curl 返回 407 Proxy Authentication Required？ 配置了 BasicAuth，用 -U 用户:密码 带凭据重试。

Q4：CONNECT 隧道建立失败？ 目标端口不在 ConnectPort 白名单（默认只有 443/563）；整体禁用时返回 403 Access violation。补白名单或改用白名单内端口。

Q5：返回 500 Unable to connect 或 404 Unable to connect to upstream proxy？ 500 = 目标站点连不上（DNS/网络/端口未监听）；404 = 上游代理不可达（Upstream 配置的上级宕机）。按标题区分层级排查。

Q6：长下载/长连接中途断开？ 空闲超过 Timeout（默认 600 秒）会被代理主动断开，客户端表现为 empty reply；按业务调大 Timeout。

Q7：改了配置服务起不来了？ 看 journalctl -u tinyproxy -n 20，典型报错 ERROR: Syntax error on line N（语法）或 Could not create listening sockets.（端口占用）；修正后 systemctl restart tinyproxy。

十、参考链接