hongguo-downloader README

The project's README from github.com/parallelpan/hongguo-downloader. As one markdown file: README.md.

hongguo-downloader

红果短剧下载工具 · hongguo-downloader

红果短剧全集下载 · 批量下载 · 整剧打包 —— 粘贴一条分享链接,云端处理,按集付费取件。 把「手动逐集存片」变成「一条链接」的下载交付系统,在线版、免安装,打开网页即可使用。

Hongguo short drama downloader: paste one share link, and every episode is delivered from the cloud with per-episode pricing. No install and no app login — it runs in a browser, on phone or desktop.

在线体验 guoshi.app   看架构

version status tests license

非官方项目,与红果 / 字节跳动无任何关联。

红果短剧下载工具 hongguo downloader 首页界面


这是什么

红果短剧只提供「在 App 里一集一集看」,没有全集下载,也没有批量导出。想留存一套完整剧集,要么手动点几百次,要么装个客户端硬啃。

这个项目把整条链路做成了一个网页服务:你只负责贴链接,下载、解密、校验、打包、发直链全部在云端完成,最后按实际下载的集数计费。

传统做法 本系统
逐集点击、逐集等加载,1000 集要几小时 贴一条链接,云端并发处理,交付以分钟计
断在中间得从头再来 每集独立状态,失败自动重排,已完成的跳过
本地存一堆文件,找起来靠记忆 统一任务列表 + 24 小时有效直链,随时回来取
先付钱、不知道能不能下成 取件时才扣费,失败不收费,重复取件不重复扣

和桌面客户端的区别:免安装、不用配环境、不用自己合并转码 —— 打开网页就能用,手机同样可以操作。下载完成既可按分集直链逐集取,也可一次整剧打包。

其他常见叫法:hongguo downloader、hongguo 短剧下载器、红果免费短剧下载工具、红果短剧批量导出、hongguo duanju downloader —— 指的都是这一个项目。


三步完成一次交付

① 贴链接 ② 云端处理 ③ 取件计费
粘贴红果分享链接、整段分享口令,或直接填剧集编号。解析后立刻看到剧名、封面、集数与更新进度。 关掉网页也没关系。任务在服务端排队执行,每集独立重试,进度实时可见,完成后站内提醒。 勾选需要的集数,确认后一次性扣费并生成 24 小时直链,可单集取、也可打整包 ZIP。

下载任务列表


功能一览

模块 能力
解析 分享链接 / 分享口令 / 剧集编号三种输入;24 小时缓存,重复解析不重复请求上游
发现 热播榜、真人榜、AI 榜、动漫榜四类榜单(6 小时刷新);按剧名搜索,60 秒缓存
任务 同剧同集自动复用运行中的任务,不重复扣费;失败集单独重试,可随时取消
交付 分集直链 / 按需整剧打包 ZIP;直链默认以「附件」下发,点开即下载而不是在线播放;支持断点续传
计费 余额 + 卡密 + 在线支付三通道;扣费发生在取件,job_id 唯一键保证并发取件只扣一次
支付 Binance Pay(USDT,唯一金额指纹 + 备注码)与 Stripe(卡 / Apple Pay,托管收银台)双通道,官方查单为准
后台 总览、用户、订单、卡密、下载任务五个页面;CSV 导出;卡密生成与作废(唯一的不可逆写操作)
运维 健康检查暴露 db / oss / device / queue 状态;任务心跳超时自动回收

界面

用户端

红果短剧剧集详情 · 选集与按集下载 余额与充值
剧集详情 · 选集、看单集均值体积、按集计费 余额与充值 · 卡密 / 在线支付双入口,流水逐笔可对
红果短剧热播榜与真人榜 下载任务
榜单 · 四类榜单 6 小时刷新 任务 · 逐集状态色块,失败集可单独重试

移动端首页     移动端任务页
移动端:390px 宽度下完整可用

运营后台

运营总览 订单管理
总览 · 按东八区切日,底部直接给 worker 存活与支付通道状态 订单 · 应付尾数高亮,确认方式区分自动 / 人工

