Ubuntu 22.04 安装 Apache Traffic Server 10.2.0 指南

一、环境信息

项目	内容
操作系统	Ubuntu 22.04.5 LTS（x86_64）
内核	5.15 及以上（实测 5.15/6.8 均正常）
组件版本	Apache Traffic Server 10.2.0
安装方式	官方源码 tar.gz（bz2）包 + CMake 构建
安装前缀	/opt/ats
运行用户	ats（系统用户，禁止登录）
服务端口	8080（HTTP 代理，IPv4 与 IPv6）
配置目录	/opt/ats/etc/trafficserver
日志目录	/opt/ats/var/log/trafficserver
运行时目录	/opt/ats/var/trafficserver

二、前置条件

具备 root 或 sudo 权限的服务器一台，内存建议不低于 4GB（编译期间峰值约 3GB），磁盘剩余空间不低于 5GB。
服务器可访问外网（下载源码包与安装依赖），或已配置可访问 mirrors 与 downloads.apache.org 的代理。
已安装基础工具 curl 与 tar（Ubuntu 22.04 最小安装通常自带 tar，curl 需确认）：

which curl tar bzip2

若缺少 curl 或 bzip2（解压 .tar.bz2 需要），先安装：

apt-get install -y curl bzip2

服务器已配置 yum 或 apt 软件源可用，且系统时间已同步（源码包校验与日志时间戳依赖准确时间）。

三、版本选型说明

到 Apache 官方下载目录 https://downloads.apache.org/trafficserver/ 确认当前最新稳定版本。截至本文实测时，官方发行目录包含 8.1.x、9.2.x（LTS，最新 9.2.15）与 10.x 主线（最新 10.2.0），官网下载页同样以 Traffic Server 10.2.0 与 9.2.15 为推荐版本。

本文选取主线最新稳定版 10.2.0。需要注意 ATS 10 与 9.x 相比有两个重大差异，直接影响安装与运维方式：

构建系统从 autoconf（./configure）全面迁移到 CMake（要求 cmake 3.20 及以上），10.2.0 源码包内已不存在 configure 脚本，README.md 明确说明以 cmake -B build 方式构建。
主配置文件由 records.config 变更为 records.yaml（YAML 格式），同时 traffic_manager 与 traffic_cop 进程被移除，启停由 traffic_server 自身配合 systemd 完成，traffic_ctl 也不再提供 server start/stop/restart 子命令。

如需 9.x 系列，安装命令把版本号替换为 9.2.15 即可，但其构建方式与配置文件格式与本文不同，请参考对应版本文档。

四、部署步骤

4.1 安装编译依赖

更新软件源索引：

apt-get update

安装编译工具链与库依赖（含 CMake、PCRE2、OpenSSL 开发头文件等）：

apt-get install -y build-essential cmake libssl-dev libpcre2-dev libcap-dev libhwloc-dev libcurl4-openssl-dev tcl-dev zlib1g-dev libluajit-5.1-dev libbrotli-dev liblzma-dev pkg-config bison flex

实测安装完成后确认关键组件版本：

gcc --version | head -1

gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0

cmake --version | head -1

cmake version 3.22.1

openssl version

OpenSSL 3.0.2 15 Mar 2022 (Library: OpenSSL 3.0.2 15 Mar 2022)

说明：ATS 10.2.0 要求 C++17 编译器（gcc 9 以上）、OpenSSL 3.0 及以上、PCRE2（libpcre2-dev 为必需项，仅装 libpcre3-dev 会在 CMake 配置阶段报 libpcre2-8 not found）。Ubuntu 22.04 自带的 gcc 11 与 OpenSSL 3.0.2 均满足要求。

4.2 下载官方源码包

创建构建目录并下载官方源码包：

mkdir -p /root/build && cd /root/build

curl -fLO https://downloads.apache.org/trafficserver/trafficserver-10.2.0.tar.bz2

确认包完整性与大小：

ls -lh trafficserver-10.2.0.tar.bz2

-rw-r--r-- 1 root root 13M Oct 12 06:16 trafficserver-10.2.0.tar.bz2

sha256sum trafficserver-10.2.0.tar.bz2

bef171a7d064794e05ec7559e46d3e07c3ae6487a4647987fcc4f1cc5a82cec6  trafficserver-10.2.0.tar.bz2

若 downloads.apache.org 当前只保留最新小版本，历史版本可从 https://archive.apache.org/dist/trafficserver/ 获取。

4.3 解压并执行 CMake 配置

解压源码包：

cd /root/build && tar xjf trafficserver-10.2.0.tar.bz2

进入源码目录执行 CMake 配置（指定安装前缀与 Release 构建）：

cd /root/build/trafficserver-10.2.0

cmake -B build -DCMAKE_INSTALL_PREFIX=/opt/ats -DCMAKE_BUILD_TYPE=Release

