Caddy 基本命令 #

命令概览 #

Caddy 提供了一套完整的命令行工具，用于管理服务、配置和证书：

text

┌─────────────────────────────────────────────────────────────┐
│                    Caddy 命令概览                            │
├─────────────────────────────────────────────────────────────┤
│  🚀 run        启动 Caddy 服务器                             │
│  🔄 reload     重载配置文件                                   │
│  🛠️ adapt      转换配置格式                                   │
│  ✅ validate   验证配置文件                                   │
│  📝 fmt        格式化 Caddyfile                              │
│  📋 list-modules 列出模块                                    │
│  📦 environ    显示环境变量                                   │
│  📖 version    显示版本信息                                   │
└─────────────────────────────────────────────────────────────┘

启动命令（run） #

基本启动 #

bash

# 使用默认配置启动
caddy run

# 指定配置文件
caddy run --config Caddyfile

# 指定配置适配器
caddy run --config caddy.json --adapter json

# 后台运行
caddy run --config Caddyfile &

常用参数 #

bash

# 指定配置文件
caddy run --config /etc/caddy/Caddyfile

# 指定配置适配器
caddy run --config Caddyfile --adapter caddyfile

# 打印环境变量
caddy run --environ --config Caddyfile

# 指定管理 API 地址
caddy run --config Caddyfile --admin :2019

# 禁用管理 API
caddy run --config Caddyfile --admin off

# 指定 PID 文件
caddy run --config Caddyfile --pidfile /var/run/caddy.pid

# 指定数据目录
caddy run --config Caddyfile --data /var/lib/caddy

# 指定配置目录
caddy run --config Caddyfile --config /etc/caddy

完整启动示例 #

bash

# 生产环境启动
caddy run \
    --config /etc/caddy/Caddyfile \
    --adapter caddyfile \
    --environ \
    --pidfile /var/run/caddy.pid

systemd 服务管理 #

bash

# 启动服务
sudo systemctl start caddy

# 停止服务
sudo systemctl stop caddy

# 重启服务
sudo systemctl restart caddy

# 查看状态
sudo systemctl status caddy

# 开机自启
sudo systemctl enable caddy

# 禁用开机自启
sudo systemctl disable caddy

# 查看日志
sudo journalctl -u caddy -f

重载命令（reload） #

基本重载 #

bash

# 重载默认配置
caddy reload

# 指定配置文件
caddy reload --config Caddyfile

# 指定管理 API 地址
caddy reload --admin localhost:2019

# 强制重载
caddy reload --config Caddyfile --force

重载参数说明 #

参数	说明	示例
`--config`	配置文件路径	`--config /etc/caddy/Caddyfile`
`--adapter`	配置适配器	`--adapter caddyfile`
`--address`	管理 API 地址	`--address localhost:2019`
`--force`	强制重载	`--force`

重载流程 #

text

┌─────────────────────────────────────────────────────────────┐
│                    配置重载流程                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 读取新配置文件                                          │
│       ↓                                                     │
│  2. 验证配置语法                                            │
│       ↓                                                     │
│  3. 解析配置内容                                            │
│       ↓                                                     │
│  4. 比较新旧配置                                            │
│       ↓                                                     │
│  5. 平滑切换配置                                            │
│       ↓                                                     │
│  6. 旧连接继续处理完成                                       │
│       ↓                                                     │
│  7. 新连接使用新配置                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

零停机重载 #

bash

# Caddy 支持零停机重载
# 修改配置后执行
caddy reload --config Caddyfile

# 服务不会中断
# 正在处理的请求继续完成
# 新请求使用新配置

停止命令（stop） #

基本停止 #

bash

# 停止 Caddy
caddy stop

# 指定管理 API 地址
caddy stop --admin localhost:2019

优雅停止 #

bash

# Caddy 默认优雅停止
# 1. 停止接受新连接
# 2. 等待现有请求完成
# 3. 关闭服务器

配置转换命令（adapt） #

Caddyfile 转 JSON #

bash

# 基本转换
caddy adapt --config Caddyfile

