Debian 12 自编译 Caddy（含 DNS 插件）并替换 apt 版本

运维
, , ,

在 Debian 12 上，官方 apt 安装的 Caddy 默认不提供 DNS 校验插件（如 Cloudflare 等）。如果需要使用 DNS 挑战来自动签发通配符证书，理想的方案是：

通过 xcaddy 编译定制的 Caddy 二进制，替换官方包运行路径，同时保留并继承官包所提供的的运行用户、标准数据目录及 systemd 守护进程。

一、安装依赖与 xcaddy

首先更新系统，补全包管理器所需的底层工具并安装 Go 代理编译环境。

1
2
3
4
5
6
7
8
9
10
# 1. 依赖安装
sudo apt update
sudo apt install -y golang git build-essential curl gnupg debian-keyring debian-archive-keyring

# 2. 安装主流 Caddy 编译器 xcaddy 
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

# 3. 将 Go 目录添加进用户环境变量并使其生效
echo 'export PATH=$PATH:~/go/bin' >> ~/.bashrc
source ~/.bashrc

二、编译含 DNS 插件的 Caddy

以编译 Cloudflare DNS 辅助解析插件为例配置底层驱动（如需多挂载比如阿里 DNS，继续空格累加 --with 扩展）：

1
xcaddy build --with github.com/caddy-dns/cloudflare

编译完成后，运行以下指令确认是否存在编译目标（caddy 二进制与对应模块）：

1
2
# 验证模块是否打入
./caddy list-modules | grep dns

三、部署 Caddy 官方运行时环境

获取标准的 systemd 服务和目录结构，我们利用官方源将基础框架搭建妥当：

1
2
3
4
5
6
7
8
9
10
11
# 导入密钥
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# 加入 Debian 源
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# 安装原版caddy
sudo apt update
sudo apt install -y caddy

四、替换二进制并阻止 apt 升级覆盖（核心步骤）

这是最重要的步骤。如果不对包管理机制进行强制声明，随后的每次环境升级操作都会覆盖您的自编译产物。

1. 安全搬运与授权

1
2
3
4
5
6
7
8
9
# 备份官方默认二进制文件
sudo mv /usr/bin/caddy /usr/bin/caddy.orig

# 输入我们刚刚手动编译出来的 Caddy 二进制包
sudo cp ./caddy /usr/bin/caddy

# 校正权限
sudo chown root:root /usr/bin/caddy
sudo chmod 755 /usr/bin/caddy

2. ⚡ 锁定 APT 包，禁止系统包管理器覆盖自编译程序

因为 /usr/bin/caddy 当前从物理侧覆盖了软件包原路径文件，如果不加上锁定指令，未来任意一次 apt upgrade 都会自动重拉无插件的官方镜像抹除您的插件！

执行以下命令锁死 Caddy 包：

1
2
# 告知 apt-mark 锁定 Caddy 将其定格于当前版本状态
sudo apt-mark hold caddy

撤销绑定锁定，可执行：sudo apt-mark unhold caddy。

五、Caddyfile 改动实例（DNS Challege）

编辑配置文件 /etc/caddy/Caddyfile。此时由于自备了 TLS 插件，可以配置泛域名：

1
2
3
4
5
6
7
8
*.example.com, example.com {
    tls {
        dns cloudflare 您的_CLOUDFLARE_API_TOKEN
    }

    # 替换为你实际的本地代理接口端口
    reverse_proxy localhost:8080
}

六、装载运行与维护命令

1
2
3
4
5
6
7
8
9
10
11
# 重新扫描 Systemd 系统变更
sudo systemctl daemon-reload

# 校验并验证配置
caddy validate --config /etc/caddy/Caddyfile

# 二进制重新热启动
sudo systemctl restart caddy

# 追踪日志
journalctl -u caddy -f

七、后续自编译升级指南

后续升级定制的 Caddy 同样轻松：

  1. 带新标志运行 xcaddy build --with... 跑编译工程包得到新包。
  2. 直接无缝覆盖：sudo cp ./caddy /usr/bin/caddy 然后修复权限 sudo chown root:root /usr/bin/caddy && sudo chmod 755 /usr/bin/caddy。
  3. 执行 sudo systemctl restart caddy ，不需要解除 apt hold 标记。