轩辕镜像 · 专业版提供 SLA 级可用性指标 · 免费版为公共服务，可能存在不可用情况。请提交工单获取在线技术支持，欢迎加入官方QQ群：13763429 进行技术交流。
面向开发者与科研用户，提供开源镜像的搜索和访问支持。所有镜像均来源于原始仓库，本站不存储、不修改、不传播任何内容。
返回博客首页
Caddy Docker 容器化部署指南
2025/12/18Docker,Caddy轩辕镜像团队约 19 分钟阅读

Caddy Docker 容器化部署指南

Caddy是一款功能强大的企业级开源Web服务器，以其内置的自动HTTPS功能和简洁的配置语法而闻名。作为用Go语言编写的现代Web服务器，Caddy提供了比传统服务器更简单的配置方式和更丰富的原生功能，包括自动TLS证书管理、HTTP/2和HTTP/3支持、反向代理、负载均衡等特性。

caddydocker部署教程

概述

Caddy是一款功能强大的企业级开源Web服务器，以其内置的自动HTTPS功能和简洁的配置语法而闻名。作为用Go语言编写的现代Web服务器，Caddy提供了比传统服务器更简单的配置方式和更丰富的原生功能，包括自动TLS证书管理、HTTP/2和HTTP/3支持、反向代理、负载均衡等特性。

本文档将详细介绍如何通过Docker容器化方式部署Caddy，包括环境准备、镜像拉取、容器配置、功能测试和生产环境优化等内容，帮助开发者快速实现Caddy的容器化部署与管理。

环境准备

安装Docker环境

在开始部署前，需要确保目标服务器已安装Docker环境。推荐使用以下一键安装脚本部署Docker：

bash
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

执行上述命令后，脚本将自动完成Docker引擎、Docker CLI、Docker Compose等组件的安装与配置。安装完成后，可以通过以下命令验证Docker是否正常运行：

bash
docker --version
docker compose version

镜像准备

拉取Caddy镜像

使用以下命令通过轩辕镜像访问支持域名拉取最新版本的Caddy镜像：

bash
docker pull xxx.xuanyuan.run/library/caddy:latest

拉取完成后，可以使用以下命令验证镜像是否成功下载：

bash
docker images | grep caddy

若需要指定特定版本的Caddy镜像，可以通过轩辕镜像标签列表页面查看所有可用标签：Caddy镜像标签列表，然后使用相应标签拉取：

bash
docker pull xxx.xuanyuan.run/library/caddy:<指定标签>

容器部署

基础部署

Caddy容器的基础部署命令如下，该命令将启动一个基本功能的Caddy服务器实例：

bash
docker run -d \
  --name caddy \
  -p 80:80 \
  -v caddy_data:/data \
  -v caddy_config:/config \
  xxx.xuanyuan.run/library/caddy:latest

参数说明：

  • -d: 后台运行容器
  • --name caddy: 指定容器名称为"caddy"
  • -p 80:80: 映射容器的80端口到主机的80端口
  • -v caddy_data:/data: 挂载命名卷caddy_data到容器的/data目录，用于持久化存储TLS证书等数据
  • -v caddy_config:/config: 挂载命名卷caddy_config到容器的/config目录，用于持久化配置文件

自定义配置文件部署

通常情况下，用户需要根据自身需求自定义CADDY配置。推荐通过挂载本地配置文件的方式进行部署：

  1. 首先在本地创建配置文件目录和CADDY配置文件：
bash
mkdir -p ./caddy/conf
touch ./caddy/conf/Caddyfile
  1. 使用文本编辑器编辑Caddyfile，添加自定义配置：
bash
nano ./caddy/conf/Caddyfile
  1. 启动容器并挂载配置文件目录：
bash
docker run -d \
  --name caddy \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  -v $PWD/caddy/conf:/etc/caddy \
  -v caddy_data:/data \
  -v caddy_config:/config \
  xxx.xuanyuan.run/library/caddy:latest

