Apache Traffic Server 10.2.0 常用 CLI 命令与工具详解
本文逐条实测 Traffic Server 10.2.0 全套命令行工具：traffic_server 参数校验、traffic_ctl 七大子命令组、traffic_layout 与日志工具的真实回显，并汇总 ATS 10 命令变化。
Apache Traffic ServerApache Traffic Server2026/10/12
Apache Traffic Server 10.2.0 常用 CLI 命令与工具详解
一、环境信息
| 项目 | 内容 |
|---|---|
| 组件版本 | Apache Traffic Server 10.2.0 |
| 安装方式 | 官方源码 CMake 构建，前缀 /opt/ats |
| 工具目录 | /opt/ats/bin |
| 运行方式 | systemd 单元 trafficserver |
| 实测系统 | Ubuntu 22.04 与 CentOS 8（工具行为一致） |
二、工具概览
/opt/ats/bin/ 下共 9 个可执行文件，职责划分如下：
| 工具 | 类型 | 职责 |
|---|---|---|
| traffic_server | 常驻主程序 | 代理服务本体，含启动参数、配置校验、维护命令 |
| traffic_ctl | 管理客户端 | 与运行中服务通信的 RPC CLI，管控与查询 |
| traffic_layout | 离线工具 | 目录布局查看与 runroot 沙箱管理 |
| traffic_cache_tool | 离线工具 | 缓存 span 的分配、检查与修复 |
| traffic_logstats | 离线工具 | 访问日志统计分析 |
| traffic_logcat | 离线工具 | 二进制日志转文本格式 |
| traffic_via | 离线工具 | 解析 Via 响应头编码段 |
| traffic_crashlog | 辅助程序 | 进程崩溃时收集诊断信息 |
| trafficserver | 管理脚本 | SysV 风格启停脚本（start/stop/restart/status） |
重要变化：ATS 10 已移除 traffic_manager 与 traffic_cop 进程，traffic_ctl 不再提供 server start/stop/restart 子命令，服务启停由 systemd 完成。
三、前置条件
- ATS 已安装且服务处于运行状态（traffic_ctl 的在线子命令依赖服务内 JSONRPC）：
systemctl is-active trafficserver
active
- 命令路径。未加入 PATH 时使用绝对路径调用，或将安装 bin 目录加入环境：
export PATH=/opt/ats/bin:$PATH
- 确认 RPC 通道正常（连接失败说明残留 socket 或服务未启动）：
/opt/ats/bin/traffic_ctl server status | head -c 80
{"initialized_done": "true", "is_ssl_handshaking_stopped": "false", "is_draining": "false",
四、工具详解
4.1 traffic_server 主程序
查看版本：
/opt/ats/bin/traffic_server --version
Traffic Server 10.2.0-0 Oct 12 2026 06:34:03 27a035cee062
traffic_server: using root directory '/opt/ats'
查看全部启动参数：
/opt/ats/bin/traffic_server -h
Usage: traffic_server [--SWITCH [ARG]]
switch__________________type__default___description
--accept_mss int 0 MSS for client connections
-a, --accept_thread tog false Use an Accept Thread
--bind_stderr str Regular file to bind stderr to
--bind_stdout str Regular file to bind stdout to
-K, --clear_cache on false Clear Cache on Startup
-C, --command str Maintenance Command to Execute
Commands: list, check, clear, clear_cache, verify_config, verify_global_plugin, verify_remap_plugin, help
-D, --conf_dir str config dir to verify
-T, --debug_tags str Vertical-bar-separated Debug Tags
-n, --net_threads int 0 Number of Net Threads
-p, --httpport str (null) Port descriptor for HTTP Accept
-i, --interval int 0 Statistics Interval
-V, --version Print version string
配置合法性校验（改配置后、重启前的标准动作）：
/opt/ats/bin/traffic_server -C verify_config
INFO: Successfully initialized SSL client context
Traffic Server 10.2.0-0 Oct 12 2026 06:34:03 27a035cee062
traffic_server: using root directory '/opt/ats'
输出无 Fatal 与 YAML 报错即通过。校验 remap 插件可加 -C verify_remap_plugin。
临时清空缓存启动（危险操作，仅排障）：
/opt/ats/bin/traffic_server -K
4.2 traffic_ctl 服务管控（server 子命令组）
查看子命令：
/opt/ats/bin/traffic_ctl server -h
server Stop, restart and examine the server
backtrace Show a full stack trace of the traffic_server process
debug Enable/Disable ATS for diagnostic messages at runtime
disable Disables logging for diagnostic messages at runtime
enable Enables logging for diagnostic messages at runtime
drain Drain the requests
status Show the proxy status
查看运行状态（12 核实测 ET_NET 12 线程）：
/opt/ats/bin/traffic_ctl server status
{"initialized_done": "true", "is_ssl_handshaking_stopped": "false", "is_draining": "false", "is_event_system_shut_down": "false", "thread_groups": [{"name": "ET_NET", "count": "12", "started": "true"}, {"name": "ET_TASK", "count": "2", "started": "true"}, {"name": "ET_UDP", "count": "0", "started": "false"}]}
运行时开启诊断日志（默认只记 NOTE 以上，enable 后输出 debug 标签日志）：
/opt/ats/bin/traffic_ctl server debug enable http
排障结束关闭：
/opt/ats/bin/traffic_ctl server debug disable
滚动排空存量请求（上线前摘流场景）：
/opt/ats/bin/traffic_ctl server drain
注意：ATS 10 中 server 组没有 start/stop/restart，执行会提示找不到子命令；启停使用 systemctl stop trafficserver 与 systemctl start trafficserver。
4.3 traffic_ctl 配置管理（config 子命令组）
查看子命令：
/opt/ats/bin/traffic_ctl config -h
config Manipulate configuration records
defaults Show default information configuration values
describe Show detailed information about configuration values
diff Show non-default configuration values
get Get one or more configuration values
match Get configuration matching a regular expression
registry Show configuration file registry
reload Request a configuration reload
reset Reset configuration values matching a path pattern to their defaults
set Set a configuration value
status Check the configuration status
查询参数值（可一次多个）：
/opt/ats/bin/traffic_ctl config get proxy.config.http.server_ports proxy.config.http.cache.http
proxy.config.http.server_ports: 8080 8080:ipv6
proxy.config.http.cache.http: 1
按正则匹配：
/opt/ats/bin/traffic_ctl config match 'proxy.config.http.keep_alive'
proxy.config.http.keep_alive_no_activity_timeout_in: 120
proxy.config.http.keep_alive_no_activity_timeout_out: 120
查看参数元信息（重点 update type）：
/opt/ats/bin/traffic_ctl config describe proxy.config.http.server_ports
name : proxy.config.http.server_ports
current value : 8080 8080:ipv6
default value : 8080 8080:ipv6
record type : CONFIG
data type : STRING
update type : static, restart traffic_server
source : administratively set
查看所有非默认值（配置漂移诊断）：
/opt/ats/bin/traffic_ctl config diff
proxy.config.ssl.client.verify.server.policy has changed
Current Value: PERMISSIVE
Default Value: ENFORCED
运行时动态设置（实测重要结论：不写回 records.yaml，重启即丢）：
/opt/ats/bin/traffic_ctl config set proxy.config.http.insert_response_via_str 1
Set proxy.config.http.insert_response_via_str, please wait 10 seconds for traffic server to sync configuration, restart is not required
请求重载并跟踪结果：
/opt/ats/bin/traffic_ctl config reload
✔ Reload scheduled [rldtk-1791787136637]
Monitor : traffic_ctl config reload -t rldtk-1791787136637 -m
Details : traffic_ctl config reload -t rldtk-1791787136637 -s -l
/opt/ats/bin/traffic_ctl config status
✔ Reload [success] — rldtk-1791787136637
Started : 2026 Oct 12 06:38:56.637
Finished: 2026 Oct 12 06:38:56.643
Duration: 6ms
✔ 1 success ◌ 0 in-progress ✗ 0 failed (1 total)
恢复参数默认值（按前缀模式）：
/opt/ats/bin/traffic_ctl config reset proxy.config.http.insert_response_via_str
4.4 traffic_ctl 指标查询（metric 子命令组）
查单个或多个指标：
/opt/ats/bin/traffic_ctl metric get proxy.process.http.incoming_requests proxy.process.http.transaction_counts.hit_fresh
proxy.process.http.transaction_counts.hit_fresh 0
proxy.process.http.incoming_requests 4
按正则批量查缓存占用类指标：
/opt/ats/bin/traffic_ctl metric match 'proxy.process.cache.*used'
proxy.process.cache.bytes_used 0
proxy.process.cache.ram_cache.bytes_used 0
proxy.process.cache.direntries.used 0
proxy.process.cache.volume_0.bytes_used 0
proxy.process.cache.volume_0.ram_cache.bytes_used 0
持续观察某指标（每 3 秒采样 10 次后输出摘要）：
/opt/ats/bin/traffic_ctl metric monitor proxy.process.http.incoming_requests -i 3 -c 10
查指标元信息：
/opt/ats/bin/traffic_ctl metric describe proxy.process.http.incoming_requests
4.5 traffic_ctl 缓存与存储（cache 与 storage 子命令组）
缓存共享内存：
/opt/ats/bin/traffic_ctl cache shm status
缓存清理（推进全局缓存代际，等效全量失效，属危险操作）：
/opt/ats/bin/traffic_ctl cache clear
存储在线状态（必须带存储路径参数，裸 status 会报 at least one argument expected）：
/opt/ats/bin/traffic_ctl storage status /opt/ats/var/trafficserver
Device: /opt/ats/var/trafficserver/cache.db
Status: online
Error Count: 0
把故障存储下线（移除故障盘场景）：
/opt/ats/bin/traffic_ctl storage offline /dev/disk/by-id/nvme1n1
4.6 traffic_ctl 主机与 HostDB（host 与 hostdb 子命令组）
手工摘除源站（健康检查与负载均衡选路层面），实测状态回显：
/opt/ats/bin/traffic_ctl host down example.com
example.com HOST_STATUS_DOWN,ACTIVE:UP:0:0,LOCAL:UP:0:0,MANUAL:DOWN:1791787171:0,SELF_DETECT:UP:0
查询与恢复：
/opt/ats/bin/traffic_ctl host status example.com
/opt/ats/bin/traffic_ctl host up example.com
HostDB 解析记录查询（JSON 输出，含解析 IP 与健康状态）：
/opt/ats/bin/traffic_ctl hostdb status
{"metadata": {"timestamp": "1791787113", "version": "Apache Traffic Server - traffic_server - 10.2.0 - (build # 0 on Oct 12 2026 at 06:24:05)"}, "partitions": [{"id": "26", "records": [{"metadata": {"name": "example.com", "port": "80", "type": "ADDR", "af_family": "AF_INET", "failed": "false", "ip_timestamp": "1791787083315208423", "hash_key": "11354878635857268058"}, "info": [{"ip": "172.66.147.243", "health": {"last_failure": "0", "fail_count": "0"}}]}]}]}
4.7 traffic_ctl 插件与 RPC（plugin 与 rpc 子命令组）
向插件发消息（插件需实现消息回调，常用于自定义插件控制）：
/opt/ats/bin/traffic_ctl plugin msg TAG message-data
直接发 JSONRPC 请求（绕过 traffic_ctl 命令封装，调试 RPC 用）：
/opt/ats/bin/traffic_ctl rpc invoke METHOD
/opt/ats/bin/traffic_ctl rpc file request.json
/opt/ats/bin/traffic_ctl rpc get-api
get-api 会列出服务端全部 RPC 方法，是排查方法名是否存在的有效手段。
4.8 traffic_layout 目录布局工具
查看安装布局（排查配置与日志实际路径的最快方式）：
/opt/ats/bin/traffic_layout info
PREFIX: /opt/ats
BINDIR: /opt/ats/bin
SYSCONFDIR: /opt/ats/etc/trafficserver
LIBDIR: /opt/ats/lib
LOGDIR: /opt/ats/var/log/trafficserver
RUNTIMEDIR: /opt/ats/var/trafficserver
PLUGINDIR: /opt/ats/libexec/trafficserver
INCLUDEDIR: /opt/ats/include
LOCALSTATEDIR: /opt/ats/var
records.yaml: /opt/ats/etc/trafficserver/records.yaml
remap.config: /opt/ats/etc/trafficserver/remap.config
plugin.config: /opt/ats/etc/trafficserver/plugin.config
storage.config: /opt/ats/etc/trafficserver/storage.config
runroot 沙箱管理（同一份安装跑多实例时使用）：
/opt/ats/bin/traffic_layout init
/opt/ats/bin/traffic_layout verify
/opt/ats/bin/traffic_layout remove
4.9 日志工具 traffic_logstats 与 traffic_logcat
traffic_logstats 统计访问日志（默认读 LOGDIR 下 squid.blog）：
/opt/ats/bin/traffic_logstats --help
Usage: traffic_logstats [--SWITCH [ARG]]
-f, --log_file str Specific logfile to parse
-o, --origin_list str Only show stats for listed Origins
-O, --origin_file str File listing Origins to show
-M, --max_origins int 0 Max number of Origins to show
指定日志文件统计：
/opt/ats/bin/traffic_logstats -f /opt/ats/var/log/trafficserver/squid.blog
traffic_logcat 把二进制日志转成文本（支持 Common、Extended、Squid 三种目标格式）：
/opt/ats/bin/traffic_logcat --help
Usage: traffic_logcat [--SWITCH [ARG]]
-o, --output_file str Specify output file
-a, --auto_filenames tog false Automatically generate output names
-f, --follow tog false Follow the log file as it grows
-C, --clf tog false Convert to Common Logging Format
-E, --elf tog false Convert to Extended Logging Format
-S, --squid tog false Convert to Squid Logging Format
转换示例（squid 二进制转 Common 格式输出到文件）：
/opt/ats/bin/traffic_logcat -C -o /tmp/access.log /opt/ats/var/log/trafficserver/squid.blog
4.10 辅助工具 traffic_via、traffic_cache_tool、traffic_crashlog、trafficserver
traffic_via 解析 Via 头编码段（前提 records.yaml 的 insert_response_via_str 设为 3）。先取得编码串：
curl -s -D - -o /dev/null http://127.0.0.1:8080/ | grep -i '^Via'
Via: http/1.1 traffic_server (ApacheTrafficServer/10.2.0 [uScMsSf pSeN:t cCMp sS])
把方括号内的编码串交给工具：
/opt/ats/bin/traffic_via 'uScMsSf pSeN:t cCMp sS'
Via Header Details:
Request headers received from client :simple request (not conditional)
Result of Traffic Server cache lookup for URL :miss (a cache "MISS")
Response information received from origin server :connection opened successfully
Result of document write-to-cache: :no cache write performed
Proxy operation result :served or connection opened successfully
Error codes (if any) :no error
Tunnel info :no tunneling
Cache Type :cache
Cache Lookup Result :cache miss (url not in cache)
Parent proxy connection status :no parent proxy or unknown
注意实测：传入整段 Via 值会报 Invalid VIA header, length should be 6 or 22 characters，必须只传方括号内的 22 字符编码段。
traffic_cache_tool 缓存 span 离线管理（必须显式给 span 与 volume）：
/opt/ats/bin/traffic_cache_tool --spans /opt/ats/var/trafficserver/cache.db free
子命令组含 alloc（存储分配）、free（空闲分配）、fill、clear、scan 等，用于容量重分配与损坏检查，操作前务必停服务。
traffic_crashlog 崩溃诊断收集（通常由 ATS 内部在子进程崩溃时自动调用，手工指定目标进程）：
/opt/ats/bin/traffic_crashlog --target 15469
trafficserver 管理脚本（SysV 风格，systemd 环境下一般不用，但在无 systemd 的环境可用）：
/opt/ats/bin/trafficserver status
/opt/ats/bin/trafficserver start
/opt/ats/bin/trafficserver stop
五、注意事项
- traffic_ctl 在线子命令依赖 JSONRPC socket。报 RPC Node Error connect Connection refused 或 Resource temporarily unavailable 时，先查 /opt/ats/var/trafficserver/ 下 jsonrpc20.sock 是否残留（异常退出会残留），清理后重启服务。
- config set 的修改只存在于运行时，重启即丢；要持久化必须编辑 records.yaml。
- cache clear 等于全库失效，会让回源流量瞬时放大，生产环境请在低峰执行。
- traffic_server -C 系列维护命令是离线执行（不启动代理监听），与 systemctl start 不冲突，可安全用于配置检查。
- ATS 10 主进程在系统中的进程名显示为 TS_MAIN，用 ps 或 ss 定位 PID 时按此特征检索。
- traffic_cache_tool 直接操作缓存文件，误操作会损毁缓存结构，仅限停机维护窗口使用。
六、常见问题
Q1：traffic_ctl server start 报找不到子命令？
ATS 10 移除了该子命令（traffic_manager 已不存在）。启动与停止一律：
systemctl start trafficserver
systemctl stop trafficserver
Q2：traffic_ctl 全部命令都报 RPC Node Error？
JSONRPC socket 残留或属主错误。清理并重启：
rm -f /opt/ats/var/trafficserver/jsonrpc20.sock /opt/ats/var/trafficserver/jsonrpc20.lock /opt/ats/var/trafficserver/server.lock
systemctl restart trafficserver
Q3：traffic_via 报 Invalid VIA header？
只传方括号内 22 字符编码段，不要带 Via: 前缀、括号与版本信息：
/opt/ats/bin/traffic_via 'uScMsSf pSeN:t cCMp sS'
Q4：traffic_ctl storage status 不带参数报错？
该命令要求显式存储路径，查看 storage.config 后逐个传入：
/opt/ats/bin/traffic_ctl storage status /opt/ats/var/trafficserver
Q5：哪里能看全部可用指标名？
用 match 通配全量或按前缀过滤：
/opt/ats/bin/traffic_ctl metric match 'proxy.process.http.transaction'
配合 stats_over_http 的 /_stats 端点可获得 JSON 格式全量指标快照。
七、参考链接
- traffic_ctl 官方手册：https://docs.trafficserver.apache.org/en/latest/admin-guide/monitoring/traffic_ctl.en.html
- traffic_server 命令行参考：https://docs.trafficserver.apache.org/en/latest/admin-guide/monitoring/traffic_server.en.html
- traffic_via 与 Via 编码说明：https://docs.trafficserver.apache.org/en/latest/admin-guide/monitoring/monitoring.en.html
- 日志工具参考：https://docs.trafficserver.apache.org/en/latest/admin-guide/logging/index.en.html
- 指标与监控章节：https://docs.trafficserver.apache.org/en/latest/admin-guide/monitoring/index.en.html
章节目录