cmliu/edgetunnel 项目理解报告

审阅时间：2026-05-26｜来源：GitHub cmliu/edgetunnel README、仓库元信息、核心 _worker.js

一句话定位：edgetunnel 是把 VLESS / Trojan / Shadowsocks 等代理协议“解码/转发”逻辑放进 Cloudflare Workers/Pages 边缘运行时的单文件隧道与订阅面板项目，核心卖点是免 VPS、靠 CF 边缘入口、带 Web 管理后台和订阅生成。

JS 单文件

核心逻辑集中在 _worker.js，约 5,857 行。

35k+

GitHub stars 约 35,818；forks 约 32,573。

CF 边缘

目标部署平台是 Cloudflare Workers / Pages。

GPL-2.0

许可证为 GNU GPL v2。

1. 项目是什么

不是传统 VPS 代理服务端：它不在一台固定 VPS 上跑 Xray/sing-box，而是把协议解析与 TCP 出站转发放进 Cloudflare 边缘函数。
不是单纯订阅转换器：它内置订阅生成、Clash/Sing-box/Surge 适配和节点配置，但核心仍是边缘隧道入口。
是 zizifn/edgetunnel 的高功能 fork：原项目描述是“Running V2ray inside edge/serverless runtime”；cmliu 分支扩展了管理面板、订阅、ProxyIP、链式代理、CF 用量、Telegram 日志等。

2. 核心功能拆解

模块	能力	证据/实现点	理解
入站协议	VLESS、Trojan、Shadowsocks	README 写明支持；源码有 `解析魏烈思请求`、`解析木马请求`、SS AEAD 加解密函数。	客户端把流量封装成代理协议，经 WebSocket/gRPC/XHTTP 进入 Worker。
传输层	WS、gRPC、XHTTP	源码入口有 `处理WS请求`、`处理gRPC请求`、`处理XHTTP请求`。	适配不同客户端/网络环境；WS 是最常见入口。
出站转发	直连、ProxyIP、SOCKS5/HTTP/HTTPS/TURN/SSTP 链式代理	`forwardataTCP` 先尝试直连，失败后按 ProxyIP/链式代理兜底。	解决 Cloudflare Worker 出站到部分目标不稳定/不可达问题。
管理面板	登录、配置保存、日志、CF 用量、TG 通知	`/admin` 路由，KV 中保存 `config.json`、`tg.json`、`cf.json`。	这是 cmliu 分支相对原始 edgetunnel 的重要增强。
订阅生成	混合订阅、Clash/Sing-box/Surge 热补丁、优选 IP	README 与源码中的 `Clash订阅配置文件热补丁`、`Singbox订阅配置文件热补丁`、`Surge订阅配置文件热补丁`。	让一个部署自动输出多客户端可用配置。
伪装首页	默认可反代 URL 或返回 nginx/1101 风格页面	环境变量 `URL`，源码 `nginx()`、`html1101()`。	降低裸露管理/订阅入口的可见性，但不是强安全边界。

3. 工作流：一次连接大概怎么走

用户客户端导入项目生成的订阅节点。
客户端发起到 Cloudflare 自定义域的 TLS + WS/gRPC/XHTTP 请求。
Worker 依据 ADMIN/KEY/UUID 派生或读取 UUID，验证入站协议首包。
Worker 解析目标地址、端口和剩余首包数据。
Worker 使用 Cloudflare runtime 的 TCP socket 尝试连接目标。
如果直连失败或命中链式代理规则，则改走 ProxyIP / SOCKS5 / HTTP / HTTPS / TURN / SSTP。
Worker 在客户端 WebSocket 与远端 TCP socket 间双向搬运字节流。

4. 配置与部署理解