部署静态网站

要使用CADDY托管静态网站，可以通过挂载网站文件目录到容器中：

  1. 创建网站文件目录并添加示例页面：
bash
mkdir -p ./caddy/site
echo "Hello Caddy" > ./caddy/site/index.html
  1. 编辑Caddyfile配置文件，添加网站根目录配置：
localhost

root * /srv
file_server
  1. 启动容器并挂载网站目录：
bash
docker run -d \
  --name caddy \
  -p 80:80 \
  -v $PWD/caddy/conf:/etc/caddy \
  -v $PWD/caddy/site:/srv \
  -v caddy_data:/data \
  -v caddy_config:/config \
  xxx.xuanyuan.run/library/caddy:latest

启用自动HTTPS部署

CADDY的核心特性之一是自动HTTPS功能。要启用此功能，需要确保服务器具有公网IP且域名已正确解析到该IP：

bash
docker run -d \
  --name caddy \
  --cap-add=NET_ADMIN \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  -v $PWD/caddy/conf:/etc/caddy \
  -v $PWD/caddy/site:/srv \
  -v caddy_data:/data \
  -v caddy_config:/config \
  xxx.xuanyuan.run/library/caddy:latest caddy file-server --domain example.com

参数说明：

  • --cap-add=NET_ADMIN: 添加网络管理权限，用于优化HTTP/3性能
  • caddy file-server --domain example.com: 指定启动命令，使用文件服务器模式并自动配置HTTPS

Docker Compose部署

对于更复杂的部署需求，推荐使用Docker Compose进行管理。创建compose.yaml文件：

yaml
version: '3.8'

services:
  caddy:
    image: xxx.xuanyuan.run/library/caddy:latest
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./caddy/conf:/etc/caddy
      - ./caddy/site:/srv
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

使用以下命令启动服务：

bash
docker compose up -d

功能测试

验证容器运行状态

容器启动后，首先检查容器是否正常运行：

bash
docker ps | grep caddy

如果容器状态显示为"Up"，则表示Caddy服务已成功启动。若容器未正常启动，可以通过以下命令查看日志排查问题：

bash
docker logs caddy

访问测试

对于基础部署或静态网站部署，可以通过以下命令测试服务是否正常响应：

bash
curl http://localhost

如果配置了域名和自动HTTPS，可以使用浏览器访问https://your-domain.com，或使用以下curl命令测试：

bash
curl https://your-domain.com

配置文件验证

Caddy提供了配置文件验证功能，可以检查配置文件语法是否正确：

bash
docker exec -it caddy caddy validate --config /etc/caddy/Caddyfile

配置重载测试

Caddy支持配置的热重载，无需重启容器即可应用新配置：

bash
# 修改配置文件后执行以下命令
docker exec -w /etc/caddy caddy caddy reload

生产环境建议

版本管理

在生产环境中，不建议使用:latest标签，而应指定具体版本以确保环境一致性：

bash
# 例如使用2.10.2版本
docker pull xxx.xuanyuan.run/library/caddy:2.10.2

可以通过Caddy镜像文档（轩辕）获取最新的稳定版本信息。

持久化存储

生产环境中应确保数据持久化的可靠性，除了使用Docker命名卷外，还可以考虑使用绑定挂载到主机目录：

bash
# 创建主机目录
mkdir -p /data/caddy/data /data/caddy/config

# 使用绑定挂载启动容器
docker run -d \
  --name caddy \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  -v /data/caddy/conf:/etc/caddy \
  -v /data/caddy/site:/srv \
  -v /data/caddy/data:/data \
  -v /data/caddy/config:/config \
  xxx.xuanyuan.run/library/caddy:2.10.2

资源限制

为CADDY容器设置资源限制可以防止资源耗尽：

