命令行

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

caddy <命令> [<参数...>]

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

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

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

--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 <路径>]
	[-a, --adapter <名称>]
	[-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 命令时获得 tab 补全或自动补全（或类似功能，取决于您的 shell）。

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

`caddy environ`

caddy environ

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

`caddy file-server`

caddy file-server
	[-r, --root <路径>]
	[--listen <地址>]
	[-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 指令了解更多信息。

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

`caddy file-server export-template`

caddy file-server export-template

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

`caddy fmt`

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

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

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

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

--diff 导致输出与输入进行比较，并带有 - 和 + 的行将有所不同。请注意，未更改的行用两个空格进行对齐，这不是有效的补丁格式；它只是作为视觉工具。

`caddy hash-password`

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

方便地对纯文本密码进行哈希处理。结果哈希写入 stdout，作为可以直接在您的 Caddy 配置中使用的格式。

--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 实例一个新的配置。这具有与 POST 到 /load 端点相同的效果，但此命令对于围绕配置文件的简单工作流程更方便。与 stop、start 和 run 命令相比，此单个命令是更改/重新加载正在运行的配置的正确、语义方式。

因为此命令使用 API，管理端点必须不处于禁用状态。

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

--adapter 指定要使用的配置适配器，如果任何。如果 --config 文件名以 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 头；Field: value 格式是预期的。此标志可以多次使用。

--body 指定响应体。或者，体可以从 stdin 管道。

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

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

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

在没有指定选项的情况下，此命令监听随机可用端口并回答 HTTP 请求，响应为空 200。监听地址可以用 --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}}"

服务器地址：[::]:2000
服务器地址：[::]:2001
服务器地址：[::]:2002
服务器地址：[::]:2003
服务器地址：[::]: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 并无限期阻止；即 "daemon" 模式。

--config 指定要立即加载和使用的初始配置文件。如果 -，配置从 stdin 读取。如果没有指定配置，Caddy 将运行空白配置并使用默认设置为 admin API 端点，这可以用于为其提供新配置。作为特殊情况，如果当前工作目录有名为 "Caddyfile" 的文件，并且插入了 caddyfile 配置适配器（默认），则该文件将加载并用于配置 Caddy，即使没有命令行标志。

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

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

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

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

--resume 使用最后加载的自动保存配置，覆盖 --config 标志（如果存在）。使用此标志可确保配置通过机器重启或进程重启保持持久性。它在 API-centric 部署中最有用。

--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 进程（除了停止命令的进程）并导致它退出。它使用 POST /stop 端点管理 API 执行优雅关闭。

此请求的地址可以通过 --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）运行时预先安装证书，如果服务器进程作为非特权用户（例如通过 systemd）运行时。您可能需要使用此命令与 sudo 到 unix 系统。

默认情况下，此命令安装 Caddy 的默认 CA（即 "local") 的根证书。您可以使用 --ca 标志指定其他 CA。

此命令将尝试连接到 Caddy 的 admin 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 标志。
通过从 admin API 使用 GET /pki/ca/<id>/certificates 端点获取根证书。这是默认行为，如果未给出标志。

如果使用管理 API，则 CA ID 默认为 "local"。您可以使用 --ca 标志指定其他 CA。您可以使用 --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 类似，用相同的模块安装最新版本，但 plus 作为参数列出的包，如果它们存在于当前二进制文件中。运行 caddy list-modules --packages 查看非标准模块的包名称列表，这些模块包含在当前二进制文件中。

`caddy remove-package`

⚠️ 实验性

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

与 caddy upgrade 类似，用相同的模块安装最新版本，但 without 作为参数列出的包，如果它们存在于当前二进制文件中。运行 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 $? 获取最后一个命令的退出代码。