保持 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

状态命令还将显示当前运行的服务文件的位置。

当使用我们的官方服务文件运行时，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 证书。许多网络浏览器现在使用自己的信任存储（忽略系统的信任存储），所以您可能还需要在那里手动安装证书。

覆盖

覆盖服务文件的最佳方式是使用此命令：

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]
# 自动重启 caddy，如果它崩溃，除非退出代码为 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>
  <!-- 服务的显示名称 -->
  <n>Caddy Web Server (powered by WinSW)<n>
  <!-- 服务描述 -->
  <description>Caddy Web Server (https://caddyserver.com/)</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 的"Tags"部分找到它。

这样做的目的是：

• 使用 unless-stopped 重启策略以确保当您的机器重启时 Caddy 容器自动重启。
• 分别为 HTTP 和 HTTPS 绑定端口 80 和 443，加上 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

许多网络浏览器现在使用自己的信任存储（忽略系统的信任存储），所以您可能还需要使用上面命令从容器中复制的 root.crt 文件在那里手动安装证书。

• 对于 Firefox，转到 首选项 > 隐私与安全 > 证书 > 查看证书 > 证书机构 > 导入，然后选择 root.crt 文件。

• 对于 Chrome，转到 设置 > 隐私和安全 > 安全 > 管理证书 > 证书机构 > 导入，然后选择 root.crt 文件。