02 - 安装与部署 / Installation & Deployment

安装与部署 / Installation & Deployment

🟢 基础 / Basics

方式一：包管理器安装（推荐）

Debian / Ubuntu:

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

Fedora / RHEL / CentOS:

dnf install 'dnf-command(copr)'
dnf copr enable @caddy/caddy
dnf install caddy

macOS (Homebrew):

brew install caddy

安装完成后，验证：

caddy version
# v2.x.x

方式二：直接下载二进制

从 github.com/caddyserver/caddy/releases 下载对应平台的二进制文件。

# Linux amd64
curl -LO https://github.com/caddyserver/caddy/releases/download/v2.9.1/caddy_2.9.1_linux_amd64.tar.gz
tar xzf caddy_2.9.1_linux_amd64.tar.gz
sudo mv caddy /usr/bin/caddy
sudo chmod +x /usr/bin/caddy

第一次运行

# 创建一个简单的 Caddyfile
echo 'localhost { respond "Hello, Caddy!" }' > Caddyfile
caddy start
# 访问 https://localhost

caddy start 在后台运行，caddy run 在前台运行（调试用）。

🟡 进阶 / Intermediate

Systemd 服务管理

包管理器安装会自动创建 systemd service。手动安装时需要自己创建：

# /etc/systemd/system/caddy.service
[Unit]
Description=Caddy
Documentation=https://caddyserver.com/docs/
After=network.target network-online.target
Requires=network-online.target

[Service]
Type=notify
User=caddy
Group=caddy
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/Caddyfile
ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile --force
TimeoutStopSec=5s
LimitNOFILE=1048576
LimitNPROC=512
PrivateTmp=true
ProtectSystem=full
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

常用命令：

sudo systemctl daemon-reload
sudo systemctl enable caddy
sudo systemctl start caddy
sudo systemctl status caddy
journalctl -u caddy --no-pager -n 50   # 查看日志

配置文件路径约定

安装方式	Caddyfile 路径	数据目录
包管理器	`/etc/caddy/Caddyfile`	`/var/lib/caddy`
手动	`./Caddyfile` 或 `~/.config/caddy/Caddyfile`	`~/.local/share/caddy`

环境变量配置

通过 systemd override 添加环境变量：

# /etc/systemd/system/caddy.service.d/override.conf
[Service]
Environment="HOME=/var/lib/caddy"
Environment="CADDY_ADMIN=127.0.0.1:2019"

🔴 高级 / Advanced

从源码编译（自定义插件）

使用 xcaddy 构建包含自定义插件的 Caddy：

# 安装 xcaddy
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

# 带插件编译
xcaddy build \
    --with github.com/caddyserver/transform-encoder \
    --with github.com/hslatman/caddy-crowdsec-bouncer \
    --output /usr/local/bin/caddy

# 验证插件是否加载
caddy list-modules | grep -i crowdsec

交叉编译

# 编译 Linux ARM64 版本
GOOS=linux GOARCH=arm64 xcaddy build --output caddy-linux-arm64

# 编译 Windows 版本
GOOS=windows GOARCH=amd64 xcaddy build --output caddy.exe

多实例部署策略

在同一台机器运行多个 Caddy 实例时，需要隔离：

# 实例 1：前端站
CADDY_ADMIN=127.0.0.1:2019 caddy run --config /etc/caddy/site1.json

# 实例 2：API 网关
CADDY_ADMIN=127.0.0.1:2020 caddy run --config /etc/caddy/site2.json

每个实例使用不同的 admin 端口和不同的 data 目录。

在无 root 环境下绑定 80/443

方式一：设置 CAP_NET_BIND_SERVICE

sudo setcap cap_net_bind_service=+ep /usr/bin/caddy

方式二：使用 authbind

sudo touch /etc/authbind/byport/80
sudo chmod 777 /etc/authbind/byport/80
authbind caddy run

方式三：iptables 端口转发

sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443

小结 / Summary

层级	内容
🟢 基础	包管理器安装、caddy start / caddy run
🟡 进阶	systemd 服务管理、配置路径、环境变量
🔴 高级	xcaddy 自定义编译、交叉编译、多实例、非 root 绑定低端口

下一章：静态文件服务 / Static File Serving

强曰为道