minitv README

项目的 README,来自 github.com/xuliang2024/minitv。合并为一个 markdown 文件:README.md。

MiniTV

开源的短剧分发平台 —— 内容方入驻上传、平台审核分发、分集解锁与结算,一套后端撑起官网 / H5 / App / 后台。

React 18 · TypeScript · FastAPI · PostgreSQL · Redis · Flutter · Bunny Stream · Stripe


短剧出海,全链路交付

收款通道 · 短剧制作 · 系统定制 · 广告投放 —— 需要哪一段就聊哪一段,扫码加微信。

线上在跑:官网 · H5 · API


在线演示

端 地址 说明
🖥 官网(营销站) https://minitv.us 产品介绍、免费试看、套餐展示
📱 H5 Web App https://h5.minitv.us 完整播放、金币、签到、评论,移动端优先
🔐 管理后台 https://admin.minitv.us 内容 / 运营 / 财务后台,需登录
⚙️ API https://api.minitv.us 接口服务,文档见 /docs

演示站由维护者提供,仅用于体验产品;请勿用于压测或爬取。

产品演示

MiniTV 官网首屏
官网 —— 首屏讲清价值主张,右侧真机模型预演产品界面,主 CTA 直达免费试看。
H5 首页
H5 · 首页
Discover / Ranking / Free 多频道,主推位轮播
H5 频道页
H5 · 新剧
最新上架一屏尽览,三列纵向浏览
App 选集面板
App · 选集
已看 / 在追 / 加锁三态一目了然
后台数据看板
后台 · 数据看板 —— 活跃、播放、完播、营收按日聚合,全站累计与待办一屏掌握。
后台金币与任务
后台 · 金币与任务 —— 7 天签到阶梯与任务激励可在线上直接调参,次日生效、全程留痕。

功能

内容与播放

变现与增长

运营与协作

技术栈

层 选型
后端 FastAPI · SQLAlchemy 2 · Alembic · psycopg3 · PyJWT
数据 PostgreSQL 16 · Redis 7
前端 React 18 · TypeScript 5 · Vite 5 · Ant Design 5
App Flutter(Dart SDK 3.13+,iOS / Android)
媒体 Bunny Stream(HLS 转码)· Bunny Storage + Optimizer(封面 / 字幕)
支付 Stripe Checkout + Webhook
邮件 Resend
部署 Cloudflare R2 托管静态站 · 单台 Linux 跑 API

目录结构

.
├── backend/            FastAPI 服务
│   ├── app/modules/    业务模块:account / content / playback / wallet /
│   │                   billing / social / ops / recommend / analytics
│   ├── alembic/        数据库迁移
│   └── tests/          pytest 用例(隔离库,跑前自动建表)
├── admin/              管理后台(React + Ant Design)
├── web/                官网营销站(React,含独立隐私政策页)
├── h5/                 移动端 Web App(React)
├── app/                Flutter App(iOS / Android)
├── cli/                单文件 CLI(纯标准库,Python 3.8+)
├── scripts/            数据导入、发布、运维脚本
├── docs/               架构 / 运营 / 验收文档
├── deployments/        发布记录(每次发布自动生成 JSON)
└── docker-compose.yml  本地 PostgreSQL + Redis

快速开始

前置要求

1. 拉代码并准备环境变量

git clone https://github.com/xuliang2024/minitv.git
cd minitv
cp .env.example .env

.env.example 默认 BUNNY_MODE=fake,播放与封面走本地桩实现 —— 不填任何外部密钥也能把接口和后台跑通。

2. 起依赖服务

docker compose up -d      # PostgreSQL :15432 / Redis :16379

3. 装后端依赖并建表

python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt

cd backend && alembic upgrade head && cd ..

4. 启动 API

.venv/bin/uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 18110

健康检查:curl http://127.0.0.1:18110/health

快捷方式:./scripts/up-local.sh 会一次性起好 Docker 依赖和 API。

5. 启动三个前端

三个终端分别执行:

cd admin && npm install && npm run dev     # http://127.0.0.1:5173
cd web   && npm install && npm run dev     # http://127.0.0.1:5174
cd h5    && npm install && npm run dev     # http://127.0.0.1:5175

Vite 已配好代理,/v1 与 /admin/v1 会自动转发到 127.0.0.1:18110,无需额外配置跨域。

6. 创建第一个后台账号

cd backend
SEED_ADMIN_PASSWORD='换成你自己的口令' ../.venv/bin/python -m app.seed_admin

不带 SEED_ADMIN_PASSWORD 时会随机生成一个并打印一次。该脚本只在 admin_users 为空时执行,可安全重复运行。

打开 http://127.0.0.1:5173,用这个账号登录。

本地端口一览

服务 地址
API http://127.0.0.1:18110
管理后台 http://127.0.0.1:5173
官网 http://127.0.0.1:5174
H5 http://127.0.0.1:5175
PostgreSQL 127.0.0.1:15432
Redis 127.0.0.1:16379

可选:灌一些演示数据

cd backend
../.venv/bin/python -m app.seed_rewards          # 签到 / 任务基线配置
../.venv/bin/python -m app.seed_users --count 20 # 假 C 端用户与钱包
../.venv/bin/python -m app.seed_catalog_episodes # 从本地片库导入剧集(需自备 catalog)

环境自检