下载任务监控
任务监控 · 逐集色块 + 失败原因 + worker 归属,卡单一眼可见

截图中的邮箱、UID、主机名均已脱敏;界面内剧集海报版权归原权利方,仅作界面示意。


案例演示

案例一 · 1000 集长剧,85 秒完成交付

一次 1000 集的整剧任务,worker 只上传分集文件(ep-001.mp4 … ep-1000.mp4),不在下载阶段同步打整包:

结果是:下载与打包解耦,长剧不必等到最后一份字节落盘才能开始取件。

案例二 · 双支付通道,对账不靠人盯

币安 Pay:下单 → 唯一金额 1.72 + 备注码 N5GSTY → 用户转账
          → 收银台每 3 秒查单,服务端顺带拉官方流水
          → 唯一金额命中 / 备注码命中 / 用户回填订单号,三选一即入账

Stripe: 下单 → 建 Checkout session(metadata 带 order_id)→ 跳转付款
          → webhook 只做唤醒,入账仍以官方 retrieve 为准

两个关键口径:

  1. 入账 = 实付。币安流水实际到账多少就入账多少,识别尾差不是手续费,绝不按面额截留;
  2. 回调不盲信。webhook 只用来提速,验签通过后仍以官方查单结果落账;未配置签名密钥时直接 503,不降级成「盲信模式」。

后台「自动确认率」就是这条链路的体检指标:正常 80%+,一掉就说明对账在退化,需要人工介入。

案例三 · 实例被摘除,75 秒自愈

生产是单机自愈架构(伸缩组 MIN=MAX=1 + 自定义镜像 + Cloudflare Tunnel,源站不开放任何公网端口)。故障演练实测时间线:

时刻 事件
T+0s 手动摘除实例,站点立即 530
T+60s 伸缩组用镜像拉起新节点,UserData 注入配置
T+68s 设备层冷启动与附着自检通过
T+75s GET /health 恢复 200,隧道自动重连

没有人工介入,也没有「重启一下就好了」这种不可复现的操作 —— 因为修复动作全部写在 UserData 里,而不是留在某台机器的 shell 历史里。


架构

架构图

四个刻意的取舍:

  1. 队列用表,不引 Redis。任务表 + CAS 乐观锁 + 心跳超时回收,少一个中间件就少一类故障;
  2. 扣费在取件,不在建任务。用户先看到「能下成」再付钱,download_links.job_id 唯一键兜住并发重复扣费;
  3. 重活全在 worker。API 只读写数据库、发任务,下载与转码在独立进程,被杀掉重启会跳过已完成的集;
  4. 直链签发分离。存储层只做预签名,链接有效期 24 小时,过期重取不重复扣费。

技术栈

