Skip to content

用 Caddy 容器部署静态站的完整链路 ​

目标:一台干净的 Ubuntu 服务器,把构建好的静态目录发布到 https://example.com,证书自动申请自动续期,重启后自恢复,全程不装宿主机软件。

这篇文章的所有命令都在 Ubuntu 24.04 / Docker 27+ 上实跑过。

一、为什么选 Caddy 而不是 nginx + certbot ​

维度Caddynginx + 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/            # 构建产物,挂载到容器内 /srv

docker-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。

四、上线前必须确认的三件事 ​

  1. DNS 已经生效:dig +short example.com @8.8.8.8 返回本机公网 IP。ACME 校验走公网,DNS 没生效就一定失败。
  2. 80 端口从公网可达:云厂商安全组 + 本机防火墙都要放行。用手机 4G 访问 http://example.com/.well-known/acme-challenge/ 测试。
  3. 没有其他进程占用 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 challenge80 被安全组挡住放行入站 80
no such hostDNS 未生效或解析到别处修正 A 记录,等待 TTL
too many certificates同域名一周内重复签发超限等窗口期,别反复重启
address already in use80/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 事件循环