从零开始学习Caddy Web服务器 – wiki基地

作者： /

从零开始：全面掌握现代 Web 服务器 Caddy

在当今互联网世界，Web 服务器是构建和托管网站、应用程序的关键基础设施。传统上，Apache 和 Nginx 一直是该领域的主导者，它们功能强大、稳定可靠，但配置相对复杂，尤其是对于新手而言。近年来，一个名为 Caddy 的现代 Web 服务器以其简洁、易用和强大的自动化特性（特别是自动 HTTPS）迅速崛起，吸引了大量开发者和系统管理员的目光。

本文旨在成为一份详尽的指南，带领您从零开始，一步步探索和学习 Caddy Web 服务器，无论您是完全的新手，还是希望从其他 Web 服务器迁移过来，都能从中受益。我们将涵盖从基本概念、安装、配置到实际应用场景的方方面面。

第一章：初识 Caddy – 为何选择它？

在我们深入技术细节之前，先来了解一下 Caddy 是什么，以及它为何值得学习和使用。

  1. 什么是 Caddy？
    Caddy 是一个用 Go 语言编写的开源 Web 服务器。它的设计哲学是“简单易用，默认安全”。Caddy 的目标是让 Web 服务器的配置和管理变得前所未有的简单，同时提供现代 Web 所需的各项功能。

  2. Caddy 的核心优势：

    • 自动 HTTPS： 这是 Caddy 最引人注目的特性。默认情况下，Caddy 会自动为您的网站获取并续订由 Let’s Encrypt 或 ZeroSSL 颁发的 TLS/SSL 证书，实现开箱即用的 HTTPS 加密。您无需手动配置证书或运行复杂的脚本。
    • 简洁的配置（Caddyfile）： Caddy 引入了一种名为 Caddyfile 的人性化配置文件格式。相比 Apache 的 .htaccess 和 Nginx 的复杂指令块，Caddyfile 结构清晰，语法直观，易于读写和理解。
    • 现代协议支持： Caddy 原生支持 HTTP/1.1, HTTP/2, 以及实验性的 HTTP/3 (QUIC)，确保您的网站能够利用最新的网络传输技术提升性能。
    • 跨平台： 基于 Go 语言的特性，Caddy 可以轻松编译并在 Windows, macOS, Linux, BSD 等多种操作系统上运行，无需复杂的依赖。
    • 可扩展性： Caddy 拥有一个模块化架构，可以通过插件轻松扩展功能，满足各种定制需求。
    • 强大的反向代理： Caddy 具备强大的反向代理和负载均衡能力，可以轻松地将流量转发到后端的应用程序（如 Node.js, Python, Java 应用或 Docker 容器），并提供健康检查、WebSocket 支持等功能。
    • 原生静态文件服务： Caddy 提供高效的静态文件服务，并内置了对 Gzip 和 Zstandard 压缩、模板渲染、Markdown 转换等功能的支持。

  3. 适合人群：

    • Web 开发人员： 需要快速、简单地在本地开发环境或生产环境部署应用。
    • 系统管理员： 寻求更易于管理和维护的 Web 服务器解决方案。
    • 个人站长和爱好者： 希望轻松为自己的博客、项目网站启用 HTTPS。
    • DevOps 工程师： 需要自动化、API 驱动的 Web 服务配置。

第二章：安装 Caddy – 迈出第一步

