BusTerminal

BusTerminal 是一个面向个人 NAS 场景的影音生命周期管理工具。它把影片发现、订阅、下载、Jellyfin 媒体库状态、缓存和清理决策放在同一个控制台里，目标是让“发现影片 -> 自动下载 -> 入库观看 -> 根据观看/收藏行为决定保留或清理”形成闭环。

项目核心思路

BusTerminal 的核心内涵不只是一个 NAS 工具，也是一场用 LLM 工具参与真实开发工作的实践。这个项目仍有很多地方不够完善，代码、交互、部署和业务边界都还在持续打磨中。它更像是一个人借助 Codex 这类工具，从需求、设计、开发、调试、部署到文档，完整走一遍软件开发流程的体验项目。

欢迎大家使用、试跑和改造它。最推荐的方式，是把项目交给 Codex 这类 AI 编程工具，让它根据你的服务器、Docker、Jellyfin、qBittorrent 和目录结构，帮助你完成部署、排错和二次开发；它会在过程中告诉你需要准备什么、修改什么，以及如何验证。

本项目用于个人媒体库自动化管理。请确保你对接入的数据源、下载内容和媒体文件拥有合法使用权，并遵守所在地区法律法规和相关站点条款。

核心能力

• 影片发现与缓存

  • 聚合多个在线来源的影片列表。
  • 抓取结果、元数据、翻译结果和封面图片本地化保存，减少重复请求。
  • 支持缓存空间上限，超限后按最旧数据滚动清理。

• 订阅与自动化

  • 支持演员、分类、关键词等订阅线索。
  • 根据筛选规则自动生成下载任务。
  • 可结合 Jellyfin 收藏和观看记录反向维护关注列表。

• qBittorrent 集成

  • 查看下载任务、状态、速度和磁盘空间。
  • 支持任务批量选择、暂停、继续和分页排序。
  • 支持 JAV 标签任务的小文件过滤，避免广告小文件挤占下载目录。
  • 支持做种时长限制和磁盘空间预警。

• Jellyfin 集成

  • 读取媒体库、影片状态、观看记录、收藏状态和封面。
  • 支持复合筛选，例如筛出“已看但未收藏”的影片。
  • 删除前二次确认，并提示预计释放空间。
  • 删除能力默认应保持受控配置，避免误删真实媒体文件。

• 前端控制台

  • React + Vite 构建。
  • 黑黄主题，适合长期运行的 NAS 控制台。
  • 顶部布局控件可全局调整卡片尺寸，影响影片/演员等卡片展示页。

技术栈

• Backend: Python 3.10, FastAPI, Uvicorn, SQLite/PostgreSQL
• Frontend: React 18, Vite, React Router, Axios, Lucide Icons
• Integrations: qBittorrent Web API, Jellyfin API
• Scraping/Parsing: requests, BeautifulSoup, Scrapling
• Deployment: Docker, Docker Compose

目录结构

backend/                 FastAPI 后端、数据库、爬虫、qB/Jellyfin 集成
frontend/                React 前端控制台
data/                    默认运行数据目录，包含 SQLite、封面缓存等
downloads/               示例下载/入库目录挂载点
docs/                    产品规划、数据库审计、路线图等文档
docker-compose.yml       单容器部署配置
Dockerfile               前后端构建镜像
.env.example             环境变量模板
AGENTS.md                本项目 AI 协作与开发测试规范

快速开始

1. 准备环境

需要安装：

• Docker
• Docker Compose

2. 配置环境变量

复制环境变量模板：

cp .env.example .env

按需修改 .env。常用配置包括：

REQUIRE_AUTH=true
DATABASE_URL=
DATA_DIR=/app/data
DELIVERY_FOLDER=/downloads/staging
EXTRA_DOMAINS=

qBittorrent、Jellyfin、翻译服务等连接信息也可以在应用设置页中配置。不要把真实账号、密码、API Key 提交到 Git 仓库。

3. 启动服务

docker compose up -d --build

默认访问：

• Web 控制台: http://localhost:8000
• 健康检查: http://localhost:8000/api/health/live

Docker 镜像发布

仓库内置 GitHub Actions 工作流：.github/workflows/docker-publish.yml。代码推送到 main/master，或推送 v*.*.* 标签后，会自动构建 Docker 镜像并发布到 GitHub Container Registry。

