文件
一個 專案

命令列

Caddy 具有標準的類 Unix 命令列介面。基本用法是

caddy <command> [<args...>]

<角括號> 表示會被您的輸入替換的參數。

[方括號] 表示選用參數。(圓括號) 表示必要參數。

省略符號 ... 表示延續，即一個或多個參數。

--flags 可能會有單字母快捷方式，例如 -f。

快速開始：caddy、caddy help 或 man caddy（如果已安裝）

子命令

caddy adapt

caddy adapt
	[-c, --config <path>]
	[-a, --adapter <name>]
	[-p, --pretty]
	[--validate]

將配置調整為 Caddy 的原生 JSON 配置結構，並將輸出寫入 stdout，以及將任何警告寫入 stderr，然後結束。

--config 是配置檔案的路徑。如果省略，則假設目前目錄中存在 Caddyfile；否則，此標誌為必要。

--adapter 指定要使用的配置轉接器；預設為 caddyfile。

--pretty 將使用縮排格式化輸出，以提高人類可讀性。

--validate 將載入並佈建調整後的配置以檢查其有效性（但實際上不會開始運行配置）。

請注意，成功調整的配置仍然可能驗證失敗。例如，使用此 Caddyfile

localhost

tls cert_notexist.pem key_notexist.pem

嘗試調整它

caddy adapt --config Caddyfile

它成功且沒有錯誤。然後嘗試

caddy adapt --config Caddyfile --validate
adapt: validation: loading app modules: module name 'tls': provision tls: loading certificates: open cert_notexist.pem: no such file or directory

即使該 Caddyfile 可以調整為 JSON 而沒有錯誤，但實際的憑證和/或金鑰檔案不存在，因此驗證失敗，因為該錯誤在佈建階段出現。因此，驗證是比調整更強大的錯誤檢查。

範例

將 Caddyfile 調整為您可以輕鬆閱讀和手動調整的 JSON

caddy adapt --config /path/to/Caddyfile --pretty

caddy build-info

caddy build-info

印出 Go 提供的關於建置的資訊（主要模組路徑、套件版本、模組替換）。

caddy completion

caddy completion [bash|zsh|fish|powershell]

產生 shell 完成腳本。這允許您在輸入 caddy 命令時獲得 Tab 完成或自動完成（或類似功能，取決於您的 shell）。

要取得將此腳本安裝到您的特定 shell 中的說明，請運行 caddy help completion 或 caddy completion -h。

caddy environ

caddy environ

印出 caddy 所看到的環境變數，然後結束。在偵錯初始化系統或程序管理器單元（如 systemd）時可能很有用。

caddy file-server

caddy file-server
	[-r, --root <path>]
	[--listen <addr>]
	[-d, --domain <example.com>]
	[-b, --browse]
	[--reveal-symlinks]
	[-t, --templates]
	[--access-log]
	[-v, --debug]
	[--no-compress]
	[-p, --precompressed]

啟動一個簡單但適用於生產環境的靜態檔案伺服器。

--root 指定根檔案路徑。預設為目前工作目錄。

--listen 接受監聽器位址。預設為 :80，除非使用 --domain，則預設為 :443。

--domain 將僅透過該主機名稱提供檔案，並且 Caddy 將嘗試透過 HTTPS 提供它，因此如果它是公共網域名稱，請確保首先正確配置任何公共 DNS。預設埠將變更為 443。

--browse 將在請求沒有索引檔案的目錄時啟用目錄列表。

--reveal-symlinks 將在啟用 --browse 時，在目錄列表中顯示符號連結的目標。

--templates 將啟用範本渲染。

--access-log 啟用請求/存取日誌。

--debug 啟用詳細記錄。

--no-compress 停用壓縮。預設情況下，Zstandard 和 Gzip 壓縮已啟用。

--precompressed 指定要搜尋預壓縮 sidecar 檔案的編碼格式。可以重複使用以指定多種格式。請參閱 file_server 指令 以取得更多資訊。