层 选型
前端 React 19 · Vite 7 · TypeScript · TanStack Query · 自建设计令牌(深色前台 / 浅色后台)
后端 FastAPI · SQLAlchemy · Pydantic · 纯 JSON API(/api/v1/*)
数据 开发 SQLite / 生产 MySQL 8.0(RDS,仅内网)
存储 阿里云 OSS 私有桶 + 预签名直链(支持 Range),可降级本地磁盘
任务 独立 worker 进程 + 表级队列 + CAS 乐观锁 + 心跳回收
支付 Binance Pay(只读 API 拉流水对账)· Stripe Checkout + Webhook
部署 自定义镜像 + 伸缩组自愈 + Cloudflare Tunnel(无公网入口)
质量 96 项接口冒烟 + 52 项 Playwright 真实浏览器 e2e(不 mock 接口、不注入登录态)

项目状态

项 值
主线版本 v0.6.1
线上地址 https://guoshi.app
接口文档 https://guoshi.app/api/docs
健康检查 https://guoshi.app/health
双通道支付 Binance Pay + Stripe,均已端到端验证

本仓库与大版本同步更新:每次正式发版后,README 与截图会跟着刷新。若你看到的状态与线上不符,欢迎开 issue 指出。


常见问题 · FAQ

红果短剧怎么下载到本地?

三步:复制红果 App 里的分享链接(或整段分享口令)→ 粘贴到在线版 → 解析后勾选要的集数取件。 下载、校验、打包都在云端完成,下完拿到的是分集直链或整剧 ZIP,可以直接存到手机、电脑或网盘,不必守着 App 一集一集点。

红果短剧下载要花钱吗?

解析、看榜单、浏览剧集信息都是免费的;只有取件时才按实际集数计费,下载失败的集不收费。 本项目不提供会员制,也不卖「无限下载」——成本与集数线性相关,按集计费对双方都更清楚。

支持红果免费短剧的全集下载吗?

支持。粘贴任意一集或整部剧的分享链接,解析后可以一次勾选全部集数;取件时既可单集直链下载,也可一次生成 ZIP 整包,两种方式都支持断点续传。

为什么按集计费,而不是会员制?

因为成本与集数线性相关(带宽、存储、设备占用),会员制会让「下 1000 集」和「下 10 集」的人付一样的钱,最后只能靠限速来平衡。按集计费更接近真实成本,用户也更容易算清一次要花多少。

重复取件会不会重复扣费?

不会。扣费绑定在「取件记录」上,job_id 唯一键保证同一任务只生成一条扣费记录;重复点取件只会刷新直链有效期。

下载失败会扣钱吗?

不会。失败的集不计费;已经扣费但交付失败的,走退款流水回补余额。

Is there a Hongguo downloader for PC or Mac?

Yes — it is browser-based, so the same site works on Windows, macOS, Linux, Android and iOS. Nothing to install: you paste the share link, the cloud workers fetch and verify every episode, and you get either per-episode direct links or one ZIP for the whole drama.

What is hongguo downloader?

hongguo-downloader is the open-source showcase of a cloud pipeline for Hongguo (红果) short dramas — the cdrama / duanju format where each drama is split into hundreds of 1–2 minute episodes. The pipeline resolves a share link, downloads every episode server-side, verifies each file, and delivers signed links priced per episode. This repository documents the design and architecture; no downloader binary or bypass tool is distributed here.


免责与权利声明


在线体验 → · 有问题请开 issue,只接受文档纠错

hongguo-downloader (parallelpan/hongguo-downloader)

Searching Database…

What is this?A paid web service that downloads full episodes of Hongguo (红果) short dramas. You paste a share link, the cloud fetches every episode, and you get per-episode links or one ZIP for the whole drama.
Is it an app I install or a website?It's a website, not a program you install. It runs in a browser on any device. This GitHub repository only documents the design and architecture of that service.
How do I download a drama?Copy the share link or the full share code from the Hongguo app, paste it into the web version, tick the episodes you want, and confirm. The links become available once the cloud job finishes.
Do I need an account or payment before trying it?No app login is needed. Searching, checking rankings and viewing episode info are free. You pay only when you pick up episodes, per episode actually fetched, using a balance, a card code or online payment.
Is there a catch I should know about?It's unofficial and not affiliated with Hongguo or ByteDance. The repo has no runnable code: it only documents the design and architecture, and no downloader or bypass tool is distributed there.
Does it work on my phone and PC?Yes. Because it's a browser site, it works on Windows, macOS, Linux, Android and iOS, and the layout is usable at a 390px phone width.
Why per-episode pricing instead of a membership?Cost scales with the number of episodes (bandwidth, storage, device time). A flat membership would charge a 10-episode viewer the same as a 1000-episode one, so per-episode pricing matches real cost.
How can a 1000-episode drama be ready so quickly?Downloading and packaging are decoupled. Workers upload each episode file, and the full ZIP is built only when requested, so in the author's 1000-episode test the drama was ready in about 85 seconds.
What happens if some episodes fail?Each episode has its own status and retries separately. Failed episodes are not charged, and if money was taken but delivery failed, the balance is refunded.
What is the stack behind it?React 19 with Vite on the front end, FastAPI with SQLAlchemy and MySQL 8.0 on the back end, Alibaba Cloud OSS for file storage, and separate worker processes that use a table-based queue instead of Redis.
Size
0.7 MB
Stars
437
Age
3d
Commits · 90 Days