Ubuntu 22.04 安装 Caddy 指南（apt 官方源 编译多方案）

在 Ubuntu 22.04 上通过 Caddy 官方 Cloudsmith apt 源安装 Caddy 2.11.7，覆盖在线安装、配置验证、启动运行与离线安装方案，全部命令与回显均为实测结果

CaddyCaddyWeb 服务器与反向代理2026/10/08

Ubuntu 22.04 安装 Caddy 指南（apt 官方源 编译多方案）

目标：在 Ubuntu 22.04 上通过 Caddy 官方 Cloudsmith apt 源安装 Web 服务器 Caddy（实测 v2.11.7），覆盖在线安装、Caddyfile 配置验证、服务运行与离线 tar.gz 安装方案。全程在 Ubuntu 22.04 真实环境逐步实测，命令与回显均为实际执行结果。

环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • 包管理器：apt 2.4.12 / dpkg 1.21.1
  • Caddy 版本：2.11.7（通过官方 Cloudsmith stable 仓库安装）
  • 默认数据目录：/var/lib/caddy、/var/log/caddy、/etc/caddy/Caddyfile
  • 管理端口：localhost:2019（Admin API）

前置条件

  • 已配置可访问外网的网络（需拉取 Cloudsmith 仓库与证书）
  • 已安装 curl、gnupg2、ca-certificates 等基础工具
  • 若绑定 80/443 等低端口，需给二进制设置 cap_net_bind_service 能力或用 root 运行

一、在线安装方案（A：官方 apt 源）

1.1 安装依赖与导入仓库签名密钥

Caddy 官方提供 Cloudsmith 仓库，先导入其 GPG 公钥（官方说明见 https://caddyserver.com/docs/install）：

sudo apt-get update
sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https ca-certificates curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

💡 说明：密钥被存入 /usr/share/keyrings/ 下的专用 keyring 文件，apt 的 signed-by 指向它，避免污染系统默认信任链。

1.2 添加 Caddy stable 仓库源

将仓库描述写入 /etc/apt/sources.list.d/caddy-stable.list（实测可直接手写该文件，云服务商的 debian.deb.txt 模板亦可）：

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

⚠️ 注意（实测教训）：模板文件里每行是 deb [signed-by=...] https://... any-version main 格式，不要再用 sed 追加 signed-by，否则会生成重复的 [signed-by=...] [signed-by=...]，apt 报 Malformed entry ... (URI parse) 导致仓库不可读。正确写法是直接用 tee 写入或手动编辑。

1.3 安装 Caddy

sudo apt-get update
sudo apt-get install -y caddy

安装完成后验证版本：

caddy version

实测回显：

v2.11.7 h1:yj0Y4fYZGPkSvibBJ1sTWE33xC0fxztVyXEW5iIdUT4=

1.4 查看安装产物

dpkg -l | grep caddy

实测回显：

ii  caddy      2.11.7  amd64  Caddy - Powerful, enterprise-ready, open source web server with automatic HTTPS written in Go

安装包自动创建 systemd 服务单元 /lib/systemd/system/caddy.service、配置目录 /etc/caddy/、数据目录 /var/lib/caddy/ 与日志目录 /var/log/caddy/。

二、配置与启动运行

2.1 编写最小 Caddyfile

创建 /etc/caddy/Caddyfile，实现静态文件服务器：

:8080 {
    root * /usr/share/caddy
    file_server
}

💡 说明：root * 指定站点根目录，file_server 启用静态文件服务。绑定 :8080 避免占用特权端口。

2.2 校验配置

sudo caddy validate --config /etc/caddy/Caddyfile

实测回显（关键行）：

{"level":"info","ts":...,"msg":"adapted config to JSON","adapter":"caddyfile"}
{"level":"info","ts":...,"msg":"started background certificate maintenance","cache":"..."}
Valid configuration

出现 Valid configuration 即表示配置合法。

2.3 前台运行验证

sudo caddy run --config /etc/caddy/Caddyfile

另开终端验证站点：

curl http://127.0.0.1:8080/
curl -sI http://127.0.0.1:8080/

实测回显（index.html 内容为 <h1>Caddy 实测</h1>）：

<h1>Caddy 实测</h1>

响应头（关键行）：

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Etag: "dlz1gona3if7-m"
Server: Caddy
Vary: Accept-Encoding

2.4 后台运行

开发/临时验证可用后台方式，但注意它依赖终端会话保持（对应官方文档建议）：

sudo caddy start --config /etc/caddy/Caddyfile
sudo caddy stop

2.5 systemd 托管（生产推荐）

sudo systemctl enable caddy
sudo systemctl start caddy
sudo systemctl status caddy

💡 说明：systemd 单元默认 ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/Caddyfile，会读取 /etc/caddy/Caddyfile，数据与证书存放在 /var/lib/caddy/。

2.6 低端口绑定能力

需要监听 80/443 时，给二进制授予绑定低端口能力（更换二进制后需重跑）：

sudo setcap cap_net_bind_service=+ep /usr/bin/caddy

三、离线安装方案（B：tar.gz 二进制）

断网环境可从官方下载页（https://caddyserver.com/download）获取对应架构的二进制包：

# 示例：2.11.7 版 linux amd64（完整文件名以官网下载页为准）
wget https://github.com/caddyserver/caddy/releases/download/v2.11.7/caddy_2.11.7_linux_amd64.tar.gz
tar -xzf caddy_2.11.7_linux_amd64.tar.gz
sudo mv caddy /usr/local/bin/
sudo chmod +x /usr/local/bin/caddy

⚠️ 注意：离线部署建议核对下载文件的 SHA-256 校验值；不同架构（arm64 等）选择对应文件名。手动放置的二进制同样可用 caddy version 验证。

四、升级与多版本管理

  • apt 在线升级：sudo apt-get update && sudo apt-get install --only-upgrade caddy，或直接 sudo apt upgrade caddy。

  • 查看仓库候选版本：

    apt-cache policy caddy

    实测回显关键行：

    caddy:
  Installed: 2.11.7
  Candidate: 2.11.7

  • 多版本管理：离线方案下可在 /usr/local/bin 保留多个版本文件，改软链接切换；caddy upgrade 命令（EXPERIMENTAL）亦可直接升级二进制。

五、常见问题（FAQ）

Q1：apt 报 Malformed entry ... (URI parse) A：见 §1.2 实测教训——/etc/apt/sources.list.d/caddy-stable.list 中 [signed-by=...] 重复。重写该文件为单次 signed-by 并 sudo apt-get update 即可。

Q2：caddy run 提示无法绑定 80 端口 A：普通用户无低端口权限。用 root 运行，或执行 sudo setcap cap_net_bind_service=+ep /usr/bin/caddy。

Q3：curl http://127.0.0.1:8080/ 返回 404 A：检查 root * 指向的目录是否存在且包含 index 文件；默认 index 文件名是 index.html。

Q4：日志显示 HTTP/2 skipped because it requires TLS A：这是正常提示——明文 HTTP 监听不启用 HTTP/2。配置 HTTPS（配域名 + 证书）后自动启用。

六、卸载方式

sudo systemctl stop caddy
sudo apt-get remove --purge caddy
sudo rm -f /etc/apt/sources.list.d/caddy-stable.list
sudo rm -f /usr/share/keyrings/caddy-stable-archive-keyring.gpg

⚠️ 注意：--purge 会删除配置与数据目录；如需保留证书数据可先备份 /var/lib/caddy/。

参考链接