Apache Serf 安装指南
Ubuntu 22.04 安装 Apache Serf 1.3.10 的完整指南，Serf 是基于 APR 的 C 语言异步 HTTP 客户端库：覆盖 apt 发行版包与官方源码 scons 编译两种方案、编译依赖安装、zlib 头文件缺失排障、动态链接库注册验证、多版本共存优先级分析与卸载清理，全部命令均实测可复现。
Apache Serf 安装指南
目标：在 Ubuntu 22.04 服务器上完成 Apache Serf 1.3.10（基于 APR 的 C 语言异步 HTTP 客户端库，以
libserf-1动态库 + 头文件形态提供，非独立服务）的安装与验证。本文给出发行版 apt 仓库安装与官方源码 scons 编译安装两种方案，以及动态链接库注册、验证命令、常见问题排障与卸载方式。所有命令与回显均在 Ubuntu 22.04.5 LTS + GCC 11.4.0 环境实测通过。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（VERSION_CODENAME=jammy）
- 架构：x86_64
- 编译器：GCC 11.4.0（
gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0） - APR：1.7.0（
libapr1-dev，apr-1-config --version回显） - APR-util：1.6.1（
libaprutil1-dev，apu-1-config --version回显） - OpenSSL：3.0.2（
libssl-dev，openssl version回显） - 构建工具：SCons 4.0.1（Ubuntu 官方源）
- zlib：1.2.11（
zlib1g-dev） - Serf 版本：1.3.10（当前 1.3.x 主线最新稳定版）
- 安装前缀：
/usr/local/serf - 演示账号：root
💡 说明：Serf 是一个发布为 C 动态库
libserf-1.so的异步 HTTP 客户端组件（Subversion 的 HTTP 访问层即基于它），本身没有可执行守护进程、没有监听端口，所谓「安装」本质是把库文件与头文件就位、注册动态链接器缓存，并确保依赖 APR/APR-util/OpenSSL/zlib 可用。
二、前置条件
2.1 更新软件源
sudo apt-get update
2.2 安装编译工具链与依赖库
sudo apt-get install -y build-essential libapr1-dev libaprutil1-dev libssl-dev scons wget
验证工具链版本（实测回显）：
gcc --version | head -1
apr-1-config --version
apu-1-config --version
scons --version | head -2
openssl version
gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0
1.7.0
1.6.1
SCons by Steven Knight et al.:
SCons: v4.0.1.c289977f8b34786ab6c334311e232886da7e8df1, 2020-07-17 01:50:03, by bdbaddog on ProDog2020
OpenSSL 3.0.2 15 Mar 2022 (Library: OpenSSL 3.0.2 15 Mar 2022)
💡
apr-1-config/apu-1-config是 Serf 构建系统的定位入口，Serf 的 SConstruct 通过它们取编译器旗标与库路径；这两个可执行文件由libapr1-dev、libaprutil1-dev提供。
三、版本选型说明
通过 Apache 官方归档目录探测当前在册版本（按版本号排序取末尾）：
wget -q -O /tmp/serf-dir.html https://archive.apache.org/dist/serf/
grep -oE 'serf-[0-9]+\.[0-9]+\.[0-9]+\.tar\.bz2' /tmp/serf-dir.html | sort -u | sort -t- -k2 -V | tail -6
实测返回：
serf-1.3.5.tar.bz2
serf-1.3.6.tar.bz2
serf-1.3.7.tar.bz2
serf-1.3.8.tar.bz2
serf-1.3.9.tar.bz2
serf-1.3.10.tar.bz2
两条安装路线的版本对照如下：
| 来源 | 版本 | 包/文件 | 适用场景 | 结论 |
|---|---|---|---|---|
| Ubuntu 22.04 仓库（universe） | 1.3.9-10ubuntu2 | libserf-1-1 / libserf-dev | 只做 Subversion 等既有组件的依赖、不写新代码 | 用 apt |
| Apache 官方归档 | 1.3.10（最新稳定） | serf-1.3.10.tar.bz2 | 直接基于 Serf 开发 HTTP 客户端、需要最新修复 | 用源码编译 |
💡 版本选择建议：Ubuntu 22.04 仓库的 libserf-dev 停在 1.3.9（2022 年构建），仅提供库与头文件、无命令行工具；若要使用最新版 1.3.10（含连接 API 现代化修复），按第五章源码编译安装。本指南主体按源码方案（1.3.10）实测，apt 方案作为第四章备用路线。
四、方案 A：发行版仓库安装（apt，版本 1.3.9）
4.1 安装运行库与开发头文件
sudo apt-get install -y libserf-dev
实测回显（节选）：
Unpacking libserf-dev:amd64 (1.3.9-10ubuntu2) ...
Setting up libserf-1-1:amd64 (1.3.9-10ubuntu2) ...
Setting up libserf-dev:amd64 (1.3.9-10ubuntu2) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
libserf-dev 会自动带上运行库 libserf-1-1，确认安装结果：
dpkg -l libserf-1-1 libserf-dev | tail -3
ii libserf-1-1:amd64 1.3.9-10ubuntu2 amd64 high-performance asynchronous HTTP client library
ii libserf-dev:amd64 1.3.9-10ubuntu2 amd64 high-performance asynchronous HTTP client library headers
4.2 安装布局与版本确认
ls /usr/include/serf-1/
ls -la /usr/lib/x86_64-linux-gnu/libserf*
pkg-config --modversion serf-1
实测回显：
serf.h
serf_bucket_types.h
serf_bucket_util.h
-rw-r--r-- 1 root root 205154 Mar 14 2022 /usr/lib/x86_64-linux-gnu/libserf-1.a
lrwxrwxrwx 1 root root 18 Mar 14 2022 /usr/lib/x86_64-linux-gnu/libserf-1.so -> libserf-1.so.1.3.0
lrwxrwxrwx 1 root root 18 Mar 14 2022 /usr/lib/x86_64-linux-gnu/libserf-1.so.1 -> libserf-1.so.1.3.0
-rw-r--r-- 1 root root 116832 Mar 14 2022 /usr/lib/x86_64-linux-gnu/libserf-1.so.1.3.0
1.3.9
⚠️ 注意：apt 方案的 serf-1.pc 位于
/usr/lib/x86_64-linux-gnu/pkgconfig/serf-1.pc，使用 pkg-config 前需安装pkg-config包（apt-get install -y pkg-config）。
五、方案 B：官方源码编译安装（scons，推荐，1.3.10）
5.1 下载源码包并校验
从 Apache 官方归档目录下载（直连即可）：
cd /opt
wget -q https://archive.apache.org/dist/serf/serf-1.3.10.tar.bz2
ls -la serf-1.3.10.tar.bz2
sha256sum serf-1.3.10.tar.bz2
实测回显：
-rw-r--r-- 1 root root 147744 May 31 2023 serf-1.3.10.tar.bz2
be81ef08baa2516ecda76a77adf7def7bc3227eeb578b9a33b45f7b41dc064e6 serf-1.3.10.tar.bz2
解压源码：
tar xjf serf-1.3.10.tar.bz2
ls serf-1.3.10
CHANGES
LICENSE
NOTICE
README
SConstruct
auth
buckets
build
context.c
design-guide.txt
incoming.c
outgoing.c
serf.h
serf_bucket_types.h
serf_bucket_util.h
serf_private.h
ssltunnel.c
test
5.2 安装 zlib 开发头文件
Serf 的 deflate 桶依赖 zlib，且构建系统需要 zlib.h 头文件。Ubuntu 22.04 的 build-essential 不自带，必须单独安装（若遗漏，5.3 步会报错，见「九、常见问题」Q1）：
sudo apt-get install -y zlib1g-dev
5.3 scons 构建
确认 apr-1-config / apu-1-config 路径后执行构建，显式指定三个关键参数：
ls -la /usr/bin/apr-1-config /usr/bin/apu-1-config
cd /opt/serf-1.3.10
scons APR=/usr/bin/apr-1-config APU=/usr/bin/apu-1-config PREFIX=/usr/local/serf
实测回显（起始与收尾关键行）：
scons: Reading SConscript files ...
Checking for GNU-compatible C compiler...yes
scons: done reading SConscript files.
scons: Building targets ...
gcc -o context.o -c -std=c89 -Wdeclaration-after-statement -Wmissing-prototypes -Wall -O2 -DNDEBUG -DOPENSSL_NO_STDIO -DLINUX -D_REENTRANT -D_GNU_SOURCE -I. -I/usr/include/apr-1.0 -I/usr/include -I/usr/include context.c
gcc -o incoming.o -c -std=c89 -Wdeclaration-after-statement -Wmissing-prototypes -Wall -O2 -DNDEBUG -DOPENSSL_NO_STDIO -DLINUX -D_REENTRANT -D_GNU_SOURCE -I. -I/usr/include/apr-1.0 -I/usr/include -I/usr/include incoming.c
gcc -o outgoing.o -c -std=c89 -Wdeclaration-after-statement -Wmissing-prototypes -Wall -O2 -DNDEBUG -DOPENSSL_NO_STDIO -DLINUX -D_REENTRANT -D_GNU_SOURCE -I. -I/usr/include/apr-1.0 -I/usr/include -I/usr/include outgoing.c
gcc -o ssltunnel.o -c -std=c89 -Wdeclaration-after-statement -Wmissing-prototypes -Wall -O2 -DNDEBUG -DOPENSSL_NO_STDIO -DLINUX -D_REENTRANT -D_GNU_SOURCE -I. -I/usr/include/apr-1.0 -I/usr/include -I/usr/include ssltunnel.c
gcc -o buckets/aggregate_buckets.o -c -std=c89 -Wdeclaration-after-statement -Wmissing-prototypes -Wall -O2 -DNDEBUG -DOPENSSL_NO_STDIO -DLINUX -D_REENTRANT -D_GNU_SOURCE -I. -I/usr/include/apr-1.0 -I/usr/include -I/usr/include buckets/aggregate_buckets.c
（中间逐个编译 buckets/、auth/ 下源文件，此处省略重复行）
gcc -o libserf-1.so.1.3.0 -shared -Wl,-soname=libserf-1.so.1 -Wl,-rpath=/usr/local/serf/lib -Wl,-rpath=/usr/lib/x86_64-linux-gnu -Wl,-rpath=/usr/lib context.os incoming.os outgoing.os ssltunnel.os buckets/aggregate_buckets.os buckets/allocator.os buckets/barrier_buckets.os buckets/buckets.os buckets/bwtp_buckets.os buckets/chunk_buckets.os buckets/dechunk_buckets.os buckets/deflate_buckets.os buckets/file_buckets.os buckets/headers_buckets.os buckets/iovec_buckets.os buckets/limit_buckets.os buckets/mmap_buckets.os buckets/request_buckets.os buckets/response_body_buckets.os buckets/response_buckets.os buckets/simple_buckets.os buckets/socket_buckets.os buckets/ssl_buckets.os auth/auth.os auth/auth_basic.os auth/auth_digest.os auth/auth_spnego.os auth/auth_spnego_gss.os auth/auth_spnego_sspi.os -L/usr/lib/x86_64-linux-gnu -L/usr/lib -lssl -lcrypto -lz -lapr-1 -laprutil-1
Create symlinks for: 'libserf-1.so.1.3.0': 'libserf-1.so.1'->'libserf-1.so.1.3.0', 'libserf-1.so'->'libserf-1.so.1.3.0'
Creating 'serf-1.pc'
scons: done building targets.
💡 构建末尾自动创建
libserf-1.so.1与libserf-1.so软链并生成serf-1.pcpkg-config 元数据。scons -h可查看全部构建变量（PREFIX/LIBDIR/APR/APU/OPENSSL/ZLIB/GSSAPI/DEBUG/APR_STATIC/CC/CFLAGS/LIBS/LINKFLAGS/CPPFLAGS），详解见《Apache Serf 配置参数详解》篇。
5.4 scons install 安装
cd /opt/serf-1.3.10
scons APR=/usr/bin/apr-1-config APU=/usr/bin/apu-1-config PREFIX=/usr/local/serf install
实测回显：
scons: Reading SConscript files ...
Checking for GNU-compatible C compiler...(cached) yes
scons: done reading SConscript files.
scons: Building targets ...
Install file: "libserf-1.a" as "/usr/local/serf/lib/libserf-1.a"
Install file: "libserf-1.so.1.3.0" as "/usr/local/serf/lib/libserf-1.so.1.3.0"
Install file: "serf.h" as "/usr/local/serf/include/serf-1/serf.h"
Install file: "serf_bucket_types.h" as "/usr/local/serf/include/serf-1/serf_bucket_types.h"
Install file: "serf_bucket_util.h" as "/usr/local/serf/include/serf-1/serf_bucket_util.h"
Install file: "serf-1.pc" as "/usr/local/serf/lib/pkgconfig/serf-1.pc"
scons: done building targets.
安装布局核对：
find /usr/local/serf -type f -o -type l | sort
ls -la /usr/local/serf/lib/
实测回显：
/usr/local/serf/include/serf-1/serf.h
/usr/local/serf/include/serf-1/serf_bucket_types.h
/usr/local/serf/include/serf-1/serf_bucket_util.h
/usr/local/serf/lib/libserf-1.a
/usr/local/serf/lib/libserf-1.so
/usr/local/serf/lib/libserf-1.so.1
/usr/local/serf/lib/libserf-1.so.1.3.0
/usr/local/serf/lib/pkgconfig/serf-1.pc
ls -la /usr/local/serf/lib/ 回显：
total 352
drwxr-xr-x 3 root root 4096 Oct 12 01:52 .
drwxr-xr-x 4 root root 4096 Oct 12 01:52 ..
-rw-r--r-- 1 root root 199642 Oct 12 01:52 libserf-1.a
lrwxrwxrwx 1 root root 18 Oct 12 01:52 libserf-1.so -> libserf-1.so.1.3.0
lrwxrwxrwx 1 root root 18 Oct 12 01:52 libserf-1.so.1 -> libserf-1.so.1.3.0
-rwxr-xr-x 1 root root 146896 Oct 12 01:52 libserf-1.so.1.3.0
drwxr-xr-x 2 root root 4096 Oct 12 01:52 pkgconfig
5.5 注册动态链接库路径
将库目录写入 ld.so 配置并刷新缓存：
echo /usr/local/serf/lib > /etc/ld.so.conf.d/serf-1.conf
ldconfig
ldconfig -p | grep serf
实测回显：
libserf-1.so.1 (libc6,x86-64) => /usr/local/serf/lib/libserf-1.so.1
libserf-1.so (libc6,x86-64) => /usr/local/serf/lib/libserf-1.so
5.6 安装验证
头文件版本宏核对：
grep -E "SERF_(MAJOR|MINOR|PATCH)_VERSION" /usr/local/serf/include/serf-1/serf.h | head -3
#define SERF_MAJOR_VERSION 1
#define SERF_MINOR_VERSION 3
#define SERF_PATCH_VERSION 10
pkg-config 版本核对：
PKG_CONFIG_PATH=/usr/local/serf/lib/pkgconfig pkg-config --modversion serf-1
1.3.10
编译链接与运行验证可直接按《Apache Serf 构建并运行示例应用指南》篇执行完整 HTTP GET 示例（实测返回 HTTP status: 200 并打印响应体）。
六、多方案对比与选择建议
| 维度 | 方案 A：apt 仓库 | 方案 B：源码编译（scons） |
|---|---|---|
| 版本 | 1.3.9-10ubuntu2 | 1.3.10（官方最新稳定） |
| 是否需联网下载源码 | 否（apt 源即可） | 是（archive.apache.org） |
| 安装方式 | apt-get install libserf-dev | scons ... && scons ... install |
| 头文件位置 | /usr/include/serf-1/ | /usr/local/serf/include/serf-1/ |
| 库文件位置 | /usr/lib/x86_64-linux-gnu/ | /usr/local/serf/lib/ |
| 包管理 | dpkg 可追踪、可卸载升级 | 手工管理（卸载删目录） |
| 优点 | 一条命令、随系统升级 | 版本最新、前缀隔离、可定制编译参数 |
| 缺点 | 版本较旧、仅随发行版更新 | 需自备工具链与依赖、手动 ldconfig |
选择建议：仅作为 Subversion 等既有软件的底层依赖，用方案 A；直接基于 Serf 二次开发、需要 1.3.10 的 API 修复（连接创建接口现代化），用方案 B。两者可共存，注意动态库优先级（见「九、常见问题」Q2）。
七、配置说明
Serf 作为 C 链接库，安装后没有运行时配置文件、没有服务端口，需要关注的只有三类「路径配置」：
- 头文件：源码方案在
/usr/local/serf/include/serf-1/，编译程序时加-I/usr/local/serf/include/serf-1（或用 pkg-config 取Cflags）。 - 动态库：源码方案在
/usr/local/serf/lib/，通过/etc/ld.so.conf.d/serf-1.conf+ldconfig注册；也可不改全局配置，仅在链接/运行时用-L、LD_LIBRARY_PATH指定。 - pkg-config 元数据：
/usr/local/serf/lib/pkgconfig/serf-1.pc，PKG_CONFIG_PATH指向该目录后，pkg-config --cflags --libs serf-1可自动展开编译与链接参数。
serf-1.pc 实际内容：
SERF_MAJOR_VERSION=1
prefix=/usr/local/serf
exec_prefix=${prefix}
libdir=/usr/local/serf/lib
includedir=${prefix}/include/serf-1
Name: serf
Description: HTTP client library
Version: 1.3.10
Requires.private: libssl libcrypto
Libs: -L${libdir} -lserf-${SERF_MAJOR_VERSION}
Libs.private: /usr/lib/x86_64-linux-gnu/libaprutil-1.la /usr/lib/x86_64-linux-gnu/libapr-1.la -lz
Cflags: -I${includedir}
构建与链接的详细参数（PREFIX/APR/APU/DEBUG 等）与编译期宏说明，见《Apache Serf 配置参数详解》篇。
八、注意事项
⚠️ 注意：
zlib1g-dev必须在 scons 构建前装好，缺zlib.h是本库构建最高频报错（详见 Q1）。- 源码方案务必执行
ldconfig，否则运行时error while loading shared libraries: libserf-1.so.1。- 若同时存在 apt 版 1.3.9 与源码版 1.3.10，链接与运行时实际加载哪一份由 ldconfig 缓存顺序决定（详见 Q2）；编译期
-I与-L指向哪一份决定用的是哪一版头文件与符号。- Serf 1.3.10 头文件版本宏为
1.3.10，而安装产出的动态库 soname 文件名为libserf-1.so.1.3.0（1.x 系列内部版本号，属正常现象）。
九、常见问题（FAQ）
Q1：scons 构建报 fatal error: zlib.h: No such file or directory？
实测报错位置与信息如下（buckets/deflate_buckets.c 第 23 行）：
buckets/deflate_buckets.c:23:10: fatal error: zlib.h: No such file or directory
23 | #include <zlib.h>
| ^~~~~~~~
compilation terminated.
scons: *** [buckets/deflate_buckets.o] Error 1
scons: building terminated because of errors.
原因：缺少 zlib 开发头文件。解决：sudo apt-get install -y zlib1g-dev，然后重新执行同一 scons 命令即可（已编译成功的对象文件会被缓存复用）。
Q2：装了 apt 版 1.3.9 又装了源码版 1.3.10，程序运行时加载的是哪个？
由 ldconfig -p 缓存顺序决定。/etc/ld.so.conf.d/serf-1.conf（内容 /usr/local/serf/lib）在字母序上先于 x86_64-linux-gnu.conf，实测缓存如下，/usr/local 的条目排前，运行时优先加载 1.3.10：
libserf-1.so.1 (libc6,x86-64) => /usr/local/serf/lib/libserf-1.so.1
libserf-1.so.1 (libc6,x86-64) => /lib/x86_64-linux-gnu/libserf-1.so.1
libserf-1.so (libc6,x86-64) => /usr/local/serf/lib/libserf-1.so
libserf-1.so (libc6,x86-64) => /lib/x86_64-linux-gnu/libserf-1.so
如需让程序强制走某一版：编译期用 -L 指定库目录 + -Wl,-rpath 固化运行时搜索路径（rpath 优先级高于 ldconfig 缓存），或用 LD_LIBRARY_PATH 临时覆盖。
Q3：Ubuntu 22.04 的 SCons 4.0.1 与 Serf 1.3.10 构建脚本兼容吗？
实测兼容。SCons 4.0.1 下 scons 一次通过（回显见 5.3 节），无需降级或改 SConstruct。
Q4：archive.apache.org 下载慢或失败怎么办？
可改用镜像站同路径 serf-1.3.10.tar.bz2，或提前在可达网络下载后上传到服务器 /opt/ 再解压；校验以 sha256（be81ef08baa2516ecda76a77adf7def7bc3227eeb578b9a33b45f7b41dc064e6）为准。
Q5：运行程序报 error while loading shared libraries: libserf-1.so.1: cannot open shared object file？
源码方案安装后没有执行 ldconfig。执行 echo /usr/local/serf/lib > /etc/ld.so.conf.d/serf-1.conf && ldconfig 即可；若不想改全局配置，也可以在运行前 export LD_LIBRARY_PATH=/usr/local/serf/lib:$LD_LIBRARY_PATH。
十、卸载方式
卸载源码方案（方案 B）：删除安装前缀与 ld 配置后刷新缓存：
rm -rf /usr/local/serf
rm -f /etc/ld.so.conf.d/serf-1.conf
ldconfig
卸载 apt 方案（方案 A）：
sudo apt-get remove -y libserf-dev libserf-1-1
sudo apt-get autoremove -y
清理源码构建目录（可选）：
rm -rf /opt/serf-1.3.10 /opt/serf-1.3.10.tar.bz2
十一、参考链接
- Apache Serf 官方归档下载目录：
https://archive.apache.org/dist/serf/ - Serf 项目主页：
https://serf.apache.org/ - Serf 源码内 API 文档：
serf.h/serf_bucket_types.h（安装于/usr/local/serf/include/serf-1/） - 构建与示例实战：见《Apache Serf 构建并运行示例应用指南》篇