文件
a project

命令列

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

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

<carets> 表示由您的輸入取代的參數。

[brackets] 表示選用參數。(brackets) 表示必要參數。

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

--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 所看到的環境，然後結束。在除錯 init 系統或程序管理員單元（例如 systemd）時可能很有用。

caddy file-server

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

啟動一個簡單但可供生產使用的靜態檔案伺服器。

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

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

--domain只會透過該主機名稱提供檔案，而 Caddy 會嘗試透過 HTTPS 提供檔案，因此如果它是公用網域名稱，請先確保任何公用 DNS 都已正確設定。預設埠將變更為 443。

--browse如果要求沒有索引檔案的目錄，將啟用目錄清單。

--templates將啟用範本呈現。

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

--debug啟用詳細記錄。

此指令會停用管理 API，讓在本地開發機器上執行多個執行個體變得更容易。

caddy file-server export-template

caddy file-server export-template

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

caddy fmt

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

格式化或美化 Caddyfile，然後結束。除非使用--overwrite，否則結果會列印到 stdout，如果有任何差異，將退出並顯示代碼1。

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

--overwrite會將結果寫入輸入檔案，而不是列印到終端機。如果輸入不是一般檔案，此旗標不會產生作用。

--diff 會將輸出與輸入進行比較，並在不同的行加上 - 和 + 前綴。請注意，未變更的行會加上兩個空格作為對齊，而且這不是有效的修補程式格式；這只是作為一個視覺化工具。

caddy hash-password

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

將純文字密碼進行雜湊處理的便利方法。產生的雜湊會寫入標準輸出，格式可直接用於 Caddy 設定檔中。

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

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

--salt 僅在演算法需要外部鹽值時使用（例如 scrypt）。

請注意，scrypt 已過時。請改用 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 是要套用的設定檔。如果是 -，設定檔會從標準輸入中讀取。如果沒有指定，它會嘗試在目前的工作目錄中尋找一個名為 Caddyfile 的檔案，如果存在，它會使用 caddyfile 設定檔轉接器來調整它；否則，如果沒有要載入的設定檔，這會是一個錯誤。

--adapter 指定要使用的設定檔轉接器（如果有）。

如果管理員端點沒有在預設的地址上監聽，而且與提供的設定檔中的地址不同，則需要使用 --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 指定回應主體。或者，主體可以從標準輸入中傳遞。

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

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

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

如果沒有指定任何選項，這個指令會在一個隨機可用的埠上監聽，並以空的 200 回應來回應 HTTP 請求。監聽地址可以使用 --listen 標記自訂，並且會永遠印出到標準輸出。如果監聽地址包含一個埠範圍，則會啟動多個伺服器。

如果給定一個最後的、未命名的引數，如果它是一個 3 位數，它將被視為狀態碼（與 --status 標記相同）。否則，它將被用作回應主體（與 --body 標記相同）。--status 和 --body 標記將永遠覆寫這個引數。

主體可以用 3 種方式給出：一個標記、一個最後的（且未命名的）指令引數，或傳遞到標準輸入（如果標記和引數未設定）。主體支援有限的 範本評估，其變數如下

變數 說明
.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 反向代理

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 將請求中的主機標頭設定為上游的位址，而不是預設為輸入的主機標頭。

    這是 --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 指定要立即載入和使用的初始設定檔。如果是 -，則從標準輸入讀取設定檔。如果未指定設定檔，Caddy 將執行空白設定檔，並使用 管理 API 端點 的預設設定，可用於提供新的設定檔。特殊情況下，如果目前的作業目錄有一個名為「Caddyfile」的檔案，且 caddyfile 設定檔配接器已插入（預設），則會載入該檔案並用於設定 Caddy，即使沒有任何命令列標記。

--adapter 是在載入初始設定檔時要使用的設定檔配接器名稱（如果有的話）。如果 --config 檔名以「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 旗標不支援 - 從標準輸入讀取設定檔。

不建議在系統服務或 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 沒有使用預設的監聽地址。

您也可以使用此指令搭配 caddy 二進位檔，在網路中的其他機器上安裝憑證，如果管理 API 可供其他機器存取，執行此操作時請小心，不要讓不受信任的用戶端接觸到管理 API。

caddy untrust

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

取消信任來自本機信任儲存體的根憑證。

此指令會解除信任；它不會完全從信任儲存體中刪除根憑證。因此，重複信任和取消信任新憑證可能會填滿信任資料庫。

此指令不會刪除或修改 Caddy 設定儲存空間中的憑證檔案。

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

  • 使用 --cert 旗標指定要取消信任的根憑證的直接路徑。
  • 使用 管理 API 透過 GET /pki/ca/<id>/certificates 端點擷取根憑證。如果沒有提供任何旗標，這是預設行為。

如果使用管理 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 是要使用的設定轉接器的名稱（如果設定檔不是 Caddy 的原生 JSON 格式）。如果設定檔以 Caddyfile 開頭，則預設使用 caddyfile 轉接器。

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

caddy version

caddy version

列印版本並結束。

訊號

Caddy 會攔截某些訊號並忽略其他訊號。訊號可以啟動特定的程序行為。

訊號 行為
SIGINT 正常結束。再次傳送訊號以立即強制結束。
SIGQUIT 立即結束 Caddy，但仍會清除儲存中的鎖定，因為這很重要。
SIGTERM 正常結束。
SIGUSR1 忽略。對於設定更新，請使用 caddy reload 指令或 API。
SIGUSR2 忽略。
SIGHUP 忽略。

正常結束表示不再接受新的連線，且現有的連線會在關閉 socket 之前耗盡。寬限期可能會套用（且可設定）。寬限期過後，連線將會強制終止。在正常關閉期間，會清除儲存中的鎖定和其他個別模組需要釋放的資源。

結束代碼

Caddy 會在程序結束時傳回代碼

代碼 意義
0 正常退出。
1 啟動失敗。不要自動重新啟動程序；除非進行變更，否則可能會再次發生錯誤。
2 強制退出。Caddy 被強制退出，而沒有清理資源。
3 退出失敗。Caddy 在清理過程中出現一些錯誤而退出。

在 bash 中，您可以使用 echo $? 來取得最後一個命令的退出代碼。