SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场caddy

caddy

部署与运维

查看项目

更新于 10-16 09:18

技能介绍

用途

Caddy 是一款 Web 服务器，本资料围绕其日常管理与运维展开，涵盖 Caddyfile 语法、通过 ACME 自动签发 HTTPS、反向代理、TLS 证书管理、JSON 配置 API，以及使用 xcaddy 构建插件。

服务身份与位置

  • 单元：caddy.service
  • 配置：/etc/caddy/Caddyfile
  • 数据目录：/var/lib/caddy（系统服务）或 ~/.local/share/caddy（用户模式）
  • 日志：journalctl -u caddy；/var/log/caddy/access.log（若已配置）
  • 用户：caddy（官方软件包创建的系统服务用户）
  • 安装：官方仓库 https://caddyserver.com/docs/install

主要能力与常用操作命令

  • 状态：systemctl status caddy
  • 启动：sudo systemctl start caddy
  • 停止：sudo systemctl stop caddy
  • 无停机重载：sudo systemctl reload caddy
  • 通过 API 重载：caddy reload --config /etc/caddy/Caddyfile
  • 重启：sudo systemctl restart caddy
  • 校验配置：caddy validate --config /etc/caddy/Caddyfile
  • 格式化 Caddyfile：caddy fmt --overwrite /etc/caddy/Caddyfile
  • Caddyfile 转为 JSON：caddy adapt --config /etc/caddy/Caddyfile
  • 查看编译后的 JSON 配置：caddy adapt --config /etc/caddy/Caddyfile | jq .
  • 打印环境：caddy environ
  • 前台运行（测试）：caddy run --config /etc/caddy/Caddyfile
  • 监听变更自动重载：caddy run --config /etc/caddy/Caddyfile --watch
  • 查看 TLS 证书状态：caddy list-modules；检查 /var/lib/caddy/.local/share/caddy/certificates/（原文如此）
  • 反向代理一键命令：caddy reverse-proxy --from :8080 --to localhost:3000
  • 文件服务器一键命令：caddy file-server --root /var/www --browse
  • 版本：caddy version

预期端口与防火墙

  • 80/tcp：HTTP，用于 ACME HTTP-01 挑战并自动重定向到 HTTPS
  • 443/tcp：HTTPS
  • 443/udp：HTTP/3（QUIC），近期版本默认启用
  • 验证：ss -tlnp | grep caddy
  • 防火墙：sudo ufw allow 80,443/tcp；sudo ufw allow 443/udp（用于 HTTP/3）

健康检查

  • systemctl is-active caddy → active
  • caddy validate --config /etc/caddy/Caddyfile 2>&1 → Valid configuration
  • curl -sI http://localhost → 返回 HTTP 响应或重定向（而非连接被拒绝）
  • ss -tlnp | grep ':80|:443' → 列表中包含 caddy

常见故障与排查

  • listen tcp :80: bind: permission denied：小于 1024 的端口需要 root 或 CAP_NET_BIND_SERVICE；可执行 sudo setcap cap_net_bind_service=+ep $(which caddy)，或在 systemd 单元中使用 AmbientCapabilities
  • ACME 挑战失败、证书未签发：80 端口从公网不可达，检查防火墙、NAT/路由器转发，并从外部访问 http://<your-domain>/.well-known/acme-challenge/test
  • too many certificates already issued：触发 ACME 速率限制（Let's Encrypt 每域名每周 5 张证书），可在全局选项切换测试 CA：acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
  • 域名变更后证书失败：新 DNS 记录尚未对 ACME CA 可见，等待 TTL 过期，用 dig +short <domain> @8.8.8.8 检查
  • 重载时 config parse error：Caddyfile 语法错误，运行 caddy validate，并查看 journalctl -u caddy -n 50
  • TLS 证书不续期：数据目录权限问题或 ACME 账户丢失，检查 /var/lib/caddy 归属（chown -R caddy:caddy /var/lib/caddy），用 caddy adapt | jq 查看证书到期情况
  • unknown directive：该指令需要 xcaddy 插件，例如 rate_limit、crowdsec 等需要自定义 xcaddy 构建，参见 https://caddyserver.com/download
  • caddy reload 无效果：API 管理端点被禁用或地址不对，管理端点默认 localhost:2019，确认全局选项中未禁用 admin
  • 反向代理返回 502：上游服务未运行或地址错误，检查上游服务并直接用 curl http://127.0.0.1:<port> 测试

使用中的痛点

  • 自动 HTTPS 默认开启：任何具备合规主机名的站点块都会自动获取 Let's Encrypt 证书，无需任何 TLS 配置。在开发/内网环境中会导致 ACME 失败，可用 tls internal（自签名）或全局选项中的 auto_https off 关闭。
  • Caddyfile 与 JSON API 双轨：Caddyfile 面向人，Caddy 原生配置是 JSON，caddy adapt 可在两者间转换。JSON API（localhost:2019）可在不重载的情况下修改在线配置，但改动不会写回 Caddyfile，容易产生配置分歧。
  • 测试期间的 ACME 速率限制：Let's Encrypt 限制每周 5 张重复证书，测试时应使用 staging CA（acme_ca https://acme-staging-v02.api.letsencrypt.org/directory），配置验证通过后再切换生产。
  • 数据目录权限：Caddy 将 ACME 账户密钥和证书存放在 /var/lib/caddy，若服务用户无法写入（例如手动复制或更改归属后），证书签发会静默失败，该目录必须归 caddy 用户所有。
  • 第三方模块需要 xcaddy：标准 caddy 二进制只包含官方模块，rate_limit、crowdsec、coraza（WAF）或 cache 等指令需要 xcaddy build 自定义构建；包管理器安装的 caddy 二进制无法在运行时扩展。
  • caddy reload 与 caddy stop && caddy start：caddy reload 通过管理 API 将新配置发送给运行中的进程，零停机且保留 TLS 会话状态；systemd restart 是完全替换进程，有短暂停机且会话状态丢失。生产中所有配置变更应优先使用 reload。

参考资料

资料提到 references/ 目录下包含：

  • Caddyfile.annotated：逐条解释每个指令的完整 Caddyfile
  • common-patterns.md：反向代理、PHP、静态文件、TLS 与 API 网关示例
  • docs.md：官方文档链接

限制与未提供信息

本资料未提供价格与收费模式、平台支持范围、性能与效果数据、版本号细节以及具体的软件许可信息；上述内容暂未提供。