命令行界面

概述

Caddy 的 CLI 基于 Cobra 命令库构建，提供了全面的命令集以进行各种操作。CLI 遵循命令-子命令模式，其中 caddy 是主命令，后面跟一个子命令，例如 run、start 或 reload。

caddy [command] [flags]

CLI 的设计用户友好，具有描述性的帮助文本和合理的默认值，同时还为高级用户提供了高级功能。

来源： cmd/main.go66-79 cmd/commands.go88-538

CLI 架构

Caddy CLI遵循结构化的设计模式。命令在初始化时注册，并通过一个处理标志、执行命令逻辑和管理退出码的管道进行处理。

来源： cmd/commands.go30-73 cmd/commands.go554-573 cmd/main.go66-79

核心命令

Caddy提供了几个核心命令用于服务器管理

run

启动 Caddy 进程并无限期阻塞（在前台运行）

caddy run [--config <path>] [--adapter <name>] [--envfile <path>] [--environ] [--resume] [--watch] [--pidfile <file>]

主要标志

--config：配置文件路径
--adapter：要应用的配置适配器名称（例如，“caddyfile”）
--envfile：环境变量文件路径
--environ：启动前打印环境变量
--resume：使用上次保存的配置
--watch：监视配置文件更改并自动重新加载
--pidfile：写入进程 ID 的文件路径

来源： cmd/commands.go114-161 cmd/commandfuncs.go172-293

start

将 Caddy 启动到后台，并返回命令提示符

caddy start [--config <path>] [--adapter <name>] [--envfile <path>] [--watch] [--pidfile <file>]

命令 start 会启动一个单独的进程来运行 caddy run，并确认它已成功启动。

来源： cmd/commands.go89-112 cmd/commandfuncs.go45-170

stop

优雅地停止正在运行的 Caddy 实例

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

此命令联系 Admin API 以优雅地关闭服务器。

来源： cmd/commands.go163-180 cmd/commandfuncs.go295-313

reload

更改正在运行的 Caddy 实例的配置

caddy reload --config <path> [--adapter <name>] [--address <interface>] [--force]

此命令将新配置发送到 Admin API，而无需停止服务器。

来源： cmd/commands.go182-202 cmd/commandfuncs.go315-348

命令执行流程

下图说明了 Caddy CLI 中命令的执行方式

来源： cmd/commandfuncs.go45-170 cmd/commandfuncs.go172-293 cmd/commandfuncs.go295-313

配置命令

adapt

将一种配置格式转换为 Caddy 的原生 JSON

caddy adapt --config <path> [--adapter <name>] [--pretty] [--validate] [--envfile <path>]

对于查看 Caddy 如何解释 Caddyfile 或其他配置格式很有用。

来源： cmd/commands.go272-297 cmd/commandfuncs.go443-522

validate

测试配置文件是否有效

caddy validate --config <path> [--adapter <name>] [--envfile <path>]

此操作会加载并配置，但不会启动运行。

来源： cmd/commands.go299-318 cmd/commandfuncs.go524-564

fmt

格式化 Caddyfile

caddy fmt [--overwrite] [--diff] [<path>]

格式化 Caddyfile，提供适当的缩进和间距，以提高可读性。

来源： cmd/commands.go370-396 cmd/commandfuncs.go566-629

信息命令

version

打印 Caddy 的版本

caddy version

来源： cmd/commands.go204-221 cmd/commandfuncs.go350-354

list-modules

列出已安装的 Caddy 模块

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

显示所有已内置到当前 Caddy 二进制文件中的模块。

来源： cmd/commands.go223-233 cmd/commandfuncs.go365-430

build-info

打印 Caddy 二进制文件的构建信息

caddy build-info

来源： cmd/commands.go235-239 cmd/commandfuncs.go356-363

environ

打印 Caddy 进程所看到的运行环境

caddy environ [--envfile <path>]

有助于调试环境变量问题。

来源： cmd/commands.go241-270 cmd/commandfuncs.go432-441 cmd/main.go444-465

高级命令

storage

用于操作 Caddy 存储（证书等）的命令

caddy storage export --config <path> --output <path>
caddy storage import --config <path> --input <path>

来源： cmd/commands.go320-368

专用命令

