命令行

Caddy 有一个标准的类 Unix 命令行界面。基本用法是

caddy <command> [<args...>]

<尖括号> 表示将被您的输入替换的参数。

[方括号] 表示可选参数。(圆括号) 表示必需参数。

省略号 ... 表示延续，即一个或多个参数。

--标志 可能有一个单字母快捷方式，如 -f。

快速开始：caddy，caddy help，或 man caddy（如果已安装）

caddy adapt 将配置文档适配为原生 JSON
caddy build-info 打印构建信息
caddy completion 生成 shell 补全脚本
caddy environ 打印环境变量
caddy file-server 一个简单但生产就绪的文件服务器
caddy file-server export-template 文件服务器的辅助命令，用于导出默认文件浏览器模板
caddy fmt 格式化 Caddyfile
caddy hash-password 哈希密码并输出 base64
caddy help 查看 caddy 命令的帮助
caddy list-modules 列出已安装的 Caddy 模块
caddy manpage 生成 manpage
caddy reload 更改正在运行的 Caddy 进程的配置
caddy respond 一个快速而简洁的、硬编码的 HTTP 服务器，用于开发和测试
caddy reverse-proxy 一个简单但生产就绪的 HTTP(S) 反向代理
caddy run 在前台启动 Caddy 进程
caddy start 在后台启动 Caddy 进程
caddy stop 停止正在运行的 Caddy 进程
caddy storage export 将配置的存储内容导出到 tarball
caddy storage import 将先前导出的 tarball 导入到配置的存储
caddy trust 将证书安装到本地信任存储
caddy untrust 从本地信任存储中移除证书信任
caddy upgrade 将 Caddy 升级到最新版本
caddy add-package 将 Caddy 升级到最新版本，并添加额外的插件
caddy remove-package 将 Caddy 升级到最新版本，并移除一些插件
caddy validate 测试配置文件是否有效
caddy version 打印版本信息
信号 Caddy 如何处理信号
退出代码 Caddy 进程退出时发出的代码

子命令

`caddy adapt`

caddy adapt
	[-c, --config <path>]
	[-a, --adapter <name>]
	[-p, --pretty]
	[--validate]

将配置适配为 Caddy 的原生 JSON 配置结构，并将输出写入 stdout，以及将任何警告写入 stderr，然后退出。

--config 是配置文件的路径。如果省略，则假定为当前目录中的 Caddyfile（如果存在）；否则，此标志是必需的。

--adapter 指定要使用的配置适配器；默认为 caddyfile。

--pretty 将使用缩进格式化输出，以提高人类可读性。

--validate 将加载并配置适配的配置以检查有效性（但它实际上不会开始运行配置）。

请注意，成功适配的配置仍可能无法通过验证。例如，使用此 Caddyfile

localhost

tls cert_notexist.pem key_notexist.pem

尝试适配它

caddy adapt --config Caddyfile

它成功而没有错误。然后尝试

caddy adapt --config Caddyfile --validate
adapt: validation: loading app modules: module name 'tls': provision tls: loading certificates: open cert_notexist.pem: no such file or directory

即使该 Caddyfile 可以无错误地适配为 JSON，但实际的证书和/或密钥文件不存在，因此验证失败，因为该错误在配置阶段出现。因此，验证是比适配更强的错误检查。

示例

要将 Caddyfile 适配为易于阅读和手动调整的 JSON

caddy adapt --config /path/to/Caddyfile --pretty

`caddy build-info`

caddy build-info

打印 Go 提供的关于构建的信息（主模块路径、包版本、模块替换）。

`caddy completion`

caddy completion [bash|zsh|fish|powershell]

生成 shell 补全脚本。这允许您在键入 caddy 命令时获得制表符补全或自动补全（或类似功能，取决于您的 shell）。

要获取将此脚本安装到您的特定 shell 中的说明，请运行 caddy help completion 或 caddy completion -h。

`caddy environ`

caddy environ

