Bllii · video-collection

Bllii · 二次元番剧与网络采集聚合平台 (Bllii-Familiar 追番使魔)

从数据采集、内容管理到多端浏览与播放，共享一套 RESTful API。

_{More Stories, Together}

Important

本项目仅供个人学习与技术研究使用，不得用于任何商业用途。

本仓库只包含源代码、配置示例与品牌素材，不存储、不提供、不分发任何影视内容，也不内置任何第三方资源站地址。采集配置中的数据源使用 example.com 占位，使用者应仅接入自己拥有版权或已获得合法授权的数据源，并遵守所在地法律法规与相关平台的服务条款。

因使用、修改或部署本项目产生的任何法律责任由使用者自行承担，与作者无关。若本项目内容侵犯了您的合法权益，请通过 Issue 联系，我们将及时处理。

功能概览

能力	主要功能
Bllii-Familiar 使魔采集	网络视频 JSON、XML、RSS / Atom、自定义 REST JSON；多源自动化增量与全量采集
使魔规则工坊	静态网页 CSS、JSON 接口、数据库、Excel / CSV；字段映射、清洗、样本预览与入库
内容浏览与播放	首页推荐、分类筛选、搜索、排行榜、新番时间表、详情、多线路选集与播放
用户与互动	登录注册、追番收藏、观看历史与进度同步；资讯、社区、通用评论及站内通知 API
增长与粘性	PWA 安装与离线浏览、个人搜索历史与自动补全、个性化首页推荐、次日/7日留存与功能渗透率看板、轻量埋点（停留/推荐/广告点击）
广告位管理	banner / 首页推荐位 / 详情页三类广告位，支持排期、上下架，客户端自动隐藏空广告位
后台管理	采集源、视频库、用户、调度、反馈、站点配置、主题、播放器、日志与数据库管理
接口与存储	RESTful API、Cookie / Bearer 鉴权、OpenAPI、Swagger UI、Redoc、RSS 订阅；PostgreSQL / SQLite

各端的具体实现与配置方式见子项目文档。数据库导入支持 PostgreSQL、MySQL、SQLite 和 SQL Server；平台自身的业务存储使用 PostgreSQL 或 SQLite。

系统架构

flowchart TB
    sources["已授权数据源<br/>JSON / XML / RSS / 网页 / 数据库 / 文件"]
    service["video-collection-service<br/>Go · RESTful API + 管理后台（go:embed）"]
    db[("PostgreSQL / SQLite")]
    redis[("Redis (radix)<br/>会话与缓存 · 可选")]
    web["Web 门户<br/>Astro + Tailwind CSS"]
    app["跨端客户端<br/>Flutter + Material 3"]
    adminClient["浏览器管理后台<br/>Vue 3 · Reka UI (Radix Vue)（Go 托管）"]

    sources -->|采集与清洗| service
    service <-->|读写| db
    service <-.->|会话 / 读缓存| redis
    web <-->|REST API| service
    service -->|/admin 托管 SPA| adminClient
    app <-->|REST API| service

    classDef service fill:#eef6ff,stroke:#4b9fff,color:#353b58
    classDef client fill:#f5f1ff,stroke:#9a83ff,color:#353b58
    classDef storage fill:#fff0f7,stroke:#ff89c7,color:#353b58
    class api service
    class web,admin,app client
    class db storage

统一服务（video-collection-service）：原 video-collection-api 与 video-collection-admin 已合并为一个 Go 服务——管理后台 SPA 通过 go:embed 内嵌，由服务直接托管 /admin，无需独立后台容器。
radix 缓存与会话：接入 Redis（mediocregopher/radix/v4）后启用分布式会话与公开读接口缓存；未配置时自动降级为内存会话 + 直连数据库。
前后端分离：门户与客户端独立运行，共用后端数据与接口。
本地开发轻量启动：未配置数据库时服务以 SQLite 单文件模式运行（也可显式 DB_DRIVER=sqlite）；SQLite 同时承担基础配置存储（数据库连接、Redis、初始管理员账号密码等）。
接口文档随服务提供：/docs、/redoc、/openapi.json。

仓库结构

目录 / 文件	职责	技术栈 / 用途
`video-collection-service/`	统一服务：RESTful API + Go 托管管理后台，含 radix 缓存/会话层	Go 1.26 · radix v4
`video-collection-service/web/admin/`	管理后台前端（Gemini 风格，Radix 原语驱动，构建产物 go:embed 进服务）	Vue 3 · Reka UI (Radix Vue) · TypeScript · Vite 6
`video-collection-web/`	用户门户与播放页面	Astro 5 · Tailwind CSS
`video-collection-app/`	桌面、移动与 Web 客户端	Flutter · Material 3
`bllii-brand-kit/`	标志、图标、品牌动画与预览	SVG · PNG · GIF · MP4
`run.ps1` / `run.sh`	多服务启动器	Windows PowerShell / Bash

快速开始

1. 准备环境

按需要运行的子项目安装工具；仅启动 Service 和 Web 时无需安装 Flutter。

