caddy中文使用文档

简介

Caddy 中文使用文档是围绕开源 Web 服务器 Caddy 整理的中文学习资料，面向需要托管站点、配置反向代理、申请 HTTPS 证书的运维人员与开发者。它解决配置语法晦涩、证书申请与续期流程繁琐这两类常见问题，用 Caddyfile 与原生 JSON 两条配置路径覆盖从入门到自动化运维的需求，核心优势是默认启用 HTTPS、基于 Go 语言的跨平台部署，以及可通过 JSON API 在线管理配置。

核心功能

• Caddyfile 配置：用少量指令声明域名、根目录与路由，适合日常站点托管，官方将其归为最易上手的配置路径。
• 原生 JSON 配置：以 JSON 完整描述服务器行为，适合由程序生成配置或做细粒度控制，官方称为功能更强的配置方式。
• JSON API 动态配置：通过接口在线修改运行中的配置，不必改文件再重启进程，可用于管理自动化与集成发布流程。
• 配置适配器（config adapters）：把其他格式的配置转换为 Caddy 使用的 JSON 配置，迁移既有配置时不必从零重写。
• 自动 HTTPS：默认启用 HTTPS，可自动获取并续期 Let's Encrypt 证书，域名解析正确时配置一次即可长期生效。
• 多协议支持：支持 HTTP/1.1、HTTP/2、HTTP/3，HTTP 功能基于 Go 标准库实现。
• 多平台与插件扩展：提供静态二进制、Debian/Ubuntu/Raspbian 包、Fedora/RedHat/CentOS 包与 Docker 镜像；第三方插件可用 xcaddy 从源码构建。

使用场景

• 站点托管：为静态站点或应用提供 Web 服务，写好 Caddyfile 指定域名与根目录即可对外提供访问。
• 反向代理：把主域名请求转发到后端服务，例如 GoToSocial 文档中在 example.org 上配置 Caddy 代理，证书由 Caddy 负责获取。
• HTTPS 上线：需要默认启用 HTTPS 的生产站点，省去手工申请证书与到期续期的重复操作。
• 自动化运维：通过管理配置的接口远程提交配置，实现 Web 服务器管理自动化、集成发布等进阶需求。
• 镜像站点快速部署：借助一键脚本或镜像快速拉起一套站点，适合需要频繁复制环境的场景。

安装与获取步骤

1. 确定获取途径：官方提供静态二进制、Debian/Ubuntu/Raspbian 软件包、Fedora/RedHat/CentOS 软件包以及 Docker 镜像，具体以官方页面 https://caddyserver.com/docs/install 为准。
2. 确认模块范围：官方软件包只包含标准模块；若需要第三方插件，用 xcaddy 从源码构建，或使用下载页面、自行部署插件。
3. 编写配置文件：在最简使用场景中，Caddy 默认读取名为 Caddyfile 的文件，在其中声明域名、根目录或反向代理目标。
4. 启动服务并完成 HTTPS：启动 Caddy 后确认域名已解析到服务器，由 Caddy 获取 Let's Encrypt 证书完成 HTTPS 配置。
5. 查阅中文文档：从入门指南开始，参考 https://caddy2.dengxiaolong.com/ 与 https://caddyserver.com.cn/docs/ 的中文页面对照学习。

与同类方案的区别

与 Nginx 相比，社区普遍认为 Caddy 在上手与配置难度上更低，自动 HTTPS 省去了证书申请环节；同时也有观点指出其性能上或许比不上 Nginx，高并发场景建议实测后再决定是否替换。

与 Caddy 1 相比，v2 的配置结构完全不同，社区反馈 v2 更简单、bug 更少、功能更多也更灵活，旧配置不能直接照搬。文档形态上，官方文档以例子为主、命令列表也带例子；中文文档由个人维护，阅读体验不错，但细节仍以官方英文页面为准。

注意事项

• 官方软件包只包含标准模块，需要第三方插件时须自行用 xcaddy 从源码构建，或使用下载页面获取带插件的产物。
• 中文文档为个人维护版本，内容可能滞后于官方英文文档，具体指令与参数以官方页面为准。
• 自动 HTTPS 依赖域名解析到服务器，本地开发或内网环境无法完成证书签发，需要另行处理证书来源。
• JSON API 属于管理配置的接口，对外开放会带来配置被篡改的风险，应限制可访问的来源与网络范围。
• Caddy 2 与 Caddy 1 的配置不通用，从 v1 迁移需要按 v2 文档重写，不能直接替换配置文件。