lucaslorentz/caddy-docker-proxy

caddy-docker-proxy 介绍

简介

caddy-docker-proxy 是 Caddy 2 的一款扩展模块，能让你通过 Docker 容器的标签（labels）自动配置反向代理，无需手动编写和维护 Caddyfile。它会监听 Docker 事件（如容器启动、停止），实时生成或更新 Caddy 配置，帮你快速搭建基于 Caddy 的反向代理服务。

核心功能

• 自动 HTTPS：集成 Let's Encrypt，自动为容器配置 HTTPS 证书（支持自定义 CA），无需手动管理证书。
• 动态配置：容器启动/停止时，Caddy 配置会自动更新，无需重启 Caddy 服务。
• 兼容 Docker 生态：支持 Docker Compose、Docker Swarm，也能用于单节点 Docker 环境。
• 灵活路由：通过标签定义域名、路径路由（如 /api 转发到特定服务），满足复杂的代理需求。
• 扩展 Caddy 能力：支持所有 Caddy 原生指令（如 headers、rate_limit、rewrite 等），直接通过标签配置。

使用步骤

1. 安装并启动 Caddy

首先需要安装 Caddy 并启用 caddy-docker-proxy 模块。推荐用官方提供的集成镜像（已预装模块），或手动编译：

方式 1：使用官方集成镜像（推荐）

直接拉取包含模块的 Caddy 镜像：

bash
docker pull lucaslorentz/caddy-docker-proxy:ci-alpine

方式 2：手动编译（适合自定义 Caddy 模块）

通过 xcaddy 编译带模块的 Caddy：

bash
xcaddy build --with github.com/lucaslorentz/caddy-docker-proxy/v2

启动 Caddy 容器

启动时需挂载 Docker Socket（让 Caddy 监听 Docker 事件），并映射 80/443 端口：

bash
docker run -d \
  --name caddy \
  -p 80:80 \
  -p 443:443 \
  -v /var/run/docker.sock:/var/run/docker.sock \  # 挂载 Docker Socket
  -v caddy_data:/data \  # 存储证书、配置等数据
  lucaslorentz/caddy-docker-proxy:ci-alpine

2. 为应用容器添加标签

给需要代理的应用容器添加 caddy.* 格式的标签，定义代理规则。

示例：代理一个简单的 Web 服务

假设你有个运行在 8080 端口的 Node.js 服务（容器名 my-app），想通过 app.example.com 访问：

启动应用容器时添加标签：

bash
docker run -d \
  --name my-app \
  -l caddy.host=app.example.com \  # 绑定域名
  -l caddy.reverse_proxy=[***] \  # 反向代理到容器内服务
  my-node-app:latest  # 你的应用镜像

标签说明

• caddy.host: 绑定的域名（支持多个，用逗号分隔，如 caddy.host=app1.example.com,app2.example.com）。
• caddy.reverse_proxy: 定义代理目标，格式同 Caddyfile（如 caddy.reverse_proxy=/api [***] 表示路径 /api转发到api-service:3000`）。
• 其他 Caddy 指令：直接用 caddy.指令名=参数，如 caddy.header.Strict-Transport-Security=max-age=31536000; includeSubDomains（添加 HSTS 头）。

3. 验证服务

容器启动后，caddy-docker-proxy 会自动生成配置。访问 `[***] Caddy 所在服务器），即可看到应用服务的响应。

注意事项

• Docker Socket 权限：挂载 /var/run/docker.sock 会让 Caddy 有权限操作 Docker 资源，生产环境建议通过用户组或第三方工具（如 docker-socket-proxy）限制权限。
• 标签语法：标签值需符合 Caddyfile 语法（可参考 Caddy 文档），复杂配置可拆分为多个标签（如 caddy.reverse_proxy.0=/api、`caddy.reverse_proxy.1=[***]
• 日志调试：查看 Caddy 日志排查问题：docker logs caddy。
• 兼容性：支持 Caddy 2.4+，不兼容 Caddy 1.x。

通过以上步骤，你可以快速用 Docker 标签管理 Caddy 反向代理，尤其适合多容器、动态部署的场景。