现在，让我们开始动手安装 Caddy。Caddy 提供了多种安装方式，您可以根据自己的操作系统和偏好进行选择。

  1. 使用包管理器（推荐，适用于 Linux）：
    这是在 Linux 发行版上安装和管理 Caddy 的最常用、最推荐的方式，可以方便地进行更新和管理服务。

    • Debian/Ubuntu/Raspbian:
      bash
      sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
      curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
      curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
      sudo apt update
      sudo apt install caddy

    • CentOS/RHEL/Fedora:
      bash
      sudo dnf install 'dnf-command(copr)'
      sudo dnf copr enable @caddy/caddy
      sudo dnf install caddy

    • Arch Linux:
      bash
      sudo pacman -S caddy

    通过包管理器安装后，Caddy 通常会被配置为一个系统服务（如 systemd），方便后台运行和管理。

  2. 下载预编译的二进制文件：
    访问 Caddy 的官方下载页面（https://caddyserver.com/download）或 GitHub Releases 页面。选择适合您操作系统和架构（如 amd64, arm64）的版本下载。下载后得到一个单一的可执行文件 caddy。您可以将其移动到系统的 PATH 目录下（如 /usr/local/bin）以便全局调用。
    bash
    # 示例：下载 Linux amd64 版本并移动到 PATH
    wget "https://caddyserver.com/api/download?os=linux&arch=amd64" -O caddy
    chmod +x caddy
    sudo mv caddy /usr/local/bin/

  3. 使用 Docker：
    如果您熟悉 Docker，官方提供了 Caddy 的 Docker 镜像。
    bash
    docker pull caddy
    使用 Docker 运行 Caddy 需要将配置文件和网站内容挂载到容器内，并映射端口。

  4. 从源码编译（适用于开发者）：
    需要安装 Go 开发环境。
    bash
    go install github.com/caddyserver/caddy/v2/cmd/caddy@latest

验证安装：
无论使用哪种方式安装，打开终端或命令提示符，运行以下命令：
bash
caddy version
如果看到类似 v2.x.x ... 的输出，说明 Caddy 已成功安装。

首次运行 Caddy（无需配置）：
在任意目录下（确保该目录为空或只有您想提供的文件），运行：
bash
caddy run
Caddy 会启动一个默认的 HTTP 服务器，监听在 :2015 端口（或环境变量 PORT 指定的端口）。它会提供当前目录下的文件。打开浏览器访问 http://localhost:2015，您应该能看到 Caddy 的默认欢迎页面或您目录下的文件列表。按 Ctrl+C 停止服务器。

这个简单的命令展示了 Caddy 的便捷性，但实际应用中我们需要更精细的控制，这就需要配置文件了。

第三章：核心概念 – 理解 Caddyfile

Caddy 的主要配置方式是通过一个名为 Caddyfile 的文本文件。它的设计目标是人类友好、易于理解。

  1. 基本结构：
    Caddyfile 由一个或多个 站点块 (Site Blocks) 组成。每个站点块定义了一个或多个 Caddy 应如何处理特定域名的请求。

    “`caddyfile

    这是一个注释行

    yourdomain.com {
    # 这里是 yourdomain.com 的配置指令
    …
    }

    sub.anotherdomain.net:8080 {
    # 这里是 sub.anotherdomain.net 在 8080 端口的配置
    …
    }

    localhost, 127.0.0.1 {
    # 可以为多个地址定义同一个配置块
    …
    }

    也可以使用通配符

    *.example.com {
    …
    }

    默认服务器块（处理未匹配的请求或 IP 地址请求）

    :80 {
    …
    }
    “`

    • 地址 (Address)： 站点块的第一行定义了 Caddy 监听的地址或域名。可以是域名、IP 地址、端口号，或者它们的组合。如果省略端口，Caddy 默认使用 80 (HTTP) 和 443 (HTTPS)。
    • 指令 (Directives)： 在花括号 {} 内的是指令。指令告诉 Caddy 如何处理请求，例如从哪里提供文件、如何代理请求、启用什么功能等。

  2. 常用指令概览：

    • root * <path>：设置网站的根目录。* 表示匹配所有请求路径，<path> 是文件系统上的路径。
    • file_server：启用静态文件服务。它可以处理目录列表、index.html 等。
    • reverse_proxy <upstream>：将请求反向代理到后端的应用或服务。<upstream> 可以是 host:port, unix//path/to/socket 等。
    • php_fastcgi <upstream>：将请求通过 FastCGI 协议转发给 PHP-FPM 进程。
    • encode gzip zstd：启用 Gzip 和 Zstandard 响应压缩。
    • log：配置访问日志。
    • tls <email> 或 tls internal：配置 TLS。通常 Caddy 会自动处理，但有时需要手动指定邮箱或使用内部 CA。
    • header <name> <value>：添加或修改响应头。
    • redir <from> <to> [code]：设置 HTTP 重定向。
    • handle_errors { ... }：定义自定义错误页面处理。
    • try_files <files...> <fallback>：尝试按顺序查找文件，如果都找不到则执行回退操作（常用于单页应用 SPA）。

  3. 第一个 Caddyfile 示例：托管静态网站
    假设您有一个简单的 HTML 网站，文件放在 /var/www/my-site 目录下，其中有一个 index.html 文件。您希望通过 http://localhost 访问它。

    • 创建一个名为 Caddyfile 的文本文件（就叫这个名字，没有扩展名）。

    • 在文件中写入以下内容：

      caddyfile
      localhost {
      root * /var/www/my-site
      file_server
      encode gzip zstd
      log {
      output file /var/log/caddy/access.log
      }
      }

    • 解释：

      • localhost { ... }：定义了一个处理 localhost 请求的站点块。
      • root * /var/www/my-site：将所有请求 (*) 的根目录指向 /var/www/my-site。
      • file_server：启用静态文件服务，Caddy 会自动查找 index.html 或显示目录列表（如果允许）。
      • encode gzip zstd：对支持的客户端启用 Gzip 和 Zstandard 压缩。
      • log { ... }：配置日志记录，将访问日志写入 /var/log/caddy/access.log 文件。（确保 Caddy 有权限写入该目录/文件）。

    • 运行 Caddy 使用此配置：
      在包含 Caddyfile 的目录下运行：
      bash
      caddy run
      # 或者，如果 Caddyfile 不在当前目录：
      # caddy run --config /path/to/your/Caddyfile
      现在，在浏览器中访问 http://localhost (或 Caddyfile 中定义的地址)，您应该能看到 /var/www/my-site/index.html 的内容。

