注意：这是 caddy镜像 的 amd64 架构构建的"per-architecture"仓库——更多信息，请参见镜像文档中的"除amd64外的架构？"[[]] 和镜像FAQ中的"镜像源在Git中更改后怎么办？"[[***]]。

快速参考

• 维护者：
  Caddy Docker维护者

• 获取帮助：
  Caddy社区论坛

支持的标签及对应的 Dockerfile 链接

（参见FAQ中的"‘Shared’和‘Simple’标签有什么区别？"[[***]]。）

Simple Tags

• 2.10.2-alpine, 2.10-alpine, 2-alpine, alpine

• 2.10.2-builder-alpine, 2.10-builder-alpine, 2-builder-alpine, builder-alpine

Shared Tags

• 2.10.2, 2.10, 2, latest:

  • 2.10.2-alpine

• 2.10.2-builder, 2.10-builder, 2-builder, builder:

  • 2.10.2-builder-alpine

快速参考（续）

• 问题提交地址：
  [***]

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

• 已发布镜像 artifact 详情：
  repo-info仓库的repos/caddy/目录（历史记录）
  （镜像元数据、传输大小等）

• 镜像更新：
  official-images仓库的library/caddy标签
  official-images仓库的library/caddy文件（历史记录）

• 本描述的来源：
  docs仓库的caddy/目录（历史记录）

!logo

什么是Caddy？

Caddy 2 是一款功能强大的企业级开源Web服务器，采用Go语言编写，具备自动HTTPS功能。

如何使用此镜像

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

Caddy需要对两个位置具有写权限：数据目录和配置目录。虽然不必持久化配置目录中的文件（但可能会方便），但持久化数据目录非常重要。

根据文档：

数据目录不得视为缓存。其内容不是临时的或仅为性能而存在。Caddy将TLS证书、私钥、OCSP staples和其他必要信息存储在数据目录中。未经了解相关影响，不应清除该目录。

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

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

注意，命名卷在容器重启和终止后仍会保留，因此当迁移到新版本镜像时，可以重用相同的数据和配置目录。

基本用法

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

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

要覆盖默认的Caddyfile，可以在$PWD/conf子文件夹中创建一个Caddyfile，并将此文件夹挂载到/etc/caddy：

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

⚠️ 不要将Caddyfile直接挂载到/etc/caddy/Caddyfile

如果使用vim或其他会更改编辑文件inode的编辑器，只有在重新创建容器时，更改才会在容器内生效，详情参见此Medium文章。使用此类编辑器时，Caddy的平滑重载功能可能无法按预期工作，如此issue中所述。

使用Caddy镜像实现自动TLS

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

console
$ 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 \
    amd64/caddy caddy file-server --domain example.com

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

有关自动HTTPS支持的更多信息，请参见Caddy文档！

构建自己的基于Caddy的镜像

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

Dockerfile
# 注意：在生产站点中切勿使用:latest标签
FROM amd64/caddy:<version>

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

添加自定义Caddy模块

Caddy可通过"模块"进行扩展。有关完整详情，请参见[***]

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

Dockerfile
FROM amd64/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 amd64/caddy:<version>

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

注意第二个FROM指令——通过简单地将新构建的二进制文件覆盖到常规amd64/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。

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

Linux capabilities

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

为容器提供此capability是可选的，虽然不太可能，但可能存在安全隐患。

更多详情参见[***]

Docker Compose示例

如果您更喜欢使用docker compose运行服务栈，以下是一个示例服务定义，位于名为compose.yaml的文件中。该配置假设您已按照上文所述将自定义Caddyfile放入$PWD/conf。

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

volumes:
  caddy_data:
  caddy_config:

然后可通过docker compose exec -w /etc/caddy caddy caddy reload进行平滑重载。

镜像变体

amd64/caddy镜像有多种变体，每种设计用于特定用例。

amd64/caddy:<version>

这是默认镜像。如果您不确定自己的需求，可能需要使用此镜像。它既设计为临时容器（挂载源代码并启动容器以启动应用），也可用作构建其他镜像的基础。

amd64/caddy:<version>-alpine

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

当最终镜像大小尽可能小是您的主要关注点时，此变体非常有用。需要注意的主要问题是它使用musl libc而非glibc及相关库，因此软件可能会因libc要求/假设的深度而遇到问题。参见此Hacker News评论线程，了解可能出现的问题以及使用Alpine-based镜像的优缺点比较。

为最小化镜像大小，Alpine-based镜像中通常不包含其他相关工具（如git或bash）。以此镜像为基础，可在您自己的Dockerfile中添加所需工具（如果不熟悉如何安装包，请参见alpine镜像描述中的示例）。

许可证

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

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

一些能够自动检测到的其他许可证信息可能位于repo-info仓库的caddy/目录中。

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