Debian / Ubuntu 使用 xcaddy 自定义编译 Caddy

本文将指导使用 xcaddy 自定义编译 Caddy。

以下操作需要 root 权限，本文命令均已带上 sudo 前缀，请确保当前用户拥有 sudo 权限；或者直接使用 root 用户操作并省略命令中的 sudo。

上一篇文章介绍了如何安装使用 Caddy，但是 Caddy 的功能有时候并不能满足业务需求，如果想要使用更多的功能，就需要自定义编译 Caddy。

xcaddy 是 Caddy 官方制作的用于自定义编译 Caddy 的工具，它可以帮助我们快速的编译出符合自己需求的 Caddy。

#安装 xcaddy

我们按照官方的安装方法，首先，安装一些必要的软件包：

bash

sudo apt update
sudo apt upgrade -y
sudo apt install curl vim wget gnupg dpkg apt-transport-https lsb-release ca-certificates

然后按照官方教程安装 Go：

bash

wget https://go.dev/dl/go1.24.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.5.linux-amd64.tar.gz

然后把 go 加入系统环境变量：

bash

echo "export PATH=\$PATH:/usr/local/go/bin" | sudo tee -a /etc/profile

然后加入 Caddy 的 GPG 公钥和 apt 源：

bash

curl -sSL https://dl.cloudsmith.io/public/caddy/xcaddy/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/xcaddy.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/xcaddy.gpg] https://dl.cloudsmith.io/public/caddy/xcaddy/deb/debian any-version main" | sudo tee /etc/apt/sources.list.d/xcaddy.list

Debian 下也可以使用 extrepo：

bash

sudo apt install extrepo
sudo extrepo enable caddyserver

然后更新系统后即可安装 xcaddy：

bash

sudo apt update
sudo apt install xcaddy

重启打开 SSH 后检查一下 go 和 xcaddy 的版本：

bash

root@debian ~ # go version
go version go1.24.5 linux/amd64

root@debian ~ # xcaddy version
v0.4.5 h1:7E4b+3Gm2do/WpuDXh5MWIj+qgCCvQqR487Sm8C6hwc=

#自定义编译 Caddy

我们可以选择一些自己喜欢的模块，比如缓存模块和 Brotli 压缩模块：

bash

xcaddy build \
    --with github.com/caddyserver/cache-handler \
	  --with github.com/ueffel/caddy-brotli

经过一段时间的编译以后，我们就可以在当前目录下看到一个名为 caddy 的二进制文件，这就是我们自定义编译的 Caddy 了。

#自定义 Caddy 和系统 Caddy 共存

如果我们想要自定义 Caddy 和系统 Caddy 共存，可以使用官方的教程：

首先，按照我们的教程安装 Caddy，安装完毕后，先停止 Caddy 服务：

bash

sudo systemctl stop caddy

然后使用 dpkg-divert 命令将系统 Caddy 的二进制文件移动到 /usr/bin/caddy.default 并做软链接：

bash

sudo dpkg-divert --divert /usr/bin/caddy.default --rename /usr/bin/caddy

然后把我们自己编译好的 Caddy 二进制文件移动到 /usr/bin/caddy.custom：

bash

sudo mv ./caddy /usr/bin/caddy.custom

然后设置优先级，让我们的自定义 Caddy 优先启动：

bash

sudo update-alternatives --install /usr/bin/caddy caddy /usr/bin/caddy.default 10
sudo update-alternatives --install /usr/bin/caddy caddy /usr/bin/caddy.custom 50

此时我们可以看到默认的 /usr/bin/caddy 已经是我们自定义的 Caddy 了：

bash

root@debian ~ # ls -l /usr/bin/caddy
lrwxrwxrwx 1 root root 23 Jan 22 10:52 /usr/bin/caddy -> /etc/alternatives/caddy*

root@debian ~ # ls -l /etc/alternatives/caddy
lrwxrwxrwx 1 root root 21 Jan 22 10:52 /etc/alternatives/caddy -> /usr/bin/caddy.custom

我们也可以使用 sudo update-alternatives --config caddy 命令来切换系统安装的 Caddy 和自定义的 Caddy：

bash

root@caddy ~ # update-alternatives --config caddy
There are 2 choices for the alternative caddy (providing /usr/bin/caddy).

  Selection    Path                    Priority   Status
------------------------------------------------------------
* 0            /usr/bin/caddy.custom    50        auto mode
  1            /usr/bin/caddy.custom    50        manual mode
  2            /usr/bin/caddy.default   10        manual mode

Press <enter> to keep the current choice[*], or type selection number:

我们可以看到默认的 Caddy 二进制文件是我们自定义的，你可以输入 0 (按照优先级自动) 1 (手工切换自定义 Caddy) 或 2 (使用系统默认 Caddy) 来修改并切换默认的 Caddy 版本。