Skip to content

建立 2026-09-15 更新 2026-09-15

模組與 xcaddy

Caddy 的外掛是編譯進同一個二進位，不是執行期再 dlopen。官方套件與 Docker image 只含標準模組。Cloudflare、DuckDNS 等 DNS-01 供應商、部分安全或度量外掛，都要另外編。

官方：Extending Caddy、下載頁（勾選模組）、xcaddy。

什麼時候需要自訂編譯

  • 泛域名憑證 *.example.com（只能走 DNS-01）
  • 家用網路／防火牆不開放 80，無法做 HTTP-01
  • 要用標準發行版沒有的 handler（例如某些認證、快取模組）

不需要外掛就不要自訂編譯，比較好升級、也比較好核對 checksum。

用官方下載頁

到 caddyserver.com/download 選作業系統，勾模組後下載。適合偶而編一次、沒有 CI 的情況。把檔案換成系統上的 caddy 後重載或重啟服務。

用 xcaddy

本機已裝 Go 時：

go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
xcaddy build --with github.com/caddy-dns/cloudflare

目前目錄會出現新的 caddy。確認模組有進去：

./caddy list-modules | grep cloudflare

應看到 dns.providers.cloudflare。

Docker 則用官方 caddy:2-builder 多階段 build，見 Docker 部署。

Caddyfile：DNS-01 範例

{
    email you@example.com
}

*.example.com {
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }

    @app host app.example.com
    handle @app {
        reverse_proxy app:3000
    }

    handle {
        respond "Not found" 404
    }
}

Cloudflare token 權限收斂到該 zone 的 Zone.DNS Edit（以及需要的 Zone Read），不要用全域 API key。Token 用環境變數注入，不要提交進 git。

泛域名只覆蓋一層子網域：*.example.com 包含 app.example.com，不包含 foo.bar.example.com。

升級注意

自訂 binary 不能只 apt upgrade。要再跑一次同樣的 xcaddy build（或下載頁、Docker build），再替換檔案並 reload。把 --with 清單寫進 Dockerfile 或小腳本，之後才不會忘記編了哪些模組。