Caddy 自动 HTTPS 服务器：零配置 TLS

FreeGuideOnline 最新 2026-06-13

Caddy 自动 HTTPS 服务器：零配置 TLS 完全指南

Caddy 是唯一一个默认启用 HTTPS 的 Web 服务器。它使用 Let‘s Encrypt 自动获取和续订证书，无需任何手动操作。本教程将带你从零开始，掌握 Caddy 的核心用法，快速架设安全的网站。

为什么选择 Caddy

  • 全自动 HTTPS：启动服务器的那一刻，SSL/TLS 证书就已经在后台申请、部署了。
  • 单一静态二进制文件：无依赖，安装就是把一个文件放到系统路径里。
  • 简洁的 Caddyfile 配置：一个只有几行的文本文件就能定义一个完整的站点。
  • 内置反向代理：一行指令即可为后端服务添加 HTTPS 网关。
  • 自动重定向 HTTP 到 HTTPS：无需额外配置。

安装 Caddy

Caddy 的安装非常简单，选择适合你系统的方式。

通过官方脚本安装（推荐）

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/setup.deb.sh' | sudo -E bash
sudo apt install -y caddy    # Debian / Ubuntu

对于其他平台（macOS、Windows、Docker），请参考官方下载页面。

安装完成后，检查版本：

caddy version

最简示例：让你的本地文件站获得 HTTPS

假设你有一个目录 ./mysite，里面有一个 index.html。想让它在公网上通过 HTTPS 访问，只需一个 Caddyfile。

在任意位置创建 Caddyfile：

example.com {
    root * /path/to/mysite
    file_server
}

将 example.com 换成你自己的域名（该域名的 DNS 必须指向这台机器）。然后在同一目录运行：

caddy run

Caddy 会立即：

  1. 启动 HTTP 服务器（端口 80），自动申请 Let’s Encrypt 证书。
  2. 获取证书后，启动 HTTPS 服务器（端口 443）。
  3. 将 HTTP 请求重定向到 HTTPS。
  4. 每 30 天自动检查证书并续期。

浏览器访问 https://example.com 就能看到你的页面，并显示安全的锁图标。

Caddyfile 核心指令

Caddyfile 是 Caddy 的配置语言，位于一个文本文件中。基本结构是站点块（Site Block）。

文件服务器

最基础的静态文件托管：

your-domain.com {
    root * /var/www/html
    file_server
}

如果你想让目录列表可浏览：

your-domain.com {
    root * /var/www/html
    file_server browse
}

反向代理

将请求转发到本地运行的应用程序（如 Node.js、Python、Go 应用）：

api.your-domain.com {
    reverse_proxy localhost:3000
}

Caddy 会自动为 api.your-domain.com 申请证书。

处理 WebSocket 和动态后端同样简单，Caddy 会自动识别并支持。

路径匹配与多站点

同一个 Caddy 里可以定义多个站点，也可以在一个站点块内用路径分发：

a.example.com {
    root * /sites/a
    file_server
}

b.example.com {
    root * /sites/b
    file_server
}

combined.example.com {
    root * /sites/combined
    file_server

    handle_path /api/* {
        reverse_proxy localhost:8080
    }
}

handle_path 会去掉匹配的前缀 /api 再传给后端。

自定义证书与高级 TLS

如果你的域名无法通过公网验证（例如内网环境），可以使用自签名证书或手动提供证书。但 Caddy 默认就是为了公网零配置设计的，通常无需修改。

要改变证书的 ACME 签发机构：

{
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

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

使用 staging 环境可避免在测试时触发速率限制。

访问日志与错误处理

启用 JSON 格式的访问日志：

example.com {
    root * /var/www
    file_server
    log {
        output file /var/log/caddy/access.log
        format json
    }
}

自定义错误页面：

example.com {
    root * /var/www
    file_server
    handle_errors {
        rewrite * /{http.error.status_code}.html
        file_server
    }
}

然后确保你的站点根目录里有对应的错误页面文件，如 404.html。

作为系统守护进程运行

在生产环境中，通常使用 Caddy 自带的服务管理方式。

安装完成后，Caddy 可以作为 systemd 服务运行（如果是通过包管理器安装的）。默认的 Caddyfile 路径是 /etc/caddy/Caddyfile。将你的配置写入该文件，然后启动服务：

sudo systemctl daemon-reload
sudo systemctl enable caddy
sudo systemctl start caddy

检查状态与日志：

sudo systemctl status caddy
sudo journalctl -u caddy -f

如果你手动下载了二进制文件，也可以用 caddy start 命令直接在后台运行，并使用 caddy stop 停止。

Docker 中使用 Caddy

官方提供了极小体积的 Docker 镜像。

创建一个 Dockerfile 或直接使用 docker-compose.yml：

# docker-compose.yml
version: "3.9"
services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./site:/srv
      - caddy_data:/data
volumes:
  caddy_data:

Caddyfile 内容：

:80 {
    root * /srv
    file_server
}

这样会为 Docker 监听的端口自动生成 HTTPS。甚至直接在公网服务器上，使用 Docker 方式也能获得自动证书，只要正确映射了端口并且域名指向该服务器。

常见问题与排错

证书申请失败

  • 确认域名已正确解析到服务器公网 IP。
  • 检查防火墙是否允许 80 和 443 端口。
  • 使用 curl -v http://example.com 看是否能返回 Caddy 的应答（应看到 “Caddy” 标识）。
  • 查看 Caddy 日志，使用 sudo journalctl -u caddy -n 50 --no-pager。

内部服务使用非标准端口

Caddy 的自动 HTTPS 默认监听 80 和 443。如果你需要在内部自定义端口，可以在本地 hosts 或内网 DNS 中解析域名，并使用 Caddy 的内置 DNS 验证插件（如 cloudflare、digitalocean 等）来获取通配符证书。这属于较进阶的用法，但 Caddy 的模块系统使其成为可能。

通配符证书

通配符证书需要 DNS 质询验证，你需要安装对应的 DNS 插件模块。从官方下载页面可以定制带有特定 DNS 提供商的 Caddy 构建。

进一步学习

Caddy 让 HTTPS 部署从“数小时的繁琐”变成了“几秒钟的自动完成”。现在就开始为你的下一个项目使用 Caddy，享受零配置 TLS 的便利。