项	含义	判断
`ADMIN`	后台登录密码；也是无 UUID 时派生 userID 的关键输入之一。	必须强密码太弱会导致订阅与管理入口被撞。
`KEY`	快速订阅路径密钥；访问 `/{KEY}` 可快速获取节点。	建议设置默认密钥不应暴露。
`UUID`	固定 VLESS UUID；不设置时由 ADMIN+KEY 派生。	可选固定后迁移/多端更稳定。
`KV`	Cloudflare KV 命名空间，保存管理面板配置、日志、订阅参数。	关键依赖无 KV 会丢失后台配置能力。
`PROXYIP`	全局自定义反代 IP。	影响可用性质量决定落地连接成功率。
`URL`	默认主页伪装地址或 1101 页面。	隐藏入口不能代替访问控制。
`GO2SOCKS5`	强制走链式代理的域名名单。	进阶项可对特定站点绕过 Worker 出站限制。

5. 适合与不适合

场景	是否适合	原因
低成本临时测试、学习边缘运行时 TCP/WebSocket 能力	适合	部署成本低、代码集中、可观察协议解析与转发逻辑。
需要一个轻量、多客户端订阅入口	适合	内置订阅生成和主流客户端适配。
长期稳定生产代理	不建议	依赖 Cloudflare 平台策略、Worker 限制、ProxyIP 质量；账号/域名有风控风险。
高吞吐/低延迟/大流量	不适合	边缘函数与平台配额不是为持续大流量隧道设计。
要求隐私强保障	谨慎	流量路径经过 Cloudflare 与可能的 ProxyIP/链式代理；订阅/日志/配置还可能落 KV。
需要明确合规、商业 SLA	不适合	项目自身免责声明要求教育/研究用途，且平台 ToS 风险不可忽略。

6. 主要风险

Cloudflare ToS / 风控风险：这种把边缘函数作为通用隧道入口的用法，可能触发平台限制或封禁，尤其是高流量、滥用目标或公开分享节点时。
管理入口风险：/admin 存在公网；ADMIN/KEY/UUID 如果弱或复用，可能导致配置泄露、订阅被盗用。
第三方 ProxyIP 风险：如果使用公共 ProxyIP 或链式代理，实际出口和可见流量控制权不完全在自己手里。
供应链风险：项目很热门、更新频繁、单文件很大；部署前应固定 commit，自行审计差异，不建议盲目追 main。
隐私与日志风险：项目支持日志、Telegram 通知、CF 用量 API；配置错误可能把访问元数据写入 KV 或外部服务。
可用性波动：Worker TCP socket、地区网络、优选 IP、Cloudflare 策略都会影响实际体验。

7. 代码层面的几个观察

观察	含义
源码头部包含大段“本代码安全/非代理/非隧道”的多语言声明。	这更像是规避自动审查的文本，不改变代码实际功能；审计时应以行为为准。
协议解析、TLS mini client、TURN/SSTP、订阅热补丁都塞进一个 worker 文件。	功能强，但维护复杂，安全审计难度高。
直连失败后有 ProxyIP/代理兜底。	提高可用性，但引入第三方出口信任问题。
默认配置会写入 KV。	便于面板管理，但 KV 权限和数据内容需要谨慎。

8. 决策建议

如果只是理解/试验：可以把它当成“Cloudflare 边缘代理协议实验项目”看，重点学习 Worker WebSocket、TCP socket、订阅生成和 KV 管理。
如果准备自用：只建议小流量、私用、强密码、固定 UUID、绑定自有二级域名、关闭不必要日志，不公开订阅地址。
如果追求稳定：优先选传统 VPS + sing-box/Xray，edgetunnel 更像“边缘入口/备用链路/实验工具”，不是主力生产方案。
如果关注合规：不要用于绕过平台限制、滥用网络或商业转售；项目 README 自身也声明仅供教育、研究和个人安全测试。

9. 最短结论

edgetunnel 的价值在“把代理入口下沉到 Cloudflare 边缘，并用面板/订阅把复杂配置包装起来”。它很适合折腾、学习和临时自用；但从稳定性、合规性、安全审计和账号风险看，不适合当长期核心基础设施。