工具	要求	用于
Go	1.26.0 或更高，参见 `go.mod`	统一服务
Node.js	建议使用当前 LTS 版本	管理后台 / Web / 门户
pnpm	启动器使用的前端包管理器	管理后台 / Web / 门户
Flutter SDK	需包含 Dart `^3.13.3`，参见 `pubspec.yaml`；安装目标平台工具链	App
PostgreSQL	可选；本地可使用 SQLite	服务存储

2. 获取项目

git clone https://github.com/plunjoin/video-collection.git
cd video-collection

3. 启动 API、后台与门户

Windows · PowerShell

.\run.ps1 service web

macOS / Linux · Bash

chmod +x run.sh
./run.sh service web

service 为合并后的统一服务（API + 管理后台）；旧参数 api / admin 仍指向合并前的两个子项目，保留兼容。启动器会检查所选目标需要的运行时，并执行 go mod download，在缺少依赖时执行 pnpm install / flutter pub get。缺少 pnpm 时会尝试通过 Corepack 或 npm 安装；其他运行时缺失时会给出安装提示并退出。

管理后台首次运行前需先构建前端（之后由 go:embed 随二进制分发）：
cd video-collection-service/web/admin
pnpm install --frozen-lockfile && pnpm build

所有服务在同一个终端并行运行，日志带 [api]、[admin]、[web]、[app] 前缀，按 Ctrl+C 停止全部。Windows 启动器会设置 UTF-8 控制台编码。

4. 打开服务

以下地址按默认配置列出，实际端口以启动日志为准。

入口	本地地址	说明
Web 门户	localhost:4321	用户浏览与播放入口
管理后台	localhost:8080/admin	管理与采集配置入口（统一服务托管）
根路径 → 后台	localhost:8080/	默认端口根目录自动跳转管理后台（服务即后台）
服务状态（程序）	localhost:8080/status	在线状态、缓存与接口索引（JSON）
Swagger UI	localhost:8080/docs	在线查看与调试接口
Redoc	localhost:8080/redoc	接口参考文档
OpenAPI JSON	localhost:8080/openapi.json	导入 Postman / Apifox 等工具
RSS 订阅	localhost:8080/rss.xml	聚合订阅输出

首次初始化数据库时会创建管理员账号：admin，密码可通过 ADMIN_INITIAL_PASSWORD 配置，未设置时为 admin123。生产部署步骤见部署与维护。

Tip

示例采集源使用占位地址。首次使用请在后台配置已授权的数据源，再执行采集；启动服务本身不会产生真实影视数据。

配置指南

API 与数据库

API 支持系统环境变量、工作目录下的 .env 和 YAML 配置，优先级为：

系统 / 容器环境变量 > .env > config/collector_rules.yaml > 默认值

复制 video-collection-service/.env.example 为同目录下的 .env，按实际环境修改。

变量	用途	默认 / 注意事项
`PORT`	API 监听端口	未设置时为 `80`；示例 `.env` 为 `8080`
`DB_DRIVER`	业务数据库引擎	`postgres` 或 `sqlite`
`DB_DSN` / `DATABASE_URL`	数据库完整连接串	设置后优先于分项连接配置
`DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD`、`DB_NAME`、`DB_SSLMODE`	PostgreSQL 分项连接配置	具体示例见服务 `.env.example`
`SQLITE_PATH`	SQLite 文件位置	`data/collection.db`
`CONFIG_PATH`	采集规则配置路径	`config/collector_rules.yaml`
`WEBHOOK_ENCRYPTION_KEY`	Webhook 密钥信封加密主密钥	可选；缺省时由 `ADMIN_INITIAL_PASSWORD` 派生，见 Webhook 文档

Note

本地端口需要统一。 Admin 和 Web 的开发代理默认指向 http://localhost:80。直接复制 API 的 .env.example 会把 API 端口改为 8080，请将 .env 中的 PORT 改为 80，或同步调整各端连接配置。Linux / macOS 监听 80 可能需要额外权限，可使用 8080 并同步修改客户端地址。

各端连接地址

子项目	配置入口	本地默认行为
Admin	服务直接托管 `/admin`；`vite.config.ts` → `server.proxy`	独立开发时 `/api` 与 `/rss.xml` 代理到 `http://localhost:80`
Web	`astro.config.mjs`；`PUBLIC_API_URL` / `INTERNAL_API_URL`	浏览器未设置 `PUBLIC_API_URL` 时使用同源请求；开发 `/api` 代理到 `http://localhost:80`；服务端优先读取 `INTERNAL_API_URL`
App	调试包可在设置中修改；正式包使用构建参数 `API_BASE_URL`	调试时 Android 模拟器使用 `http://10.0.2.2:80`，其他平台默认 `http://127.0.0.1:80`。正式包执行 `flutter build ... --dart-define=API_BASE_URL=https://api.example.com`，不再显示服务端地址配置

