Browse by type
# CF-EMBY-PROXY-UI
基于 Cloudflare Workers 的 Emby/Jellyfin 代理、分流与可视化管理面板
一个以
worker/为生产源码、以根目录worker.js为单文件部署产物的 Cloudflare Worker 项目:统一多台 Emby 节点入口、隐藏源站 IP、支持直连/反代混合策略、提供ADMIN_PATH(默认/admin)可视化后台,并集成日志、Cloudflare 统计、Telegram 日报与控制面 / 数据面分层优化。当前 V19.4 在原有新手 / 高手设置模式、配置快照和分区导航基础上,进一步加入节点配置资源上限、全局 GET 探测并发池、元数据预热字节预算、播放列表 / 分片空闲超时,以及带签名预览和硬预算的 D1 整理流程;同时继续保留控制面 / 数据面分层、缓存键清洗、转码
m3u8禁缓存、Geo 白/黑名单模式切换等优化。

CF-EMBY-PROXY-UI 是一个运行在 Cloudflare Workers 上的媒体代理系统,适用于:
项目当前版本由模块化 Worker 源码和同源管理端组成:worker/index.js 是唯一生产入口,worker/ 内按 core、runtime 和代理功能域组织源码,构建后生成根目录 worker.js 单文件部署产物;管理端则由 frontend/admin-runtime.template.html 与 frontend/scripts/admin-runtime-enhancements.mjs 组合,经 Vite 输出到 frontend/dist/index.html,再由 Wrangler Static Assets 与 Worker 一起部署。
ADMIN_PATH(默认 /admin)CNAME模式 / A模式 可切换,保存时自动处理互斥关系JWT_SECRET / ADMIN_PASS 时直接在控制台与页面提示sys:theme 脏值、sys:nodes_index 错乱与遗留缓存键Locationwangpandirect 关键词匹配,可识别网盘 / 对象存储链接并直连.m3u8 / 字幕),不在 Worker 内做视频 Range 旁路预取或大对象缓存m3u8 与非白名单播放列表不会写入 Worker 缓存ADMIN_PATH,降低固定 /admin 扫描命中率sys_status、定时清理、Telegram 每日报表flowchart LR
U[客户端 / 播放器] --> W[Worker 控制面]
W --> A["管理面板 (ADMIN_PATH)"]
W --> C["鉴权 / 路由 / UI / 元数据预热"]
C --> KV[(Cloudflare KV)]
C --> D1[(Cloudflare D1)]
C --> G["CF 原生数据面 / Cache Rules"]
G --> E[Emby / Jellyfin 源站]
G --> X[外部直链 / 网盘 / 对象存储]
S[scheduled 定时任务] --> D1
S --> TG[Telegram 日报]
A --> CF[Cloudflare GraphQL Analytics]
| 模块 | 说明 |
|---|---|
| 后台认证 | JWT 登录态;绑定 D1 时启用按 IP 的密码错误累计锁定 |
| 节点管理 | 节点增删改查、导入导出、备注/标签/密钥、4 并发 GET 健康探测、资源上限校验 |
| 路由模式 | 透明反代、同源跳转继续代理、源站直连节点 |
| 外链策略 | 强制反代外部链接 / 直接下发 Location |
| 网盘直连 | wangpandirect 关键词模糊匹配 |
| 缓存 | 静态资源缓存、视频透传、字幕边缘缓存、预热微缓存 |
| 安全 | Geo 白名单/黑名单模式、IP 黑名单、单 IP 限速、真实客户端 IP 透传模式 |
| 兼容补丁 | Authorization / X-Emby-Authorization / X-MediaBrowser-Authorization 兼容 |
| 协议优化 | H1/H2/H3 开关、晚高峰自动降级、403 重试 |
| 日志监控 | D1 请求日志、签名预览与预算整理、Telegram 日报 |
| 仪表盘 | Cloudflare GraphQL 聚合 + D1 本地兜底 |
| 设置中心 | 新手/高手模式、分区导航、设置快照、专用迁移 |
| 连接能力 | HTTP(S) + WebSocket |
客户端请求先到 Worker,Worker 根据 URL 中的节点名读取 KV 中的节点配置,再构造回源请求发送到 Emby 源站;源站响应由 Worker 流式回传给客户端。对普通 API、静态资源、视频流、重定向、WebSocket,会分别走不同的处理分支。
Worker 作为公网入口,外部只能看到 Cloudflare 边缘节点,而不是你的 Emby 源站真实 IP。需要注意的是,这种“隐藏”是网络入口层面的隐藏,不等于完全匿名:Cloudflare 仍会追加自身请求头,源站 TCP 层看到的也仍然是 Cloudflare 网络。
默认情况下,项目在回源时会先清洗 X-Real-IP / X-Forwarded-For / Forwarded 以及 Connection / Upgrade 等易伪造或可能影响协议升级的请求头,再由 Worker 注入真实内容,方便上游日志审计与访问控制。
这里的“真实 IP”指的是客户端与 Cloudflare 建立连接时被 Cloudflare 识别到的来源 IP。它可以是用户本机的公网出口 IP,也可以是用户前置代理的出口 IP。默认情况下,节点会透传 X-Real-IP 和 X-Forwarded-For;项目注入的这两个请求头传达的是同一个真实 IP,其中 X-Forwarded-For 不是完整代理链。并且注入发生在节点自定义请求头之后,因此节点里新增同名请求头也不能覆盖这两个值。如果个别上游会按真实出口 IP、地区或 ASN 做风控,也可以在节点级改为仅保留 X-Real-IP、强制不透传【慎用】。
本项目不是“全量一刀切反代”。它支持:
这意味着它既能保留 Worker 统一入口,也能在带宽敏感场景下降低 Worker 中继成本。
这次架构调整的核心,是让 Worker 只做自己擅长的轻逻辑:
对应到实现上,项目已经移除了 Worker 里对视频流的“黑洞式 drain”和大对象缓存倾向。海报、字幕、白名单播放列表继续在 Worker 层用 caches.default 做轻缓存;而视频本体则尽量保持薄透传,更依赖 Cloudflare 底层转发与 Cache Rules 配置,尤其建议为视频路径启用 Ignore query string 来实现跨用户共享缓存。
在部署本项目时,你需要配置相应的环境变量与服务绑定。为了方便管理,我们将配置项分为 Worker 核心配置(在 Cloudflare 控制台设置)和 SaaS 面板进阶配置(在部署后的管理后台设置)。
在 Cloudflare Worker 的 设置 -> 变量和机密 或 绑定页面 中进行配置。建议首次部署时对照下表直接填写:
这些是系统正常运行的基础,必须配置。
| 变量名 / 绑定名称 | 类型 | 作用说明 | 配置示例 / 建议 |
|---|---|---|---|
ENI_KV |
KV 绑定 | 核心配置存储。用于持久化保存项目主配置、节点信息、配置快照和 DNS 修改历史等。 | 绑定你创建的 KV 命名空间(例如:EMBY_DATA)。 |
ADMIN_PASS |
加密变量 (Secret) | 后台登录密码。用于验证管理面板的访问权限。 | MyStrongPassword123 |
JWT_SECRET |
加密变量 (Secret) | 安全会话密钥。用于生成和校验后台登录状态 (JWT),防止越权访问。 | 建议填入一段高强度的随机长字符串。 |
按需配置,用于开启日志统计或自定义系统行为。
| 变量名 / 绑定名称 | 类型 | 作用说明 | 配置示例 / 建议 |
|---|---|---|---|
DB |
D1 绑定 | 运行数据库。保存请求日志、聚合统计、运行状态、任务锁、缓存和认证失败计数等数据。 | 绑定你创建的 D1 数据库。 |
ADMIN_PATH |
文本变量 (Var) | 自定义管理入口。用于修改默认的 /admin 路径,有效防范自动化扫描工具的嗅探。 |
/secret_portal_99 |
> ⚠️ 注意:不能以 /api 开头。 |
| HOST | 文本变量 (Var) | 主访问域名。启用 host prefix 代理或保存 host prefix 节点前必须配置;只填写合法 DNS 主机名。 | emby.example.com,不要带协议、端口、路径、通配符或 IP。 |
| LEGACY_HOST | 文本变量 (Var) | 兼容旧访问域名。迁移主域名时保留旧的路径式节点入口。 | old-emby.example.com |
💡 命名兼容性提示: 核心代码已向下兼容多种旧版命名(如
KV/EMBY_KV/EMBY_PROXY会自动映射为ENI_KV,D1/PROXY_LOGS会映射为DB)。但强烈建议在新部署时统一使用ENI_KV和DB,以确保与后续的更新、README 说明及自动化脚本保持一致。
项目部署成功并登录管理后台后,可在**“全局设置”**中配置以下进阶参数。这些参数经后端清洗后以 JSON 写入 ENI_KV 的 sys:theme;cfApiToken、tgBotToken 不会写入配置快照,普通备份导出也会默认移除它们,只有经过二次确认的“含密钥”导出才会包含。主配置本身不是静态加密密文,请严格限制 KV 和管理后台的访问权限。
| 参数分类 | 参数名 | 作用说明 |
|---|---|---|
| Cloudflare 联动(推荐配置) | cfApiToken |
Cloudflare API 令牌:用于实现一键清理缓存、GraphQL 流量高级统计等深度联动功能。 |
cfZoneId |
区域 ID:对应你当前代理域名所在的 Zone ID。 | |
cfAccountId |
账户 ID:对应你的 Cloudflare 账户 ID。 | |
| Telegram 通知(按需配置) | tgBotToken |
机器人 Token:用于发送每日数据报表及系统告警。 |
tgChatId |
会话 ID:接收通知的个人或群组 Chat ID。 |
💡 节点级补充: “媒体认证头模式”和“真实客户端 IP 透传”都支持在 节点编辑面板 单独配置。 适合按节点对个别 Emby / Jellyfin 源站或特殊风控上游做差异化处理。
如果你希望在后台配置 cfApiToken 以启用完整的增强能力(如仪表盘高级统计、一键清缓存),请确保生成的 API Token 至少包含以下权限:
Account Analytics -> Read (读取)Workers Scripts -> Read (读取)Workers Routes -> Read (读取)Analytics -> Read (读取)Cache Purge -> Purge (清除)DNS -> Edit (编辑)
📝 提示:如果你仅需要基础的代理分发与节点管理,不需要仪表盘数据增强或缓存控制,可以暂不配置此 Token。
为实现自动化运维,本项目依赖 Cloudflare Worker 的定时触发器功能。
corn,请确认拼写为 cron)。EMBY_DATA你可以任选以下三种方式:
worker.js 全量替换进去并部署这种方式只部署 Worker 单文件,不会自动上传
frontend/dist或创建ASSETS绑定。基础代理和管理 API 可以运行,但要使用仓库内置的完整管理端,请优先选择方式 B / C;继续使用方式 A 时,请完成下方“第六步:上传管理端 HTML”。
wrangler.tomlname 改成你要使用的名称iddatabase_name,并复制页面上显示的 数据库 ID (Database ID)对应database_idwrangler.toml 中的 id、database_name 和 database_idwrangler.toml 中的 [[d1_databases]] 配置段,再进行首次部署wrangler.toml 提交并推送到你自己的 GitHub 仓库wrangler.toml:构建命令从 worker/ 生成 worker.js,并把仓库中的 frontend/dist 作为 ASSETS 静态资源随 Worker 上传push 新提交,Cloudflare 就会自动拉取最新代码并重新部署仓库中的
wrangler.toml同时声明 Worker 入口、构建命令、frontend/dist静态资源、兼容日期以及 KV / D1 绑定信息;部署前请先把占位符替换成你自己的实际值。Cloudflare Git 部署会使用仓库已提交的frontend/dist,因此修改管理端源码后要先按仓库脚本重新构建并提交生成物。
完成方式 B 部署后,可以继续跳转到 第五步:设置环境变量。
wrangler.tomlname 改成你要使用的名称wrangler.toml 中的 id、database_name 和 database_idwrangler.toml 中的 [[d1_databases]] 配置段CLOUDFLARE_ACCOUNT_ID:你的 Cloudflare Account IDCLOUDFLARE_API_TOKEN:使用 Edit Cloudflare Workers 模板创建的 API Tokenmain 或 master 分支npm ci 和 npm run build:frontend,随后由 Wrangler 按 wrangler.toml 构建 worker.js,并将 Worker 与 frontend/dist 一起部署到 Cloudflare Workersmain 或 master,请先修改 .github/workflows/deploy-worker.yml 里的 branches 配置push 新提交,GitHub Actions 都会自动重新部署方式 C 不依赖 Cloudflare 的 Git 仓库集成,而是由 GitHub Actions 按仓库脚本构建管理端与 Worker,再读取
wrangler.toml完成部署;如果你更希望把部署权限收敛在 GitHub Secrets 中,这种方式会更合适。
完成方式 C 部署后,可以继续跳转到 第五步:设置环境变量。
ENI_KVemby_proxy_logsDBwrangler.toml,然后重新推送到已绑定分支触发自动部署如果你使用“方式 A:控制台直接粘贴”,KV / D1 仍然需要在 Cloudflare Dashboard 中手动绑定;如果你使用“方式 B / 方式 C”,则优先以
wrangler.toml中填写的绑定信息为准。
在 Worker 的 变量与机密 中新增:
ADMIN_PASS:后台密码JWT_SECRET:随机高强度字符串ADMIN_PATH:可选,自定义管理后台入口,默认 /admin如果首次请求时缺少
ADMIN_PASS或JWT_SECRET,Worker 会在控制台打印一次初始化警告,首页和管理页也会显示“系统未初始化”提示。
如果使用方式 A 在 Cloudflare 控制台直接粘贴 worker.js,还需要手动上传管理端 HTML;方式 B / C 已由 Wrangler 将 frontend/dist 作为静态资源上传,可以跳过本步。
ADMIN_PASS、JWT_SECRET 环境变量配置https://你的 Worker 域名/ADMIN_PATH(默认是 /admin),使用 ADMIN_PASS 登录ASSETS 绑定时,登录后会自动进入“上传 index.html”页面;如果已经进入管理台,可访问 https://你的 Worker 域名/ADMIN_PATH?setup=1 重新打开上传页frontend/dist/index.html上传文件名必须保持为
index.html,大小不能超过 2 MiB,并且 HTML 会保存到已绑定的ENI_KV。不要上传frontend/admin-runtime.template.html;如果修改过管理端源码,请先运行npm.cmd run build:frontend,再上传重新生成的frontend/dist/index.html。
如果你需要自动清理日志、发送 Telegram 日报或定时异常告警,再补这一步:
wrangler.toml 的默认表达式为 0 * * * *,即每小时执行一次Cloudflare 官方文档说明:注意Cron Trigger 使用 UTC,而中国时区是UTC+8,免费计划最
$ claude mcp add CF-EMBY-PROXY-UI \
-- python -m otcore.mcp_server <graph>