实测配置成功尾部输出：

-- Build files have been written to: /root/build/trafficserver-10.2.0/build

如果配置阶段报 No package 'libpcre2-8' found，说明缺少 PCRE2 开发包，安装 libpcre2-dev 后删除 build 目录重新执行配置即可：

apt-get install -y libpcre2-dev

4.4 编译并安装

执行编译（12 核服务器使用 8 并发；默认会同时编译单元测试，耗时约 15 至 20 分钟）：

cmake --build build -j8

生产部署建议跳过回归测试目标以明显缩短编译时间（约可减少三分之一以上）：

cmake -B build-fast -DCMAKE_INSTALL_PREFIX=/opt/ats -DCMAKE_BUILD_TYPE=Release -DBUILD_REGRESSION_TESTING=OFF

cmake --build build-fast -j8

执行安装：

cmake --install build-fast

确认安装结果：

ls /opt/ats/bin/

traffic_cache_tool  traffic_crashlog  traffic_ctl  traffic_layout  traffic_logcat  traffic_logstats  traffic_server  traffic_via  trafficserver

/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'

4.5 创建运行用户与目录

创建专用系统用户 ats（禁止登录）：

useradd -r -s /usr/sbin/nologin ats

chown -R ats:ats /opt/ats/var

说明：ATS 以 root 启动时会自动把工作进程切换为 nobody 用户；直接以非 root 用户启动时进程保持当前身份。使用 systemd 的 User=ats 指定专用用户运行是推荐做法，此时无需依赖 nobody。

4.6 基础配置

设置缓存存储（编辑 /opt/ats/etc/trafficserver/storage.config，将默认行改为期望的缓存大小，实测示例为 512MB）：

sed -i 's|var/trafficserver 256M|var/trafficserver 512M|' /opt/ats/etc/trafficserver/storage.config

确认修改结果：

grep -v '^#' /opt/ats/etc/trafficserver/storage.config | tail -1

var/trafficserver 512M

配置反向代理映射（编辑 /opt/ats/etc/trafficserver/remap.config，写入一行映射规则，实测以 example.com 为回源站点）：

printf 'map / http://example.com/\n' > /opt/ats/etc/trafficserver/remap.config

监听端口与缓存行为等参数位于 /opt/ats/etc/trafficserver/records.yaml（ATS 10 新格式），默认 server_ports 即 8080，可暂不修改。

安装前校验配置合法性：

/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'

4.7 配置 systemd 服务

创建服务单元文件 /etc/systemd/system/trafficserver.service：

cat > /etc/systemd/system/trafficserver.service <<'EOF'
[Unit]
Description=Apache Traffic Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ats
Group=ats
ExecStartPre=/bin/rm -f /opt/ats/var/trafficserver/server.lock /opt/ats/var/trafficserver/jsonrpc20.sock /opt/ats/var/trafficserver/jsonrpc20.lock
ExecStart=/opt/ats/bin/traffic_server
ExecReload=/opt/ats/bin/traffic_ctl config reload
Restart=on-failure
RestartSec=5
LimitNOFILE=131072

[Install]
WantedBy=multi-user.target
EOF

其中 ExecStartPre 清理异常退出残留的锁与 RPC socket 文件，避免下次启动时 JSONRPC 绑定失败导致 traffic_ctl 不可用。

重载并设置开机自启：

systemctl daemon-reload

systemctl enable trafficserver

Created symlink /etc/systemd/system/multi-user.target.wants/trafficserver.service → /etc/systemd/system/trafficserver.service.

systemctl start trafficserver

4.8 启动验证

确认服务状态：

systemctl status trafficserver --no-pager -n 3

