Caddy命令行接口

本页面介绍了Caddy的命令行接口。如果需要快速查看帮助和一些默认值，可以在运行caddy的时候加上参数-help或者-h，比如：caddy -h。

请记住，Caddy没有任何选项也能正常启动。选项只是在需要的时候帮助更好地控制好程序。

选项

• -agree

  表明你已经阅读和同意Let’s Encrypt订阅者协议。如果这个选项没有指明，Caddy有可能在运行过程中要求你同意相关条款。因此，这个选项推荐在自动环境中使用。

• -ca

  指定凭证管理中心的ACME服务的基本网址。用来创建TLS证书。

• -catimeout

  更换ACME CA的HTTP超时时间。这个选项通常没有必要使用，除非你的网络中ACME CA服务有明显延迟。在这种情况下，提升这个值将有所帮助。接收一个时间值；默认值是10s。

• -conf

  指定Caddy的配置文件Caddyfile的所在位置。可以使用绝对或相对地址，但必须是一个有效的路径。还可以是一个通配符字符串，将会把匹配到的所有文件加载进来，就像将他们导入了一个单独文件一样。

• -cpu

  CPU上限。可以是一个百分比（比如“75%”），或者一个表示多少核数的数字（如3）。

• -disable-http-challenge

  禁止用来获取证书的ACME HTTP验证。

• -disable-tls-sni-challenge

  禁止用来获取证书的ACME TLS-SNI验证。

• -disabled-metrics

  用逗号分隔的需要禁用的数据采集指标。注意只有顶级的维度可以被指定（比如“cup”，而不能是”cup.aes_ni”）。

• -email

  当Caddyfile没有指定email时，可以通过这个选项指定用来生成TLS证书的email地址。这不是必须的，但是强烈建议使用，当你丢失掉私钥的时候，可以通过它来找回。如果邮箱地址不可用，Caddy在运行过程中会提示你输入一个email地址。在自动运行环境强烈建议使用此选项。

• -grace

  优雅关闭的等待时长。如果你重载的频率很高（每秒多次），这个时长设置断点。用法和Go的时间相同，使用ParseDuration函数（如5s、1m30s等）。

• -help 或者 -h

  显示基本的帮助。显示完帮助后Caddy将会退出，不会提供站点服务。

• -host

  默认监听的主机名或者IP地址。在Caddyfile没有配置主机名的话将会使用这个。通常会和-port选项一起使用，用来快速搭建不需要Caddyfile的简单站点。

• -http-port

  HTTP协议的端口（默认为80）。需要注意，修改默认端口会带来意外后果。因为ACME的HTTP验证要求必须使用80端口。使用此选项表明是对80端口进行内部转发。

• -https-port

  HTTPS协议的端口（默认为443）。需要注意，修改默认端口会带来意外后果。因为ACME TLS-SNI验证要求必须使用443端口。使用此选项表明是对443端口进行内部转发。

• -http2

  启用HTTP/2支持。要全部禁止它则将其设置为false。如果针对特定站点，可以使用tls指令的alpn设置。

• -log

  启用日志。其值必须是日志文件的路径、stdout或者stderr。如果文件不存在，Caddy将会自动创建。日志文件被用来记录运行期间的信息及错误。当日志文件变大时，会被滚动覆盖，因此长时间运行也是安全的。

• -pidfile

  进程ID文件。适合自动化环境。Caddy将会往文件里边写入当前进程的ID。

• -plugins

  列举在Caddy注册了的插件。打印后Caddy将会终止；不会继续提供站点服务。

• -port

  默认监听的端口。通常和-host结合起来使用，快速启动简单的站点，而不需要Caddyfile。

• -quic

  启用实验性的QUIC的支持。点击查看QUIC的wiki页面了解更多关于QUIC的尝试。

• -quiet

  安静模式。如果设置quiet，Caddy不会打印初始化相关的信息，只输出服务的网址。

• -revoke

  需要撤销SSL证书的主机名。当撤销完成时Caddy将会推出；不会继续服务站点。必须是被Caddy管理的证书才能取消。取消仅限于私钥。不要通过撤销证书去更新它。

• -root

  默认站点的根目录。

• -type

  更换服务类型。默认是http。如果你的Caddyfile用于别的服务类型，通过这个选项告知应该使用哪种类型。

