注意：这是caddy镜像的arm64v8架构专用仓库——更多信息请参见镜像文档中的“非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服务器，支持自动HTTPS，采用Go语言编写。

如何使用本镜像

⚠️ 关于持久化数据的注意事项

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

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

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

构建自定义 Caddy 镜像

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

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

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

添加自定义 Caddy 模块

Caddy 可通过“模块”进行扩展。详见 [***] Caddy 官网下载页面 找到可用模块列表。

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

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

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

注意第二个 FROM 指令——通过将新构建的二进制文件叠加到常规 arm64v8/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 库会尝试增加其 socket 的缓冲区大小。NET_ADMIN capability 允许它覆盖操作系统的低默认限制，而无需通过 sysctl 更改内核参数。

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

更多详情参见 [***]

Docker Compose 示例

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

yaml
services:
  caddy:
    image: arm64v8/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 执行优雅重载。

镜像变体

arm64v8/caddy 镜像有多种版本，每种版本针对特定用例设计。

arm64v8/caddy:<version>

这是默认镜像。如果不确定需求，通常应使用此版本。它既可用作临时容器（挂载源代码并启动容器以运行应用），也可用作构建其他镜像的基础。

arm64v8/caddy:<version>-alpine

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

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

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

许可协议

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

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

可能通过自动检测获得的其他许可信息可在 repo-info 仓库的 caddy/ 目录 中找到。

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