保持 Caddy 運作

雖然可以直接使用 命令列介面 執行 Caddy，但使用服務管理器來保持其運作有許多優點，例如確保系統重新啟動時自動啟動，並捕獲 stdout/stderr 記錄檔。

• Linux 服務
  • Unit 檔案
  • 手動安裝
  • 使用服務
  • 本機 HTTPS
  • 覆寫
    • 環境變數
    • run 和 reload 覆寫
    • 崩潰時重新啟動
  • SELinux 考量
• Windows 服務
  • sc.exe
  • WinSW
• Docker Compose
  • 設定
  • 用法
  • 本機 HTTPS

Linux 服務

在具有 systemd 的 Linux 發行版上執行 Caddy 的建議方式是使用我們的官方 systemd unit 檔案。

Unit 檔案

我們提供了兩個不同的 systemd unit 檔案供您選擇，具體取決於您的使用案例

• caddy.service 如果您使用 Caddyfile 配置 Caddy。如果您更喜歡使用不同的配置轉接器或 JSON 配置檔案，您可以覆寫 ExecStart 和 ExecReload 命令。

• caddy-api.service 如果您僅透過其 API 配置 Caddy。此服務使用 --resume 選項，它將使用預設情況下 持久化 的 autosave.json 啟動 Caddy。

它們非常相似，但在 ExecStart 和 ExecReload 命令中有所不同，以適應工作流程。

如果您需要在服務之間切換，您應該先停用並停止先前的服務，然後再啟用並啟動另一個服務。例如，要從 caddy 服務切換到 caddy-api 服務

sudo systemctl disable --now caddy
sudo systemctl enable --now caddy-api

手動安裝

某些安裝方法會自動設定 Caddy 作為服務執行。如果您選擇的方法沒有這樣做，您可以按照這些指示進行操作

需求

• 您下載或從原始碼建置的 caddy 二進制檔案
• systemctl --version 232 或更新版本
• sudo 權限

將 caddy 二進制檔案移動到您的 $PATH，例如

sudo mv caddy /usr/bin/

測試它是否有效

caddy version

建立名為 caddy 的群組

sudo groupadd --system caddy

建立名為 caddy 且具有可寫入主目錄的使用者

sudo useradd --system \
    --gid caddy \
    --create-home \
    --home-dir /var/lib/caddy \
    --shell /usr/sbin/nologin \
    --comment "Caddy web server" \
    caddy

如果使用配置檔案，請確保您剛建立的 caddy 使用者可以讀取該檔案。

接下來，根據您的使用案例選擇 systemd unit 檔案。

仔細檢查 ExecStart 和 ExecReload 指令。 確保二進制檔案的位置和命令列引數對於您的安裝是正確的！例如：如果使用配置檔案，如果您的 --config 路徑與預設值不同，請更改它。

儲存服務檔案的常用位置是：/etc/systemd/system/caddy.service

儲存服務檔案後，您可以使用常用的 systemctl 指令首次啟動服務

sudo systemctl daemon-reload
sudo systemctl enable --now caddy

驗證它正在運行

systemctl status caddy

現在您可以使用服務了！

使用服務

如果使用 Caddyfile，您可以使用 nano、vi 或您偏好的編輯器編輯您的配置

sudo nano /etc/caddy/Caddyfile

您可以將靜態網站檔案放置在 /var/www/html 或 /srv 中。確保 caddy 使用者具有讀取檔案的權限。

要驗證服務是否正在運行

systemctl status caddy

status 命令也會顯示目前正在運行的服務檔案的位置。

當使用我們的官方服務檔案運行時，Caddy 的輸出將重新導向到 journalctl。要讀取您的完整記錄檔並避免行被截斷

journalctl -u caddy --no-pager | less +G

如果使用配置檔案，您可以在進行任何更改後優雅地重新載入 Caddy

sudo systemctl reload caddy

您可以使用以下命令停止服務

sudo systemctl stop caddy

Caddy 程序將以 caddy 使用者身份運行，其 $HOME 設定為 /var/lib/caddy。這表示

• 預設的 資料儲存位置（用於憑證和其他狀態資訊）將位於 /var/lib/caddy/.local/share/caddy 中。
• 預設的 配置儲存位置（用於自動儲存的 JSON 配置，主要用於 caddy-api 服務）將位於 /var/lib/caddy/.config/caddy 中。