第四章：自动 HTTPS – Caddy 的魔法

这是 Caddy 最强大的功能之一。如果您拥有一个公网可访问的服务器和域名，Caddy 可以自动为您配置 HTTPS。

  1. 前提条件：

    • 公网 IP 地址： 您的服务器必须有一个公共 IP 地址。
    • DNS 解析： 您的域名（例如 yourdomain.com 和 www.yourdomain.com）的 A 记录（IPv4）或 AAAA 记录（IPv6）必须正确指向您服务器的公网 IP 地址。
    • 端口开放： 服务器的防火墙必须允许外部访问 TCP 端口 80 和 443。Caddy 需要使用这些端口与 Let’s Encrypt (或其他 ACME CA) 服务器进行验证。

  2. 配置 Caddyfile 启用自动 HTTPS：
    非常简单，只需将 Caddyfile 中的地址从 localhost 或 IP 地址更改为您的 公共域名 即可。

    “`caddyfile
    yourdomain.com {
    root * /var/www/my-site
    file_server
    encode gzip zstd
    log {
    output file /var/log/caddy/access.log
    }
    }

    如果您还想让 www 子域名也工作，可以这样写：

    www.yourdomain.com {

    redir https://yourdomain.com{uri} permanent

    }

    或者更简洁的方式（Caddy v2.5+）:

    yourdomain.com, www.yourdomain.com {

    … (配置内容) …

    # Caddy 会自动处理 www 到 非www 的重定向（如果需要）

    }

    “`

  3. 启动 Caddy 并观察：
    使用 caddy run 或 sudo systemctl start caddy（如果使用 systemd 服务）启动 Caddy。首次启动时，您会在日志中看到 Caddy 尝试获取证书的过程：

    • 它会连接到 ACME CA（默认为 Let’s Encrypt）。
    • CA 会要求 Caddy 证明它确实控制着该域名（通常通过 HTTP-01 或 TLS-ALPN-01 挑战）。
    • Caddy 会自动响应这些挑战（这就是需要开放 80/443 端口的原因）。
    • 验证成功后，CA 会颁发证书，Caddy 会保存并开始使用它。
    • Caddy 还会自动处理证书的续订，您无需担心证书过期。

    重要提示： Let’s Encrypt 对证书申请有速率限制。在测试时，可以使用 Let’s Encrypt 的 Staging 环境，避免耗尽生产环境的限额。可以在 Caddyfile 的全局选项或特定站点块中添加 acme_ca https://acme-staging-v02.api.letsencrypt.org/directory。

  4. 测试 HTTPS：
    在浏览器中访问 https://yourdomain.com。您应该能看到您的网站，并且浏览器地址栏会显示一个锁形图标，表示连接是安全的。

