快速参考

• 维护者：
  Caddy Docker 维护者

• 获取帮助的途径：
  Caddy 社区论坛

支持的标签和相应的 Dockerfile 链接

（请参阅常见问题解答中的“‘共享’和‘简单’标签有什么区别？”）

简单标签

• 2.8.4-alpine, 2.8-alpine, 2-alpine, alpine

• 2.8.4-builder-alpine, 2.8-builder-alpine, 2-builder-alpine, builder-alpine

• 2.8.4-windowsservercore-1809, 2.8-windowsservercore-1809, 2-windowsservercore-1809, windowsservercore-1809

• 2.8.4-windowsservercore-ltsc2022, 2.8-windowsservercore-ltsc2022, 2-windowsservercore-ltsc2022, windowsservercore-ltsc2022

• 2.8.4-builder-windowsservercore-1809, 2.8-builder-windowsservercore-1809, 2-builder-windowsservercore-1809, builder-windowsservercore-1809

• 2.8.4-builder-windowsservercore-ltsc2022, 2.8-builder-windowsservercore-ltsc2022, 2-builder-windowsservercore-ltsc2022, builder-windowsservercore-ltsc2022

共享标签

• 2.8.4, 2.8, 2, latest:

  • 2.8.4-alpine
  • 2.8.4-windowsservercore-1809
  • 2.8.4-windowsservercore-ltsc2022

  • 2.8.4-builder, 2.8-builder, 2-builder, builder:

  • 2.8.4-builder-alpine

  • 2.8.4-builder-windowsservercore-1809
  • 2.8.4-builder-windowsservercore-ltsc2022

  • 2.8.4-windowsservercore, 2.8-windowsservercore, 2-windowsservercore, windowsservercore:

  • 2.8.4-windowsservercore-1809

  • 2.8.4-windowsservercore-ltsc2022

快速参考（续）

• 问题提交至何处：
  https://github.com/caddyserver/caddy-docker/issues

• 支持的架构：（更多信息）
  amd64, arm32v6, arm32v7, arm64v8, ppc64le, riscv64, s390x, windows-amd64

• 已发布的映像工件详细信息：
  repo-info repo 的 repos/caddy/ 目录（历史记录）
  （图像元数据、传输大小等）

• 图像更新：
  官方镜像仓库的 library/caddy 标签
  官方镜像仓库的 library/caddy 文件（历史记录）

• 来源：此描述的来源：
  docs 存储库的 caddy/ 目录（历史记录）

什么是 Caddy？

Caddy 2 是一个强大的、企业级的、开源的 Web 服务器，用 Go 编写，具有自动 HTTPS 功能。

如何使用此图像

⚠️ 关于持久化数据的说明

Caddy 需要对两个位置具有写入访问权限：数据目录和配置目录。虽然不必保留存储在配置目录中的文件，但这样做很方便。但是，保留数据目录非常重要。

从文档中：

数据目录不能被视为缓存。其内容不是短暂的，也不仅仅是为了性能。Caddy 将 TLS 证书、私钥、OCSP 装订和其他必要信息存储到数据目录中。在不了解其影响的情况下，不应清除它。

此图像提供了两个卷的挂载点： /data 和 /config 。

在下面的示例中，将命名卷 caddy_data 挂载到 /data ，以便数据将被持久化。

请注意，命名卷在容器重启和终止时会被保留，因此如果您迁移到新的映像版本，相同的数据和配置目录可以被重复使用。

基本用法

默认配置文件仅从 /usr/share/caddy 提供文件，因此如果您想从当前工作目录提供 index.html ：

$ echo "hello world" > index.html
$ docker run -d -p 80:80 \
    -v $PWD/index.html:/usr/share/caddy/index.html \
    -v caddy_data:/data \
    caddy
...
$ curl http://localhost/
hello world

若要覆盖默认的 Caddyfile ，您可以在 /etc/caddy/Caddyfile 挂载一个新的：

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

使用 Caddy 镜像自动进行 TLS

默认的 Caddyfile 仅监听端口 80 ，并且没有设置自动 TLS。但是，如果您的站点有域名，并且其 A/AAAA DNS 记录已正确指向此机器的公共 IP，则可以使用此命令简单地通过 HTTPS 提供站点服务：

$ docker run -d --cap-add=NET_ADMIN -p 80:80 -p 443:443 -p 443:443/udp \
    -v /site:/srv \
    -v caddy_data:/data \
    -v caddy_config:/config \
    caddy caddy file-server --domain example.com

这里的关键是 Caddy 能够监听端口 80 和 443 ，这两个端口都是 ACME HTTP 挑战所需要的。

查看 Caddy 的文档以获取有关自动 HTTPS 支持的更多信息！

构建您自己的基于 Caddy 的镜像

大多数部署生产站点的用户不会希望依赖于将文件挂载到容器中，而是会基于 caddy 创建自己的镜像：

# note: never use the :latest tag in a production site
FROM caddy:<version>

COPY Caddyfile /etc/caddy/Caddyfile
COPY site /srv

添加自定义 Caddy 模块