使用 systemd 的本機 HTTPS

當使用 Caddy 進行本機 HTTPS 開發時，您可能會使用像 localhost 或 app.localhost 這樣的 主機名稱。這會啟用 本機 HTTPS，使用 Caddy 的本機 CA 頒發憑證。

由於 Caddy 作為服務運行時以 caddy 使用者身份運行，因此它將沒有權限將其根 CA 憑證安裝到系統信任儲存區。為此，請運行 sudo caddy trust 執行安裝。

如果您希望其他裝置在使用 internal 頒發者 時連線到您的伺服器，您也需要在這些裝置上安裝根 CA 憑證。您可以在 /var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt 找到根 CA 憑證。許多 Web 瀏覽器現在使用它們自己的信任儲存區（忽略系統的信任儲存區），因此您可能還需要在那裡手動安裝憑證。

覆寫

覆寫服務檔案各方面的最佳方法是使用此命令

sudo systemctl edit caddy

這將在您的預設終端文字編輯器中開啟一個空白檔案，您可以在其中覆寫或新增指令到 unit 定義。這稱為「drop-in」檔案。

環境變數

如果您需要定義要在配置中使用的環境變數，您可以這樣做

[Service]
Environment="CF_API_TOKEN=super-secret-cloudflare-tokenvalue"

同樣地，如果您更喜歡維護一個單獨的檔案來維護環境變數（envfile），您可以使用 EnvironmentFile 指令，如下所示

[Service]
EnvironmentFile=/etc/caddy/.env

然後您的 /etc/caddy/.env 檔案可能如下所示（不要在值周圍使用 " 引號）

CF_API_TOKEN=super-secret-cloudflare-tokenvalue

run 和 reload 覆寫

如果您需要將配置檔案從預設的 Caddyfile 更改為改用 JSON 檔案（請注意，Exec* 指令 必須使用空字串重置，然後才能設定新值）

[Service]
ExecStart=
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/caddy.json
ExecReload=
ExecReload=/usr/bin/caddy reload --config /etc/caddy/caddy.json

崩潰時重新啟動

如果您希望 caddy 在意外崩潰後 5 秒自動重新啟動

[Service]
# Automatically restart caddy if it crashes except if the exit code was 1
RestartPreventExitStatus=1
Restart=on-failure
RestartSec=5s

然後，儲存檔案並退出文字編輯器，並重新啟動服務以使其生效

sudo systemctl restart caddy

SELinux 考量

在啟用 SELinux 的系統上，您有兩個選項

1. 使用 COPR 儲存庫 安裝 Caddy。您的 systemd 檔案和 caddy 二進制檔案將已正確建立和標記（因此您可以忽略本節）。如果您希望使用 Caddy 的自訂建置版本，您需要如下所述標記可執行檔。

2. 從本網站下載 Caddy 或使用 xcaddy 編譯它。在任何一種情況下，您都需要自行標記檔案。

Systemd unit 檔案及其可執行檔除非標記為 systemd_unit_file_t 和 bin_t，否則不會運行。

systemd_unit_file_t 標籤會自動應用於在 /etc/systemd/... 中建立的檔案，因此請務必按照手動安裝指示在那裡建立您的 caddy.service 檔案。

要標記 caddy 二進制檔案，您可以使用以下命令

semanage fcontext -a -t bin_t /usr/bin/caddy && restorecon -Rv /usr/bin/caddy

Windows 服務

在 Windows 上將 Caddy 作為服務運行有兩種方法：sc.exe 或 WinSW。

sc.exe

要建立服務，請運行

sc.exe create caddy start= auto binPath= "YOURPATH\caddy.exe run"

（將 YOURPATH 替換為您的 caddy.exe 的實際路徑）

要啟動

sc.exe start caddy

要停止

sc.exe stop caddy

WinSW

按照這些指示在 Windows 上安裝 Caddy 作為服務。

需求

• 您下載或從原始碼建置的 caddy.exe 二進制檔案
• 來自 WinSW 服務包裝器的最新發行版的任何 .exe（以下服務配置是為 v2.x 發行版編寫的）

將所有檔案放入服務目錄。在以下範例中，我們使用 C:\caddy。

將 WinSW-x64.exe 檔案重新命名為 caddy-service.exe。

