动手撸个 Caddy（二）| Caddy 命令行参数最全教程 | 飞雪无情的总结

> 本文由 [简悦 SimpRead](http://ksria.com/simpread/) 转码， 原文地址 [www.flysnow.org](https://www.flysnow.org/2021/07/04/caddy-in-action-command-line.html)

> 动手撸个 Caddy（二）| Caddy 命令行参数最全教程

在上一篇文章中，你已经成功安装了 Caddy，并且使用 `caddy file-server` 命令成功托管了自己的网站，那么这一篇文章中呢，我就为你详细的介绍 Caddy 的命令以及他们的参数。

命令行参数用法
-------

Caddy 是一个标准的 unix-like 命令，它的基本用法为:

```
caddy <command> [<args...>]
```

其中:

1.  `command` 是 caddy 的子命令，比如上一篇文章中的 `file-server` 。子命令是必须的，不能省略。
2.  `args...` 是子命令的参数，可以是 0 个，也可以是多个。

help 命令
-------

一个好的命令行工具，是绝对要有 `help` 命令的，caddy 当然不会例外。通过 `help` 命令，你可以详细的了解 caddy 的用法和帮助说明，可以让我们很快的入门使用。

```
➜  ~ caddy help    
Caddy is an extensible server platform.

usage:
  caddy <command> [<args...>]

commands:
  adapt           Adapts a configuration to Caddy's native JSON
  build-info      Prints information about this build
  environ         Prints the environment
  file-server     Spins up a production-ready file server
  fmt             Formats a Caddyfile
  hash-password   Hashes a password and writes base64
  help            Shows help for a Caddy subcommand
  list-modules    Lists the installed Caddy modules
  reload          Changes the config of the running Caddy instance
  reverse-proxy   A quick and production-ready reverse proxy
  run             Starts the Caddy process and blocks indefinitely
  start           Starts the Caddy process in the background and then returns
  stop            Gracefully stops a started Caddy process
  trust           Installs a CA certificate into local trust stores
  untrust         Untrusts a locally-trusted CA certificate
  upgrade         Upgrade Caddy (EXPERIMENTAL)
  validate        Tests whether a configuration file is valid
  version         Prints the version

Use 'caddy help <command>' for more information about a command.
```

可以看到 `help` 命令列出了 caddy 支持的所有子命令和说明，并且在最后还提醒我们，可以通过 `caddy help <command>` 更详细的了解某个子命令的用法。

现在，我们使用 `caddy help file-server` 来看下我们上一篇文章中，使用的 `file-server` 命令的详细用法。

```
➜  ~ caddy help file-server
//我特意省略了很多描述，不然文字太多了
usage:
  caddy file-server [--domain <example.com>] [--root <path>] [--listen <addr>] [--browse] [--access-log]

flags:
  -access-log
    	Enable the access log
  -browse
    	Enable directory browsing
  -domain string
    	Domain name at which to serve the files
  -listen string
    	The address to which to bind the listener
  -root string
    	The path to the root of the site
  -templates
    	Enable template rendering
```

以上关于 `file-server` 子命令的用法，等下我会详细介绍，这里大家先了解下。

run 命令
------

`run` 会运行一个前台 caddy 进程，直到你使用 `ctrl+c` 或者关闭终端退出。它的用法为：

```
usage:
  caddy run [--config <path> [--adapter <name>]] [--envfile <path>] [--environ] [--resume] [--watch] [--pidfile <fil>]

flags:
  -adapter string
    	如果你使用的配置文件不是以Caddyfile开头的，那么要使用这个标记来指定，比如-adapter caddyfile。
  -config string
    	启动Caddy使用的配置文件
  -envfile string
    	从指定的文件加载环境变量，环境变量的格式为KEY=VALUE
  -environ
    	打印环境变量
  -pidfile string
    	这个大家都知道，用于存放PID的文件
  -pingback string
    	启动成功的信息要回显到pingback指定的ip:port上，这里是通过tcp拨号发送回显信息的。
  -resume
    	这个挺有意思，会使用最近一次自动保存的配置，这对于恢复一个caddy非常有用。这里需要注意的是，当使用这个标记的时候，通过config标记指定的配置就不再生效了。
  -watch
    	这个其实就是在检测到你的配置文件发生变化的时候，自动重新加载配置,这个不要在生产环境使用，自己开发环境用用就得了。
```

现在来看几个例子，这样可以更好的理解 `run` 这个命令。

_示例 1_

```
## 加载当前目录下名称为Caddyfile的配置文件启动caddy，并且监控到配置文件改变的时候，自动重新加载配置。
➜ caddy run -config Caddyfile -watch
```

_示例 2_

```
## 和示例1相比，增加了一个pid文件
➜ caddy run -config Caddyfile -watch -pidfile /var/run/flysnow.pid
```

`run` 命令其他 `flag` 的用法都大同小异，这里不再做演示，你自己可以试一下。

start 命令
--------

`start` 命令的使用 `run` 一样，不同的是 `start` 会启动一个在后台运行的 caddy, 这意味着它不会阻塞终端的使用，你可以去做其他甚至退出当前终端，但是一个 caddy 已经被启动了，你可以正常访问托管的网络服务。

stop 命令
-------

`start` 命令对应的就是 `stop` 命令，需要使用 `stop` 命令通知后台正在运行的 caddy，它的使用格式如下所示：

```
➜  ~ caddy help stop
Stops the background Caddy process as gracefully as possible.

It requires that the admin API is enabled and accessible, since it will
use the API's /stop endpoint. The address of this request can be
customized using the --address flag if it is not the default.

usage:
  caddy stop

flags:
  -address string
    	The address to use to reach the admin API endpoint, if not the default
```

如果你的 `start` 是使用默认的 `localhost:2019` 管理地址启动的，那么直接使用 `stop` 命令就可以优雅的停止 caddy，如果不是默认的，那么需要使用 `-address` 来指定管理地址。

```
//因为我的caddy的管理地址是localhost:2021，所以需要指定才可以停止caddy
caddy stop -address localhost:2021
```

这里有个小提示，caddy 在启动后，不仅可以通过终端命令来管理它，还可以通过 API，也就是说 caddy 提供了一组 API 服务，用于管理它自身，比如加载配置等。这组管理 API 默认的地址就是 `localhost:2019` ，所以当你的 caddy 启动起来后，在浏览器里输入这个地址，就可以看到相应的配置信息了。

reload 命令
---------

通过 `satrt` 启动的 caddy 是不轻易停止的，因为这会导致网络服务不可用。但是你又想使你修改的配置文件生效，怎么办呢？caddy 提供了 `reload` 命令可以帮我们做到，这个 Nginx 是一样的。

```
➜  ~ caddy help reload
usage:
  caddy reload --config <path> [--adapter <name>] [--address <interface>]

flags:
  -adapter string
    	Name of config adapter to apply
  -address string
    	Address of the administration listener, if different from config
  -config string
    	Configuration file (required)
  -force
    	Force config reload, even if it is the same
```

以上就是 `reload` 命令的使用，是不是很眼熟？是的，它和 `run` 命令基本上一直，参数也差不多，可以参考 `run` 命令的使用。 注意：这里的 `address` 参数和 `stop` 命令中的 `address` 是一样的，都是管理 API 的地址，比如`localhost:2019` , 这两个命令，其实都是基于管理 API 实现的。

file-server 命令
--------------

这个命令可以启动一个文件服务，比如托管一个静态网站、把你的文件夹共享在网络上等等。它的使用如下所示：

```
➜  ~ caddy help file-server
//我特意省略了很多描述，不然文字太多了
usage:
  caddy file-server [--domain <example.com>] [--root <path>] [--listen <addr>] [--browse] [--access-log]

flags:
  -access-log
    	启用访问日志
  -browse
    	启用目录浏览
  -domain string
    	指定一个域名
  -listen string
    	监听的地址，http默认是:80,https默认是:443
  -root string
    	要托管的文件服务的根目录
  -templates
    	启用模板渲染
```

关于 file-server 命令的使用可以参考我的这篇 [Caddy 实战（一）| 托管你的网站，只需一行命令](https://www.flysnow.org/2021/06/28/caddy-in-action-getting-started.html) 文章，这里不再赘述。

reverse-proxy 命令
----------------

在 caddy 中，配置一个反向代理非常简单，使用 `reverse-proxy` 命令即可。

```
➜  ~ caddy help reverse-proxy

usage:
  caddy reverse-proxy [--from <addr>] [--to <addr>] [--change-host-header]

flags:
  -change-host-header
    	变更主机头，从传入的值变为上游的值
  -from string
    	用户访问的地址，默认是localhost
  -insecure
    	禁用TLS
  -to string
    	被代理的上游地址,用户看不到这个地址
```

比如你有个后端服务 `127.0.0.1:9000` ，想要代理到 `localhost` ，运行如下命令即可。

```
➜  ~ caddy reverse-proxy --to 127.0.0.1:9000
```

现在，使用 `localhost` 访问，其实就是访问的 `127.0.0.1:9000` 这个后端服务。

假如你想换个端口访问，比如 `localhost:2016` ，只需要运行如下命令即可。

```
➜  ~ caddy reverse-proxy --from :2016 --to 127.0.0.1:9000
```

adapt 命令
--------

caddy 是有自己的配置文件的，它叫 Caddyfile，这是一种可读性、书写性非常强的配置文件，类似 Nginx 的 Config，但是它并不是 caddy 的原生配置文件，caddy 的原生配置文件是 JSON 的，但是非常复杂。

adapt 这个命令就是给我们提供了 Caddyfile 转 JSON 原生配置的能力，让我们可以看到真实的配置是什么。它的用法如下：

```
➜  ~ caddy help adapt
usage:
  caddy adapt --config <path> [--adapter <name>] [--pretty] [--validate]

flags:
  -adapter string
    	配置适配器的名字，默认是 caddyfile。其实就是告诉命令，要使用什么样的适配器，把相应的配置转为JSON原生配置
  -config string
    	配置文件
  -pretty
    	是否美化输出
  -validate
    	可以帮助检验下输出，其实并没有真正的运行caddy
```

比如最简单的 Caddyfile，只有一行 `localhost` ，使用 `adapt` 命令转为 JSON 原生配置的结果如下：

```
➜  ~ caddy adapt --config ~/Desktop/Caddyfile --pretty
{
	"apps": {
		"http": {
			"servers": {
				"srv0": {
					"listen": [
						":443"
					],
					"routes": [
						{
							"match": [
								{
									"host": [
										"localhost"
									]
								}
							],
							"terminal": true
						}
					]
				}
			}
		}
	}
}
```

还是非常复杂的，包括端口、路由的配置都有，所以还是用 Caddyfile 配置效率最高，可读性也强。

fmt 命令
------

这是 caddy 提供的一个辅助工具，可以帮你格式化你的 Caddyfile 配置文件， 让它更美观。

```
➜  ~ caddy help fmt

usage:
  caddy fmt [--overwrite] [<path>]

flags:
  -overwrite
    	用格式化后的结果，覆盖你的配置文件
```

整个命令非常简单，比如我想用这个命令把我的配置文件美化下，并且把美化的结果覆盖我的配置文件，可以这么做。

```
➜  ~ caddy fmt --overwrite ~/Desktop/Caddyfile
```

environ 命令
----------

打印 caddy 知道的环境变量，你可以看到很多关于 caddy 自身和你的系统环境的信息，这对于你调试 caddy 命令非常有用，比如启动不了？路径设置是否错误等等。

它的用法非常简单，在终端输入如下命令，即可看到环境变量信息。

hash-password 命令
----------------

一个自带的密码 Hash 工具，主要用来为配置文件的授权提供 Hash 过的密码，因为不能配置明文密码。

```
➜  ~ caddy help hash-password
usage:
  caddy hash-password [--algorithm <name>] [--salt <string>] [--plaintext <password>]

flags:
  -algorithm string
    	Hash算法，支持scrypt和bcrypt两种，默认是bcrypt
  -plaintext string
    	要Hash的明文密码
  -salt string
    	加点盐，仅当Hash算法是scrypt有效
```

看看这个工具运行的效果。

```
➜  ~ caddy hash-password  --plaintext 1
JDJhJDE0JGJLdzc0M0R1bDUzOTNTWGVJSTV4QU9kMGpQNC5WQTBnZ1E4N3FKOVpXUmQ1NEE2dmRzMWR1
```

list-modules 命令
---------------

caddy 是支持模块的，而且我们可以开发自己的模块，所以这个命令可以列出 caddy 当前已经安装的模块。

```
➜  ~ caddy list-modules --packages
admin.api.load
admin.api.metrics
admin.api.reverse_proxy
caddy.adapters.caddyfile
caddy.config_loaders.http
caddy.listeners.tls
caddy.logging.encoders.console
caddy.logging.encoders.filter
caddy.logging.encoders.filter.delete
caddy.logging.encoders.filter.ip_mask
caddy.logging.encoders.filter.replace
caddy.logging.encoders.json
caddy.logging.encoders.single_field

......
```

build-info 命令
-------------

打印 caddy 的构建信息，主要是 Go Module 的依赖信息，包括包名、版本等。

trust 命令
--------

安装一个根证书到本地信任存储中，可能会需要密码才能安装，主要用于开发环境。大部分情况下，这个命令是用不到的，因为 caddy 启动的时候会自动安装证书。

untrust 命令
----------

从本地信任存储中，卸载一个根证书，也是用于开发环境，和上面的 `trust` 命令是对应的。

```
➜  ~ caddy help untrust
usage:
  caddy untrust [--ca <id> | --cert <path>]

flags:
  -ca string
    	要卸载CA证书的ID，默认为local
  -cert string
    	要卸载CA证书的路径
```

upgrade 命令
----------

这个是升级 caddy 的命令，它会下载最新的二进制文件，然后把本地的给替换了。这个过程并不会停止 caddy 服务，所以不用担心，它仅仅是替换你的 caddy 文件。

当然，为了保险起见，原来的二进制文件还是要备份一下。

validate 命令
-----------

这是一个验证 Caddyfile 配置文件的命令，它会模拟启动 caddy，但是并不会真的启动。验证的过程中，遇到的问题，会在控制台输出。它的使用和 `adapt` 命令基本上一致。

```
➜  ~ caddy help validate
usage:
  caddy validate --config <path> [--adapter <name>]

flags:
  -adapter string
    	配置适配器的名字，默认是 caddyfile
  -config string
    	配置文件的路径
```

version 命令
----------

最简单的一个命令了，打印出 caddy 的版本，大部分的命令行工具都具备。

```
➜  ~ caddy version
(devel)
```

哈哈，看到了吧，我这个其实是我自己编译的一个开发版。

小结
--

这一篇非常详细的介绍了 caddy 命令的使用，建议收藏，需要的时候可以当做手册来用。下一篇开始，就要介绍 Caddyfile 这个配置文件了。

> 本文为原创文章，转载注明出处, 欢迎扫码关注公众号`flysnow_org`或者网站 asf [http://www.flysnow.org/](http://www.flysnow.org/) ，第一时间看后续精彩文章。觉得好的话，请猛击文章右下角「好看」，感谢支持。

[![](https://www.flysnow.org/about/qrcode_for_weixin.jpg)](https://www.flysnow.org/about/qrcode_for_weixin.jpg)