lc121a/caddy-ui repository overview

⁠Caddy UI

一个面向个人服务器、家庭网关和轻量反代节点的中文 Caddy Web 管理面板。

⁠简介

Caddy UI 把定制版 Caddy、React 前端控制台和 Go 后端 API 打包到同一个容器中，用可视化方式管理反向代理、证书、动态 DNS、访问控制、通信规则、域名监控、推送通知和网络唤醒。

它更适合这类场景：

⁠目录

• 功能亮点⁠
• 快速开始⁠
• 端口说明⁠
• 核心功能⁠
• 持久化目录⁠
• 环境变量⁠
• 从源码构建⁠
• 本地开发验证⁠
• 安全建议⁠

⁠功能亮点

⁠快速开始

⁠方式一：Host 网络模式

这是仓库内 docker-compose.yml 当前使用的模式，适合需要直接监听宿主机 80/443 和自定义端口的网关场景。

services:
  caddy:
    image: lc121a/caddy-ui:latest
    container_name: caddy-ui
    network_mode: host
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - caddy_data:/data
      - caddy_config:/config
    restart: unless-stopped

volumes:
  caddy_data:
  caddy_config:

启动：

docker compose up -d

访问管理面板：

http://<服务器 IP>:8888/

⁠方式二：桥接网络模式

如果你不想使用 Host 网络，可以显式发布端口。反代里配置了额外监听端口时，也要同步发布对应端口。

services:
  caddy:
    image: lc121a/caddy-ui:latest
    container_name: caddy-ui
    ports:
      - "8888:8888"     # 管理面板和 API
      - "80:80"         # HTTP 业务流量和 ACME HTTP-01
      - "443:443"       # HTTPS 业务流量
      # - "11111:11111" # 自定义监听端口
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - caddy_data:/data
      - caddy_config:/config
    restart: unless-stopped

volumes:
  caddy_data:
  caddy_config:

⁠端口说明

反代页面里的「监听端口」是 Caddy 容器内监听端口。例如填写：

443,11111

桥接网络模式下需要同步发布：

ports:
  - "443:443"
  - "11111:11111"

如果宿主机把 HTTPS 映射到非标准端口，例如 "8443:443"，外部访问地址就是 https://example.com:8443/，容器内仍监听 443。HTTP-01 证书申请仍要求外部能访问映射到容器 80 的端口。

⁠核心功能

⁠反向代理与站点

• 可视化管理反向代理、重定向、404 站点、TCP/UDP Streams。
• 反向代理支持多个监听端口，例如 443,11111。
• 列表页会展示实际监听端口，域名链接会根据 HTTPS 状态和端口生成。
• Cloudflare Origin Rule、内网 DNS 直连等场景，需要让请求最终到达同一个反代监听端口。

⁠证书与 ACME

• 支持 Caddy 自动 HTTPS、HTTP-01、DNS-01、自定义证书、Caddy Internal、自定义 ACME Directory。
• 支持 Let's Encrypt、Let's Encrypt Staging、ZeroSSL、Google Trust Services、自定义 ACME。
• ZeroSSL / Google / 自定义 ACME 的 EAB 和 Directory 配置可复用。
• 多域名反代可以逐域绑定不同证书，避免一个域名的证书配置影响其它域名。
• 可为父域申请 DNS-01 通配符证书，多条反代可复用同一父域凭据。
• 证书列表展示状态、签发机构、CN、验证方式、DNS 凭据、关联站点，并支持重签、下载和删除。

证书列表会展示可读的签发机构和 CN，例如 Let's Encrypt（R12）、Google Trust Services（WE1），避免只看到 R12、YE2、WE1 这类中间 CA 名称。

⁠动态 DNS

• 基于 github.com/mholt/caddy-dynamicdns 生成 Caddy 全局动态 DNS 配置。
• 保存配置时会立即尝试检查当前公网 IP 和远端记录。
• 适合动态公网 IP、家庭宽带和云解析自动同步场景。
• 开启 Cloudflare 橙云代理时，远端 DNS 查询可能返回代理 IP；实际 DDNS 更新仍应以 DNS 提供商记录为准。

⁠访问控制与认证

• 支持 Basic Auth 访问列表。
• 支持 IP allow/deny。
• 支持 Authelia / authentik forward_auth 集成。
• 未启用认证的站点不会被认证配置拦截。

⁠通信规则

• 可管理 TCP/UDP Streams。
• 通信规则可关联到代理服务。
• 适合非 HTTP 服务转发，例如 SSH、游戏服务、数据库内网入口等。

⁠域名监控与续期

「域名监控」可以同时检查：

• DNS 解析结果；
• SSL 证书到期时间和签发机构；
• 域名注册到期时间；
• DigitalPlat / DNSHE API 是否可用；
• DNSHE 手动续期和自动续期结果。

SSL 检查目标支持非标准端口：

example.com:8443

域名商 API 支持：

不支持 API 的免费/托管二级域名会标记为「不可用」，不会强行识别成错误的根域名。

⁠推送通知

推送渠道独立管理，支持：

每个渠道可以选择接收全部消息，也可以只订阅指定消息类型：

• 域名即将到期；
• 证书即将到期；
• DNS 检查失败；
• SSL 检查失败；
• 域名到期检查失败；
• DNSHE 续期成功；
• DNSHE 续期失败；
• 自动续期失败；
• 推送渠道测试消息。

⁠网络唤醒

网络唤醒位于一级菜单，默认放在「访问控制」和「系统管理」之间。设备配置支持：

⁠凭据管理

• ACME DNS 凭据、域名商 API Key、推送渠道都保存到 /config。
• 凭据可在不同站点、监控项和证书申请流程中复用。
• 敏感字段默认隐藏，可通过小眼睛按钮临时查看明文。

⁠持久化目录

常见文件：

⁠环境变量

DigitalPlat / DNSHE API Key 不通过环境变量配置，请在界面的凭据管理中维护。

⁠从源码构建

git clone https://github.com/jadylc/caddyUI.git
cd caddyUI
docker compose up -d --build

Dockerfile 分为四个阶段：

定制版 Caddy 当前包含：

• github.com/caddy-dns/alidns
• github.com/caddy-dns/cloudflare
• github.com/caddy-dns/dnspod
• github.com/caddy-dns/he
• github.com/mholt/caddy-l4
• github.com/mholt/caddy-dynamicdns

⁠本地开发验证

后端：

cd backend
go test ./...

前端：

cd ui
npm ci
npm run build

⁠安全建议

• 管理面板没有内置登录鉴权，生产环境请仅暴露给内网、VPN，或在前面增加可信反代认证。
• 不要把 2019 Caddy Admin API 暴露到公网。
• DNS、ACME、DigitalPlat、DNSHE、推送渠道等凭据都保存在 /config，请保护好该目录并定期备份。
• 使用 HTTP-01 时，确认 80 端口对外可达；无法开放 80/443 的环境建议使用 DNS-01。
• 桥接网络模式下，反代新增自定义监听端口后，需要同时更新 Docker 端口映射。