● trafficserver.service - Apache Traffic Server
     Loaded: loaded (/etc/systemd/system/trafficserver.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-12 06:47:06 UTC; 8s ago
   Main PID: 15039 (/opt/ats/bin/traffic_server)

确认端口监听：

ss -lnt | grep 8080

LISTEN 0      4096         0.0.0.0:8080      0.0.0.0:*
LISTEN 0      4096            [::]:8080         [::]:*

确认服务内部状态（JSON 格式）：

/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"}]}

发起请求验证代理链路（第一次回源）：

curl -s -o /dev/null -w 'HTTP %{http_code}, %{size_download} bytes, %{time_total}s\n' http://127.0.0.1:8080/

HTTP 200, 577 bytes, 0.179005s

立即再次请求验证缓存命中（Age 大于 0 即命中缓存）：

curl -sI http://127.0.0.1:8080/ | grep -E '^Age|^Server'

Age: 2
Server: ATS/10.2.0

确认缓存文件已生成：

ls -lh /opt/ats/var/trafficserver/cache.db

-rw-r--r-- 1 ats ats 512M Oct 12 06:41 /opt/ats/var/trafficserver/cache.db

确认运行用户与内存占用（C++ 进程，无 JVM）：

ps -o user=,rss=,etime= -p $(systemctl show trafficserver -p MainPID --value)

ats      72896  01:05

实测 RSS 约 71MB，为 12 个网络线程的默认配置，生产环境按并发与缓存规模线性评估。

五、配置说明

安装后 /opt/ats/etc/trafficserver/ 下的核心配置文件：

文件	作用
records.yaml	主配置文件（ATS 10 新 YAML 格式），监听端口、缓存开关、线程、超时等
storage.config	缓存存储定义，每行一个存储路径与大小
remap.config	URL 映射规则（反向代理核心）
plugin.config	全局插件加载清单
cache.config	缓存对象 TTL 与失效控制
ip_allow.yaml	客户端访问控制
logging.yaml	访问日志格式与管道定义
sni.yaml	SNI 层 TLS 配置

常用运行时验证命令：

/opt/ats/bin/traffic_ctl config get proxy.config.http.server_ports

proxy.config.http.server_ports: 8080 8080:ipv6

修改 records.yaml 后无需重启的参数可用 reload 生效：

/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

server_ports 等标记为 static 的参数修改后必须重启服务。

六、注意事项

ATS 10.2.0 源码包没有 configure 脚本，不要执行 ./configure，直接使用 cmake。
libpcre2-dev 是必需依赖；libbrotli-dev 与 liblzma-dev 缺失时仅关闭对应压缩加速，编译可继续。
traffic_ctl config set 只修改运行时值，不写回 records.yaml，持久化必须手工编辑配置文件。
进程被 kill 或异常退出后，/opt/ats/var/trafficserver/ 下会残留 server.lock、jsonrpc20.sock、jsonrpc20.lock，导致下次启动 JSONRPC 绑定失败（traffic_ctl 报 Resource temporarily unavailable），务必使用 systemd 管理（ExecStartPre 已内置清理）。
ATS 10 主进程启动后进程名显示为 TS_MAIN，pkill -x traffic_server 无法命中运行中的主进程；停止请使用 systemctl stop trafficserver。
优雅停止需要数秒到数十秒的连接排空时间，脚本化重启应轮询 8080 端口释放后再启动，否则报 Address already in use。
缓存扩容（storage.config）必须重启生效；生产建议使用整盘裸设备以获得 O_DIRECT 性能。

七、常见问题

Q1：cmake 配置阶段报 No package 'libpcre2-8' found 怎么处理？

安装 PCRE2 开发包并删除 build 目录重新配置：

apt-get install -y libpcre2-dev

rm -rf /root/build/trafficserver-10.2.0/build

cmake -B build -DCMAKE_INSTALL_PREFIX=/opt/ats -DCMAKE_BUILD_TYPE=Release

Q2：启动后 traffic_ctl 报 RPC Node Error 或 Resource temporarily unavailable？

上次进程异常退出残留了 RPC 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：请求返回 404 且内容是回源站点的错误页？

remap_required 默认开启，所有请求必须命中 remap.config 规则。检查映射规则是否覆盖目标主机名，例如：

printf 'map / http://example.com/\n' > /opt/ats/etc/trafficserver/remap.config

/opt/ats/bin/traffic_ctl config reload

Q4：如何确认响应来自缓存？

先开启 Via 响应头（records.yaml 中 insert_response_via_str 由 0 改为 1 并 reload），再用 traffic_via 解析编码段：

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:
Result of Traffic Server cache lookup for URL          :miss (a cache "MISS")
Cache Lookup Result                                    :cache miss (url not in cache)

八、卸载方式

停止并禁用服务（每行仅一个单元名）：

systemctl stop trafficserver

systemctl disable trafficserver

删除服务单元并重载：

rm -f /etc/systemd/system/trafficserver.service

systemctl daemon-reload

删除安装目录与运行数据：

rm -rf /opt/ats

删除构建目录与运行用户：

rm -rf /root/build/trafficserver-10.2.0 /root/build/trafficserver-10.2.0.tar.bz2

userdel ats

如曾为编译安装过额外依赖且不再需要，可按需清理 libpcre2-dev 等开发包。

九、参考链接

Apache Traffic Server 官方下载页：https://trafficserver.apache.org/downloads
官方发行目录（10.2.0 源码包）：https://downloads.apache.org/trafficserver/
官方安装文档（Building and Installing）：https://docs.trafficserver.apache.org/en/latest/getting-started/index.html
records.yaml 参数参考：https://docs.trafficserver.apache.org/en/latest/admin-guide/files/records.yaml.en.html
storage.config 参考：https://docs.trafficserver.apache.org/en/latest/admin-guide/files/storage.config.en.html
remap.config 参考：https://docs.trafficserver.apache.org/en/latest/admin-guide/files/remap.config.en.html