# CF-EMBY-PROXY-UI
基于 Cloudflare Workers 的 Emby/Jellyfin 代理、分流与可视化管理面板
一个单文件
worker.js项目:统一多台 Emby 节点入口、隐藏源站 IP、支持直连/反代混合策略、提供ADMIN_PATH(默认/admin)可视化后台,并集成日志、Cloudflare 统计、Telegram 日报与控制面 / 数据面分层优化。当前版本的全局设置页已支持新手 / 高手模式切换、设置变更快照、全局设置专用迁移,以及“系统 UI / 代理与网络 / 静态资源策略 / 安全防护 / 日志设置 / 监控告警 / 账号设置 / 备份与恢复”分区导航;同时继续保留控制面 / 数据面分层、缓存键清洗、转码
m3u8禁缓存、Geo 白/黑名单模式切换等优化。

CF-EMBY-PROXY-UI 是一个运行在 Cloudflare Workers 上的媒体代理系统,适用于:
项目当前版本在单文件内集成了以下模块:认证、KV/D1 数据管理、代理主链路、日志、可视化控制台、定时任务入口。代码头部也明确将其定义为单文件部署架构。
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(KV 兜底)、定时清理、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 登录态,密码错误累计锁定 |
| 节点管理 | 节点增删改查、导入导出、备注/标签/密钥 |
| 路由模式 | 透明反代、同源跳转继续代理、源站直连节点 |
| 外链策略 | 强制反代外部链接 / 直接下发 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 绑定 | 核心数据存储。用于持久化保存项目主配置、节点信息、失败计数统计以及登录锁定状态等。 | 绑定你创建的 KV 命名空间(例如:EMBY_DATA)。 |
ADMIN_PASS |
加密变量 (Secret) | 后台登录密码。用于验证管理面板的访问权限。 | MyStrongPassword123 |
JWT_SECRET |
加密变量 (Secret) | 安全会话密钥。用于生成和校验后台登录状态 (JWT),防止越权访问。 | 建议填入一段高强度的随机长字符串。 |
按需配置,用于开启日志统计或自定义系统行为。
| 变量名 / 绑定名称 | 类型 | 作用说明 | 配置示例 / 建议 |
|---|---|---|---|
DB |
D1 绑定 | 日志数据库。绑定后可开启请求日志审计、流量统计及自动化日报功能。 | 绑定你创建的 D1 数据库。 |
ADMIN_PATH |
文本变量 (Var) | 自定义管理入口。用于修改默认的 /admin 路径,有效防范自动化扫描工具的嗅探。 |
/secret_portal_99 |
> ⚠️ 注意:不能以 /api 开头。 |
💡 命名兼容性提示: 核心代码已向下兼容多种旧版命名(如
KV/EMBY_KV/EMBY_PROXY会自动映射为ENI_KV,D1/PROXY_LOGS会映射为DB)。但强烈建议在新部署时统一使用ENI_KV和DB,以确保与后续的更新、README 说明及自动化脚本保持一致。
项目部署成功并登录管理后台后,可在**“全局设置”**中配置以下进阶参数。这些参数最终会安全地加密存储在 ENI_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 全量替换进去并部署wrangler.tomlname 改成你要使用的名称iddatabase_name,并复制页面上显示的 数据库 ID (Database ID)对应database_idwrangler.toml 中的 id、database_name 和 database_idwrangler.toml 中的 [[d1_databases]] 配置段,再进行首次部署wrangler.toml 提交并推送到你自己的 GitHub 仓库wrangler.toml,并以 worker.js 作为入口文件push 新提交,Cloudflare 就会自动拉取最新代码并重新部署仓库中的
wrangler.toml现在同时声明 Worker 入口、兼容日期以及 KV / D1 绑定信息;部署前请先把占位符替换成你自己的实际值。
完成方式 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 分支worker.js + wrangler.toml 结构,GitHub Actions 会直接调用 Wrangler 部署到 Cloudflare Workersmain 或 master,请先修改 .github/workflows/deploy-worker.yml 里的 branches 配置push 新提交,GitHub Actions 都会自动重新部署方式 C 不依赖 Cloudflare 的 Git 仓库集成,而是由 GitHub Actions 直接读取仓库根目录的
worker.js和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 会在控制台打印一次初始化警告,首页和管理页也会显示“系统未初始化”提示。
如果你需要自动清理日志、发送 Telegram 日报或定时异常告警,再补这一步:
0 1 * * *Cloudflare 官方文档说明:注意Cron Trigger 使用 UTC,而中国时区是UTC+8,免费计划最多 5 个、付费计划最多 250 个;单次 Cron 执行最长 15 分钟。
Cloudflare Dashboard->左侧导航栏->域注册->管理域
点击要绑定的域名,在仪表盘右侧DNS模块,点击DNS记录
类型选择CNAME ,名称自定义,目标为优选域名 可以从https://cf.090227.xyz/ 中选
优选域名推荐:saas.sin.fan mfa.gov.ua www.shopify.com
格外注意:关闭代理状态[关闭小黄云],然后点击保存即可

在你的域名管理页面左侧菜单栏,点击 Workers 路由 (Workers Routes)-在HTTP 路由-点击添加路由
举例:我的域名是 xyz9923.qzz.io ,我上面设置的名称为emby
路由填写为 emby.xyz9923.qzz.io/ 必须在域名的后边携带/**
Worker选择:Worker 一栏选择你第一步创建的那个Worker

域名推荐设置:
反代访问端口需使用 Cloudflare 支持的 HTTPS 端口,例如
443 / 2053 / 2083 / 2087 / 2096 / 8443。
如果你想快速理解当前版本里最容易看花眼的部分,建议按下面顺序阅读:
fetch / scheduled 入口看整条请求链路怎么分发后台路径:
https://你的域名/admin
如果设置了自定义环境变量:
ADMIN_PATH=/secret_portal_99
https://你的域名/secret_portal_99
CNAME 草稿,但仍需要再点一次“保存 DNS”才会真正写入 CloudflareCNAME模式:只保留 1 条 CNAME;保存时会自动删除当前站点下的 A / AAAAA模式:可混合多条 A / AAAA,最少保留 1 条;切换到该模式时只会先改后台草稿,不会立刻改 CloudflareA模式 切回 CNAME模式 时,如果当前没有有效 CNAME 草稿,会默认回填 saas.sin.fanCNAME 修改历史,点击历$ claude mcp add CF-EMBY-PROXY-UI \
-- python -m otcore.mcp_server <graph>