此命令停用管理 API，使其更容易在本地開發機器上運行多個實例。

caddy file-server export-template

caddy file-server export-template

將預設檔案瀏覽範本匯出到 stdout

caddy fmt

caddy fmt [<path>]
	[-w, --overwrite]
	[-d, --diff]

格式化或美化 Caddyfile，然後結束。結果會列印到 stdout，除非使用 --overwrite，並且如果存在任何差異，將以代碼 1 結束。

<path> 指定 Caddyfile 的路徑。如果是 -，則從 stdin 讀取輸入。如果省略，則預設為目前目錄中名為 Caddyfile 的檔案。

--overwrite 使結果寫入到輸入檔案，而不是列印到終端機。如果輸入不是常規檔案，則此標誌無效。

--diff 使輸出與輸入進行比較，並且差異行將以 - 和 + 作為前綴。請注意，未變更的行以兩個空格作為前綴以對齊，並且這不是有效的修補程式格式；它僅用作視覺工具。

caddy hash-password

caddy hash-password
	[-p, --plaintext <password>]
	[-a, --algorithm <name>]

雜湊純文字密碼的便捷方式。產生的雜湊值將以可直接在 Caddy 配置中使用的格式寫入 stdout。

--plaintext 是密碼的純文字形式。如果省略，則將假設為互動模式，並且將向使用者顯示提示以手動輸入密碼。

--algorithm 可以是 bcrypt 或任何已安裝的雜湊演算法。預設為 bcrypt。

caddy help

caddy help [<command>]

列印 CLI 說明文字，可選地用於特定子命令，然後結束。

caddy list-modules

caddy list-modules
	[--packages]
	[--versions]
	[-s, --skip-standard]

列印已安裝的 Caddy 模組，可選地包含來自其關聯 Go 模組的套件和/或版本資訊，然後結束。

在某些腳本情況下，列印所有標準模組也可能是多餘的，因此您可以使用 --skip-standard 從輸出中省略這些模組。

注意：由於 Go 中的錯誤，僅當 Caddy 建置為依賴項而不是主要模組時，版本資訊才可用。使用 xcaddy 使此操作更容易。

caddy manpage

caddy manpage
	(-o, --directory <path>)

為 Caddy 命令產生手冊/文件頁面，並將它們寫入指定路徑的目錄。此命令的輸出可以由 man 命令讀取。

--directory（必要）是要在其中寫入手冊頁面的目錄路徑。如果目錄不存在，將會建立它。

產生後，通常需要安裝手冊頁面。此過程因平台而異，但在典型的 Linux 系統上，它類似於這樣