python3 scripts/check_local_env.py

检查 .env、PostgreSQL、Redis 与 Python 依赖;Flutter / Android / iOS 工具链单独报告,不影响后端启动。

运行 App

cd app
flutter pub get

# iOS 模拟器(默认就连本机 API)
flutter run

# Android 模拟器 / 真机需要显式指定 API 地址
flutter run --dart-define=API_BASE=http://10.0.2.2:18110

命令行工具

cli/minitv 是单文件、零依赖的 CLI(Python 3.8+,当前 0.4.0),覆盖剧集 / 分集 / 标签 / 分组 / 排期 / 上传 / 上剧方等 57 条命令。

curl -fsSL https://minitv.us/cli/install.sh | sh
minitv config set-key                      # 交互式写入 API Key(不落 shell 历史)
minitv drama list --status published
minitv episode upload 12345 ./ep01.mp4
minitv doctor                              # 自检:连通 / 身份 / 权限

完整命令见 docs/cli-reference.md。

发布

线上发布统一走一个入口,内含共享锁与自动版本号:

python3 scripts/release.py status          # 先看锁和线上版本
python3 scripts/release.py r2   --dist web/dist --source web
python3 scripts/release.py run  --target server -- ./scripts/deploy_server.sh

版本形如 v2026.10.29.1,由脚本在锁内生成并打 tag;回滚同样走脚本。细节见 docs/release-process.md。

这些日期构建号属于本地部署记账,权威记录是 deployments/releases/*.json(含版本号与提交 SHA)。它们不推送到远端——公开仓库只保留语义化版本 tag,当前为 v1.0.0。

文档

文档 内容
docs/technical-architecture.md 技术拓扑、密钥边界、部署架构
docs/release-process.md 发布 / 回滚流程与故障处理
docs/membership-coins-unlock.md 会员、金币、解锁的账务设计
docs/comment-architecture.md 评论与异步审核链路
docs/supplier-role-plan.md 上剧方角色的权限与结算设计
docs/cli-reference.md CLI 全部命令

商务合作

我们提供短剧出海的全链路解决方案 —— 从系统到变现一次打通,欢迎咨询。

服务 我们做什么
💳 收款通道 海外收款落地:Stripe 订阅 + 金币解锁双模式,多币种定价、退款与对账已跑通
🎬 短剧制作 剧本、拍摄、剪辑、字幕与多语言本地化,直接交付可上线的竖屏片源
🧩 系统定制 本仓库源码私有化部署、品牌换皮、功能二开,含 iOS / Android App 打包上架
📣 广告投放 TikTok / Meta 素材制作与投放代运营,按 ROI 逐步放量

自建站、代制剧、代投放,哪一项都能单独合作;已有系统只缺支付或买量,也可以只补那一段。

扫码加微信,咨询短剧出海全链路解决方案

扫码加微信,备注「MiniTV」,聊聊你的出海项目

遇到 Bug 或功能建议,也可以直接开 Issue。

许可证

本项目基于 MIT License 开源,© 2026 MiniTV。

可自由用于商业项目,保留版权声明即可。如需改为 Apache-2.0(附带专利授权条款),替换 LICENSE 文件并同步本节即可。

minitv (xuliang2024/minitv)

正在搜索数据库…

413 ·GitHub
这是什么?MiniTV 是一个开源的竖屏短剧分发平台:内容提供方上传剧集,平台审核并分发,观众使用金币或会员解锁剧集;网站、H5、手机应用和管理后台都由同一个后端提供服务。
这是单个应用还是完整平台?它是一个完整平台,而不是单一应用:一个 FastAPI 后端同时为营销网站、H5 网页端、Flutter 手机应用和基于 React 的管理后台提供服务,这些均基于同一技术栈。
我该如何把它运行起来?克隆仓库,复制 .env.example 文件,用 Docker 启动 Postgres/Redis,安装后端依赖并执行数据库迁移,然后启动 API 和三个前端——或者直接运行提供的辅助脚本,一键完成全部步骤。
试用之前需要先安装什么?后端和前端需要 Python 3.11+ 和 Node.js 18+,本地运行 Postgres 和 Redis 需要 Docker,只有想运行手机应用时才需要 Flutter 3.x。
运行它是否需要 Bunny Stream 和 Stripe 账号?本地测试不需要——.env.example 默认使用模拟的 Bunny 模式,视频播放和封面由本地模拟组件提供,无需任何外部密钥。若要正式部署,则需要真实的 Bunny Stream 和 Stripe 凭据,分别用于视频分发和支付。
金币和解锁系统是如何运作的?剧集可以免费观看、按金币单独定价,或需要会员才能观看;金币余额采用只追加的账本,并通过幂等扣款机制,确保用户不会被重复扣费。
运营方如何通过平台盈利?Stripe Checkout 同时支持自动续费订阅和一次性限时通行证两种方式,运营方可以在管理后台中在这两种计费模式之间切换。
第三方短剧供应商能否自行使用平台?可以,供应商拥有专门的角色,可自行注册、上传自己的短剧并提交审核,同时可只读查看其结算账单。
剧集评论是否会自动审核?会的,剧集评论会通过兼容 OpenAI 接口的 AI 进行异步审核,审核所用的密钥加密存储在管理后台中。
大小
100.7 MB
星标
413
时长
1个月
提交 · 90 天