默认镜像名：

ghcr.io/<github-user>/busterminal:latest

部署时可以直接拉取镜像：

docker pull ghcr.io/<github-user>/busterminal:latest
docker run -d --name bus_terminal \
  -p 8000:8000 \
  -v ./data:/app/data \
  -v ./qb_data:/app/qb_data \
  -v ./downloads:/downloads \
  ghcr.io/<github-user>/busterminal:latest

不要把 .env、data/、downloads/、qb_data/、数据库文件或真实 API Key 提交到 GitHub。仓库提供 .dockerignore 用于避免这些运行数据进入 Docker 构建上下文。

本地开发

本项目默认保留 Docker 作为稳定对照环境，本地开发另起端口：

• Docker 稳定版: http://127.0.0.1:8000
• 本地后端: http://127.0.0.1:8001
• 本地前端: http://127.0.0.1:3000

后端

cd backend
set BUS_TERMINAL_DISABLE_STARTUP_TASKS=true
set BUS_TERMINAL_DISABLE_DOMAIN_ROTATION=true
python -m uvicorn main:app --host 127.0.0.1 --port 8001

PowerShell 示例：

cd backend
$env:BUS_TERMINAL_DISABLE_STARTUP_TASKS="true"
$env:BUS_TERMINAL_DISABLE_DOMAIN_ROTATION="true"
python -m uvicorn main:app --host 127.0.0.1 --port 8001

前端

cd frontend
npm install
npm run dev

Vite 会把 /api 代理到本地后端 http://127.0.0.1:8001。

常用命令

# 前端构建
cd frontend && npm run build

# 后端语法检查
python -m py_compile backend/main.py backend/database.py

# 重新生成女优/影片基础资料库
python backend/build_r18_base_db.py --output data/actress_base.db --reset --include-movies --batch-size 5000

# Docker 构建运行
docker compose up -d --build

# 查看容器日志
docker logs -f bus_terminal

数据与配置

默认情况下，容器内数据目录为 /app/data，通过 docker-compose.yml 映射到宿主机 ./data。

SQLite 默认数据库路径：

data/movies.db

女优/影片基础资料库默认路径：

data/actress_base.db

服务启动时会自动检查并导入 actress_base.db。这个文件用于预置演员、艺名、番号、标题、封面、标签和演员-影片关系，减少首次使用时对来源站点的重复请求。基础库体积较大，不建议提交到 Git 仓库或放进 Docker 镜像构建上下文；部署时把它放进挂载的 data/ 目录后重启服务即可。详细说明见 docs/ActressBaseDatabase.md。

重要数据包括：

• 系统配置
• 订阅记录
• 女优/影片基础资料库
• 抓取缓存
• 翻译缓存
• 封面缓存
• Jellyfin 行为分析结果
• 下载任务生命周期状态

安全注意事项

• 不要提交 .env、真实 API Key、qB/Jellyfin 密码、NAS 内网地址等敏感信息。
• 涉及 Jellyfin 删除、真实下载、qB 写入的操作应先在测试环境确认。
• Jellyfin 删除能力应保持显式开关和二次确认。
• 爬虫和自动下载任务应设置合理频率，避免给来源站点造成压力。
• 本项目默认用于内网或个人 NAS 环境，不建议直接暴露到公网。

开发规范

项目内置开发测试约定见 AGENTS.md。关键原则：

• Docker 稳定环境和本地开发环境分端口运行。
• UI 调试优先使用 3000 + 8001。
• 开发后端默认禁用启动后台任务和域名轮换，避免调试时产生副作用。
• 修改后尽量运行最小验证，例如 npm run build、后端语法检查和健康检查。

路线规划

当前重点方向：

• 完善影片生命周期管理闭环。
• 强化 Jellyfin 观看/收藏行为分析。
• 改进缓存、翻译和封面长期存储策略。
• 优化 qBittorrent 任务治理和磁盘空间策略。
• 统一前端卡片、字号、间距和控制台交互规范。

更多规划文档见：

• docs/ProductUpgradePlan.md
• docs/DatabaseSchemaAudit.md
• docs/JellyfinControlPlaneRoadmap.md
• docs/ResponsibleMaintenancePlan.md

License

目前仓库尚未声明开源许可证。上传 GitHub 前建议补充 LICENSE 文件，并明确项目的使用、分发和二次开发许可。