Caddy 2.11.7 Docker Compose 部署指南

目标：使用 Docker Compose 一键部署 Caddy（官方镜像 caddy:2，实测容器内 caddy version 为 v2.11.7），涵盖配置挂载、数据持久化、常用环境变量与等价 docker run 方式。本文档已在 /tmp/caddy-compose 目录实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• 容器引擎：Docker 29.8.1 + Docker Compose v2
• 镜像：caddy:2（实测容器内 Caddy v2.11.7）
• 工作目录：/tmp/caddy-compose
• 映射端口：宿主机 18080→容器 80、18443→容器 443

二、镜像选型说明

• caddy:2：官方主线镜像，跟随 2.x 最新版（实测为 2.11.7），适合持续更新场景。
• caddy:2-alpine：Alpine 精简版，体积更小，适合对镜像大小敏感的场景。
• caddy:2.11.7：锁定小版本，适合生产固定版本部署。
• 镜像内默认 CADDY_VERSION=v2.11.7 环境变量标识版本。

三、前置条件

• 已安装 Docker 与 Docker Compose v2
• 宿主机 18080、18443 端口未被占用

四、部署步骤

4.1 准备目录与文件

mkdir -p /tmp/caddy-compose/{data,config,www}
cd /tmp/caddy-compose

4.2 编写 Caddyfile

/tmp/caddy-compose/Caddyfile：

:80 {
    root * /usr/share/caddy
    file_server
}

💡 说明：容器内静态文件根目录统一用 /usr/share/caddy，通过挂载覆盖。

4.3 编写 docker-compose.yml

/tmp/caddy-compose/docker-compose.yml：

services:
  caddy:
    image: caddy:2
    container_name: caddy-compose-test
    restart: unless-stopped
    ports:
      - "18080:80"
      - "18443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./data:/data
      - ./config:/config
      - ./www:/usr/share/caddy
    environment:
      - TZ=Asia/Shanghai

💡 说明：

• ./Caddyfile:/etc/caddy/Caddyfile：配置文件挂载，改配置后重启即生效；
• ./data:/data：证书与状态数据持久化（本地证书、自动 HTTPS 数据）；
• ./config:/config：Caddy 配置缓存目录；
• ./www:/usr/share/caddy：站点静态文件目录；
• TZ=Asia/Shanghai：设置时区，日志时间与国内一致。

4.4 准备站点文件并启动

echo '<h1>Caddy Compose 实测</h1>' > www/index.html
docker compose up -d
docker compose ps

实测回显：

NAME                 IMAGE     COMMAND                  SERVICE   STATUS
caddy-compose-test   caddy:2   "caddy run --config …"   caddy     Up Less than a second

4.5 验证

curl http://127.0.0.1:18080/
curl -sI http://127.0.0.1:18080/

实测回显：

<h1>Caddy Compose 实测</h1>
HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: text/html; charset=utf-8
Etag: "dlz1he1umgiz-u"
Server: Caddy

五、数据持久化说明

• 配置：Caddyfile 挂载在 /etc/caddy/Caddyfile，宿主机改动即对应容器内内容；
• 证书/状态：/data 保存自动 HTTPS 证书与存储数据（对应无容器部署的 /var/lib/caddy）；
• 配置缓存：/config 保存 Caddy 的配置快照；
• 站点文件：/usr/share/caddy 即 Web 根目录，持久化到宿主机 www/。

六、常用环境变量表

七、常用配置参数说明（command）

• caddy run --config /etc/caddy/Caddyfile：默认启动命令，加载配置文件。
• --adapter：指定配置适配器（默认 caddyfile）。
• --environ：运行时注入环境变量到进程。
• --resume：重启时恢复上次的自动保存配置（配合 Admin API 动态修改时使用）。

八、配置文件持久化（conf 挂载）

volumes:
  - ./Caddyfile:/etc/caddy/Caddyfile
  - ./data:/data
  - ./config:/config

⚠️ 注意：挂载的 Caddyfile 若用 caddy fmt --overwrite 格式化，会直接改写宿主机文件；建议先备份。

九、等价 docker run 运行方式

docker run -d --name caddy-compose-test \
  --restart unless-stopped \
  -p 18080:80 -p 18443:443 \
  -v "$(pwd)/Caddyfile:/etc/caddy/Caddyfile" \
  -v "$(pwd)/data:/data" \
  -v "$(pwd)/config:/config" \
  -v "$(pwd)/www:/usr/share/caddy" \
  -e TZ=Asia/Shanghai \
  caddy:2

十、常用运维命令

# 查看容器内 Caddy 版本
docker exec caddy-compose-test caddy version

# 查看已加载模块数量
docker exec caddy-compose-test caddy list-modules | wc -l   # 实测 137

# 校验挂载的配置文件
docker exec caddy-compose-test caddy validate --config /etc/caddy/Caddyfile

# 查看 Admin API 当前配置
docker exec caddy-compose-test curl -s http://localhost:2019/config/

# 查看日志
docker compose logs -f caddy

# 停止/删除
docker compose down

十一、常见问题（FAQ）

Q1：启动报 failed to bind host port ... address already in use A：宿主机端口被占用。改 ports 映射为未占用端口（如 18080:80），或先释放占用端口。

Q2：curl 访问返回 404 A：检查 www/ 下是否有 index.html，且 Caddyfile 中 root * /usr/share/caddy 路径正确。

Q3：HTTPS 自动证书未生成 A：自动 HTTPS 需要配置域名（非 :80/IP 直写）并保证公网可解析；纯内网环境可用 tls internal 自签证书。

十二、参考链接

• Caddy Docker 官方说明：https://caddyserver.com/docs/installation#docker
• Docker Hub caddy 镜像：https://hub.docker.com/_/caddy
• Caddyfile 配置参考：https://caddyserver.com/docs/caddyfile