Caddy Web Server 使用指南

Caddy Web Server Usage Guide

概述 (Overview)

Caddy是一款现代化的开源Web服务器，以其自动HTTPS、简洁配置和易用性而著称。Caddy采用Go语言编写，天然支持HTTP/2和HTTP/3，自动申请和续期SSL/TLS证书，是传统Web服务器的现代化替代方案。

Caddy is a modern open-source web server known for its automatic HTTPS, simple configuration, and ease of use. Written in Go, Caddy natively supports HTTP/2 and HTTP/3, automatically obtains and renews SSL/TLS certificates, making it a modern alternative to traditional web servers.

核心特性 (Core Features)

🔒 自动HTTPS (Automatic HTTPS)

自动申请Let's Encrypt证书
自动证书续期
HTTPS默认启用
OCSP Stapling支持

📝 简洁配置 (Simple Configuration)

Caddyfile简洁语法
JSON配置支持
热重载配置
零停机更新

🚀 现代协议 (Modern Protocols)

HTTP/2原生支持
HTTP/3/QUIC支持
WebSocket支持
gRPC反向代理

⚡ 高性能 (High Performance)

Go语言编写，高并发
内置缓存和压缩
静态文件服务优化
反向代理性能优越

主要应用场景 (Main Use Cases)

🌐 静态网站托管

个人博客和文档站点
单页应用(SPA)部署
静态资源CDN
GitHub Pages替代方案

🔄 反向代理

API网关
微服务代理
负载均衡
WebSocket代理

🐳 容器化部署

Docker友好
Kubernetes Ingress
云原生应用
边缘计算节点

🎓 开发测试

本地HTTPS开发
API Mock服务
快速原型验证
CI/CD集成

技术规格 (Technical Specifications)

支持的协议 (Supported Protocols)

HTTP/1.1, HTTP/2, HTTP/3
WebSocket, Server-Sent Events
FastCGI, Reverse Proxy
gRPC

系统要求 (System Requirements)

操作系统: Linux, Windows, macOS, FreeBSD
架构: amd64, arm64, arm, 386
内存: 最小 512MB RAM
依赖: 无需额外依赖（单二进制文件）

基础配置示例 (Basic Configuration Example)

Caddyfile 简单示例

# 基础静态站点（自动HTTPS）
example.com {
    root * /var/www/html
    file_server
    encode gzip
}

# 反向代理
api.example.com {
    reverse_proxy localhost:8080
}

# PHP应用（如WordPress）
blog.example.com {
    root * /var/www/blog
    php_fastcgi unix//run/php/php-fpm.sock
    file_server
}

常用指令 (Common Directives)

root - 设置网站根目录
file_server - 启用静态文件服务
reverse_proxy - 配置反向代理
encode - 启用压缩
tls - SSL/TLS配置
header - HTTP头管理
rewrite - URL重写
handle - 请求处理器

快速安装 (Quick Installation)

Linux (官方脚本)

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

Docker

docker run -d \
  -p 80:80 \
  -p 443:443 \
  -v caddy_data:/data \
  -v caddy_config:/config \
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile \
  caddy:latest

下载二进制

# 从官网下载对应平台的二进制文件
# https://caddyserver.com/download

常用命令 (Common Commands)

# 启动Caddy
caddy start

# 停止Caddy
caddy stop

# 重载配置
caddy reload

# 验证配置
caddy validate --config Caddyfile

# 格式化Caddyfile
caddy fmt Caddyfile

# 查看版本
caddy version

# 运行（前台）
caddy run

# 适配Caddyfile到JSON
caddy adapt --config Caddyfile

与传统Web服务器对比 (Comparison with Traditional Servers)

Caddy vs Nginx

特性	Caddy	Nginx
配置复杂度	极简	中等
自动HTTPS	✅ 内置	❌ 需手动配置
HTTP/3支持	✅ 原生	⚠️ 需编译模块
零停机重载	✅	✅
插件生态	中等	丰富
性能	优秀	卓越

Caddy vs Apache

特性	Caddy	Apache
配置语法	简洁直观	复杂详细
自动HTTPS	✅	❌
部署复杂度	低	中高
模块系统	编译时	动态加载
学习曲线	平缓	陡峭

适用场景建议 (Use Case Recommendations)

✅ 非常适合

现代Web应用和API
需要自动HTTPS的场景
微服务和云原生应用
开发和测试环境
个人项目和小型网站
边缘计算和IoT网关

⚠️ 需要评估

超大规模流量站点（考虑Nginx）
复杂的旧版应用（考虑Apache）
需要大量第三方模块的场景
对配置细节有极致要求的场景

最佳实践 (Best Practices)

🔧 配置管理

使用Caddyfile进行简单配置
复杂场景使用JSON配置
分离不同站点的配置文件
使用环境变量管理敏感信息

🛡️ 安全防护

利用自动HTTPS特性
配置安全响应头
实施速率限制
定期更新Caddy版本

📊 监控与日志

启用结构化日志
集成Prometheus指标
配置日志轮转
监控证书有效期

🚀 性能优化

启用HTTP/2推送
配置适当的压缩
使用缓存指令
优化上游连接池

插件与扩展 (Plugins and Extensions)

Caddy支持通过模块进行功能扩展，常用模块包括：

caddy-dns: DNS provider支持（用于DNS验证）
caddy-security: 高级认证和授权
caddy-rate-limit: 速率限制
caddy-cache: 高级缓存功能
caddy-geo: 地理位置路由
caddy-git: Git集成自动部署

访问 Caddy官方插件库了解更多。

学习资源 (Learning Resources)

官方网站: https://caddyserver.com/
官方文档: https://caddyserver.com/docs/
GitHub仓库: https://github.com/caddyserver/caddy
社区论坛: https://caddy.community/
配置示例: https://github.com/caddyserver/examples

故障排除 (Troubleshooting)

常见问题

问题	可能原因	解决方案
证书申请失败	端口80/443被占用	检查防火墙和端口占用
配置不生效	缓存或语法错误	运行 `caddy validate`
性能问题	上游服务慢	检查反向代理配置
启动失败	配置文件错误	查看错误日志

日志位置

Linux: /var/log/caddy/
Docker: docker logs <container_id>
Windows: 查看事件查看器

总结 (Summary)

Caddy是一款注重开发者体验和安全性的现代Web服务器，特别适合：

需要快速部署HTTPS站点的场景
云原生和容器化应用
开发测试环境
个人和中小型项目

其简洁的配置和自动HTTPS功能大大降低了Web服务器的使用门槛，是现代Web开发的优秀选择。

最后更新: 2025年11月

Last Updated: November 2025