winamd64/caddy Docker 镜像 - 轩辕镜像

注意：这是 官方 caddy 镜像 的 windows-amd64 架构构建的“按架构”仓库——更多信息，请参见官方镜像文档中的“除 amd64 外的架构？”“Architectures other than amd64?” 和官方镜像FAQ中的“镜像源在Git中更改后怎么办？”“An image's source changed in Git, now what?”。

快速参考

-** 维护者 **：
Caddy Docker 维护者

-** 获取帮助 **：
Caddy 社区论坛

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

（参见 FAQ 中的“‘Shared’和‘Simple’标签有什么区别？”“What's the difference between 'Shared' and 'Simple' tags?”。）

Simple Tags

• 2.10.2-windowsservercore-ltsc2022, 2.10-windowsservercore-ltsc2022, 2-windowsservercore-ltsc2022, windowsservercore-ltsc2022

• 2.10.2-windowsservercore-ltsc2025, 2.10-windowsservercore-ltsc2025, 2-windowsservercore-ltsc2025, windowsservercore-ltsc2025

• 2.10.2-builder-windowsservercore-ltsc2022, 2.10-builder-windowsservercore-ltsc2022, 2-builder-windowsservercore-ltsc2022, builder-windowsservercore-ltsc2022

• 2.10.2-builder-windowsservercore-ltsc2025, 2.10-builder-windowsservercore-ltsc2025, 2-builder-windowsservercore-ltsc2025, builder-windowsservercore-ltsc2025

共享标签

• 2.10.2, 2.10, 2, latest:

  • 2.10.2-windowsservercore-ltsc2022
  • 2.10.2-windowsservercore-ltsc2025

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

  • 2.10.2-builder-windowsservercore-ltsc2022
  • 2.10.2-builder-windowsservercore-ltsc2025

• 2.10.2-windowsservercore, 2.10-windowsservercore, 2-windowsservercore, windowsservercore:

  • 2.10.2-windowsservercore-ltsc2022
  • 2.10.2-windowsservercore-ltsc2025

快速参考（续）

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

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

-** 已发布镜像制品详情 **：
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 \
    winamd64/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 \
    winamd64/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 \
    winamd64/caddy caddy file-server --domain example.com

关键在于 Caddy 需监听 80 和 443 端口（ACME HTTP 挑战必需）。

详见 Caddy 文档 了解自动 HTTPS 支持。

构建自定义 Caddy 镜像

多数生产环境用户不会依赖容器内文件挂载，而是基于 winamd64/caddy 构建自定义镜像：

Dockerfile
# 注意：生产环境请勿使用 :latest 标签
FROM winamd64/caddy:<version>

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

添加自定义 Caddy 模块

Caddy 可通过“模块”扩展功能（详见 扩展 Caddy）。可用模块列表见 Caddy 下载页。

可使用 :builder 镜像快速构建包含自定义模块的 Caddy 二进制文件：

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

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

注意第二个 FROM 指令：通过将新构建的二进制文件覆盖到常规 winamd64/caddy 镜像，生成更小的最终镜像。

xcaddy 工具用于 构建新的 Caddy 入口点，支持指定模块名或带版本的模块（用 @ 分隔），也可指定 Caddy 版本（标签或提交哈希）。详见 xcaddy 使用说明。

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

优雅重载

配置更改时，Caddy 无需完全重启。可使用 caddy reload 命令实现零停机配置重载。

Docker 环境中，推荐通过在运行中的容器内执行 caddy reload 触发重载：

首先获取容器 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 为可选操作，虽可能存在安全影响，但风险较低。

详见 UDP 缓冲区大小。

Docker Compose 示例

若偏好使用 docker compose，以下是 compose.yaml 服务定义示例（假设已按上文在 $PWD/conf 中放置自定义 Caddyfile）：

yaml
services:
  caddy:
    image: winamd64/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 执行。

镜像变体

winamd64/caddy 镜像提供多种变体，适用于不同场景：

winamd64/caddy:<version>

默认镜像。若不确定需求，建议使用此变体。既可作为临时容器（挂载源码启动），也可作为基础镜像构建其他镜像。

winamd64/caddy:<version>-windowsservercore

基于 Windows Server Core (mcr.microsoft.com/windows/servercore)。仅在支持该基础镜像的环境中可用，如 Windows 10 专业版/企业版（周年更新）或 Windows Server 2016。

Windows