打印 caddy 看到的环境变量，然后退出。在调试 init 系统或进程管理器单元（如 systemd）时非常有用。

`caddy file-server`

caddy file-server
	[-r, --root <path>]
	[--listen <addr>]
	[-d, --domain <example.com>]
	[-b, --browse]
	[--reveal-symlinks]
	[-t, --templates]
	[--access-log]
	[-v, --debug]
	[--no-compress]
	[-p, --precompressed]

启动一个简单但生产就绪的静态文件服务器。

--root 指定根文件路径。默认为当前工作目录。

--listen 接受监听器地址。默认为 :80，除非使用了 --domain，则默认为 :443。

--domain 将仅通过该主机名提供文件，并且 Caddy 将尝试通过 HTTPS 提供它，因此如果它是公共域名，请确保首先正确配置任何公共 DNS。默认端口将更改为 443。

--browse 如果请求没有索引文件的目录，将启用目录列表。

--reveal-symlinks 将在目录列表中显示符号链接的目标，当 --browse 启用时。

--templates 将启用模板渲染。

--access-log 启用请求/访问日志。

--debug 启用详细日志记录。

--no-compress 禁用压缩。默认情况下，启用 Zstandard 和 Gzip 压缩。

--precompressed 指定要搜索预压缩 sidecar 文件的编码格式。可以重复多次以指定多种格式。有关更多信息，请参阅 file_server 指令。

此命令禁用管理 API，使其更容易在本地开发机器上运行多个实例。

`caddy file-server export-template`

caddy file-server export-template

将默认文件浏览模板导出到 stdout

`caddy fmt`

caddy fmt [<path>]
	[-w, --overwrite]
	[-d, --diff]

格式化或美化 Caddyfile，然后退出。结果将打印到 stdout，除非使用了 --overwrite，并且如果存在任何差异，将以代码 1 退出。

<path> 指定 Caddyfile 的路径。如果为 -，则从 stdin 读取输入。如果省略，则假定为当前目录中名为 Caddyfile 的文件。

--overwrite 使结果写入到输入文件，而不是打印到终端。如果输入不是常规文件，则此标志无效。

--diff 使输出与输入进行比较，并且差异行将以 - 和 + 作为前缀。请注意，未更改的行以两个空格作为前缀以对齐，并且这不是有效的补丁格式；它仅用作可视化工具。

`caddy hash-password`

caddy hash-password
	[-p, --plaintext <password>]
	[-a, --algorithm <name>]

哈希明文密码的便捷方式。生成的哈希值以可直接在 Caddy 配置中使用的格式写入 stdout。

--plaintext 是密码的明文形式。如果省略，则假定为交互模式，并且将向用户显示提示以手动输入密码。

--algorithm 可以是 bcrypt 或任何已安装的哈希算法。默认为 bcrypt。

`caddy help`

caddy help [<command>]

打印 CLI 帮助文本，可以选择针对特定的子命令，然后退出。

`caddy list-modules`

caddy list-modules
	[--packages]
	[--versions]
	[-s, --skip-standard]

打印已安装的 Caddy 模块，可以选择包含来自其关联 Go 模块的包和/或版本信息，然后退出。

在某些脚本情况下，打印所有标准模块可能显得冗余，因此您可以使用 --skip-standard 从输出中省略这些模块。

注意：由于 Go 中的一个错误，只有当 Caddy 作为依赖项而不是作为主模块构建时，版本信息才可用。使用 xcaddy 可以更轻松地实现这一点。

`caddy manpage`

caddy manpage
	(-o, --directory <path>)

为 Caddy 命令生成手册页/文档页，并将它们写入指定路径的目录。此命令的输出可以由 man 命令读取。

--directory（必需）是要将手册页写入的目录的路径。如果该目录不存在，则将创建它。

生成后，通常需要安装手册页。此过程因平台而异，但在典型的 Linux 系统上，它类似于这样

