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,享受共用证书资源的便利等)

退出码

退出码 含义
0 正常或符合预期的退出
1 服务未启动前就退出了。比如,配置文件出错
2 第二次发送SIGINT(强制退出)
3 发送信号SIGTERM导致的退出
4 关闭时的回调(钩子)执行时产生的错误

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