在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

caddyserver/caddy

菜单

命令

相关源文件

本文档涵盖了 Caddy 的命令行界面（CLI）系统，包括内置命令、特定于模块的命令、命令注册和执行流程。CLI 提供了基础的服务器管理操作以及用于配置、模块管理和开发工作流的专门的实用命令。

有关配置管理的信息，请参阅 配置系统。有关某些命令交互的 Admin API 的详细信息，请参阅 Admin API。

命令架构

Caddy 的 CLI 基于 Cobra 框架构建，并采用注册式架构，其中命令被定义为 Command 结构，并在初始化期间注册。该系统支持 Caddy 核心附带的内置命令以及扩展功能的特定于模块的命令。

来源： cmd/commands.go88-538 cmd/cobra.go11-28 cmd/main.go64-79

Command 结构定义了所有命令的接口

字段目的必填
姓名命令名称（必须唯一）是
用途简要语法描述否
短期单行描述是
长期详细帮助文本否
Func命令实现函数是（或 CobraFunc）
CobraFunc高级 Cobra 配置Func 的替代选项

来源： cmd/commands.go30-73

内置命令

Caddy 包含多个内置命令，用于服务器生命周期管理、配置操作和系统工具。

服务器生命周期命令

来源： cmd/commandfuncs.go45-293 cmd/commands.go89-202

启动命令（cmdStart）

将 Caddy 作为后台进程启动并立即返回。在父进程退出前，它使用 pingback 机制来确认启动成功。

主要实现细节

运行命令（cmdRun）

在前台模式下启动 Caddy，无限期阻塞直到进程停止。这是在生产环境中运行 Caddy 的推荐方式。

主要功能

停止命令（cmdStop）

通过调用 Admin API 的 /stop 端点，优雅地停止正在运行的 Caddy 实例。

重新加载命令（cmdReload）

通过 Admin API 的 /load 端点更新正在运行的 Caddy 实例的配置。

来源： cmd/commandfuncs.go295-348

配置命令

来源： cmd/commandfuncs.go443-629 cmd/commands.go272-396

转换命令（cmdAdaptConfig）

使用已注册的配置适配器，将各种格式（通常是 Caddyfile）的配置文件转换为 Caddy 的原生 JSON 格式。

验证命令（cmdValidateConfig）

在不启动服务器的情况下加载和验证配置文件，这对于测试配置很有用。

格式化命令（cmdFmt）

使用正确的缩进和空格格式化 Caddyfile 配置。支持使用 --overwrite 进行就地编辑，以及使用 --diff 显示差异。

实用命令

版本命令（cmdVersion）

显示编译时嵌入的版本信息。

列出模块命令（cmdListModules）

列出所有已加载的 Caddy 模块，并将其归类为标准（Caddy 自带）或非标准（第三方插件）。

构建信息命令（cmdBuildInfo）

显示来自 Go 的 debug.ReadBuildInfo() 的详细构建信息。

环境命令（cmdEnviron）

打印进程环境，有助于调试环境变量问题。

来源： cmd/commandfuncs.go350-441 cmd/commands.go204-270

模块命令

Caddy 模块可以注册自己的命令，以提供专门的功能。这些命令通常侧重于快速部署或开发工作流。

来源： modules/caddyhttp/reverseproxy/command.go37-85 modules/caddyhttp/fileserver/command.go39-83

反向代理命令

提供了一种无需编写完整配置文件即可快速设置反向代理配置的方法。支持多个上游、头部操作和 TLS 配置。

主要功能

  • 自动 HTTPS 和证书管理
  • 跨多个上游负载均衡 modules/caddyhttp/reverseproxy/command.go157-177
  • 使用 --header-up 和 --header-down 进行头部操作
  • 使用 --change-host-header 修改主机头部
  • 使用 --insecure 控制 TLS 验证

文件服务器命令

创建一个生产就绪的静态文件服务器，具有目录浏览、压缩和模板等可选功能。

主要功能

来源: modules/caddyhttp/reverseproxy/command.go87-321 modules/caddyhttp/fileserver/command.go86-224

命令执行流程

来源: cmd/main.go66-79 cmd/cobra.go122-148 cmd/commandfactory.go22-28 cmd/commandfactory.go22-28

执行流程涉及几个关键组件

  1. 主入口点: Main() 函数构建命令树并执行它 cmd/main.go66-79
  2. 命令工厂: rootCommandFactory 组装根命令及其所有已注册的子命令 cmd/commandfactory.go22-28
  3. 标志包装: Flags 包装器提供对命令行标志的类型安全访问 cmd/main.go295-342
  4. 错误处理: 命令返回退出码和错误，由 exitError 处理，该错误会通过 Cobra 执行链传递到主函数 cmd/cobra.go150-161

标志和参数处理

Caddy 使用 pflags 的包装器来提供对命令行参数的类型安全访问

来源: cmd/main.go295-342

Flags 类型提供了访问不同标志类型的方法

  • String(name) - 字符串标志
  • Bool(name) - 布尔标志
  • Int(name) - 整数标志
  • Duration(name) - 持续时间标志 (使用 Caddy 的持续时间解析)
  • GetStringSlice(name) - 字符串切片标志

命令间的常用标志

  • --config - 配置文件路径
  • --adapter - 配置适配器名称
  • --envfile - 环境变量文件路径
  • --watch - 监视配置更改
  • --address - Admin API 地址

来源: cmd/commandfuncs.go46-49 cmd/commandfuncs.go179-185

错误处理和退出码

Caddy 命令使用核心包中定义的标准化退出码

退出码常量目的
0caddy.ExitCodeSuccess成功执行
1caddy.ExitCodeFailedStartup启动或配置失败
2caddy.ExitCodeFailedQuit正常关机失败

命令同时返回退出码和错误。exitError 类型将退出码通过 Cobra 执行链传递到主函数。

来源: cmd/cobra.go150-161 cmd/commandfuncs.go55-56

Admin API 集成

多个命令通过 Admin API 与正在运行的 Caddy 实例进行交互

来源: cmd/commandfuncs.go650-785

AdminAPIRequest() 函数处理

  • TCP、Unix 套接字和文件描述符的网络地址解析
  • 不同网络类型的 HTTP 客户端配置
  • 错误响应解析和报告
  • 请求头管理

DetermineAdminAPIAddress() 函数按优先级解析 Admin 端点地址

  1. 显式 --address 标志
  2. 来自已加载配置的地址
  3. 默认 Admin 监听地址

来源: cmd/commandfuncs.go737-785 cmd/commandfuncs.go650-735