保持 Caddy 运行

虽然可以直接使用 命令行界面 运行 Caddy，但使用服务管理器来保持其运行有很多优势，例如确保它在系统重启时自动启动并捕获 stdout/stderr 日志。

• Linux 服务
  • 单元文件
  • 手动安装
  • 使用服务
  • 本地 HTTPS
  • 覆盖
    • 环境变量
    • run 和 reload 覆盖
    • 崩溃时重启
  • 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 命令首次启动该服务

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 这样的主机名。这使用 Caddy 的本地 CA 颁发证书来启用 本地 HTTPS。

由于 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

这将使用您的默认终端文本编辑器打开一个空白文件，您可以在其中覆盖或向单元定义添加指令。这称为“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_file_t 和 bin_t 分别标记 systemd 单元文件及其可执行文件，否则它们将不会运行。

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.golang.ac.cn/)</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 这样的主机名。这使用 Caddy 的本地 CA 颁发证书来启用 本地 HTTPS。这意味着容器外部的 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 文件。