命令行

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

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

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

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

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

--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 生成手册页
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]
	[-t, --templates]
	[--access-log]
	[-v, --debug]

启动一个简单但可用于生产环境的静态文件服务器。

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

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

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

--browse 将在请求没有索引文件的目录时启用目录列表。

--templates 将启用模板渲染。

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

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

此命令禁用管理 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>]
	[-s, --salt <string>]

对明文密码进行哈希处理的便捷方法。生成的哈希值将作为可直接在 Caddy 配置中使用的格式写入 stdout。

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

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

--salt 仅在算法需要外部盐（如 scrypt）时使用。

请注意，scrypt 已弃用。请改用 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 实例提供新的配置。这与将文档 POST 到 /load 端点的效果相同，但此命令对于围绕配置文件的简单工作流程来说很方便。与 stop、start 和 run 命令相比，此单个命令是更改/重新加载正在运行的配置的正确语义方法。

因为此命令使用 API，所以管理端点不能被禁用。

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

--adapter 指定要使用的配置适配器（如果有）。

--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 标头；预期使用 Field: value 格式。此标志可以多次使用。

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

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

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

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

如果没有指定选项，此命令将在随机可用的端口上监听，并使用空的 200 响应回复 HTTP 请求。监听地址可以使用 --listen 标志自定义，并将始终打印到标准输出。如果监听地址包含端口范围，则将启动多个服务器。

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

可以通过 3 种方式给出主体：标志、命令的最终（且无名）参数或通过管道传输到标准输入（如果标志和参数未设置）。对主体支持有限的模板评估，使用以下变量

变量	描述
`.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 反向代理`

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 方案或端口覆盖）。

如果提供 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 指定一个初始配置文件，以便立即加载并使用。如果为 -，则从标准输入读取配置。如果未指定配置，Caddy 将使用空白配置运行，并使用管理 API 端点的默认设置，这些设置可用于向其提供新的配置。作为特殊情况，如果当前工作目录中有一个名为“Caddyfile”的文件，并且已插入 caddyfile 配置适配器（默认），则即使没有命令行标志，也会加载并使用该文件来配置 Caddy。

--adapter 是加载初始配置时要使用的配置适配器名称（如果有）。如果 --config 文件名以“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 标志不支持 - 从标准输入读取配置。

不建议在系统服务或 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 的文件名。如果为 -，则输出将写入标准输出。

`caddy storage import`

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

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

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

`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 的管理 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 是要验证的配置文件。如果为 -，则从标准输入读取配置。默认情况下为当前目录中的 Caddyfile（如果有）。

--adapter 是要使用的配置适配器的名称，如果配置文件不是 Caddy 的原生 JSON 格式。如果配置文件以 Caddyfile 开头，则默认情况下使用 caddyfile 适配器。

`caddy 版本`

caddy version

打印版本并退出。

信号

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

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

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

退出代码

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

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

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