$ caddy manpage --directory man
$ gzip -r man/
$ sudo cp man/* /usr/share/man/man8/
$ sudo mandb

然後您可以運行 man caddy（或子命令的 man caddy-*）以在您的終端機中閱讀文件。

手冊頁面與我們網站上的文件是分開的文件。我們的網站具有更全面的文件，並且經常更新。

caddy reload

caddy reload
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--address <interface>]
	[-f, --force]

為正在運行的 Caddy 實例提供新的配置。這與將文檔 POST 到 /load 端點 具有相同的效果，但是此命令對於圍繞配置檔案的簡單工作流程來說很方便。與 stop、start 和 run 命令相比，此單個命令是變更/重新載入運行配置的正確語義方式。

由於此命令使用 API，因此不得停用管理端點。

--config 是要應用的配置檔案。如果是 -，則從 stdin 讀取配置。如果未指定，它將嘗試目前工作目錄中名為 Caddyfile 的檔案，如果存在，它將使用 caddyfile 配置轉接器調整它；否則，如果沒有要載入的配置檔案，則會發生錯誤。

--adapter 指定要使用的配置轉接器（如果有的話）。如果 --config 檔案名稱以 Caddyfile 開頭或以 .caddyfile 結尾，則不需要此標誌，這表示使用 caddyfile 轉接器。否則，如果提供的配置檔案不是 Caddy 的原生 JSON 格式，則此標誌為必要。

如果管理端點未在預設位址上監聽，並且與提供的配置檔案中的位址不同，則需要使用 --address。請注意，目前僅支援 TCP 位址。

--force 將導致即使指定的配置與 Caddy 已經運行的配置相同，也會發生重新載入。可用於強制 Caddy 重新佈建其模組，這可能會產生副作用，例如：重新載入手動載入的 TLS 憑證。

caddy respond

caddy respond
	[-s, --status <code>]
	[-H, --header "<Field>: <value>"]
	[-b, --body <content>]
	[-l, --listen <addr>]
	[-v, --debug]
	[--access-log]
	[<status|body>]

啟動一個或多個簡單的、硬編碼的 HTTP 伺服器，這些伺服器對於開發、暫存和某些生產用例很有用。它可以用於驗證或偵錯 HTTP 用戶端、腳本，甚至負載平衡器。

--status 是要傳回的 HTTP 狀態代碼。

--header 新增 HTTP 標頭；預期格式為 欄位: 值。此標誌可以多次使用。

--body 指定回應正文。或者，正文可以從 stdin 管道傳輸。

--listen 是監聽器位址，可以是 Caddy 識別的任何 網路位址，並且可能包含埠範圍以啟動多個伺服器。

--debug 啟用詳細偵錯記錄。

--access-log 啟用存取/請求記錄。

在未指定任何選項的情況下，此命令會在隨機可用的埠上監聽，並使用空的 200 回應來回應 HTTP 請求。監聽位址可以使用 --listen 標誌自訂，並且將始終列印到 stdout。如果監聽位址包含埠範圍，則將啟動多個伺服器。

如果給定最後一個未命名的參數，如果它是 3 位數字，則將被視為狀態代碼（與 --status 標誌相同）。否則，它將用作回應正文（與 --body 標誌相同）。--status 和 --body 標誌將始終覆蓋此參數。

可以透過 3 種方式給定正文：標誌、命令的最後一個（和未命名的）參數，或透過管道傳輸到 stdin（如果標誌和參數未設定）。正文支援有限的 範本評估，具有以下變數

變數 描述
.N 伺服器編號
.Port 監聽器埠
.Address 監聽器位址

範例

隨機埠上的空 200 回應

caddy respond

具有正文的 HTTP 回應

caddy respond "Hello, world!"

多個伺服器和範本

$ caddy respond --listen :2000-2004 "I'm server {{.N}} on port {{.Port}}"

Server address: [::]:2000
Server address: [::]:2001
Server address: [::]:2002
Server address: [::]:2003
Server address: [::]:2004

$ curl 127.0.0.1:2002
I'm server 2 on port 2002

透過管道傳輸維護頁面

cat maintenance.html | caddy respond \
	--listen :80 \
	--status 503 \
	--header "Content-Type: text/html"

caddy reverse-proxy

caddy reverse-proxy
	[-f, --from <addr>]
	(-t, --to <addr>)
	[-H, --header-up "<Field>: <value>"]
	[-d, --header-down "<Field>: <value>"]
	[-c, --change-host-header]
	[-r, --disable-redirects]
	[-i, --internal-certs]
	[-v, --debug]
	[--access-log]
	[--insecure]

一個簡單但適用於生產環境的反向代理。適用於快速部署、演示和開發。

僅將 HTTP(S) 流量從 --from 位址傳輸到 --to 位址。可以透過重複標誌來指定多個 --to 位址。至少需要一個 --to 位址。--to 位址可以具有埠範圍作為展開到多個上游伺服器的快捷方式。

除非在位址中另有指定，否則如果給定主機名稱，則 --from 位址將被假定為 HTTPS，而 --to 位址將被假定為 HTTP。

如果 --from 位址具有主機或 IP，則 Caddy 將嘗試透過 HTTPS 使用憑證來提供代理服務（除非被 HTTP 方案或埠覆蓋）。

如果提供 HTTPS 服務

  • 可以使用 --disable-redirects 來避免綁定到 HTTP 埠。

  • 可以使用 --internal-certs 來強制使用內部 CA 頒發憑證，而不是嘗試頒發公共憑證。

對於代理

  • 可以使用 --header-up 來設定要傳送到上游伺服器的請求標頭。

  • 可以使用 --header-down 來設定要傳送回用戶端的回應標頭。

  • --change-host-header 將請求上的 Host 標頭設定為上游伺服器的位址，而不是預設為傳入的 Host 標頭。

    這是 --header-up "Host: {http.reverse_proxy.upstream.hostport}" 的快捷方式

  • --insecure 停用與上游伺服器的 TLS 驗證。警告：這會透過不驗證上游伺服器的憑證來停用安全性。

  • --debug 啟用詳細記錄。

此命令停用管理 API，因此更容易在本地開發機器上運行多個實例。

caddy run

caddy run
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--pidfile <file>]
	[-e, --environ]
	[--envfile <file>]
	[-r, --resume]
	[-w, --watch]

運行 Caddy 並無限期阻止；即“守護程序”模式。

--config 指定要立即載入和使用的初始配置檔案。如果是 -，則從 stdin 讀取配置。如果未指定任何配置，Caddy 將以空白配置運行，並對 管理 API 端點 使用預設設定，這些端點可用於向其饋送新配置。作為一個特例，如果目前工作目錄中有一個名為 "Caddyfile" 的檔案，並且插入了 caddyfile 配置轉接器（預設），則即使沒有任何命令列標誌，也會載入並使用該檔案來配置 Caddy。

--adapter 是在載入初始配置時要使用的配置轉接器的名稱（如果有的話）。如果 --config 檔案名稱以 Caddyfile 開頭或以 .caddyfile 結尾，則不需要此標誌，這表示使用 caddyfile 轉接器。否則，如果提供的配置檔案不是 Caddy 的原生 JSON 格式，則此標誌為必要。任何警告都將列印到日誌中，但請注意，任何沒有錯誤的調整都會立即使用，即使存在警告也是如此。如果您想首先檢閱調整的結果，請使用 caddy adapt 子命令。

--pidfile 將 PID 寫入指定的檔案。

--environ 在啟動之前列印出環境變數。這與 caddy environ 命令相同，但不會在列印後結束。

--envfile 從指定的檔案載入環境變數，格式為 KEY=VALUE。支援以 # 開頭的註解；金鑰可以以 export 作為前綴；值可以用雙引號引起來（雙引號內可以轉義）；支援多行值。

--resume 使用上次載入的自動儲存配置，覆蓋 --config 標誌（如果存在）。使用此標誌可保證配置在機器重新啟動或程序重新啟動時的持久性。它在以 API 為中心的部署中最有用。

--watch 將監視配置檔案，並在檔案變更後自動重新載入它。⚠️ 此功能僅適用於本地開發環境！

caddy start

caddy start
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--envfile <file>]
	[--pidfile <file>]
	[-w, --watch]

與 caddy run 相同，但在背景中運行。此命令僅在背景程序成功運行（或運行失敗）之前阻止，然後返回。

注意：標誌 --config 不支援 - 從 stdin 讀取配置。

不建議在系統服務或 Windows 上使用此命令。在 Windows 上，子程序將保持附加到終端機，因此關閉視窗將強制停止 Caddy，這不明顯。請考慮將 Caddy 作為服務 運行。

啟動後，您可以使用 caddy stop 或 POST /stop API 端點來結束背景程序。

caddy stop

caddy stop
	[--address <interface>]
	[-c, --config <path> [-a, --adapter <name>]]

優雅地停止正在運行的 Caddy 程序（停止命令的程序除外）並使其結束。它使用管理 API 的 POST /stop 端點來執行優雅關閉。

可以使用 --address 標誌或從給定的 --config 自訂此請求的位址，如果正在運行的實例的管理 API 未使用預設監聽位址。

如果您想停止目前的配置但不希望結束程序，請使用 caddy reload 和空白配置，或 DELETE /config/ 端點。

caddy storage

⚠️ 實驗性

允許匯出和匯入 Caddy 配置的資料儲存空間的內容。

當需要從一個 儲存模組 轉換到另一個模組時，這很有用，方法是從舊模組匯出，更新您的配置，然後匯入到新模組中。

以下命令可用於在一個步驟中複製不同模組之間的儲存空間，使用新舊配置，將匯出命令的輸出透過管道傳輸到匯入命令中。

$ caddy storage export -c Caddyfile.old -o- |
  caddy storage import -c Caddyfile.new -i-

caddy storage export

caddy storage export
	-c, --config <path>
	[-o, --output <path>]

--config 是要載入的配置檔案。這是必要的，以便連接到正確的儲存模組。

--output 是要寫入 tarball 的檔案名稱。如果是 -，則輸出將寫入 stdout。

caddy storage import

caddy storage import
	-c, --config <path>
	-i, --input <path>

--config 是要載入的配置檔案。這是必要的，以便連接到正確的儲存模組。

--input 是要從中讀取 tarball 的檔案名稱。如果是 -，則從 stdin 讀取輸入。

caddy trust

caddy trust
	[--ca <id>]
	[--address <interface>]
	[-c, --config <path> [-a, --adapter <name>]]

將 Caddy 的 PKI 應用程式 管理的 CA 的根憑證安裝到本地信任儲存區。

Caddy 會在首次產生根憑證時嘗試自動將其安裝到本地信任儲存區中，但如果 Caddy 沒有寫入信任儲存區的適當權限，則可能會失敗。如果伺服器程序以非特權使用者身份運行（例如透過 systemd），則此命令對於在使用憑證之前預先安裝憑證是必要的。您可能需要使用 sudo 在 Unix 系統上運行此命令。

預設情況下，此命令會安裝 Caddy 預設 CA（即 "local"）的根憑證。您可以使用 --ca 標誌指定另一個 CA 的 ID。

此命令將嘗試連接到 Caddy 的 管理 API 以獲取根憑證，使用 GET /pki/ca/<id>/certificates 端點。您可以明確指定 --address，或使用 --config 標誌從您的配置中載入管理位址，如果正在運行的實例的管理 API 未使用預設監聽位址。

如果管理 API 可供其他機器存取，您也可以將 caddy 二進制檔案與此命令一起使用，以在您網路中的其他機器上安裝憑證 - 如果這樣做，請小心不要將管理 API 暴露給不受信任的用戶端。

caddy untrust

caddy untrust
	[-p, --cert <path>]
	[--ca <id>]
	[--address <interface>]
	[-c, --config <path> [-a, --adapter <name>]]

從本地信任儲存區移除根憑證的信任。

此命令會移除信任；它不一定會從信任儲存區中完全刪除根憑證。因此，重複信任和移除新憑證的信任可能會填滿信任資料庫。

此命令不會刪除或修改 Caddy 配置的儲存空間中的憑證檔案。

此命令可以使用兩種方式之一

  • 透過使用 --cert 標誌指定要移除信任的根憑證的直接路徑。
  • 透過使用 GET /pki/ca/<id>/certificates 端點從 管理 API 獲取根憑證。如果未給定任何標誌，這是預設行為。

如果使用管理 API，則 CA ID 預設為 "local"。您可以使用 --ca 標誌指定另一個 CA 的 ID。您可以明確指定 --address，或使用 --config 標誌從您的配置中載入管理位址，如果正在運行的實例的管理 API 未使用預設監聽位址。

caddy upgrade

⚠️ 實驗性

caddy upgrade
	[-k, --keep-backup]

將目前的 Caddy 二進制檔案替換為 我們的下載頁面 中的最新版本，並安裝相同的模組，包括 Caddy 網站上註冊的所有第三方外掛程式。

升級不會中斷正在運行的伺服器；目前，該命令僅替換磁碟上的二進制檔案。如果我們可以找到一種好的方法來執行此操作，則將來可能會更改。

升級過程具有容錯能力；目前的二進制檔案會先備份（複製在目前檔案旁邊），如果出現任何問題，則會自動還原。如果您希望在升級過程完成後保留備份，可以使用 --keep-backup 選項。

如果您的使用者沒有寫入可執行檔案的權限，則此命令可能需要提升的權限。

caddy add-package

⚠️ 實驗性

caddy add-package <packages...>
	[-k, --keep-backup]

與 caddy upgrade 類似，將目前的 Caddy 二進制檔案替換為最新版本，並安裝相同的模組，加上 新二進制檔案中包含的參數中列出的套件。從 我們的下載頁面 找到您可以安裝的套件列表。每個參數都應該是完整的套件名稱。

範例

caddy add-package github.com/caddy-dns/cloudflare

caddy remove-package

⚠️ 實驗性

caddy remove-package <packages...>
	[-k, --keep-backup]

與 caddy upgrade 類似，將目前的 Caddy 二進制檔案替換為最新版本，並安裝相同的模組，但不包含 參數中列出的套件（如果它們存在於目前的二進制檔案中）。運行 caddy list-modules --packages 以查看目前二進制檔案中包含的非標準模組的套件名稱列表。

caddy validate

caddy validate
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--envfile <file>]

驗證配置檔案，然後結束。此命令反序列化配置，然後載入並佈建其所有模組，就像要啟動配置一樣，但實際上並未啟動配置。這會暴露在載入或佈建階段出現的配置中的錯誤，並且是比僅將配置序列化為 JSON 更強大的錯誤檢查。

--config 是要驗證的配置檔案。如果是 -，則從 stdin 讀取配置。預設為目前目錄中的 Caddyfile（如果有的話）。

--adapter 是要使用的配置轉接器的名稱。如果 --config 檔案名稱以 Caddyfile 開頭或以 .caddyfile 結尾，則不需要此標誌，這表示使用 caddyfile 轉接器。否則，如果提供的配置檔案不是 Caddy 的原生 JSON 格式，則此標誌為必要。

--envfile 從指定的檔案載入環境變數，格式為 KEY=VALUE。支援以 # 開頭的註解；金鑰可以以 export 作為前綴；值可以用雙引號引起來（雙引號內可以轉義）；支援多行值。

caddy version

caddy version

印出版本並結束。

信號

Caddy 捕獲某些信號並忽略其他信號。信號可以啟動特定的程序行為。

信號 行為
SIGINT 優雅結束。再次發送信號以立即強制結束。
SIGQUIT 立即退出 Caddy，但仍然清理儲存空間中的鎖定，因為這很重要。
SIGTERM 優雅結束。
SIGUSR1 已忽略。對於配置更新，請使用 caddy reload 命令或 API。
SIGUSR2 已忽略。
SIGHUP 已忽略。

優雅結束表示不再接受新連線，並且現有連線將在關閉套接字之前被耗盡。寬限期可能適用（並且是可配置的）。寬限期結束後，連線將被強制終止。在優雅關閉期間，將清理儲存空間中的鎖定以及各個模組需要釋放的其他資源。

結束代碼

Caddy 在程序結束時傳回一個代碼

代碼 含義
0 正常結束。
1 啟動失敗。請勿自動重新啟動程序；除非進行變更，否則它很可能會再次出錯。
2 強制退出。Caddy 被強制退出，沒有清理資源。
3 退出失敗。Caddy 在清理期間退出時發生了一些錯誤。

在 bash 中，您可以使用 echo $? 取得上一個命令的結束代碼。