文件
由 贊助的專案

慣例

Caddy 生態系統遵循一些慣例，以使整個平台的操作保持一致性和直觀性。

網路位址

當指定要撥號或綁定的網路位址時，Caddy 接受以下格式的字串

network/address

網路部分是可選的（預設為 tcp），並且是 Go 的 net.Dial 函數 可識別的任何內容。如果指定了網路，則必須使用單個正斜線 / 分隔網路和位址部分。

網路可以是以下任何一種；後綴為 4 或 6 的分別僅為 IPv4 或 IPv6

  • TCP：tcp, tcp4, tcp6
  • UDP：udp, udp4, udp6
  • IP：ip, ip4, ip6
  • Unix：unix, unixgram, unixpacket

位址部分可以是以下任何形式

  • 主機
  • 主機:埠號
  • :埠號
  • [ipv6%區域]:埠號
  • /unix/socket 的路徑
  • /unix/socket 的路徑|0200

主機可以是任何主機名稱、可解析的網域名稱或 IP 位址。

對於 IPv6 位址，位址必須用方括號 [] 括起來。區域標識符（以 % 開頭）是可選的（通常用於鏈路本地位址）。

埠號可以是單個值（:8080）或包含範圍（:8080-8085）。埠號範圍將會被展開為單個位址。並非所有配置欄位都接受埠號範圍。特殊的埠號 :0 表示任何可用的埠號。

僅在使用 unix* 網路類型時，unix socket 路徑才是可接受的。分隔網路和位址的正斜線不被視為路徑的一部分。

當 unix socket 用作綁定位址時，您可以選擇在路徑後指定檔案權限模式，並以管道符號 | 分隔。預設值為 0200（八進制），即 u=w,g=,o=（符號表示）。開頭的 0 是可選的。

有效範例

:8080
127.0.0.1:8080
localhost:8080
localhost:8080-8085
tcp/localhost:8080
tcp/localhost:8080-8085
udp/localhost:9005
[::1]:8080
tcp6/[fe80::1%eth0]:8080
unix//path/to/socket
unix//path/to/socket|0200

佔位符

Caddy 的配置支援使用佔位符。使用佔位符是一種將動態值注入到靜態配置中的簡單方法。

佔位符兩側以大括號 { } 包圍，並在內部包含標識符，例如：{foo.bar}。開頭的佔位符大括號可以使用反斜線 \{like.this} 轉義，以防止替換。佔位符標識符通常使用點號進行命名空間劃分，以避免跨模組衝突。

哪些佔位符可用取決於上下文。並非所有佔位符在配置的所有部分都可用。例如，HTTP 應用程式設置的佔位符 僅在與處理 HTTP 請求相關的配置區域中可用。

以下佔位符始終可用（全域）

佔位符 描述
{env.*} 環境變數；範例：{env.HOME}
{file.*} 來自檔案的內容；範例：{file./path/to/secret.txt}
{system.hostname} 系統的本地主機名稱
{system.slash} 系統的檔案路徑分隔符
{system.os} 系統的作業系統
{system.arch} 系統的架構
{system.wd} 當前工作目錄
{time.now} 以 Go Time 結構表示的當前時間
{time.now.http} 以 HTTP 標頭 中使用的格式表示的當前時間
{time.now.unix} 以秒為單位的 Unix 時間戳表示的當前時間
{time.now.unix_ms} 以毫秒為單位的 Unix 時間戳表示的當前時間
{time.now.common_log} 以通用日誌格式表示的當前時間
{time.now.year} 以 YYYY 格式表示的當前年份

並非所有配置欄位都支援佔位符，但大多數在您期望的地方都支援。對佔位符的支援需要顯式添加到這些欄位中。外掛程式作者可以閱讀這篇文章，以了解如何在自己的模組中添加對佔位符的支援。

檔案位置

本節包含有關在何處找到各種檔案的資訊。此處描述的檔案和目錄路徑充其量是預設值；有些可以被覆蓋。

您的配置檔案

沒有單一、傳統的地方供您放置配置檔案。將它們放在對您來說最有意義的任何地方。

隨附預設配置檔案的發行版應記錄此配置檔案的位置，即使對於套件/發行版維護者來說這可能是顯而易見的。對於大多數 Linux 安裝，Caddyfile 將位於 /etc/caddy/Caddyfile。

資料目錄

Caddy 將 TLS 憑證和其他重要資產儲存在資料目錄中，該目錄由配置的儲存模組（預設：本機檔案系統）支援。

如果設置了 XDG_DATA_HOME 環境變數，則為 $XDG_DATA_HOME/caddy。

否則，其路徑因平台而異，並遵循作業系統慣例

作業系統 資料目錄路徑
Linux, BSD $HOME/.local/share/caddy
Windows %AppData%\Caddy
macOS $HOME/Library/Application Support/Caddy
Plan 9 $HOME/lib/caddy
Android $HOME/caddy (或 /sdcard/caddy)

所有其他作業系統都使用 Linux/BSD 目錄路徑。

資料目錄不得視為快取。其內容並非臨時性的，也不僅僅是為了效能。Caddy 將 TLS 憑證、私鑰、OCSP Stapling 和其他必要資訊儲存在資料目錄中。在不了解其影響的情況下，不應清除它。

這個目錄對於 Caddy 來說必須是持久且可寫入的，這一點至關重要。

配置目錄

這是 Caddy 可能將某些配置儲存到磁碟的位置。最值得注意的是，它（預設情況下）將最後一個活動配置持久儲存到此資料夾中，以便稍後使用 caddy run --resume 輕鬆恢復。

如果設置了 XDG_CONFIG_HOME 環境變數，則為 $XDG_CONFIG_HOME/caddy。

否則，其路徑因平台而異，並遵循作業系統慣例

作業系統 配置目錄路徑
Linux, BSD $HOME/.config/caddy
Windows %AppData%\Caddy
macOS $HOME/Library/Application Support/Caddy
Plan 9 $HOME/lib/caddy

所有其他作業系統都使用 Linux/BSD 目錄路徑。

這個目錄對於 Caddy 來說必須是持久且可寫入的，這一點至關重要。

持續時間

持續時間字串在 Caddy 的配置中很常用。它們採用與 Go 的 time.ParseDuration 語法 相同的格式，但您也可以使用 d 表示天（為了簡單起見，我們假設 1 天 = 24 小時）。有效單位為

  • ns（奈秒）
  • us/µs（微秒）
  • ms（毫秒）
  • s（秒）
  • m（分鐘）
  • h（小時）
  • d（天）

範例

  • 250ms
  • 5s
  • 1.5h
  • 2h45m
  • 90d

在 JSON 配置 中，持續時間值也可以是表示奈秒的整數。