Caddy 包含多个专用命令，这些命令使用命令行标志构建完整的配置。

reverse-proxy

创建一个生产就绪的反向代理

caddy reverse-proxy [--from <addr>] [--to <addr>] [--change-host-header] [--insecure] [--internal-certs] [--disable-redirects] [--header-up "Field: value"] [--header-down "Field: value"] [--access-log] [--debug]

此命令创建一个具有反向代理功能的完整 HTTP 服务器配置。

来源： modules/caddyhttp/reverseproxy/command.go37-85 modules/caddyhttp/reverseproxy/command.go87-321

file-server

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

caddy file-server [--domain <example.com>] [--root <path>] [--listen <addr>] [--browse] [--reveal-symlinks] [--access-log] [--precompressed]

包含内置压缩（Zstandard 和 Gzip）以及目录浏览功能。

来源： modules/caddyhttp/fileserver/command.go39-84 modules/caddyhttp/fileserver/command.go86-225

包管理

用于管理 Caddy 安装和插件的实验性命令

caddy upgrade [--keep-backup]
caddy add-package <package[@version]...> [--keep-backup]
caddy remove-package <packages...> [--keep-backup]

这些命令使用 Caddy 下载服务来构建带有指定插件的自定义二进制文件。

来源： cmd/commands.go398-441 cmd/packagesfuncs.go36-47 cmd/packagesfuncs.go68-94 cmd/packagesfuncs.go96-122

配置处理

下图显示了 Caddy CLI 如何处理配置文件

来源： cmd/main.go103-105 cmd/main.go141-234 cmd/commandfuncs.go443-522 cmd/main.go344-442

Admin API 交互

许多 CLI 命令与 Caddy 的 Admin API 交互。下图显示了这种交互方式

来源： cmd/commandfuncs.go655-735 cmd/commandfuncs.go743-785

通用标志

许多 Caddy 命令共享通用标志

标志	描述	命令
`--config`	配置文件的路径	run, start, reload, adapt, validate
`--adapter`	要应用的配置适配器名称	run, start, reload, adapt, validate
`--envfile`	环境文件路径	run, start, adapt, validate, environ
`--address`	Admin API 的地址	stop, reload
`--watch`	监视配置文件更改	run, start
`--pidfile`	PID 文件路径	run, start
`--keep-backup`	升级后保留备份二进制文件	upgrade, add-package, remove-package
`--force`	即使配置相同也强制重新加载	reload
`--pretty`	格式化 JSON 输出以提高可读性	adapt
`--validate`	验证适配后的配置	adapt

来源： cmd/commands.go89-318

环境变量

Caddy 使用环境变量进行各种配置方面。这些可以直接设置，也可以使用 --envfile 标志从环境文件中加载。环境变量可以在配置文件中使用语法 {env.VARIABLE_NAME}。

名为 environ 的命令以及 run 命令的 --environ 标志会显示 Caddy 所看到的运行环境，包括：

caddy.HomeDir
caddy.AppDataDir
caddy.AppConfigDir
caddy.ConfigAutosavePath
caddy.Version
运行时信息（操作系统、架构等）

来源： cmd/main.go444-465 cmd/main.go344-442

高级特性

Pingback 机制

在使用 caddy start 时，pingback 机制可确保子进程已成功启动。

来源： cmd/commandfuncs.go45-170 cmd/main.go82-93

配置监控

当使用 --watch 标志时，Caddy 会监控配置文件，并自动重新加载。

来源： cmd/main.go243-293

错误处理

Caddy 命令返回一个退出码和一个错误。退出码由操作系统使用，错误则会显示在控制台上。以下是使用的退出码：

0（ExitCodeSuccess）：命令成功完成。
1（ExitCodeFailedStartup）：Caddy 启动失败。
2（ExitCodeFailedQuit）：Caddy 优雅停止失败。
3（ExitCodeFailedReload）：配置重新加载失败。
4（ExitCodeFailedRestart）：Caddy 重启失败。

来源： cmd/cobra.go137-161

完成和文档

Caddy 提供 shell 自动完成脚本和 man 手册页。

caddy completion [bash|zsh|fish|powershell]
caddy manpage --directory <path>

这些命令会为 Caddy 命令生成 shell 自动完成脚本和手册页。

来源： cmd/commands.go443-537