第五章：反向代理 – 连接后端应用

现代 Web 应用通常由前端（HTML/CSS/JS）和后端（Node.js, Python, Go, Java, PHP 等）组成。Caddy 作为反向代理，可以将来自用户的请求转发给这些后端应用，同时处理 HTTPS、压缩、日志等。

  1. 基本反向代理配置：
    假设您有一个 Node.js 应用运行在本地的 http://localhost:3000。您希望通过 https://app.yourdomain.com 访问它。

    “`caddyfile
    app.yourdomain.com {
    # 将所有请求转发给 localhost:3000
    reverse_proxy localhost:3000

    # 可选：启用压缩（如果后端应用没有压缩）
encode gzip zstd

# 可选：配置日志
log {
    output file /var/log/caddy/app.access.log
}

    }
    “`

    • reverse_proxy localhost:3000：这是核心指令。它告诉 Caddy 将所有到达 app.yourdomain.com 的请求（路径、查询参数、请求体等）都转发给运行在 localhost:3000 的服务。Caddy 会处理与客户端的 HTTPS 连接，然后与后端建立 HTTP 连接（通常是这样）。

  2. 代理到 Unix Socket：
    一些应用（如 PHP-FPM, Gunicorn）可能监听在 Unix Socket 上，这通常比 TCP 端口更高效。

    “`caddyfile

    假设 Gunicorn 运行在 /run/gunicorn.sock

    python-app.yourdomain.com {
    reverse_proxy unix//run/gunicorn.sock
    encode gzip zstd
    log { … }
    }
    “`

  3. 负载均衡：
    如果您有多个后端应用实例，Caddy 可以进行负载均衡。

    caddyfile
    api.yourdomain.com {
    reverse_proxy node1:8080 node2:8080 node3:8080 {
    lb_policy round_robin # 负载均衡策略（可选，默认随机）
    health_uri /health # 健康检查路径（可选）
    health_interval 10s # 健康检查间隔（可选）
    }
    encode gzip zstd
    log { ... }
    }

  4. 处理 WebSocket：
    Caddy 的 reverse_proxy 默认支持 WebSocket 升级，无需特殊配置。

  5. 修改请求/响应头：
    有时需要修改转发给后端或返回给客户端的头信息。

    “`caddyfile
    my-service.com {
    reverse_proxy localhost:5000 {
    # 发送给后端的头
    header_up Host {http.request.host}
    header_up X-Real-IP {http.request.remote.ip}
    header_up X-Forwarded-For {http.request.remote.ip}
    header_up X-Forwarded-Proto {http.request.scheme}

        # 从后端响应中删除某个头
    # header_down -Server
}

    }
    “`

第六章：集成 PHP – 运行 WordPress 及类似应用