bash
docker run -d \
  --name caddy \
  --memory=1g \
  --memory-swap=1g \
  --cpus=0.5 \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  -v caddy_data:/data \
  -v caddy_config:/config \
  xxx.xuanyuan.run/library/caddy:2.10.2

上述命令限制容器最多使用1GB内存和0.5个CPU核心，可根据实际服务器配置和业务需求进行调整。

安全加固

生产环境中应采取以下安全措施加固CADDY容器：

  1. 使用非root用户运行容器：
bash
# 创建本地用户和组
sudo groupadd -r caddy
sudo useradd -r -g caddy caddy

# 调整目录权限
sudo chown -R caddy:caddy /data/caddy

# 使用--user参数运行容器
docker run -d \
  --name caddy \
  --user caddy \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  -v /data/caddy/conf:/etc/caddy \
  -v /data/caddy/site:/srv \
  -v /data/caddy/data:/data \
  -v /data/caddy/config:/config \
  xxx.xuanyuan.run/library/caddy:2.10.2
  1. 限制容器的Linux capabilities，只保留必要权限：
bash
docker run -d \
  --name caddy \
  --cap-drop=ALL \
  --cap-add=NET_BIND_SERVICE \
  --cap-add=NET_ADMIN \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  -v caddy_data:/data \
  -v caddy_config:/config \
  xxx.xuanyuan.run/library/caddy:2.10.2
  1. 使用只读文件系统，只将必要目录设为可写：
bash
docker run -d \
  --name caddy \
  --read-only \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  -v caddy_data:/data \
  -v caddy_config:/config \
  -v /data/caddy/conf:/etc/caddy:ro \
  -v /data/caddy/site:/srv:ro \
  -v /tmp:/tmp \
  --tmpfs /var/run \
  --tmpfs /var/log \
  xxx.xuanyuan.run/library/caddy:2.10.2

日志管理

生产环境中应配置适当的日志管理策略：

  1. 使用Docker的日志驱动将日志输出到文件或集中式日志系统：
bash
docker run -d \
  --name caddy \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  -p 80:80 \
  -p 443:443 \
  -p 443:443/udp \
  -v caddy_data:/data \
  -v caddy_config:/config \
  xxx.xuanyuan.run/library/caddy:2.10.2
  1. 配置CADDY的日志格式和输出方式，编辑Caddyfile：
{
  log {
    format json
    output file /var/log/caddy/access.log {
      roll_size 10MiB
      roll_keep 10
      roll_keep_for 720h
    }
  }
}

your-domain.com {
  # 站点配置...
  log {
    # 站点特定日志配置
  }
}

监控配置

可以通过以下方式实现对CADDY容器的监控：

  1. 使用CADDY的metrics模块暴露Prometheus指标：

在Caddyfile中添加：

{
  admin off
  metrics
}

your-domain.com {
  # 站点配置...
}
  1. 使用cadvisor等工具监控容器资源使用情况：
bash
docker run -d \
  --name cadvisor \
  -p 8080:8080 \
  -v /:/rootfs:ro \
  -v /var/run:/var/run:ro \
  -v /sys:/sys:ro \
  -v /var/lib/docker/:/var/lib/docker:ro \
  gcr.io/cadvisor/cadvisor:latest

故障排查

常见问题及解决方法

容器无法启动

若CADDY容器无法启动，首先应查看容器日志获取详细错误信息：

bash
docker logs caddy

常见原因及解决方法：

  1. 端口冲突：Caddy默认使用80和443端口，若这些端口已被其他服务占用，容器将无法启动。解决方法是停止占用端口的服务或修改Caddy的端口映射：
bash
# 修改端口映射示例
docker run -d \
  --name caddy \
  -p 8080:80 \
  -p 8443:443 \
  -v caddy_data:/data \
  -v caddy_config:/config \
  xxx.xuanyuan.run/library/caddy:latest
  1. 配置文件错误：Caddyfile语法错误会导致容器启动失败。可以使用CADDY的配置验证功能检查：
