s390x/caddy Docker 镜像 - 轩辕镜像

注意：这是 caddy 官方镜像 的 s390x 架构专用仓库——更多信息，请参见官方镜像文档中的「除 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

• 镜像制品详情：
  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 \
    s390x/caddy
...
$ curl http://localhost/
hello world

若要覆盖默认 Caddyfile，可在当前目录的 conf 子文件夹中创建 Caddyfile，并将该文件夹挂载到 /etc/caddy：

console
$ docker run -d -p 80:80 \
    -v $PWD/conf:/etc/caddy \
    -v caddy_data:/data \
    s390x/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 \
    s390x/caddy caddy file-server --domain example.com

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

更多自动 HTTPS 支持信息见 Caddy 文档！

构建自定义 Caddy 镜像

大多数生产环境用户不会依赖挂载文件到容器，而是基于 s390x/caddy 构建自己的镜像：

Dockerfile
# 注意：生产环境不要使用 :latest 标签
FROM s390x/caddy:<version>

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

添加自定义 Caddy 模块

Caddy 可通过「模块」扩展功能。详见 [***] Caddy 官网下载页。

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

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

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

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

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

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

优雅重载

更改配置时无需完全重启 Caddy。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 权限

Caddy 默认启用 HTTP/3 支持。为提升 UDP 协议性能，底层 quic-go 库会尝试增加其 socket 缓冲区大小。NET_ADMIN 权限允许其覆盖操作系统的低默认限制，无需通过 sysctl 修改内核参数。

授予容器此权限是可选的，可能存在（尽管可能性低）安全影响。

更多详情见 [***]

Docker Compose 示例

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

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

镜像变体

s390x/caddy 镜像有多种版本，适用于不同场景。

s390x/caddy:<version>

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

s390x/caddy:<version>-alpine

此镜像基于流行的 Alpine Linux 项目（alpine 官方镜像）。Alpine Linux 比大多数发行版基础镜像小得多（约 5MB），因此生成的镜像更精简。

当首要目标是最小化最终镜像大小时，此变体非常有用。需注意其使用 musl libc 而非 glibc 等，软件可能因 libc 依赖/假设深度而遇到问题。更多讨论见 此 Hacker News 评论 thread。

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

许可证

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

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

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

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