Caddy 可通过使用“模块”进行扩展。请参阅 https://caddyserver.com/docs/extending-caddy 以获取完整详细信息。您可以在 Caddy 网站的下载页面上找到可用模块列表。

您可以使用 :builder 映像作为构建新 Caddy 二进制文件的快捷方式：

FROM caddy:<version>-builder AS builder

RUN xcaddy build \
    --with github.com/caddyserver/nginx-adapter \
    --with github.com/hairyhenderson/caddy-teapot-module@v0.0.3-0

FROM caddy:<version>

COPY --from=builder /usr/bin/caddy /usr/bin/caddy

请注意第二个 FROM 指令 - 这会通过简单地将新构建的二进制文件覆盖在常规的 caddy 映像之上，生成一个小得多的映像。

xcaddy 工具用于使用提供的模块构建新的 Caddy 入口点。您可以仅指定模块名称，也可以指定带有版本的名称（用 @ 分隔）。您还可以指定要构建的 Caddy 的特定版本（可以是版本标签或提交哈希）。阅读有关 xcaddy 用法的更多信息。

请注意，“标准”Caddy 模块（ github.com/caddyserver/caddy/master/modules/standard ）始终包含在内。

优雅的重新加载

Caddy 在配置更改时不需要完全重启。Caddy 附带了一个 caddy reload 命令，可用于在零停机时间内重新加载其配置。

在 Docker 中运行 Caddy 时，触发配置重新加载的推荐方法是在运行的容器中执行 caddy reload 命令。

首先，您需要确定您的容器 ID 或名称。然后，将容器 ID 传递给 docker exec 。工作目录设置为 /etc/caddy ，因此 Caddy 可以在没有其他参数的情况下找到您的 Caddyfile。

$ caddy_container_id=$(docker ps | grep caddy | awk '{print $1;}')
$ docker exec -w /etc/caddy $caddy_container_id caddy reload

Linux 能力

Caddy 默认启用 HTTP/3 支持。为了提高这个基于 UDP 的协议的性能，底层的 quic-go 库尝试增加其套接字的缓冲区大小。 NET_ADMIN 功能允许它覆盖操作系统的低默认限制，而无需通过 sysctl 更改内核参数。

赋予容器此功能是可选的，并且有可能（尽管不太可能）产生安全影响。

请访问 https://github.com/quic-go/quic-go/wiki/UDP-Buffer-Sizes 以获取更多详细信息。

Docker Compose 示例

如果您更喜欢使用 docker-compose 来运行您的堆栈，这里有一个示例服务定义。

version: "3.7"

services:
  caddy:
    image: caddy:<version>
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - $PWD/Caddyfile:/etc/caddy/Caddyfile
      - $PWD/site:/srv
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
    external: true
  caddy_config:

将数据卷定义为 external 可确保 docker-compose down 不会删除该卷。您可能需要使用 docker volume create [project-name]_caddy_data 手动创建它。

图像变体

caddy 图像有多种类型，每种都针对特定的用例进行了设计。

caddy:<version>

这是默认的镜像。如果您不确定自己的需求是什么，您可能想要使用这个。它被设计为既可以用作一次性容器（挂载您的源代码并启动容器以启动您的应用程序），也可以用作构建其他镜像的基础。

caddy:<version>-alpine

该镜像基于流行的 Alpine Linux 项目，可在 alpine 官方镜像中使用。Alpine Linux 比大多数发行版基础镜像（约 5MB）小得多，因此通常会生成更精简的镜像。

当您主要关注最终图像大小尽可能小时，此变体很有用。需要注意的主要警告是，它确实使用 musl libc 而不是 glibc 等，因此软件通常会根据其 libc 要求/假设的深度遇到问题。有关可能出现的问题以及使用基于 Alpine 的映像的一些优缺点比较的更多讨论，请参阅此 Hacker News 评论线程。

为了最小化镜像大小，在基于 Alpine 的镜像中包含额外的相关工具（如 git 或 bash ）是不常见的。使用此镜像作为基础，在您自己的 Dockerfile 中添加您需要的东西（如果您不熟悉如何安装软件包，请参阅 alpine 镜像描述中的示例）。

caddy:<version>-windowsservercore

此映像基于 Windows Server Core ( microsoft/windowsservercore )。因此，它仅在该映像适用的位置工作，例如 Windows 10 专业版/企业版（周年纪念版）或 Windows Server 2016。

有关如何在 Windows 上运行 Docker 的信息，请参阅 Microsoft 提供的相关“快速入门”指南：

• Windows Server 快速入门
• Windows 10 快速入门

许可证

查看此映像中包含的软件的许可证信息。

与所有 Docker 镜像一样，这些镜像可能还包含其他软件，这些软件可能受其他许可证的约束（例如来自基础发行版的 Bash 等，以及所包含的主要软件的任何直接或间接依赖项）。

一些能够自动检测到的额外许可证信息可能会在 repo-info 存储库的 caddy/ 目录中找到。

对于任何预构建的映像使用，映像用户有责任确保对此映像的任何使用都符合其中包含的所有软件的任何相关许可证。