注意： 这是 *** caddy 镜像 的 arm32v7 架构专用仓库 — 更多信息请参见镜像文档中的 "非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 \
    arm32v7/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 \
    arm32v7/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 \
    arm32v7/caddy caddy file-server --domain example.com

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

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

构建自己的 Caddy 镜像

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

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

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

添加自定义 Caddy 模块

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

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

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

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

注意第二个 FROM 指令 — 这通过将新构建的二进制文件覆盖到常规 arm32v7/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: arm32v7/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 进行优雅重载。

镜像变体

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

arm32v7/caddy:<version>

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

arm32v7/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/ 目录 中找到一些能够自动检测到的额外许可证信息。

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