Caddy 实用入门与常用配置速查表

在现代 Web 服务部署中，配置 HTTPS 证书和反向代理往往是让人头疼的环节。Caddy 的出现完美解决了“配置繁琐、忘记续签证书”的经典难题。本文将带你从零开始安装 Caddy，快速梳理核心概念，并汇总个人博客部署和日常服务器运维中最常用的配置模版与命令，建议收藏作为手边备忘录。---

Caddy 的官方推荐安装方式

根据你的使用习惯，Caddy 官方提供了多种安装方式。这里介绍最常用的包管理器安装和 Docker 容器化安装。

方式 A：Debian/Ubuntu 官方源安装 (推荐物理机/云服务器)

这是官方最推荐的生产环境安装方式。依次执行以下命令，添加官方 Cloudsmith 仓库并安装：

bash
# 1. 安装必要的依赖（包含 curl 和 gpg 等）
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl

# 2. 添加官方 GPG 密钥
curl -1sLf '[https://dl.cloudsmith.io/public/caddy/stable/gpg.key](https://dl.cloudsmith.io/public/caddy/stable/gpg.key)' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# 3. 添加 Caddy 官方源列表
curl -1sLf '[https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt](https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt)' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# 4. 更新软件源并安装 Caddy
sudo apt update
sudo apt install caddy

通过此方式安装后，Caddy 会自动注册为 Systemd 服务并默认开机自启。你可以通过 sudo systemctl status caddy 查看运行状态。

方式 B：Docker 一键运行 (推荐容器化玩家)

如果你更喜欢隔离的容器环境，可以直接拉取官方镜像运行。注意要将端口和必要的目录挂载出来以持久化数据和证书：

bash
docker run -d -p 80:80 -p 443:443 -p 443:443/udp \
    --name caddy \
    -v /您的绝对路径/Caddyfile:/etc/caddy/Caddyfile \
    -v caddy_data:/data \
    -v caddy_config:/config \
    caddy:alpine

(注：caddy_data 卷极其重要，它保存了 Caddy 自动申请的 TLS 证书。如果没有持久化这个目录，每次重建容器都会重新申请证书，极易触发 Let's Encrypt 的请求频率限制)

一、 Caddy 核心概念速览

在开始写配置之前，理解以下三个核心概念会让你的部署更加得心应手：

Caddyfile：Caddy 的专属配置文件，默认路径通常在 /etc/caddy/Caddyfile。它的语法极其简洁，摒弃了 Nginx 中那些冗长的分号和复杂的结构。
自动 HTTPS (Automatic HTTPS)：Caddy 的杀手锏。只要你在 Caddyfile 中绑定了有效的公网域名（且域名 A 记录已解析到该服务器），Caddy 就会在后台自动向 Let's Encrypt 或 ZeroSSL 申请证书，并在到期前自动续签。
反向代理 (Reverse Proxy)：最常用的功能。它像是一个“前台接待”，负责将外部互联网通过 80/443 端口发来的请求，安全地转发给服务器内部运行的实际应用（比如运行在 8000 端口的容器服务）。

二、常用配置模版 (Caddyfile Configuration)

修改配置只需编辑 /etc/caddy/Caddyfile 文件。以下是日常建站和部署服务的高频配置代码：

1. 基础反向代理（博客/API/面板）

代理本地端口： (例如：你部署了某博客系统，内部映射到本地 8000 端口。只需两行即可实现外部域名访问 + HTTPS)
```
caddy
blog.yourdomain.com {
    reverse_proxy localhost:8000
}
```

2. 静态网站托管

指定目录映射： (如果你只有纯 HTML/CSS/JS 的静态页面)

caddy
[www.yourdomain.com](https://www.yourdomain.com) {
    root * /var/www/mysite
    file_server
}

3. 多域名与重定向规则

WWW 跳转到主域名： (为了 SEO 和统一入口，强制将带 www 的请求 301 重定向到根域名)

caddy
[www.yourdomain.com](https://www.yourdomain.com) {
    redir [https://yourdomain.com](https://yourdomain.com){uri}
}

yourdomain.com {
    reverse_proxy localhost:8080
}

同时为多个域名配置相同服务：

caddy
site1.com, site2.com {
    reverse_proxy localhost:3000
}

三、服务与状态命令 (Service Commands)

配置文件修改后，我们需要告诉 Caddy 重新加载它们：

1. 配置检查与格式化

校验配置文件语法（核心命令）：
```
bash
caddy validate --config /etc/caddy/Caddyfile
```
(强烈建议每次修改后、重载前执行此命令，避免因语法错误导致网站宕机)
自动格式化 Caddyfile：
```
bash
caddy fmt --overwrite /etc/caddy/Caddyfile
```
(自动帮你调整缩进和换行，强迫症福音)

2. 状态控制 (基于 Systemd 安装)

平滑重载配置：sudo systemctl reload caddy (服务不会中断，当前连接保持，仅加载新配置。修改 Caddyfile 后最常用的命令)
重启 Caddy 服务：sudo systemctl restart caddy
停止 Caddy 服务：sudo systemctl stop caddy

(注：如果是 Docker 部署，平滑重载配置的命令为 docker exec -w /etc/caddy caddy caddy reload)

四、进阶实用技巧 (高阶配置)

这里补充几个在实际排错或特殊网络环境下经常能“救命”的技巧：

查看 Caddy 运行日志：
```
bash
journalctl -u caddy --no-pager | tail -n 50
```
(如果你的域名无法访问，或者证书申请失败，这里通常会打印出 Let's Encrypt 的具体报错原因，比如“DNS 未解析”或“端口被占用”)
本地局域网开发使用自动 HTTPS：如果你的域名是 localhost 或以 .local 结尾，Caddy 不会去公共机构申请证书，而是会在本地自动生成一个“自签发”证书。
```
caddy
localhost {
    reverse_proxy localhost:8080
}
```
反向代理时传递真实 IP： (其实这是个冷知识：与 Nginx 需要手动配置 X-Forwarded-For 不同，Caddy 的 reverse_proxy 指令默认就会自动传递真实的客户端 IP 头信息，无需额外写任何代码！)

总结： Caddy 的配置哲学就是“约定优于配置”。掌握了 reverse_proxy 和 file_server 这两个核心指令，结合 systemctl reload caddy 或 Docker 对应命令实现无缝更新，你就能轻松应对绝大多数的个人博客建站、容器代理和日常 Web 部署场景。

目录