$ caddy manpage --directory man
$ gzip -r man/
$ sudo cp man/* /usr/share/man/man8/
$ sudo mandb

然后您可以运行 man caddy（或 man caddy-* 用于子命令）以在终端中阅读文档。

手册页是与我们网站上内容不同的文档。我们的网站有更全面的文档，并且经常更新。

`caddy reload`

caddy reload
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--address <interface>]
	[-f, --force]

为正在运行的 Caddy 实例提供新的配置。这与向 /load 端点 POST 文档具有相同的效果，但此命令对于围绕配置文件的简单工作流程非常方便。与 stop、start 和 run 命令相比，此单个命令是更改/重新加载运行配置的正确语义方式。

由于此命令使用 API，因此不得禁用管理端点。

--config 是要应用的配置文件。如果为 -，则从 stdin 读取配置。如果未指定，它将尝试当前工作目录中名为 Caddyfile 的文件，如果存在，则使用 caddyfile 配置适配器适配它；否则，如果没有要加载的配置文件，则会出错。

--adapter 指定要使用的配置适配器（如果有）。如果 --config 文件名以 Caddyfile 开头或以 .caddyfile 结尾，则不需要此标志，这将假定使用 caddyfile 适配器。否则，如果提供的配置文件不是 Caddy 的原生 JSON 格式，则此标志是必需的。

如果管理端点未在默认地址上监听，并且与提供的配置文件中的地址不同，则需要使用 --address。请注意，目前仅支持 TCP 地址。

--force 将导致即使指定的配置与 Caddy 已经运行的配置相同也进行重新加载。这对于强制 Caddy 重新配置其模块可能很有用，这可能会产生副作用，例如：手动重新加载 TLS 证书。

`caddy respond`

caddy respond
	[-s, --status <code>]
	[-H, --header "<Field>: <value>"]
	[-b, --body <content>]
	[-l, --listen <addr>]
	[-v, --debug]
	[--access-log]
	[<status|body>]

启动一个或多个简单的、硬编码的 HTTP 服务器，这些服务器对于开发、暂存和某些生产用例非常有用。它对于验证或调试 HTTP 客户端、脚本甚至负载均衡器非常有用。

--status 是要返回的 HTTP 状态代码。

--header 添加一个 HTTP 标头；期望的格式为 字段: 值。此标志可以多次使用。

--body 指定响应正文。或者，正文可以从 stdin 管道输入。

--listen 是监听器地址，可以是 Caddy 识别的任何网络地址，并且可以包含端口范围以启动多个服务器。

--debug 启用详细调试日志记录。

--access-log 启用访问/请求日志记录。

在未指定任何选项的情况下，此命令在随机可用端口上监听，并使用空的 200 响应来应答 HTTP 请求。可以使用 --listen 标志自定义监听地址，并且始终会打印到 stdout。如果监听地址包含端口范围，则将启动多个服务器。

如果给出了最后一个未命名的参数，则如果它是 3 位数字，则将其视为状态代码（与 --status 标志相同）。否则，它将用作响应正文（与 --body 标志相同）。--status 和 --body 标志将始终覆盖此参数。

可以通过 3 种方式给出正文：一个标志、命令的最后一个（和未命名的）参数，或管道输入到 stdin（如果标志和参数未设置）。正文支持有限的模板评估，具有以下变量

变量	描述
`.N`	服务器编号
`.Port`	监听器端口
`.Address`	监听器地址

示例

在随机端口上的空 200 响应

caddy respond

带有正文的 HTTP 响应

caddy respond "Hello, world!"

多个服务器和模板

$ caddy respond --listen :2000-2004 "I'm server {{.N}} on port {{.Port}}"

Server address: [::]:2000
Server address: [::]:2001
Server address: [::]:2002
Server address: [::]:2003
Server address: [::]:2004

$ curl 127.0.0.1:2002
I'm server 2 on port 2002

管道输入维护页面

cat maintenance.html | caddy respond \
	--listen :80 \
	--status 503 \
	--header "Content-Type: text/html"

`caddy reverse-proxy`

caddy reverse-proxy
	[-f, --from <addr>]
	(-t, --to <addr>)
	[-H, --header-up "<Field>: <value>"]
	[-d, --header-down "<Field>: <value>"]
	[-c, --change-host-header]
	[-r, --disable-redirects]
	[-i, --internal-certs]
	[-v, --debug]
	[--access-log]
	[--insecure]

一个简单但生产就绪的反向代理。适用于快速部署、演示和开发。

只需将 HTTP(S) 流量从 --from 地址传输到 --to 地址。可以通过重复标志来指定多个 --to 地址。至少需要一个 --to 地址。--to 地址可以具有端口范围，作为扩展到多个上游服务器的快捷方式。

除非地址中另有指定，否则如果给出了主机名，则 --from 地址将被假定为 HTTPS，而 --to 地址将被假定为 HTTP。

如果 --from 地址具有主机或 IP，Caddy 将尝试使用证书通过 HTTPS 提供代理服务（除非被 HTTP 方案或端口覆盖）。

如果提供 HTTPS 服务

--disable-redirects 可用于避免绑定到 HTTP 端口。
--internal-certs 可用于强制使用内部 CA 颁发证书，而不是尝试颁发公共证书。

对于代理

--header-up 可用于设置要发送到上游服务器的请求标头。
--header-down 可用于设置要发送回客户端的响应标头。
--change-host-header 将请求中的 Host 标头设置为上游服务器的地址，而不是默认为传入的 Host 标头。

这是 --header-up "Host: {http.reverse_proxy.upstream.hostport}" 的快捷方式
--insecure 禁用与上游服务器的 TLS 验证。警告：此选项通过不验证上游服务器的证书来禁用安全性。
--debug 启用详细日志记录。

此命令禁用管理 API，使其更容易在本地开发机器上运行多个实例。

`caddy run`

caddy run
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--pidfile <file>]
	[-e, --environ]
	[--envfile <file>]
	[-r, --resume]
	[-w, --watch]

运行 Caddy 并无限期阻塞；即“守护进程”模式。

--config 指定要立即加载和使用的初始配置文件。如果为 -，则从 stdin 读取配置。如果未指定任何配置，Caddy 将使用空白配置运行，并为管理 API 端点使用默认设置，可用于向其馈送新配置。作为特殊情况，如果当前工作目录中有一个名为 “Caddyfile” 的文件，并且插入了 caddyfile 配置适配器（默认），则即使没有任何命令行标志，该文件也将被加载并用于配置 Caddy。

--adapter 是加载初始配置时要使用的配置适配器的名称（如果有）。如果 --config 文件名以 Caddyfile 开头或以 .caddyfile 结尾，则不需要此标志，这将假定使用 caddyfile 适配器。否则，如果提供的配置文件不是 Caddy 的原生 JSON 格式，则此标志是必需的。任何警告都将打印到日志中，但请注意，任何没有错误的适配都将立即使用，即使存在警告。如果您想首先查看适配结果，请使用 caddy adapt 子命令。

--pidfile 将 PID 写入指定的文件。

--environ 在启动之前打印出环境变量。这与 caddy environ 命令相同，但不会在打印后退出。

--envfile 从指定的文件加载环境变量，格式为 KEY=VALUE。支持以 # 开头的注释；键可以以 export 为前缀；值可以用双引号括起来（双引号内部可以转义）；支持多行值。

--resume 使用上次加载的自动保存的配置，覆盖 --config 标志（如果存在）。使用此标志可保证配置在机器重启或进程重启时的持久性。它在以 API 为中心的部署中最有用。

--watch 将监视配置文件并在更改后自动重新加载它。⚠️ 此功能仅适用于本地开发环境！

`caddy start`

caddy start
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--envfile <file>]
	[--pidfile <file>]
	[-w, --watch]

与 caddy run 相同，但在后台运行。此命令仅阻塞到后台进程成功运行（或运行失败），然后返回。

注意：标志 --config 不支持使用 - 从 stdin 读取配置。

不建议在系统服务或 Windows 上使用此命令。在 Windows 上，子进程将保持附加到终端，因此关闭窗口将强制停止 Caddy，这并不明显。请考虑作为服务运行 Caddy。

启动后，您可以使用 caddy stop 或 POST /stop API 端点来退出后台进程。

`caddy stop`

caddy stop
	[--address <interface>]
	[-c, --config <path> [-a, --adapter <name>]]

优雅地停止正在运行的 Caddy 进程（除了 stop 命令的进程）并使其退出。它使用管理 API 的 POST /stop 端点来执行优雅关闭。

可以使用 --address 标志或从给定的 --config 自定义此请求的地址，如果正在运行的实例的管理 API 未使用默认监听地址。

如果您想停止当前配置但不希望退出进程，请使用 caddy reload 和空白配置，或 DELETE /config/ 端点。

`caddy storage`

⚠️ 实验性功能

允许导出和导入 Caddy 配置的数据存储的内容。

当需要从一个存储模块转换到另一个存储模块时，这很有用，方法是从旧的存储模块导出，更新您的配置，然后导入到新的存储模块中。

以下命令可用于在一个步骤中复制不同模块之间的存储，使用旧的和新的配置，将导出命令的输出通过管道传输到导入命令。

$ caddy storage export -c Caddyfile.old -o- |
  caddy storage import -c Caddyfile.new -i-

`caddy storage export`

caddy storage export
	-c, --config <path>
	[-o, --output <path>]

--config 是要加载的配置文件。这是必需的，以便连接到正确的存储模块。

--output 是要写入 tarball 的文件名。如果为 -，则将输出写入 stdout。

`caddy storage import`

caddy storage import
	-c, --config <path>
	-i, --input <path>

--config 是要加载的配置文件。这是必需的，以便连接到正确的存储模块。

--input 是要从中读取的 tarball 的文件名。如果为 -，则从 stdin 读取输入。

`caddy trust`

caddy trust
	[--ca <id>]
	[--address <interface>]
	[-c, --config <path> [-a, --adapter <name>]]

将 Caddy 的 PKI 应用程序管理的 CA 的根证书安装到本地信任存储中。

Caddy 将尝试在其首次生成根证书时自动将其安装到本地信任存储中，但如果 Caddy 没有写入信任存储的适当权限，则可能会失败。如果服务器进程以非特权用户身份运行（例如通过 systemd），则此命令对于在使用证书之前预先安装证书是必要的。您可能需要使用 sudo 在 Unix 系统上运行此命令。

默认情况下，此命令安装 Caddy 默认 CA（即 “local”）的根证书。您可以使用 --ca 标志指定另一个 CA 的 ID。

此命令将尝试连接到 Caddy 的管理 API 以获取根证书，使用 GET /pki/ca/<id>/certificates 端点。您可以显式指定 --address，或使用 --config 标志从您的配置中加载管理地址，如果正在运行的实例的管理 API 未使用默认监听地址。

您还可以将 caddy 二进制文件与此命令一起使用，以在网络中的其他机器上安装证书，如果管理 API 可以被其他机器访问 - 如果这样做，请小心不要将管理 API 暴露给不受信任的客户端。

`caddy untrust`

caddy untrust
	[-p, --cert <path>]
	[--ca <id>]
	[--address <interface>]
	[-c, --config <path> [-a, --adapter <name>]]

从本地信任存储中移除根证书的信任。

此命令取消信任；它不一定会从信任存储中完全删除根证书。因此，重复信任和取消信任新证书可能会填满信任数据库。

此命令不会删除或修改 Caddy 配置的存储中的证书文件。

此命令可以通过两种方式使用

通过使用 --cert 标志指定要取消信任的根证书的直接路径。
通过使用 GET /pki/ca/<id>/certificates 端点从管理 API 获取根证书。如果没有给出任何标志，这是默认行为。

如果使用管理 API，则 CA ID 默认为 “local”。您可以使用 --ca 标志指定另一个 CA 的 ID。您可以显式指定 --address，或使用 --config 标志从您的配置中加载管理地址，如果正在运行的实例的管理 API 未使用默认监听地址。

`caddy upgrade`

⚠️ 实验性功能

caddy upgrade
	[-k, --keep-backup]

使用我们的下载页面中的最新版本替换当前的 Caddy 二进制文件，并安装相同的模块，包括 Caddy 网站上注册的所有第三方插件。

升级不会中断正在运行的服务器；目前，该命令仅替换磁盘上的二进制文件。如果我们能找到一种好的方法来做到这一点，将来可能会发生变化。

升级过程具有容错能力；当前二进制文件首先被备份（复制在当前二进制文件旁边），如果出现任何问题，则自动恢复。如果您希望在升级过程完成后保留备份，可以使用 --keep-backup 选项。

如果您的用户没有写入可执行文件的权限，则此命令可能需要提升的权限。

`caddy add-package`

⚠️ 实验性功能

caddy add-package <packages...>
	[-k, --keep-backup]

类似于 caddy upgrade，使用最新版本替换当前的 Caddy 二进制文件，并安装相同的模块，加上作为参数列出的包包含在新二进制文件中。从我们的下载页面查找您可以安装的软件包列表。每个参数都应该是完整的软件包名称。

例如

caddy add-package github.com/caddy-dns/cloudflare

`caddy remove-package`

⚠️ 实验性功能

caddy remove-package <packages...>
	[-k, --keep-backup]

类似于 caddy upgrade，使用最新版本替换当前的 Caddy 二进制文件，并安装相同的模块，但不包括 作为参数列出的包（如果它们存在于当前二进制文件中）。运行 caddy list-modules --packages 以查看当前二进制文件中包含的非标准模块的软件包名称列表。

`caddy validate`

caddy validate
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--envfile <file>]

验证配置文件，然后退出。此命令反序列化配置，然后加载和配置其所有模块，就像要启动配置一样，但实际上并未启动配置。这暴露了在加载或配置阶段出现的配置错误，并且是比仅仅将配置序列化为 JSON 更强的错误检查。

--config 是要验证的配置文件。如果为 -，则从 stdin 读取配置。默认为当前目录中的 Caddyfile（如果有）。

--adapter 是要使用的配置适配器的名称。如果 --config 文件名以 Caddyfile 开头或以 .caddyfile 结尾，则不需要此标志，这将假定使用 caddyfile 适配器。否则，如果提供的配置文件不是 Caddy 的原生 JSON 格式，则此标志是必需的。

`caddy version`

caddy version

打印版本并退出。

信号

Caddy 捕获某些信号并忽略其他信号。信号可以启动特定的进程行为。

信号	行为
`SIGINT`	优雅退出。再次发送信号以立即强制退出。
`SIGQUIT`	立即退出 Caddy，但仍会清理存储中的锁，因为这很重要。
`SIGTERM`	优雅退出。
`SIGUSR1`	忽略。对于配置更新，请使用 `caddy reload` 命令或 API。
`SIGUSR2`	忽略。
`SIGHUP`	忽略。

优雅退出意味着不再接受新连接，并且现有连接将在套接字关闭之前被耗尽。宽限期可能适用（并且是可配置的）。一旦宽限期结束，连接将被强制终止。在优雅关闭期间，将清理存储中的锁以及各个模块需要释放的其他资源。

退出代码

Caddy 在进程退出时返回一个代码

代码	含义
`0`	正常退出。
`1`	启动失败。不要自动重启进程；除非进行更改，否则它很可能会再次出错。
`2`	强制退出。Caddy 被强制退出，未清理资源。
`3`	退出失败。Caddy 在清理期间退出并出现一些错误。

在 bash 中，您可以使用 echo $? 获取最后一个命令的退出代码。