第二章：安装与配置¶

系统要求¶

操作系统：Linux、macOS、Windows
架构：amd64、arm64、armv7 等
依赖：无外部依赖（Go 编译的单二进制文件）

安装方式¶

方式一：官方脚本安装（推荐）¶

Debian/Ubuntu¶

# 添加 GPG 密钥
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¶

# 添加仓库
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/rpm.repo.txt' | sudo tee /etc/yum.repos.d/caddy-stable.repo

# 安装
sudo dnf install caddy
# 或
sudo yum install caddy

安装完成后，Caddy 会自动创建 systemd 服务：

# 检查状态
sudo systemctl status caddy

# 启动服务
sudo systemctl start caddy

# 开机自启
sudo systemctl enable caddy

方式二：Docker 安装¶

基本运行¶

docker run -d \
    --name caddy \
    -p 80:80 \
    -p 443:443 \
    -p 443:443/udp \
    -v /path/to/Caddyfile:/etc/caddy/Caddyfile \
    -v caddy_data:/data \
    -v caddy_config:/config \
    caddy:latest

Docker Compose¶

# docker-compose.yml
version: '3.8'

services:
  caddy:
    image: caddy:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
      - ./www:/var/www/html

volumes:
  caddy_data:
  caddy_config:

启动：

docker-compose up -d

方式三：手动下载二进制¶

# 下载最新版本
curl -Lo caddy "https://github.com/caddyserver/caddy/releases/latest/download/caddy_$(uname -s)_$(uname -m)"

# 添加执行权限
chmod +x caddy

# 移动到 PATH
sudo mv caddy /usr/local/bin/

# 验证安装
caddy version

目录结构¶

安装后的目录结构：

/etc/caddy/
├── Caddyfile          # 主配置文件
└── sites/             # 可选：多站点配置目录

/var/lib/caddy/
├── .local/            # Caddy 内部数据
├── certificates/      # SSL 证书存储
└── keys/              # 私钥存储

/var/log/caddy/        # 日志目录（可选）

Caddyfile 基础¶

Caddyfile 是 Caddy 的配置文件，语法简洁直观。

基本语法¶

# 全局选项块（可选）
{
    email admin@example.com
    admin off
}

# 站点块
域名 {
    指令
}

# 另一个站点
另一个域名 {
    指令
}

最简示例¶

# 静态文件服务
localhost {
    root * /var/www/html
    file_server
}

常用指令¶

指令	说明	示例
`root`	设置根目录	`root * /var/www`
`file_server`	启用静态文件服务	`file_server browse`
`reverse_proxy`	反向代理	`reverse_proxy localhost:3000`
`encode`	启用压缩	`encode gzip zstd`
`log`	访问日志	`log output /var/log/access.log`
`tls`	TLS 配置	`tls internal` 或 `tls /path/cert.pem /path/key.pem`
`basicauth`	基础认证	`basicauth * { user hash }`

命令行工具¶

Caddy 提供了丰富的命令行工具：

常用命令¶

# 查看版本
caddy version

# 验证配置文件
caddy validate --config /etc/caddy/Caddyfile

# 格式化配置文件
caddy fmt --overwrite /etc/caddy/Caddyfile

# 启动服务（前台运行）
caddy run --config /etc/caddy/Caddyfile

# 启动服务（后台运行）
caddy start --config /etc/caddy/Caddyfile

# 停止服务
caddy stop

# 重新加载配置（无停机）
caddy reload --config /etc/caddy/Caddyfile

# 列出配置
caddy list-modules
caddy environ

适配器¶

Caddy 支持多种配置格式：

# 使用 JSON 配置
caddy run --config caddy.json --adapter json

# 使用 Caddyfile（默认适配器）
caddy run --config Caddyfile --adapter caddyfile

# 将 Caddyfile 转换为 JSON
caddy adapt --config Caddyfile --pretty

systemd 服务管理¶

使用包管理器安装后，Caddy 会自动配置为 systemd 服务：

# 启动
sudo systemctl start caddy

# 停止
sudo systemctl stop caddy

# 重启
sudo systemctl restart caddy

# 重载配置（推荐，无停机）
sudo systemctl reload caddy

# 查看状态
sudo systemctl status caddy

# 查看日志
sudo journalctl -u caddy -f

配置示例¶

示例 1：静态网站¶

example.com {
    root * /var/www/html
    file_server
    encode gzip
    log {
        output file /var/log/caddy/access.log
    }
}

示例 2：反向代理¶

api.example.com {
    reverse_proxy localhost:8000 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

示例 3：多站点配置¶

# 网站 A
site-a.com {
    root * /var/www/site-a
    file_server
}

# 网站 B
site-b.com {
    reverse_proxy localhost:3000
}

# API 子域名
api.site-b.com {
    reverse_proxy localhost:8000
}

示例 4：带认证的管理后台¶

admin.example.com {
    basicauth * {
        admin $2a$14$Zkx9...  # 密码哈希
    }
    reverse_proxy localhost:8080
}

生成密码哈希：

caddy hash-password --plaintext 'your-password'

小结¶

本章介绍了 Caddy 的多种安装方式和基本配置：

推荐使用官方脚本或 Docker 安装
Caddyfile 语法简洁直观
使用 systemd 管理服务
caddy reload 可无停机更新配置

下一章将详细介绍反向代理配置。