# 格式化输出
caddy adapt --config Caddyfile --pretty

# 保存到文件
caddy adapt --config Caddyfile --pretty > caddy.json

# 指定适配器
caddy adapt --config caddy.json --adapter json

转换示例 #

bash

# 输入 Caddyfile
cat Caddyfile

caddyfile

example.com {
    reverse_proxy localhost:3000
}

bash

# 转换输出
caddy adapt --config Caddyfile --pretty

json

{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [":443"],
          "routes": [
            {
              "match": [
                {
                  "host": ["example.com"]
                }
              ],
              "handle": [
                {
                  "handler": "subroute",
                  "routes": [
                    {
                      "handle": [
                        {
                          "handler": "reverse_proxy",
                          "upstreams": [
                            {
                              "dial": "localhost:3000"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ],
              "terminal": true
            }
          ],
          "automatic_https": {
            "disable": false
          }
        }
      }
    }
  }
}

验证命令（validate） #

基本验证 #

bash

# 验证 Caddyfile
caddy validate --config Caddyfile

# 验证 JSON 配置
caddy validate --config caddy.json --adapter json

验证输出 #

bash

# 配置有效
$ caddy validate --config Caddyfile
Valid configuration

# 配置无效
$ caddy validate --config Caddyfile
Error: adapting config using caddyfile: parsing caddyfile tokens for 'example.com': 
Caddyfile:2 - Error during parsing: unknown directive: invalid_directive

验证并显示配置 #

bash

# 验证并显示转换后的 JSON
caddy adapt --config Caddyfile --validate

格式化命令（fmt） #

基本格式化 #

bash

# 检查格式
caddy fmt --check Caddyfile

# 格式化并输出
caddy fmt Caddyfile

# 格式化并覆盖原文件
caddy fmt --overwrite Caddyfile

# 格式化多个文件
caddy fmt --overwrite *.caddyfile

格式化示例 #

bash

# 格式化前
cat Caddyfile

caddyfile

example.com{
root * /var/www
file_server
}

bash

# 格式化后
caddy fmt --overwrite Caddyfile
cat Caddyfile

caddyfile

example.com {
	root * /var/www
	file_server
}

模块命令（list-modules） #

列出所有模块 #

bash

# 列出所有模块
caddy list-modules

# 输出示例
http
http.handlers
http.handlers.static_response
http.handlers.reverse_proxy
http.handlers.file_server
http.handlers.authentication
...

过滤模块 #

bash

# 过滤特定模块
caddy list-modules | grep reverse_proxy

# 列出 HTTP 相关模块
caddy list-modules | grep http

# 列出认证模块
caddy list-modules | grep auth

查看模块版本 #

bash

# 显示模块版本信息
caddy list-modules --versions

环境命令（environ） #

显示环境变量 #

bash

# 显示 Caddy 相关环境变量
caddy environ

# 输出示例
CADDY_ADMIN=localhost:2019
HOME=/root
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
XDG_DATA_HOME=/var/lib
XDG_CONFIG_HOME=/var/lib/caddy/config

版本命令（version） #

查看版本 #

bash

# 显示版本
caddy version

# 输出示例
v2.7.6 h1:bPufDvWY/4DnL1Q1J9jDQ4L3N+8Q4L3N+8Q4L3N+8Q4L3N+8Q4L3N+8Q4L3N+8Q4=

证书命令 #

信任证书 #

bash

# 信任本地开发证书
caddy trust

# 指定管理 API
caddy trust --admin localhost:2019

列出证书 #

bash

# 通过 API 列出证书
curl localhost:2019/certificates | jq

手动获取证书 #

caddyfile

# Caddyfile 中配置域名后启动
# Caddy 会自动获取证书
example.com {
    respond "Hello"
}

管理 API #

API 端点 #

Caddy 提供了丰富的管理 API：

bash

# 获取当前配置
curl localhost:2019/config

# 获取配置的特定部分
curl localhost:2019/config/apps/http

# 更新配置
curl -X POST \
    -H "Content-Type: application/json" \
    -d @config.json \
    localhost:2019/load

# 删除配置
curl -X DELETE localhost:2019/config/apps/http/servers/srv0

常用 API 操作 #

bash

# 获取服务器信息
curl localhost:2019/config/

# 获取所有路由
curl localhost:2019/config/apps/http/servers

# 添加新路由
curl -X POST \
    localhost:2019/config/apps/http/servers/srv0/routes/0 \
    -H "Content-Type: application/json" \
    -d '{
        "match": [{"host": ["new.example.com"]}],
        "handle": [{
            "handler": "static_response",
            "body": "Hello from new site"
        }]
    }'

# 获取证书信息
curl localhost:2019/certificates

# 获取反向代理上游状态
curl localhost:2019/reverse_proxy/upstreams

动态配置示例 #

bash

# 动态添加站点
curl -X POST localhost:2019/config/apps/http/servers/srv0/routes \
    -H "Content-Type: application/json" \
    -d '{
        "match": [{"host": ["dynamic.example.com"]}],
        "handle": [{
            "handler": "reverse_proxy",
            "upstreams": [{"dial": "localhost:4000"}]
        }],
        "terminal": true
    }'

# 动态删除站点
curl -X DELETE localhost:2019/config/apps/http/servers/srv0/routes/0

日志查看 #

实时日志 #

bash

# systemd 服务日志
sudo journalctl -u caddy -f

# 查看最近日志
sudo journalctl -u caddy -n 100

# 查看特定时间段日志
sudo journalctl -u caddy --since "2024-01-01" --until "2024-01-02"

# 过滤日志
sudo journalctl -u caddy | grep "error"

文件日志 #

bash

# 查看访问日志
tail -f /var/log/caddy/access.log

# 查看错误日志
tail -f /var/log/caddy/error.log

# 实时查看 JSON 格式日志
tail -f /var/log/caddy/access.log | jq

常用操作示例 #

完整启动流程 #

bash

# 1. 验证配置
caddy validate --config /etc/caddy/Caddyfile

# 2. 格式化配置
caddy fmt --overwrite /etc/caddy/Caddyfile

# 3. 查看转换后的 JSON（可选）
caddy adapt --config /etc/caddy/Caddyfile --pretty

# 4. 启动服务
sudo systemctl start caddy

# 5. 查看状态
sudo systemctl status caddy

# 6. 查看日志
sudo journalctl -u caddy -f

配置更新流程 #

bash

# 1. 编辑配置文件
vim /etc/caddy/Caddyfile

# 2. 验证新配置
caddy validate --config /etc/caddy/Caddyfile

# 3. 重载配置（零停机）
caddy reload --config /etc/caddy/Caddyfile

# 或使用 systemd
sudo systemctl reload caddy

# 4. 验证效果
curl -I https://example.com

故障排查流程 #

bash

# 1. 检查服务状态
sudo systemctl status caddy

# 2. 查看日志
sudo journalctl -u caddy -n 50

# 3. 验证配置
caddy validate --config /etc/caddy/Caddyfile

# 4. 检查端口占用
sudo netstat -tlnp | grep caddy
sudo lsof -i :80
sudo lsof -i :443

# 5. 检查证书
curl localhost:2019/certificates | jq

# 6. 测试连接
curl -v https://example.com

命令速查表 #

命令	说明	示例
`run`	启动服务器	`caddy run --config Caddyfile`
`stop`	停止服务器	`caddy stop`
`reload`	重载配置	`caddy reload --config Caddyfile`
`validate`	验证配置	`caddy validate --config Caddyfile`
`adapt`	转换配置	`caddy adapt --config Caddyfile --pretty`
`fmt`	格式化配置	`caddy fmt --overwrite Caddyfile`
`version`	显示版本	`caddy version`
`environ`	显示环境变量	`caddy environ`
`list-modules`	列出模块	`caddy list-modules`
`trust`	信任证书	`caddy trust`

下一步 #

现在你已经掌握了 Caddy 的基本命令，接下来学习静态资源服务开始实际配置你的 Web 服务器！