• -validate 解析Caddyfile并退出，如果句法结构正确，将会通过标准输出打印一条信息，记录日志（如果配置了），最后会退出，退出码为0。否则，会报出相应的错误信息，状态码为非0。

• -version

  打印版本。如果不是从一个标记过的发布的版本，同时还会输出构建信息。打印完毕Caddy就退出了；不会继续提供站点服务。

信号

对于POSIX兼容的系统而言，可以通过信号来控制caddy。下面我们粗略按照先强制后优雅的顺序列举相关的控制信号：

• KILL

  强制马上退出进程。这个信号不能被捕捉到，因此caddy对此毫无感知。通过-pidfile指定的pid文件，以及运行时资源都不会被清理。

• QUIT

  不执行关闭时的钩子而强制性退出进程。

• INT

  在执行关闭时的钩子后强制性退出进程。这也是在Windows系统里边唯一支持的信号了（通过Ctrl+C触发）。如果终端再次传输一次SIGINT信号，即使还在执行关闭时的钩子，也会立即退出进程。

• TERM

  在执行完关闭时的钩子后优雅地退出。

• USR1

  重新加载配置文件，然后优雅（平滑）重启服务。如果新的配置文件有错误，错误会打印到日志，配置文件会自动回滚到之前的状态，整个过程是不会中断服务的。

• USR2

  平滑重启进程，重启后使用新的二进制包。这个信号在升级caddy二进制包的时候非常有用。把二进制文件替换为新版本的，并且发生这个心血号，配置信息将会被传输给新的进程。如果发生错误，错误信息将会打印到日志，配置也会回滚，服务不会中断。

短Caddyfile

Caddy也接收非标记参数，可以理解为速记Caddyfile文本。这对于快速的临时服务示例而言无疑非常管用。

每一个未标记的参数是Caddyfile里边的一行，用于服务默认的主机和端口。如果参数包含空格或者特殊字符，务必通过引号将其引用起来。

例如，一个允许你通过默认主机和端口浏览文件的服务：

$ caddy browse

一个在指定端口能马上提供即时markdown文件浏览的服务：

$ caddy -port 8080 markdown

满足上述要求，同时能记录访问日志：

$ caddy -port 8080 browse markdown "log access.log"

这些简易功能仅适合快速、简单的配置。

管道形成的Caddyfile

高级用户可能希望在编程环境通过管道将Caddyfile内容传给Caddy。如果希望通过管道使用Caddyfile，必须使用值为stdin的-conf参数。比如：

$ echo "localhost:1234" | caddy -conf stdin

如果想在你控制的父进程通过动态生成的Caddyfile去启动Caddy，那么使用管道形成Caddyfile会非常方便。

警告: 如果你在Caddyfile使用管道，将不能获取标准输出的字符，这是因为父进程需要发送EOF关闭管道，这样才能停止阻塞开始服务。这会带来一些问题，比如，Caddy有可能提示你输入email地址或者同意协议条款。所以当使用管道输入，需要通过一些额外的参数来避免从标准输入获取内容（比如-email参数）。

环境变量

Caddy识别特定的环境变量。

• HOME

  家目录。Caddy会在这里创建.caddy目录，用来管理TLS（自动化的HTTPS），也有可能保存将来的或者被配置的一些状态。

• CADDYPATH

  如果有这个环境变量，Caddy将会使用这个目录存储一些资料，替代默认的$HOME/.caddy目录。当使用多个Caddy实例服务没有关联的站点（比如一些通过多用户提供的主机服务），强烈建议给每个Caddy实例设置自己的CADDYPATH变量，这样每个实例的状态就能相互保持独立了。

• CASE_SENSITIVE_PATH

  如果设置成1或者true，Caddy在管理文件系统资源或者通过中间件匹配请求时，都将保持大小写敏感。默认值是0（false;意味着对路径大小写不敏感）。

• CADDY_UUID_FILE

  指定实例的UUID文件存储的位置。当有多个Caddy实例被配置使用同样的CADDYPATH时（比如在一个集群中），此变量设置了之后每个实例才能保持独立运行。（它们仍然能使用同样的CADDYPATH,享受共用证书资源的便利等）

退出码

一个好的做法是当退出码为1时，不要自动重启Caddy。