PHP 是构建动态网站（如 WordPress, Drupal, Laravel）最流行的语言之一。Caddy 通过 php_fastcgi 指令与 PHP-FPM（FastCGI Process Manager）集成。

  1. 前提条件：

    • 安装 PHP 和 PHP-FPM 扩展。
    • 确保 PHP-FPM 服务正在运行并监听在一个地址上（通常是 Unix Socket，如 /run/php/php8.1-fpm.sock，或 TCP 端口，如 127.0.0.1:9000）。具体路径/端口取决于您的 PHP 安装和配置。

  2. 基本 PHP 配置：
    假设您的 PHP 网站文件在 /var/www/wordpress，并且 PHP-FPM 监听在 /run/php/php8.1-fpm.sock。

    “`caddyfile
    wordpress.yourdomain.com {
    root * /var/www/wordpress
    encode gzip zstd
    log {
    output file /var/log/caddy/wordpress.access.log
    }

    # 将所有以 .php 结尾的请求交给 PHP-FPM 处理
php_fastcgi unix//run/php/php8.1-fpm.sock

# 启用静态文件服务处理非 PHP 文件（如 CSS, JS, 图片）
file_server

    }
    “`

    • php_fastcgi unix//run/php/php8.1-fpm.sock：将匹配到的请求（默认是所有请求，但通常我们希望只处理 .php 文件，见下文）通过 FastCGI 协议发送给指定的 PHP-FPM 实例。

  3. 更健壮的 PHP 配置（适用于 WordPress 等框架）：
    对于像 WordPress 这样的应用，需要处理 “Pretty Permalinks”，即优雅链接（例如 yoursite.com/my-post/ 而不是 yoursite.com/index.php?p=123）。这通常需要 try_files 指令。

    “`caddyfile
    wordpress.yourdomain.com {
    root * /var/www/wordpress
    encode gzip zstd
    log { … }

    # 优先尝试直接匹配文件或目录，如果找不到，则将请求交给 /index.php
try_files {path} {path}/ /index.php?{query}

# 只将实际存在的 .php 文件或回退到 index.php 的请求交给 PHP-FPM
php_fastcgi unix//run/php/php8.1-fpm.sock {
    # 可选：定义 index 文件名
    # try_files {path} /index.php
    # 可选：分离路径信息
    # split_path .php
}

# 处理非 PHP 文件
file_server

# 阻止访问敏感文件（可选但推荐）
@forbidden {
    path /.git* /wp-config.php /wp-admin/includes*
}
respond @forbidden 403

    }
    ``
    *    try_files {path} {path}/ /index.php?{query}：这是处理 Pretty Permalinks 的关键。它告诉 Caddy：
    1. 尝试查找与请求路径完全匹配的文件 (    {path})。
    2. 如果找不到，尝试查找与请求路径匹配的目录下的    index.html或index.php({path}/)。
    3. 如果都找不到，则内部重写请求到    /index.php，并将原始查询字符串 ({query}) 附加其后。这样 WordPress 的路由系统就能接管处理。
    * 将    php_fastcgi放在try_files之后，确保只有需要 PHP 处理的请求（.php文件或重写到index.php` 的请求）才会被转发。

第七章：管理 Caddy – 作为服务运行