Web 的 .env.example 默认留空 PUBLIC_API_URL，浏览器使用同源 /api；开发代理和生产 Node 服务代理默认连接 http://localhost:80，生产服务可通过运行时的 INTERNAL_API_URL 修改后端地址。调试真机访问 API 时，App 应在设置里填写宿主机局域网 IP，不能使用真机自己的 localhost。正式包只读取构建时的 API_BASE_URL。

生产环境的反向代理、数据库、构建与服务部署步骤见统一服务文档与 Web 文档。

文档导航

文档	适用内容
生产部署与维护	Docker Compose、域名 HTTPS、数据持久化、备份恢复与升级
可配置采集规则	模板目录、自定义请求、字段映射与分页
统一服务 API 使用与部署	采集协议、鉴权、存储、OpenAPI、radix 缓存、二进制构建与部署
管理后台	Gemini 风格后台界面、模块、开发与构建
Web 门户	页面组件、开发、构建与接口调用
Flutter 客户端	多端运行、API 配置与发布构建
通用采集规则工作台	来源配置、字段映射、预览、入库与能力边界
内容与通知 API	资讯、社区、站内通知与权限规则
通用评论 API	多级回复、点赞、通知与内容类型扩展
数据库管理 API	数据浏览、备份恢复、维护与管理 SQL
Webhook 回调采集 API	回调端点、HMAC 验签、防重放、原始报文留痕与密钥管理
品牌资产说明	标志、图标、动画与接入规范

品牌资产

Web 与 App 沿用 Bllii / bllii 视觉体系，以蓝、紫、粉为主色。品牌资产位于 bllii-brand-kit/，包含矢量标志、透明 PNG、App 图标、功能图标与品牌动画。

蓝	紫	粉	深墨
`#4B9FFF`	`#9A83FF`	`#FF89C7`	`#353B58`

更新功能图标 bllii-brand-kit/svg/bllii-ui.svg 后，在 Web 目录执行：

cd video-collection-web
pnpm brand:sync

该命令同步图标预览、Web 图标资源，以及 Web / API 两份播放器中的图标。完整资产与动画预览可在本地打开 bllii-brand-kit/index.html，功能图标总览见 ui-icons.html。

查看品牌资产总览

常见问题

前端已启动，但接口请求失败

先检查 Service 是否启动，再确认端口和连接地址一致。服务默认端口为 80，服务 .env.example 中为 8080；Admin / Web 开发代理默认连接 80。Web 设置了 PUBLIC_API_URL 时，浏览器会使用该地址，也应确认后端跨域配置。

启动时报 PostgreSQL 连接失败并退出

系统不再把 SQLite 作为 PostgreSQL 故障时的数据兜底（避免两套库数据漂移）。请通过以下任一方式修正后重启：

管理后台「基础配置」页面（/admin/bootstrap，接口 GET|PUT /api/admin/bootstrap）填写数据库连接并保存，支持「测试连通性」；
环境变量：DB_DSN 或 DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME；
确需 SQLite 单文件模式时，将 db.driver 显式设为 sqlite。容器中 localhost 指向容器自身，数据库地址应填写可达的数据库容器名或宿主机地址。

App 无法连接本机 API

Android 模拟器使用 10.0.2.2 访问宿主机；真机需与宿主机网络互通，并在「我的 → API 配置」中填写宿主机局域网 IP 和实际端口。检查宿主机防火墙是否允许该端口。

Flutter 找不到目标设备

运行 flutter doctor 检查工具链，再运行 flutter devices 确认目标设备可用。启动器的 all 包含 Flutter 客户端；只需要浏览器门户与后台时，使用 api admin web。

Bllii · More Stories, Together

快速开始 · 文档导航 · 反馈问题

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bllii-brand-kit		bllii-brand-kit
deploy		deploy
video-collection-app		video-collection-app
video-collection-service		video-collection-service
video-collection-web		video-collection-web
.dockerignore		.dockerignore
.gitignore		.gitignore
README.md		README.md
compose.yaml		compose.yaml
index.html		index.html
run.ps1		run.ps1
run.sh		run.sh

参数	含义
`api` / `admin` / `web`	分别启动 Go API / Vue 后台 / Astro 门户，可组合使用
`app`	启动 Flutter 客户端；默认平台为 Windows → `windows`、macOS → `macos`、Linux → `linux`
`all`	启动 API + Admin + Web + App
`windows` / `android` / `ios` / `macos` / `linux` / `chrome` / `edge` / `web-server`	指定 Flutter 目标平台，同时启用 App；需具备对应工具链与可用设备

Navigation Menu

Repository navigation

About

Repository files navigation

Bllii · video-collection

功能概览

系统架构

仓库结构

快速开始

1. 准备环境

2. 获取项目

3. 启动 API、后台与门户

4. 打开服务

更多启动组合

配置指南

API 与数据库

各端连接地址

文档导航

品牌资产

常见问题

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Bllii · video-collection

功能概览

系统架构

仓库结构

快速开始

1. 准备环境

2. 获取项目

3. 启动 API、后台与门户

4. 打开服务

更多启动组合

配置指南

API 与数据库

各端连接地址

文档导航

品牌资产

常见问题

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages