命令行

Caddy 具有标准的类 Unix 命令行接口。基本用法为：

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

<carets> 表示将被你的输入替换的参数。

[brackets] 表示可选参数。(brackets) 表示必需参数。

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

--flags 可能有一个单字母快捷方式，例如 -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 生成 man 手册页
caddy reload 更改正在运行的 Caddy 进程的配置
caddy respond 一个用于开发和测试的快速且简洁的硬编码 HTTP 服务器
caddy reverse-proxy 一个简单但可用于生产的 HTTP(S) 反向代理
caddy run 在前台启动 Caddy 进程
caddy start 在后台启动 Caddy 进程
caddy stop 停止正在运行的 Caddy 进程
caddy storage export 将配置的存储内容导出为 tar 包
caddy storage import 将之前导出的 tar 包导入到配置的存储中
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 指定要查找的预压缩旁侧文件的编码格式。可重复使用以指定多种格式。更多信息请参见 file_server 指令。

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

`caddy file-server export-template`

caddy file-server export-template

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

`caddy fmt`

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

格式化或美化 Caddyfile，然后退出。除非使用 --overwrite，结果将打印到 stdout，如果有任何差异则以代码 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，因此 admin 端点不得被禁用。

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

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

--address 在 admin 端点没有监听默认地址且与提供的配置文件中的地址不同时需要使用。注意，目前仅支持 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 头；期望格式为 Field: value。此标志可多次使用。

--body 指定响应体。或者，响应体也可以通过 stdin 管道传入。

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

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

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

未指定任何选项时，此命令在随机可用端口监听并以空的 200 响应回答 HTTP 请求。监听地址可以通过 --listen 标志自定义并总是会打印到 stdout。如果监听地址包含端口范围，将启动多个服务器。

如果给定了最终的无名参数，则若该参数是三位数则将被视为状态代码（等同于 --status 标志）。否则，它将被用作响应体（等同于 --body 标志）。--status 和 --body 标志将始终覆盖该参数。

响应体可以通过三种方式提供：通过标志、作为命令的最终（且无名）参数，或通过 stdin 管道（当标志和参数未设置时）。在响应体上支持有限的模板求值（https://pkg.go.dev/text/template），可用变量如下：

Variable	Description
`.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]

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

简单地将来自 --from 地址的 HTTP(S) 流量转发到 --to 地址。可以通过重复该标志指定多个 --to 地址。至少需要一个 --to 地址。--to 地址可以包含端口范围，用作扩展为多个上游的快捷方式。

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

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

如果提供 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 启用详细日志。

此命令会禁用 admin 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 将以空配置运行并使用 admin 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 命令本身的进程）并使其退出。它使用 admin API 的 POST /stop 端点执行优雅关闭。

如果正在运行的实例的 admin API 未使用默认监听地址，则可以使用 --address 标志或从给定的 --config 中获取该地址来定制此请求的地址。

如果你想停止当前配置但不想退出进程，请使用 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 是写入 tar 包的文件名。如果为 -，则将输出写入 stdout。

`caddy storage import`

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

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

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

`caddy trust`

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

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

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

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

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

如果将 admin API 暴露给网络中的其他机器，你也可以在其他机器上使用此 caddy 二进制来安装证书——但在这样做时要小心，不要将 admin API 暴露给不受信任的客户端。

`caddy untrust`

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

从本地信任存储中取消信任根证书。

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

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

此命令有两种使用方式：

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

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

`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 捕获某些信号并忽略其他信号。信号可以触发特定的进程行为。

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

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

退出代码

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

Code	Meaning
`0`	正常退出。
`1`	启动失败。不要自动重启该进程；除非做出更改，否则它很可能会再次出错。
`2`	强制退出。Caddy 在未清理资源的情况下被强制退出。
`3`	退出失败。Caddy 在清理期间出现某些错误后退出。

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