视频下载器（Videodownloader）

一个独立运行的视频解析下载插件，参考 SnapVid 的交互形态，支持多平台、多格式、多语言，并内置登录/VIP 权限与广告位自助购买能力。

• 插件标识：Videodownloader
• 版本：1.0.00
• 作者：kuakeba.cn
• 命名空间：plugins\Videodownloader

一、功能概览

• 粘贴视频链接，服务端解析出可用格式列表（清晰度、体积、编码、是否需要音轨）
• 视频 / 音频两种解析模式
• 多格式选择，逐条下载
• 下载走签名代理，解决跨域、防盗链、文件名与 Range 问题
• 10 种语言，支持按设备语言自动切换
• 三级下载权限：游客 / 登录用户 / VIP
• 广告位虚线占位，可跳转广告插件完成自助购买
• 站群支持：多个独立域名各自配置品牌、语言、SEO
• 后台解析记录、限流、SSRF 防护

二、环境要求

三、安装与卸载

安装：后台「应用中心 → 插件管理」上传或放入 plugins/Videodownloader 后点击安装。

安装过程会自动：

1. 执行 [install.sql](install.sql)，创建 zsensvideodownloaderlog 表
2. 复制静态资源到 public/static/Videodownloader/
3. 写入后台菜单「视频下载器」及子菜单（基础配置 / 站群管理 / 解析记录）
4. 写入权限节点并清理缓存

卸载会删除菜单、权限节点与数据表，不可恢复。

修改 static/ 下的 CSS/JS 后，需要重新复制到 public/static/Videodownloader/；资源版本号按文件修改时间生成，会自动破缓存。

四、目录结构

Videodownloader/
├── plugin.json                 插件元信息
├── VideodownloaderPlugin.php   插件入口、配置、菜单、域名、广告位
├── routes.php                  前台与后台路由
├── install.sql                 数据表
├── icon.svg / static/favicon.svg
├── controller/
│   ├── FrontBase.php           前台基类（视图路径、启用校验）
│   ├── Index.php               首页、解析、下载、日志
│   └── admin/
│       ├── Base.php            后台基类
│       ├── Config.php          基础配置
│       ├── Sites.php           站群管理
│       └── Log.php             解析记录
├── service/
│   ├── LangService.php         多语言识别与加载
│   ├── HttpService.php         cURL 请求、SSRF 校验
│   ├── ParseService.php        各平台解析策略
│   └── DownloadService.php     签名 URL、流式下载
├── lang/                       10 个语言包
├── view/
│   ├── front/index.html        前台单页
│   └── admin/{config,sites,log}.html
└── static/
    ├── videodownloader.css
    └── videodownloader.js

五、路由

前台

后台（需登录）

六、解析策略

ParseService::parse() 按以下顺序尝试，命中即返回：

1. 直链媒体：URL 本身就是 mp4/m3u8 等
2. 通用解析 API：后台配置 parseapiurl，支持任意返回 JSON 的第三方接口
3. Cobalt：自建 Cobalt 实例（cobalturl / cobaltapi_key）
4. yt-dlp：开启 ytdlp_enabled 并填写可执行路径，支持 cookies 与代理
5. 内置适配器：Twitter/X（api.fxtwitter.com）、Vimeo（player.vimeo.com）

解析结果统一去重、按清晰度排序、按 maxformats 裁剪，并缓存 cachettl 秒。

支持识别的平台：YouTube、TikTok、Twitter/X、Instagram、Facebook、Vimeo、Dailymotion、Bilibili、小红书、快手、抖音等（部分平台依赖 yt-dlp 或第三方 API 才能解析）。

没有长期稳定且完全免费的公共解析 API。生产环境推荐自建 yt-dlp 或 Cobalt。

七、下载与权限

下载地址使用 HMAC-SHA256 签名（参数 u/n/e/s/vip/login），默认 downloadttl 秒有效；开启 downloadproxy 后由服务端 cURL 流式中转，支持 HTTP Range、中文文件名与体积上限。

• 锁定格式在解析响应中不返回下载地址，直接访问签名链接返回 403
• 关闭 vipenabled 后所有格式免费；关闭 loginrequired 后低清免登录
• 关闭 download_proxy 时返回原始直链（不经过本站中转）

八、多语言

内置语言：zh-CN、zh-TW、en、ja、ko、es、fr、de、pt、ru。

语言判定优先级：

1. URL 参数 ?lang=xx
2. Cookie（访客手动选择过的语言）
3. 浏览器 Accept-Language
4. 站点默认语言 default_lang

后台可关闭「自动识别浏览器语言」，也可在语言列表中裁剪可用语言。

新增语言：复制 lang/en.php，保持键名一致，保存为对应语言代码并在后台多语言设置中启用。

九、独立域名与站群

• bind_domain：单域名绑定，DNS 指向本站后，根路径即下载站首页（不能填主站域名）
• domain_sites：站群配置，每个域名可单独设置标题、LOGO、默认语言、SEO、主题色
• 未命中站群域名时使用主配置

十、广告位

固定三个广告位：

• 广告插件已安装：空位显示虚线框「广告位招租 + 自助购买」，点击打开购买弹窗
• 广告插件未安装：虚线框显示「暂不支持自助购买」
• 已有投放：自动替换为真实广告
• 关闭 ads_enabled 后三处均不显示

安装时已创建三个默认套餐（30 天 ¥10 / 90 天 ¥25），可在「广告位 → 套餐管理」改价或调整时长。

十一、主要配置项

十二、安全设计

• SSRF 防护：HttpService::isSafeUrl() 拒绝内网、回环、保留地址与非 http(s) 协议
• IP 限流：按 rate_limit 次 / 10 分钟，基于 Cache 计数
• 签名下载：HMAC-SHA256，链接过期或篡改返回 403
• XSS 防护：前端结果列表使用 DOM API 渲染，不拼接 HTML
• 文件名清洗：下载文件名移除路径符号与控制字符
• 模板转义：JSON 通过 raw 输出，其余变量默认转义

十三、数据表

zsensvideodownloaderlog

十四、常见问题

一直显示解析中

浏览器或 CDN 缓存了旧 JS/CSS。资源版本号已按文件时间生成，强制刷新 Ctrl + F5 即可。

解析失败 / 提示未配置

YouTube、TikTok 等受保护平台需要以下任一：填写第三方解析 API、启用 yt-dlp、配置 Cobalt 实例。纯直链或 Twitter/X 可免配置解析。

点击自助购买报错

确认「广告位」插件已安装启用，并且对应广告位存在启用状态的套餐（后台「广告位 → 套餐管理」）。

修改模板/CSS 后不生效

ThinkPHP 编译模板缓存在 runtime/temp，静态资源需复制到 public/static/Videodownloader/；必要时清理 runtime/cache 与 runtime/temp。

emoji / 中文乱码

语言包必须保存为 UTF-8 无 BOM。