主题
用 Caddy 容器部署静态站的完整链路
目标:一台干净的 Ubuntu 服务器,把构建好的静态目录发布到 https://example.com,证书自动申请自动续期,重启后自恢复,全程不装宿主机软件。
这篇文章的所有命令都在 Ubuntu 24.04 / Docker 27+ 上实跑过。
一、为什么选 Caddy 而不是 nginx + certbot
| 维度 | Caddy | nginx + certbot |
|---|---|---|
| 证书申请 | 配置里写域名即可,自动完成 | 装 certbot、写 webroot、加定时任务 |
| 续期 | 进程内自动,无需 cron | 依赖 systemd timer / cron 生效 |
| 配置量 | 十来行 | 两个 server 块 + 跳转块 |
| 静态托管 | file_server 一行 | root + try_files |
| 灵活度 | 够用,插件生态较小 | 极强,模块化 |
个人站点没有复杂的 upstream 编排需求,Caddy 的「少一个故障点」更有价值。
二、目录与 Compose
text
/opt/site-demo/
├── docker-compose.yml
├── Caddyfile
├── data/ # Caddy 自动管理的证书与状态
├── config/ # Caddy 运行时配置
└── site/ # 构建产物,挂载到容器内 /srvdocker-compose.yml:
yaml
services:
caddy:
image: caddy:2-alpine
container_name: site-demo
restart: unless-stopped
network_mode: host # 直接占用宿主 80/443,省掉端口映射与真实 IP 丢失
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- ./site:/srv:ro
- ./data:/data
- ./config:/config
environment:
- TZ=Asia/Shanghai
network_mode: host在 Linux 上让 Caddy 直接绑定宿主端口,ACME 的 HTTP-01 校验也能正常回源。如果你有多个站点共用 80/443,也仍然可以用 host 模式,由 Caddy 内部按域名分流。
Caddyfile:
text
{
email you@example.com
}
example.com, www.example.com {
root * /srv
encode zstd gzip
try_files {path} {path}.html {path}/index.html
file_server
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
Referrer-Policy "strict-origin-when-cross-origin"
-Server
}
@immutable path /assets/*
header @immutable Cache-Control "public, max-age=31536000, immutable"
handle_errors {
respond "{err.status_code} {err.status_text}" {err.status_code}
}
}几个细节值得说明:
try_files是静态站的关键。预渲染产物常有/foo/index.html与/foo.html两种形态,缺了它会大量 404。encode zstd gzip同时支持两种压缩,Caddy 会按Accept-Encoding协商。- HSTS 一旦下发,浏览器在有效期内只走 HTTPS。确认全站 HTTPS 正常后再开,否则回退很麻烦。
-Server移除响应头里的 Caddy 版本标识,减少指纹信息。
三、启动与首次签发
bash
cd /opt/site-demo
docker compose up -d
docker compose logs -f caddy日志里出现下面两行即表示证书已下发:
text
{"level":"info","msg":"certificate obtained successfully","identifier":"example.com"}
{"level":"info","msg":"serving initial configuration"}验证:
bash
curl -sI https://example.com | head -5
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null \
| openssl x509 -noout -subject -dates -ext subjectAltName应看到 HTTP/2 200、subject=CN=example.com、subjectAltName 同时包含裸域与 www。
四、上线前必须确认的三件事
- DNS 已经生效:
dig +short example.com @8.8.8.8返回本机公网 IP。ACME 校验走公网,DNS 没生效就一定失败。 - 80 端口从公网可达:云厂商安全组 + 本机防火墙都要放行。用手机 4G 访问
http://example.com/.well-known/acme-challenge/测试。 - 没有其他进程占用 80/443:
ss -ltnp | grep -E ':80|:443'应为空。有宝塔、旧 nginx 先停掉。
五、排障顺序
按这个顺序排查,能覆盖九成问题:
bash
# 1. 容器活着吗
docker compose ps
# 2. Caddy 说什么
docker compose logs --tail=100 caddy
# 3. 端口有没有人听
sudo ss -ltnp | grep -E ':80|:443'
# 4. 本机能不能访问自己
curl -sI -H 'Host: example.com' http://127.0.0.1/
# 5. 外网能不能访问
curl -sI --resolve example.com:443:203.0.113.10 https://example.com/
# 6. 证书详情
docker compose exec caddy ls /data/caddy/certificates/acme-v02.api.letsencrypt.org-directory/常见错误对照:
| 日志关键字 | 原因 | 处理 |
|---|---|---|
connection refused during challenge | 80 被安全组挡住 | 放行入站 80 |
no such host | DNS 未生效或解析到别处 | 修正 A 记录,等待 TTL |
too many certificates | 同域名一周内重复签发超限 | 等窗口期,别反复重启 |
address already in use | 80/443 被占用 | 停掉旧服务 |
六、发布脚本
把构建产物同步上去,并做一次健康检查:
bash
#!/usr/bin/env bash
set -euo pipefail
SRC="docs/.vitepress/dist/"
DST="ubuntu@203.0.113.10:/opt/site-demo/site/"
HOST="https://example.com/"
rsync -az --delete \
--exclude '.DS_Store' \
-e 'ssh -i ~/.ssh/deploy.pem' \
"$SRC" "$DST"
code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 15 "$HOST")
if [ "$code" != "200" ]; then
echo "健康检查失败:$code" >&2
exit 1
fi
echo "发布完成:$HOST ($code)"--delete 会删除远端多余文件,注意别把 site/ 之外的目录写进 DST,否则会误删。
小结
一条最小可用链路:Compose 起 Caddy(host 网络)→ 挂载静态目录 → 配置里写两个域名 → 打开 80/443 → docker compose up -d。证书、续期、HTTP 跳转 HTTPS、压缩与缓存头全部内置,剩下的只是往 site/ 里放文件。
相关阅读:JavaScript 事件循环