bash
# 容器外检查
docker run --rm -v $PWD/Caddyfile:/etc/caddy/Caddyfile xxx.xuanyuan.run/library/caddy:latest caddy validate

# 或容器内检查
docker exec -it caddy caddy validate --config /etc/caddy/Caddyfile
  1. 权限问题：挂载的主机目录权限不足可能导致容器无法读取配置文件或写入数据。解决方法是调整目录权限：
bash
chmod -R 755 /path/to/caddy/directory
chown -R 101:101 /path/to/caddy/directory  # CADDY容器内默认使用UID/GID 101

HTTPS配置问题

若HTTPS证书申请失败或无法正常工作，可以通过以下步骤排查：

  1. 检查域名解析是否正确：
bash
nslookup your-domain.com
  1. 检查80和443端口是否开放且可从公网访问：
bash
# 在服务器上检查端口监听
netstat -tulpn | grep -E '80|443'

# 使用外部工具检查端口可访问性，如https://portchecker.co/
  1. 查看证书申请相关日志：
bash
docker logs caddy | grep -i cert

性能问题

若CADDY服务器出现性能问题，可以从以下方面排查：

  1. 检查系统资源使用情况：
bash
docker stats caddy
  1. 查看CADDY访问日志，分析请求模式和异常请求：
bash
docker exec -it caddy tail -f /var/log/caddy/access.log
  1. 检查是否启用了HTTP/3，以及网络缓冲区设置：
bash
# 检查HTTP/3支持
curl -I --http3 https://your-domain.com

# 确认是否添加了NET_ADMIN权限
docker inspect caddy | grep -i "NET_ADMIN"

参考资源

总结

本文详细介绍了Caddy的Docker容器化部署方案，包括环境准备、镜像拉取、基础部署、自定义配置、功能测试和生产环境优化等内容。通过容器化部署，用户可以快速搭建Caddy服务，同时确保环境一致性和部署效率。

关键要点：

  • 使用轩辕镜像访问支持可改善Caddy镜像的访问体验
  • 镜像拉取命令格式为docker pull xxx.xuanyuan.run/library/caddy:latest
  • 持久化存储/data和/config目录对于Caddy的数据安全至关重要
  • 生产环境中应指定具体版本标签而非使用:latest
  • 自动HTTPS功能需要域名正确解析且80/443端口可从公网访问
  • 配置热重载功能可实现零 downtime 更新配置

后续建议：

  • 深入学习Caddy的配置语法和高级特性，如反向代理、负载均衡、插件系统等
  • 根据实际业务需求优化Caddy配置，特别是缓存策略和安全设置
  • 建立完善的监控和日志分析系统，及时发现并解决问题
  • 定期更新Caddy版本，以获取最新的安全补丁和功能改进
  • 考虑使用Docker Compose或Kubernetes进行更复杂的部署和管理
  • 对于大规模部署，可研究Caddy的集群部署方案和配置同步机制

通过合理配置和优化，Caddy可以成为一个高性能、安全可靠的Web服务器解决方案，满足从个人网站到企业级应用的各种需求。

免责声明

本博客文章所提供的内容、技术方案、配置示例及部署指南等信息，仅供学习交流和技术参考使用。文章内容基于发布时的技术环境和版本信息编写，可能因时间推移、技术更新或环境差异而存在不适用的情况。

用户在参考本博客内容进行部署操作前，应当充分了解相关技术风险，并建议在测试环境中进行充分验证和测试，确认无误后再考虑在生产环境中使用。生产环境部署前，请务必进行数据备份，并制定相应的回滚方案。

用户因使用本博客内容进行部署操作而产生的任何损失、数据丢失、系统故障、安全风险或其他问题，均由用户自行承担全部责任。轩辕镜像官方不对因使用本博客内容而产生的任何直接或间接损失承担责任。

本免责声明的最终解释权归轩辕镜像官方所有。

最后更新：2025/12/18