在同一個目錄中新增 caddy-service.xml

<service>
  <id>caddy</id>
  <!-- Display name of the service -->
  <name>Caddy Web Server (powered by WinSW)</name>
  <!-- Service description -->
  <description>Caddy Web Server (https://caddy.dev.org.tw/)</description>
  <executable>%BASE%\caddy.exe</executable>
  <arguments>run</arguments>
  <log mode="roll-by-time">
    <pattern>yyyy-MM-dd</pattern>
  </log>
</service>

您現在可以使用以下命令安裝服務

caddy-service install

您可能想要啟動 Windows 服務控制台，以查看服務是否正常運行

services.msc

請注意，Windows 服務無法重新載入，因此您必須直接告訴 caddy 重新載入

caddy reload

可以透過正常的 Windows 服務命令重新啟動，例如透過工作管理員的「服務」標籤。

有關自訂服務包裝器的資訊，請參閱 WinSW 文件

Docker Compose

使用 Docker 啟動和運行的最簡單方法是使用 Docker Compose。有關官方 Caddy Docker 映像的更多詳細資訊，請參閱 Docker Hub 上的文件。

設定

首先，建立一個檔案 compose.yml（或將此服務新增到您現有的檔案中）

services:
  caddy:
    image: caddy:<version>
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./site:/srv
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

確保使用最新的版本號填寫映像 <version>，您可以在 Docker Hub 的「標籤」部分找到該版本號。

這會做什麼

• 使用 unless-stopped 重新啟動策略，以確保在您的機器重新啟動時自動重新啟動 Caddy 容器。
• 綁定到埠 80 和 443 分別用於 HTTP 和 HTTPS，以及 443/udp 用於 HTTP/3。
• 綁定掛載 Caddyfile 檔案，這是您的 Caddy 配置。
• 綁定掛載 site 目錄，以從 /srv 提供您網站的靜態檔案。
• 用於 /data 和 /config 的具名卷，以持久化重要資訊。

然後，在 compose.yml 旁邊建立一個名為 Caddyfile 的檔案，並編寫您的 Caddyfile 配置。

如果您有靜態檔案要提供，您可以將它們放置在配置旁邊的 site/ 目錄中，然後使用 root * /srv 設定 root。如果您沒有，則可以移除 /srv 卷掛載。

如果您需要具有插件的 Caddy 自訂建置版本，請按照 Docker 建置指示 建立自訂 Docker 映像。在您的 compose.yml 旁邊建立 Dockerfile，然後將 compose.yml 中的 image: 行替換為 build: .。

用法

然後，您可以啟動容器

docker compose up -d

要在更改 Caddyfile 後重新載入 Caddy

docker compose exec -w /etc/caddy caddy caddy reload

要查看 Caddy 最新的 1000 條記錄檔，並 follow 以查看新的串流

docker compose logs caddy -n=1000 -f

使用 Docker 的本機 HTTPS

當使用 Docker 進行本機 HTTPS 開發時，您可能會使用像 localhost 或 app.localhost 這樣的 主機名稱。這會啟用 本機 HTTPS，使用 Caddy 的本機 CA 頒發憑證。這表示容器外部的 HTTP 客户端將不信任 Caddy 提供的 TLS 憑證。要解決此問題，您可以將 Caddy 的根 CA 憑證安裝到主機機器的信任儲存區

docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    /usr/local/share/ca-certificates/root.crt \
  && sudo update-ca-certificates

docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    /tmp/root.crt \
  && sudo security add-trusted-cert -d -r trustRoot \
    -k /Library/Keychains/System.keychain /tmp/root.crt

docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    %TEMP%/root.crt \
  && certutil -addstore -f "ROOT" %TEMP%/root.crt

許多 Web 瀏覽器現在使用它們自己的信任儲存區（忽略系統的信任儲存區），因此您可能還需要在那裡手動安裝憑證，使用從上述命令中的容器複製的 root.crt 檔案。

• 對於 Firefox，前往「偏好設定」>「隱私權與安全性」>「憑證」>「檢視憑證」>「授權單位」>「匯入」，然後選取 root.crt 檔案。

• 對於 Chrome，前往「設定」>「隱私權和安全性」>「安全性」>「管理憑證」>「授權單位」>「匯入」，然後選取 root.crt 檔案。