保持 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 操作首次启动服务

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 证书。许多网络浏览器现在使用自己的信任存储（忽略系统的信任存储），因此您可能还需要在其中手动安装证书。

覆盖

覆盖服务文件各个方面的最佳方法是使用以下命令

sudo systemctl edit caddy

这将在您的默认终端文本编辑器中打开一个空白文件，您可以在其中覆盖或添加单元定义的指令。这被称为“插入”文件。

例如，如果您需要定义要在配置中使用的环境变量，则可以像这样操作

[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 存储库 安装 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://caddyserver.com.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

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

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

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