602 Caddy v2 自动HTTPS Web服务器¶

# Ubuntu/Debian 安装
# 添加 Caddy 官方 APT 源
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  # 导入 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  # 安装 Caddy

# macOS 安装
brew install caddy  # 通过 Homebrew 安装

# Docker 安装
docker run -d \
  --name caddy \                        # 容器名称
  -p 80:80 \                            # 映射 HTTP 端口
  -p 443:443 \                          # 映射 HTTPS 端口
  -v caddy_data:/data \                 # 持久化证书数据
  -v caddy_config:/config \             # 持久化配置
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile \  # 挂载配置文件
  caddy:latest                          # 使用最新镜像

# 验证安装
caddy version  # 查看版本号

# 系统服务配置文件
/etc/caddy/Caddyfile          # 主配置文件（白话：Caddy 的"菜谱"）
/var/lib/caddy/.local/share/caddy  # 证书存储目录
/var/log/caddy/               # 日志目录（需自行配置）

# Caddyfile - 最简配置
# 白话：告诉 Caddy "在 example.com 上提供 /var/www/html 目录的文件"
example.com {
    root * /var/www/html       # 设置网站根目录（* 表示所有路径）
    file_server                # 启用静态文件服务
}
# 就这两行！Caddy 自动申请 HTTPS 证书，自动 HTTP→HTTPS 跳转

# 反向代理到后端服务
# 白话：用户访问 api.example.com，Caddy 偷偷转发给本机 8080 端口的应用
api.example.com {
    reverse_proxy localhost:8080  # 将请求转发到后端应用
}

# 多后端负载均衡
api.example.com {
    reverse_proxy localhost:8080 localhost:8081 localhost:8082 {
        lb_policy round_robin   # 轮询策略（白话：三个后端轮着来）
        health_uri /health      # 健康检查路径
        health_interval 10s     # 每 10 秒检查一次
    }
}

# 本地开发环境（localhost 自动生成自签名证书）
localhost {
    reverse_proxy localhost:3000  # 前端开发服务器
}

localhost:8443 {
    reverse_proxy localhost:8080  # 后端 API 服务器
}

# 服务管理
sudo systemctl start caddy     # 启动 Caddy
sudo systemctl stop caddy      # 停止 Caddy
sudo systemctl reload caddy    # 重载配置（不中断服务）
sudo systemctl status caddy    # 查看运行状态

# 配置管理
caddy fmt --overwrite Caddyfile  # 格式化配置文件
caddy validate --config Caddyfile  # 验证配置是否正确
caddy adapt --config Caddyfile    # 将 Caddyfile 转为 JSON 格式

# 快速启动（不用写配置文件）
caddy file-server --root /var/www/html --listen :8080  # 快速启动文件服务
caddy reverse-proxy --from :443 --to localhost:8080    # 快速反向代理

# 一个 Caddyfile 配置多个站点
# 白话：一台服务器同时跑多个网站，每个域名对应不同服务

blog.example.com {
    root * /var/www/blog       # 博客站点
    file_server
    encode gzip zstd           # 启用 gzip 和 zstd 压缩（加快加载）
}

app.example.com {
    reverse_proxy localhost:3000  # 前端应用
}

api.example.com {
    reverse_proxy /v1/* localhost:8080  # API v1 转发到 8080
    reverse_proxy /v2/* localhost:8081  # API v2 转发到 8081
}

api.example.com {
    # 跨域资源共享设置（白话：允许前端从不同域名调用 API）
    header {
        Access-Control-Allow-Origin "https://app.example.com"  # 允许的来源
        Access-Control-Allow-Methods "GET, POST, PUT, DELETE"  # 允许的方法
        Access-Control-Allow-Headers "Content-Type, Authorization"  # 允许的请求头
    }

    # 安全头（白话：告诉浏览器加强安全防护）
    header {
        X-Content-Type-Options "nosniff"      # 防止 MIME 类型嗅探
        X-Frame-Options "DENY"                # 禁止被嵌入 iframe
        Strict-Transport-Security "max-age=31536000"  # 强制 HTTPS（一年）
    }

    reverse_proxy localhost:8080
}

example.com {
    log {
        output file /var/log/caddy/access.log {
            roll_size 100mb           # 单个日志文件最大 100MB
            roll_keep 10              # 保留 10 个历史文件
            roll_compression zstd     # 使用 zstd 压缩旧日志（v2.11新特性）
        }
        format json                   # JSON 格式方便日志分析
        level INFO                    # 日志级别
    }
    reverse_proxy localhost:8080
}

admin.example.com {
    # 基本认证（白话：访问前弹出用户名密码框）
    basicauth {
        # 生成密码哈希：caddy hash-password
        admin $2a$14$xxx...  # 用户名 admin，密码哈希值
    }
    reverse_proxy localhost:9090
}

# 通配符证书（白话：*.example.com 下所有子域名共用一个证书）
*.example.com {
    tls {
        dns cloudflare {env.CF_API_TOKEN}  # 通过 DNS 验证申请通配符证书
    }

    @blog host blog.example.com
    handle @blog {
        reverse_proxy localhost:3001
    }

    @api host api.example.com
    handle @api {
        reverse_proxy localhost:8080
    }
}

ERROR: obtaining certificate: acme: error: 403

# 检查 DNS 解析
dig example.com                # 确认 A 记录指向服务器 IP
nslookup example.com           # 另一种 DNS 查询方式

# 检查防火墙
sudo ufw allow 80/tcp          # 开放 80 端口（HTTP 验证需要）
sudo ufw allow 443/tcp         # 开放 443 端口

ERROR: loading initial config: address already in use

sudo lsof -i :80               # 查看谁占了 80 端口
sudo systemctl stop nginx      # 停掉 Nginx
sudo systemctl disable nginx   # 禁止 Nginx 开机启动

caddy validate --config /etc/caddy/Caddyfile  # 先验证再重载
caddy fmt --overwrite /etc/caddy/Caddyfile     # 自动格式化

# Caddy 需要绑定 80/443 特权端口
sudo setcap 'cap_net_bind_service=+ep' $(which caddy)  # 给 Caddy 绑定特权端口的权限