讓 Caddy 持續執行

雖然 Caddy 可直接透過其 命令列介面 執行，但使用服務管理員讓它持續執行有許多優點，例如確保它在系統重新開機時自動啟動，以及擷取 stdout/stderr 記錄。

• Linux 服務
  • 單元檔案
  • 手動安裝
  • 使用服務
  • 本機 HTTPS
  • 覆寫
  • SELinux 考量
• Windows 服務
  • sc.exe
  • WinSW
• Docker Compose
  • 設定
  • 用法
  • 本機 HTTPS

Linux 服務

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

單元檔案

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

• 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 單元檔。

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

儲存服務檔的通常位置為：/etc/systemd/system/caddy.service

儲存服務檔後，您可以使用通常的 systemctl dance 首次啟動服務

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

狀態命令還會顯示目前執行的服務檔的位置。

使用我們的官方服務檔執行時，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 進行本機開發時，您可能會使用像 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 憑證。許多網路瀏覽器現在使用自己的信任儲存區（忽略系統的信任儲存區），因此您可能也需要在那裡手動安裝憑證。

覆寫

覆寫服務檔案面向的最佳方式是使用此指令

sudo systemctl edit caddy

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

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

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

類似地，如果您偏好維護一個獨立的檔案來維護環境變數 (envfile)，您可以使用 EnvironmentFile 指令，如下所示

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

或者，例如如果您需要將組態檔案從 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 repo 安裝 Caddy。您的 systemd 檔案和 caddy 二進位檔將會自動建立並正確標籤（因此您可以忽略此部分）。如果您想要使用 Caddy 的自訂建置，您需要依照以下說明標籤可執行檔。

2. 從此網站下載 Caddy 或使用 xcaddy 編譯。無論使用哪一種方式，您都需要自行標籤檔案。

Systemd 單元檔案及其可執行檔在未標籤為 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 Compose 是開始使用 Docker 的最簡單方式。請參閱 Docker Hub 上的文件，以取得有關官方 Caddy Docker 映像的更多其他詳細資訊。

設定

首先，建立一個檔案 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

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

• 對於 Firefox，請前往偏好設定 > 隱私權與安全性 > 憑證 > 查看憑證 > 驗證機構 > 匯入，然後選取 root.crt 檔案。

• 對於 Chrome，請前往設定 > 隱私權和安全性 > 安全性 > 管理憑證 > 驗證機構 > 匯入，然後選取 root.crt 檔案。