amd64/caddy Docker Image Overview

amd64/caddy

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

0 次下载activeamd64镜像

注意：这是 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进行平滑重载。