Ghost Downloader 3 极简 LGPL FFmpeg 自建方案从 80MB 全量包到 4–6MB 定向裁剪的架构决策与安装链路实现【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3本篇文章以仓库内架构决策记录 docs/adr/0002-minimal-lgpl-self-built-ffmpeg.md 为核心剖析 Ghost Downloader 3 为何放弃预编译的完整 FFmpeg 发行包改为自建极简、LGPL二进制并深入讲解其构建矩阵、版本策略、正确性门禁以及应用内下载即安装的统一路由实现。读完你将掌握FFmpeg 按需裁剪的 configure 思路、多平台Windows/macOS/Linux/Android构建与分发设计以及如何通过featureService.parse这一统一入口将二进制安装无缝接入镜像加速、SHA256 校验与 Gatekeeper 隔离机制。一、背景应用内 FFmpeg 只有三类用途且从不转码ADR 开篇就给出一个关键事实Ghost Downloader 捆绑 FFmpeg 只为三件事服务没有任何调用点会做音视频转码流拷贝重封装stream-copy remux由bili_pack哔哩哔哩与ffmpeg_pack通用视频合并驱动把已下载的视频/音频轨道直接复制进 MP4 容器M3U8 混流与 AES-128 解密由m3u8_pack驱动借助 N_m3u8DL-RE 完成分片合并与加密流解密yt-dlp 后期处理合并 bestvideobestaudio、嵌入元数据/章节/缩略图。全应用触碰过的编码器只有mjpeg/png两种——仅当 yt-dlp 需要把 webp 缩略图转成 mp4 容器可识别的格式时才会用到。这一点在源码中得到印证ffmpeg_pack的FFmpegStep实际执行的命令是-c copy流拷贝合并见 features/ffmpeg_pack/task.py并用ffprobe -show_entries formatduration探测时长来驱动进度条-progress pipe:1解析out_time_us全程无编码负载。二、问题现状为三类用途背负 80MB 与 GPLv3 许可在自建方案落地前桌面端与移动端各自引用了不同的预编译包现状来源体积平台问题桌面端BtbN 的 GPL static 构建约 80 MBzip仅 Windows体积大、携带 GPLv3 二进制构成许可风险、无其他平台Androidhzw1199 的综合 LGPL 构建约 30 MBffmpegffprobeAndroid仍然携带应用从不调用的完整编码器/滤镜套件两者都包含一整套应用永远用不到的编码器与滤镜。换言之为了一次 remux用户要为 x264、x265 等一整条编码链买单——这既是体积浪费也是许可负担。三、决策自建极简 LGPL FFmpeg定向白名单裁剪ADR 的决策核心是构建属于项目自己的、最小化的 LGPL FFmpeg配置策略为--disable-everything全禁用起步再精确白名单放行所需的 demuxers / muxers / bitstream-filters / protocols额外开启mjpeg/png编码器供缩略图转换加上--enable-small进一步压缩体积目标单平台体积约4–6 MB对比原 80 MB缩减超过 90%。3.1 构建矩阵一份 configure 规格喂饱四个平台ADR 规划的构建位置是一个独立构建仓库采用 GitHub Actions 矩阵Windowsfork BtbN 的 Docker 交叉编译方案产出 win64 / arm64Linux同样基于交叉编译产出 x64 / arm64macOS新增原生 runner产出 x64 / arm64Android独立 NDK 车道仅 arm64、minSdk 28、不启用 MediaCodec。值得强调的是一份 configure 规格喂饱四个平台——所有平台共用同一份裁剪清单避免平台间行为漂移。该决策文档标记为Status: accepted — implemented已实施构建产物仓库名在应用源码中同样可见FFMPEG_REPO Repo(XiaoYouChR/Ghost-Downloader-FFmpeg, mirrors...)见 features/ffmpeg_pack/config.py。3.2 版本固定与安全更新8.1.x 稳定线 releases/latest版本钉死固定 FFmpeg 8.1.x 稳定分支与当时 Android 端 8.1.1 对齐构建 tag 形如n8.1.1-gd1…安全更新独立于应用发版应用每次从自建仓库的/releases/latest拉取最新构建FFmpeg 安全修复无需等待应用整体更新即可随二进制下发从 features/ffmpeg_pack/config.py 可见fetchLatestVersion与createInstallTask均通过fetchLatestRelease(FFMPEG_REPO)取最新 tag运行时还通过probeVersion读取安装目录下的VERSION文件或执行ffmpeg -version完成版本探测与 ADR 的版本策略一一对应。3.3 正确性门禁真实资产 smoke test 卡住发版每个构建任务都会跑真实资产冒烟测试任何一项失败即阻断发布——缺少某个 demuxer 会在 CI 失败而不是让用户下载时才报错。测试项覆盖bvba → mp4 remux视频音频流拷贝合并HLS AES-128 解密 混流fmp4 / m4sEAC3webp → mp4 缩略图转换ffprobe duration 探测。这与应用内的错误边界设计相呼应ffmpeg_pack的FFmpegStep在合并失败时会读取文件头 8 字节并比对ISOBMFF_BOX_TYPESftyp/styp/moof/moov/…对非 ISOBMFF 输入直接提示可能受 DRM 保护或下载不完整见 features/ffmpeg_pack/task.py把用户侧问题与二进制缺失问题区分开。3.4 分发CN 加速 直连回退 SHA256 校验产物分发复用github_pack的国内加速能力失败时回退到 GitHub 直连下载完成后核对官方发布的 SHA256。这一点在 features/ffmpeg_pack/config.py 的createInstallTask中有完整实现先probeDownloadUrl探测镜像可用地址随后同时传入sha256Url让安装任务执行校验。四、备选方案评估为什么换一个预编译包都不够ADR 记录了四条候选路径的对比最终结论非常清晰方案体积许可评价维持 BtbN GPL static现状约 80 MBGPLv3否决只为 remux 背负 80MB且仅 Windows换用 BtbN LGPL static略小LGPL否决为终极方案去掉 GPL 风险但仍是全量编码器套件仅作为紧急回退源保留gyan.dev essentials约 32 MB7zGPLv3否决仍带 x264/x265 等体积无明显优势且无 LGPL/极简变体自建极简选定4–6 MBLGPL唯一只带恰好用到的组件的方案自建方案的代价被明确接受需要自己维护 CI 构建流水线和 FFmpeg 安全升级节奏而这个代价被冒烟测试门禁框定在可控范围内。五、实现接缝安装不是新机制而是统一路由的子资源ADR 特别强调镜像机制不是新机制。安装任务与普通下载任务走同一条路——统一路由器featureService.parse见 app/services/feature_service.pyFeatureService._register在注册每个 pack 时会把self.parse挂到 pack 与 parser 上作为delegateL51、L61parse按 parser 的priority排序后逐个match命中即执行L75-L93GitHubParserpriority 90负责把 GitHub 文件 URL 改写到镜像但它自己不做 HTTP——通过self.delegate(replace(options, urlurl))把改写后的 URL再次交回featureService.parse让路由器决定见 features/github_pack/pack.py L83-L124MergeParser是先例模板它从不触碰 HTTP 或镜像只把子资源如options.video交回featureService.parse路由。安装的下载同样是待解析的子资源因此天然复用同一套镜像/回退逻辑。GitHubParser的具体实现还包含_buildFallbackUrls依次尝试选中的代理站点、其余代理站点、最后直连原 URLL126-L133并把剩余回退列表封装进GitHubHttpTaskStep.fallbackUrls运行时逐级降级L60-L80这就是 ADR 中CN 加速 直连回退的落地代码。5.1 安装侧设计BinaryInstallOptions InstallParserADR 描述的安装接缝对应disk_pack模块priority 55为运行时runtime发出BinaryInstallOptions(url, outputFolder, name, executableNames, sha256Url)并调用featureService.parseInstallParser把下载以及.sha256文件再次委托回featureService.parse(TaskOptions(...))让GitHubParser完成镜像改写随后包装上校验/解压/安装归档或 chmod单文件运行时与disk_pack从不 importgithub_pack——彻底解耦镜像细节归档与单文件统一按资源扩展名分支.zip/.tar.gz走解压否则走 chmod。5.2 当前仓库的落地实现app/install.py 的步骤链从当前仓库源码结构看安装任务的步骤编排集中在 app/install.py 的createInstallTaskL268-L323其步骤链与 ADR 完全对应FetchStep下载主资产与.sha256文件L252-L265ChecksumStep读取.sha256文件首字段对本地资产计算 SHA256 并比对失败即报SHA256 校验失败并中断L210-L233——由于比对发生在两个本地文件之间该步骤天然与镜像机制无关ExtractStep解压 zip/tar.gz内含 zip-slip 路径穿越防护safeRoot not in {memberPath, *memberPath.parents}即拒绝越界路径与实时进度/速度上报L42-L152InstallStep清理旧目录、搬移文件、为executableNames中命中的可执行文件补 0o755 权限非 WindowsL155-L207BinaryInstallStep单文件场景下的 chmodL236-L248。结合 features/ffmpeg_pack/config.py 的createInstallTask调用资产名按ffmpegAssetTarget()生成win64/winarm64/macos-x64/macos-arm64/linux-x64/linux-arm64Windows 用 zip、其余平台用 tar.gzexecutableNames传(ffmpeg, ffprobe)同时传sha256Url启用校验——与 ADR 的分发与校验要求完全一致。5.3 macOS 隔离处理removeQuarantine最后一道细节在InstallStep与BinaryInstallStep的 chmod 之后会调用removeQuarantine(path)仅 darwin防止 macOS Gatekeeper 直接杀掉从网上下载的ffmpeg。这与整个链路下载-校验-解压-安装闭环共同构成了二进制分发的完整安全模型。六、联动验证三大消费方如何命中同一份二进制FFmpeg 的安装状态被各 pack 实时消费形成闭环ffmpeg_pack的FFmpegRuntime.path()/ffprobePath()在 Android 上从nativeLibraryDir读取libffmpeg.so/libffprobe.so桌面端则通过findExecutable(installFolder, ffmpeg, bin)定位canInstall not IS_ANDROIDAndroid 依赖 NDK 车道预置的 soyt_dlp_pack在后期处理合并/嵌入元数据前同样从ffmpegRuntime取路径缺失即报错见 features/yt_dlp_pack/task.pym3u8_pack复用同一份N_m3u8DL-RE ffmpeg 组合完成 MP4/MKV 混流与直播管道混流见 features/m3u8_pack/config.py其安装任务同样支持镜像配置。三者共用同一份 4–6MB 的 LGPL 二进制且任何一个调用点都不会触发未编译进二进制的能力——这正是--disable-everything白名单模式的精髓把用不到的功能从二进制层面彻底删除而不是运行时假装它不存在。七、总结一次按需裁剪 统一路由的双重瘦身本 ADR 的价值可以浓缩为两句话裁剪层面--disable-everything 精确白名单 --enable-small把为三类 remux/解密/后处理场景服务的 FFmpeg 从约 80MB 压缩到 4–6MB同时消除 GPLv3 许可风险架构层面安装下载不是新机制而是featureService.parse路由下的普通子资源——镜像加速、多级回退、SHA256 校验、归档/单文件统一处理全部免费复用跨平台 CI 矩阵 真实资产冒烟测试把少组件的风险挡在发版之前。对于任何需要捆绑系统工具二进制的桌面/移动应用这份 ADR 及其在 app/install.py、features/github_pack/pack.py、features/ffmpeg_pack/config.py 中的落地实现都是一份可复用的参考模板先精确盘点真实调用点再决定裁剪边界最后把分发接入既有路由——而非简单换一个更小的预编译包。【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ghost Downloader 3 极简 LGPL FFmpeg 自建方案：从 80MB 全量包到 4–6MB 定向裁剪的架构决策与安装链路实现
Ghost Downloader 3 极简 LGPL FFmpeg 自建方案从 80MB 全量包到 4–6MB 定向裁剪的架构决策与安装链路实现【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3本篇文章以仓库内架构决策记录 docs/adr/0002-minimal-lgpl-self-built-ffmpeg.md 为核心剖析 Ghost Downloader 3 为何放弃预编译的完整 FFmpeg 发行包改为自建极简、LGPL二进制并深入讲解其构建矩阵、版本策略、正确性门禁以及应用内下载即安装的统一路由实现。读完你将掌握FFmpeg 按需裁剪的 configure 思路、多平台Windows/macOS/Linux/Android构建与分发设计以及如何通过featureService.parse这一统一入口将二进制安装无缝接入镜像加速、SHA256 校验与 Gatekeeper 隔离机制。一、背景应用内 FFmpeg 只有三类用途且从不转码ADR 开篇就给出一个关键事实Ghost Downloader 捆绑 FFmpeg 只为三件事服务没有任何调用点会做音视频转码流拷贝重封装stream-copy remux由bili_pack哔哩哔哩与ffmpeg_pack通用视频合并驱动把已下载的视频/音频轨道直接复制进 MP4 容器M3U8 混流与 AES-128 解密由m3u8_pack驱动借助 N_m3u8DL-RE 完成分片合并与加密流解密yt-dlp 后期处理合并 bestvideobestaudio、嵌入元数据/章节/缩略图。全应用触碰过的编码器只有mjpeg/png两种——仅当 yt-dlp 需要把 webp 缩略图转成 mp4 容器可识别的格式时才会用到。这一点在源码中得到印证ffmpeg_pack的FFmpegStep实际执行的命令是-c copy流拷贝合并见 features/ffmpeg_pack/task.py并用ffprobe -show_entries formatduration探测时长来驱动进度条-progress pipe:1解析out_time_us全程无编码负载。二、问题现状为三类用途背负 80MB 与 GPLv3 许可在自建方案落地前桌面端与移动端各自引用了不同的预编译包现状来源体积平台问题桌面端BtbN 的 GPL static 构建约 80 MBzip仅 Windows体积大、携带 GPLv3 二进制构成许可风险、无其他平台Androidhzw1199 的综合 LGPL 构建约 30 MBffmpegffprobeAndroid仍然携带应用从不调用的完整编码器/滤镜套件两者都包含一整套应用永远用不到的编码器与滤镜。换言之为了一次 remux用户要为 x264、x265 等一整条编码链买单——这既是体积浪费也是许可负担。三、决策自建极简 LGPL FFmpeg定向白名单裁剪ADR 的决策核心是构建属于项目自己的、最小化的 LGPL FFmpeg配置策略为--disable-everything全禁用起步再精确白名单放行所需的 demuxers / muxers / bitstream-filters / protocols额外开启mjpeg/png编码器供缩略图转换加上--enable-small进一步压缩体积目标单平台体积约4–6 MB对比原 80 MB缩减超过 90%。3.1 构建矩阵一份 configure 规格喂饱四个平台ADR 规划的构建位置是一个独立构建仓库采用 GitHub Actions 矩阵Windowsfork BtbN 的 Docker 交叉编译方案产出 win64 / arm64Linux同样基于交叉编译产出 x64 / arm64macOS新增原生 runner产出 x64 / arm64Android独立 NDK 车道仅 arm64、minSdk 28、不启用 MediaCodec。值得强调的是一份 configure 规格喂饱四个平台——所有平台共用同一份裁剪清单避免平台间行为漂移。该决策文档标记为Status: accepted — implemented已实施构建产物仓库名在应用源码中同样可见FFMPEG_REPO Repo(XiaoYouChR/Ghost-Downloader-FFmpeg, mirrors...)见 features/ffmpeg_pack/config.py。3.2 版本固定与安全更新8.1.x 稳定线 releases/latest版本钉死固定 FFmpeg 8.1.x 稳定分支与当时 Android 端 8.1.1 对齐构建 tag 形如n8.1.1-gd1…安全更新独立于应用发版应用每次从自建仓库的/releases/latest拉取最新构建FFmpeg 安全修复无需等待应用整体更新即可随二进制下发从 features/ffmpeg_pack/config.py 可见fetchLatestVersion与createInstallTask均通过fetchLatestRelease(FFMPEG_REPO)取最新 tag运行时还通过probeVersion读取安装目录下的VERSION文件或执行ffmpeg -version完成版本探测与 ADR 的版本策略一一对应。3.3 正确性门禁真实资产 smoke test 卡住发版每个构建任务都会跑真实资产冒烟测试任何一项失败即阻断发布——缺少某个 demuxer 会在 CI 失败而不是让用户下载时才报错。测试项覆盖bvba → mp4 remux视频音频流拷贝合并HLS AES-128 解密 混流fmp4 / m4sEAC3webp → mp4 缩略图转换ffprobe duration 探测。这与应用内的错误边界设计相呼应ffmpeg_pack的FFmpegStep在合并失败时会读取文件头 8 字节并比对ISOBMFF_BOX_TYPESftyp/styp/moof/moov/…对非 ISOBMFF 输入直接提示可能受 DRM 保护或下载不完整见 features/ffmpeg_pack/task.py把用户侧问题与二进制缺失问题区分开。3.4 分发CN 加速 直连回退 SHA256 校验产物分发复用github_pack的国内加速能力失败时回退到 GitHub 直连下载完成后核对官方发布的 SHA256。这一点在 features/ffmpeg_pack/config.py 的createInstallTask中有完整实现先probeDownloadUrl探测镜像可用地址随后同时传入sha256Url让安装任务执行校验。四、备选方案评估为什么换一个预编译包都不够ADR 记录了四条候选路径的对比最终结论非常清晰方案体积许可评价维持 BtbN GPL static现状约 80 MBGPLv3否决只为 remux 背负 80MB且仅 Windows换用 BtbN LGPL static略小LGPL否决为终极方案去掉 GPL 风险但仍是全量编码器套件仅作为紧急回退源保留gyan.dev essentials约 32 MB7zGPLv3否决仍带 x264/x265 等体积无明显优势且无 LGPL/极简变体自建极简选定4–6 MBLGPL唯一只带恰好用到的组件的方案自建方案的代价被明确接受需要自己维护 CI 构建流水线和 FFmpeg 安全升级节奏而这个代价被冒烟测试门禁框定在可控范围内。五、实现接缝安装不是新机制而是统一路由的子资源ADR 特别强调镜像机制不是新机制。安装任务与普通下载任务走同一条路——统一路由器featureService.parse见 app/services/feature_service.pyFeatureService._register在注册每个 pack 时会把self.parse挂到 pack 与 parser 上作为delegateL51、L61parse按 parser 的priority排序后逐个match命中即执行L75-L93GitHubParserpriority 90负责把 GitHub 文件 URL 改写到镜像但它自己不做 HTTP——通过self.delegate(replace(options, urlurl))把改写后的 URL再次交回featureService.parse让路由器决定见 features/github_pack/pack.py L83-L124MergeParser是先例模板它从不触碰 HTTP 或镜像只把子资源如options.video交回featureService.parse路由。安装的下载同样是待解析的子资源因此天然复用同一套镜像/回退逻辑。GitHubParser的具体实现还包含_buildFallbackUrls依次尝试选中的代理站点、其余代理站点、最后直连原 URLL126-L133并把剩余回退列表封装进GitHubHttpTaskStep.fallbackUrls运行时逐级降级L60-L80这就是 ADR 中CN 加速 直连回退的落地代码。5.1 安装侧设计BinaryInstallOptions InstallParserADR 描述的安装接缝对应disk_pack模块priority 55为运行时runtime发出BinaryInstallOptions(url, outputFolder, name, executableNames, sha256Url)并调用featureService.parseInstallParser把下载以及.sha256文件再次委托回featureService.parse(TaskOptions(...))让GitHubParser完成镜像改写随后包装上校验/解压/安装归档或 chmod单文件运行时与disk_pack从不 importgithub_pack——彻底解耦镜像细节归档与单文件统一按资源扩展名分支.zip/.tar.gz走解压否则走 chmod。5.2 当前仓库的落地实现app/install.py 的步骤链从当前仓库源码结构看安装任务的步骤编排集中在 app/install.py 的createInstallTaskL268-L323其步骤链与 ADR 完全对应FetchStep下载主资产与.sha256文件L252-L265ChecksumStep读取.sha256文件首字段对本地资产计算 SHA256 并比对失败即报SHA256 校验失败并中断L210-L233——由于比对发生在两个本地文件之间该步骤天然与镜像机制无关ExtractStep解压 zip/tar.gz内含 zip-slip 路径穿越防护safeRoot not in {memberPath, *memberPath.parents}即拒绝越界路径与实时进度/速度上报L42-L152InstallStep清理旧目录、搬移文件、为executableNames中命中的可执行文件补 0o755 权限非 WindowsL155-L207BinaryInstallStep单文件场景下的 chmodL236-L248。结合 features/ffmpeg_pack/config.py 的createInstallTask调用资产名按ffmpegAssetTarget()生成win64/winarm64/macos-x64/macos-arm64/linux-x64/linux-arm64Windows 用 zip、其余平台用 tar.gzexecutableNames传(ffmpeg, ffprobe)同时传sha256Url启用校验——与 ADR 的分发与校验要求完全一致。5.3 macOS 隔离处理removeQuarantine最后一道细节在InstallStep与BinaryInstallStep的 chmod 之后会调用removeQuarantine(path)仅 darwin防止 macOS Gatekeeper 直接杀掉从网上下载的ffmpeg。这与整个链路下载-校验-解压-安装闭环共同构成了二进制分发的完整安全模型。六、联动验证三大消费方如何命中同一份二进制FFmpeg 的安装状态被各 pack 实时消费形成闭环ffmpeg_pack的FFmpegRuntime.path()/ffprobePath()在 Android 上从nativeLibraryDir读取libffmpeg.so/libffprobe.so桌面端则通过findExecutable(installFolder, ffmpeg, bin)定位canInstall not IS_ANDROIDAndroid 依赖 NDK 车道预置的 soyt_dlp_pack在后期处理合并/嵌入元数据前同样从ffmpegRuntime取路径缺失即报错见 features/yt_dlp_pack/task.pym3u8_pack复用同一份N_m3u8DL-RE ffmpeg 组合完成 MP4/MKV 混流与直播管道混流见 features/m3u8_pack/config.py其安装任务同样支持镜像配置。三者共用同一份 4–6MB 的 LGPL 二进制且任何一个调用点都不会触发未编译进二进制的能力——这正是--disable-everything白名单模式的精髓把用不到的功能从二进制层面彻底删除而不是运行时假装它不存在。七、总结一次按需裁剪 统一路由的双重瘦身本 ADR 的价值可以浓缩为两句话裁剪层面--disable-everything 精确白名单 --enable-small把为三类 remux/解密/后处理场景服务的 FFmpeg 从约 80MB 压缩到 4–6MB同时消除 GPLv3 许可风险架构层面安装下载不是新机制而是featureService.parse路由下的普通子资源——镜像加速、多级回退、SHA256 校验、归档/单文件统一处理全部免费复用跨平台 CI 矩阵 真实资产冒烟测试把少组件的风险挡在发版之前。对于任何需要捆绑系统工具二进制的桌面/移动应用这份 ADR 及其在 app/install.py、features/github_pack/pack.py、features/ffmpeg_pack/config.py 中的落地实现都是一份可复用的参考模板先精确盘点真实调用点再决定裁剪边界最后把分发接入既有路由——而非简单换一个更小的预编译包。【免费下载链接】Ghost-Downloader-3The only downloader you need. 下载器的集大成者。项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost-Downloader-3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