在生产环境中，您需要让 Caddy 在后台持续运行，并在服务器重启后自动启动。这通常通过系统的服务管理器（如 systemd, launchd, Windows Services）来实现。

  1. 使用 systemd (Linux 主流)：
    如果您通过包管理器安装 Caddy，通常会自动创建一个 systemd 服务单元文件（如 /lib/systemd/system/caddy.service）。

    • 常用命令：

      • 启动 Caddy 服务：sudo systemctl start caddy
      • 停止 Caddy 服务：sudo systemctl stop caddy
      • 重启 Caddy 服务：sudo systemctl restart caddy
      • 重新加载配置（无需停机）：sudo systemctl reload caddy 或 caddy reload --config /etc/caddy/Caddyfile (需要确保服务文件配置正确以支持 reload)
      • 查看服务状态：sudo systemctl status caddy
      • 设置开机自启：sudo systemctl enable caddy
      • 取消开机自启：sudo systemctl disable caddy
      • 查看 Caddy 日志：journalctl -u caddy -f --no-pager

    • 配置文件位置： systemd 服务通常期望 Caddyfile 位于 /etc/caddy/Caddyfile。

    • caddy reload vs caddy restart： reload 会平滑地加载新配置，不会中断现有连接，是更新配置的首选方式。restart 会完全停止并重新启动 Caddy 进程，会导致短暂的服务中断。

  2. 手动创建 systemd 服务文件（如果需要）：
    如果 Caddy 不是通过包管理器安装的，您可以自己创建一个服务文件，例如 /etc/systemd/system/caddy.service：

    “`ini
    [Unit]
    Description=Caddy Web Server
    Documentation=https://caddyserver.com/docs/
    After=network.target network-online.target
    Requires=network-online.target

    [Service]
    Type=notify
    User=caddy # 推荐创建一个专门运行 Caddy 的用户
    Group=caddy # 和对应的组
    ExecStart=/usr/local/bin/caddy run –environ –config /etc/caddy/Caddyfile
    ExecReload=/usr/local/bin/caddy reload –config /etc/caddy/Caddyfile –force
    TimeoutStopSec=5s
    LimitNOFILE=1048576 # 提高文件描述符限制
    LimitNPROC=512 # 限制进程数
    PrivateTmp=true # 使用私有 /tmp 目录
    ProtectSystem=full # 保护系统文件
    AmbientCapabilities=CAP_NET_BIND_SERVICE # 允许绑定低位端口 (80, 443)

    [Install]
    WantedBy=multi-user.target
    ``
    * **注意：** 您需要根据实际情况调整    User,Group,ExecStart,ExecReload中的路径。需要创建caddy用户和组，并确保它对配置文件、日志文件、网站根目录以及 Caddy 存储 TLS 证书/状态的目录（默认为$HOME/.local/share/caddy或/var/lib/caddy）有读写权限。
    * 创建文件后，运行    sudo systemctl daemon-reload使其生效，然后就可以使用systemctl` 命令管理了。

  3. 其他系统：

    • macOS: 使用 launchd。可以通过 brew services start caddy (如果用 Homebrew 安装) 或手动创建 .plist 文件。
    • Windows: 可以将 Caddy 注册为 Windows 服务，使用 caddy run --resume 或第三方工具如 NSSM。

第八章：进阶话题与后续学习

Caddy 的功能远不止于此。当您掌握了基础之后，可以探索以下方向：

  1. Caddy API： Caddy V2 拥有一个强大的 JSON API，允许您动态地、编程地管理配置，无需修改 Caddyfile 和重载。这对于自动化和集成非常有用。
  2. JSON 配置： Caddy 的原生配置格式其实是 JSON。Caddyfile 只是被适配器转换为 JSON。直接使用 JSON 配置可以实现 Caddyfile 无法表达的更复杂的逻辑和结构。
  3. 模板 (templates)： 在静态文件中嵌入动态数据或逻辑。
  4. 自定义构建： 使用 xcaddy 工具将第三方插件编译到您的 Caddy 二进制文件中，扩展其功能（例如，添加 DNS 插件以支持更多 DNS 提供商进行 ACME 挑战）。
  5. 高级 TLS 配置： 使用自己的证书、配置客户端认证 (mTLS)、管理内部 CA 等。
  6. 度量指标 (Metrics)： 通过 /metrics 端点暴露 Prometheus 格式的度量指标，用于监控。
  7. 结构化日志： 输出 JSON 格式的日志，便于机器解析和集成到日志聚合系统。

学习资源：
* Caddy 官方文档： https://caddyserver.com/docs/ – 这是最权威、最全面的信息来源。务必经常查阅。
* Caddy 社区论坛： https://caddy.community/ – 提问、寻求帮助、分享经验的好地方。
* Caddy GitHub 仓库： https://github.com/caddyserver/caddy – 查看源码、报告 Bug、了解开发动态。

结语

Caddy Web 服务器以其革命性的易用性、强大的自动化 HTTPS 功能和现代化的设计，正在改变 Web 服务器领域的格局。从简单的静态网站托管到复杂的反向代理和应用服务，Caddy 都能提供简洁而高效的解决方案。

本指南为您铺设了从零开始学习 Caddy 的道路，涵盖了安装、核心概念、基本配置以及常见的应用场景。然而，真正的掌握来自于实践。动手去配置、去尝试、去解决遇到的问题，您会发现 Caddy 不仅功能强大，而且使用起来确实令人愉悦。

希望这篇文章能够帮助您成功入门 Caddy，并利用它来简化您的 Web 服务部署和管理工作。祝您在 Caddy 的世界里探索愉快！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部