🎬 IKuYo 动漫资源管理系统

面向追番爱好者的智能动漫资源采集与管理工具

📖 项目简介

IKuYo 是一个现代化的全栈动漫资源管理系统，集成了智能爬虫、数据聚合、RESTful API和美观的Web界面。系统自动化采集 Mikan Project 站点的番剧资源信息，结合 Bangumi API 提供丰富的番剧元数据，为追番爱好者提供一站式的番剧浏览和资源管理体验。

✨ 核心特性

🎯 智能后端

🚀 多模式采集：支持首页、按年、按季、全量、增量等多种采集策略
⏰ 定时调度：内置 APScheduler 定时任务，自动化追番更新
🎯 精准解析：智能识别番剧信息、字幕组、资源链接等关键数据
💾 本地存储：SQLite 数据库持久化，支持数据导出和分析
🚀 RESTful API：FastAPI驱动的高性能查询接口，支持分页、搜索、过滤
📺 Bangumi集成：自动获取番剧评分、简介、标签等丰富元信息

🎨 现代前端

⚡ Vue 3界面：基于 Composition API 构建的现代化响应式界面
📱 响应式设计：适配桌面、平板、移动端各种屏幕尺寸
🎪 直观浏览：每日放送展示、番剧详情页、智能排序和搜索
🏷️ 丰富信息：评分分布、标签系统、集数状态可视化
🎭 美观UI：卡片式布局，现代化设计风格，暗色主题友好

🔧 技术先进

🧩 模块化架构：爬虫、API、前端分离设计，便于维护和扩展
📦 一体化部署：单仓库管理，简化开发和部署流程
🚀 性能优化：前后端缓存、API响应优化、图片懒加载
🔮 跨平台就绪：为后续桌面端(Tauri)和移动端(Capacitor)APP奠定基础

🚀 快速开始

📋 环境要求

后端

🐍 Python 3.12 及以上版本
📦 uv 包管理器（推荐）

前端

📦 Node.js 18 及以上版本
🧶 npm 或其他包管理器

📥 一键启动

# 1. 克隆项目
git clone https://github.com/Niloux/IKuYo.git
cd IKuYo

# 2. 安装后端依赖
uv sync

# 3. 安装前端依赖
cd frontend
npm install
cd ..

# 4. 启动后端API (新终端)
uv run python scripts/run_api.py --reload --debug

# 5. 启动前端开发服务器 (新终端)
cd frontend
npm run dev

# 6. 访问应用
# 前端: http://localhost:5173
# API文档: http://localhost:8000/docs

🎮 爬虫使用

模式	命令	说明
🏠 首页模式	`uv run python scripts/run_crawler.py`	采集首页推荐番剧
📅 按年模式	`uv run python scripts/run_crawler.py --mode year --year 2024`	采集2024年所有番剧
🍃 按季模式	`uv run python scripts/run_crawler.py --mode season --year 2024 --season 春`	采集2024年春季番剧
🌐 全量模式	`uv run python scripts/run_crawler.py --mode full`	采集所有年份番剧
🔄 增量模式	`uv run python scripts/run_crawler.py --mode incremental`	仅采集新增/更新番剧

🏗️ 技术架构

📊 整体架构图

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端界面       │    │    后端API     │    │   数据采集      │
│                │    │                │    │                │
│  Vue 3         │◄──►│  FastAPI       │◄──►│  Scrapy        │
│  TypeScript    │    │  SQLite        │    │  APScheduler   │
│  Responsive    │    │  Bangumi API   │    │  智能解析      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
  用户友好界面           高性能API服务        自动化数据采集

🛠️ 技术栈详情

后端 (Python)

核心框架: FastAPI - 高性能异步API框架
数据存储: SQLite - 轻量级关系数据库
爬虫引擎: Scrapy - 专业网页爬虫框架
任务调度: APScheduler - 定时任务管理
外部API: Bangumi API - 番剧元数据集成
缓存机制: 内置缓存 - 提升API响应性能

前端 (TypeScript)

核心框架: Vue 3 (Composition API) - 现代响应式框架
类型系统: TypeScript - 静态类型检查
构建工具: Vite - 极速开发构建
路由管理: Vue Router 4 - 客户端路由
HTTP客户端: Axios - API通信
UI设计: 原生CSS + 响应式布局

开发工具

包管理: uv (Python) + npm (Node.js)
代码检查: ESLint + Prettier
版本控制: Git
API文档: FastAPI自动生成 (Swagger UI)

📁 项目结构

IKuYo/
├── 📄 config.yaml              # 主配置文件
├── 📄 pyproject.toml           # Python依赖管理
├── 🖼️ assets/                  # 静态资源
├── 📁 ikuyo/                   # Python后端代码
│   ├── api/                   # FastAPI接口层
│   │   ├── main.py           # API应用入口
│   │   ├── routes/           # 路由模块
│   │   └── models/           # 数据模型
│   ├── core/                  # 核心业务逻辑
│   │   ├── bangumi_service.py # Bangumi API服务
│   │   ├── cache_service.py   # 缓存服务
│   │   ├── database.py        # 数据库抽象层
│   │   └── scheduler.py       # 任务调度器
│   ├── crawler/               # Scrapy爬虫模块
│   │   ├── spiders/           # 爬虫实现
│   │   ├── items.py           # 数据结构定义
│   │   └── pipelines.py       # 数据处理管道
│   └── utils/                 # 工具函数
├── 📁 frontend/                # Vue前端应用
│   ├── src/
│   │   ├── views/             # 页面组件
│   │   │   ├── HomeView.vue   # 首页 - 每日放送
│   │   │   └── AnimeDetailView.vue # 详情页
│   │   ├── components/        # 通用组件
│   │   │   ├── AnimeCard.vue  # 番剧卡片
│   │   │   ├── EpisodeDisplay.vue # 集数展示
│   │   │   └── EpisodeCarousel.vue # 集数轮播
│   │   ├── services/          # API服务层
│   │   │   └── api.ts         # API封装
│   │   └── router/            # 路由配置
│   ├── package.json           # 前端依赖
│   └── vite.config.ts         # 构建配置
├── 📁 scripts/                 # 管理脚本
│   ├── run_crawler.py         # 爬虫启动脚本
│   ├── run_api.py            # API启动脚本
│   └── manage_scheduler.py    # 调度管理脚本
├── 📁 data/                   # 数据存储
│   ├── database/              # SQLite数据库
│   ├── logs/                  # 运行日志
│   └── output/                # 导出数据
└── 📁 docs/                   # 技术文档
    ├── CRAWL_MODES_USAGE.md
    └── SCHEDULER_USAGE.md

⚙️ 配置说明

后端配置 (`config.yaml`)

database:
  path: data/database/ikuyo.db    # 📁 数据库文件路径

site:
  base_url: https://mikanani.me   # 🌐 目标站点地址

crawler:
  download_delay: 0.1             # ⏱️ 爬取延迟（秒）
  concurrent_requests: 32         # 🔄 并发请求数

scheduler:
  enabled: true                   # 📅 启用定时任务
  jobs:                          # 📋 任务列表
    - cron: "0 2 * * *"          # 🕐 每天凌晨2点执行

bangumi:
  base_url: https://api.bgm.tv    # 🎭 Bangumi API地址
  cache_ttl: 3600                # 🕐 缓存过期时间（秒）

前端配置 (`frontend/vite.config.ts`)

export default defineConfig({
  plugins: [vue()],
  server: {
    port: 5173,
    proxy: {
      '/api': 'http://127.0.0.1:8000'  # API代理
    }
  }
})

🎯 核心功能

🖥️ Web界面功能

📺 首页 - 每日放送

📅 按星期分组显示当日播出的番剧
🔥 智能排序：今天的节目优先显示
🎨 响应式卡片布局，适配各种屏幕
⭐ 实时评分显示，一目了然

📖 番剧详情页

🖼️ 高清封面与完整番剧信息展示
📊 Bangumi评分分布可视化图表
🏷️ 智能标签分类（题材、制作、来源等）
📺 集数可用性状态展示
🔙 便捷的返回导航

🎪 交互体验

⚡ 快速加载与错误重试机制
📱 触摸友好的移动端适配
🌙 现代化UI设计，支持暗色主题
🔍 智能搜索与过滤功能

🤖 数据采集功能

模式	适用场景	数据量	推荐频率
🏠 首页模式	关注热门新番	少量	每日
📅 按年模式	补全年度番剧	中等	按需
🍃 按季模式	季度新番追踪	中等	每季
🌐 全量模式	构建完整数据库	大量	初次/定期
🔄 增量模式	日常更新维护	少量	每日

⏰ 定时任务管理

# 📊 查看任务状态
uv run python scripts/manage_scheduler.py status

# 🚀 启动定时调度
uv run python scripts/manage_scheduler.py start

# 🧪 测试任务执行
uv run python scripts/manage_scheduler.py test

💾 数据存储

所有采集数据和运行日志保存在 data/ 目录：

📁 data/database/ - SQLite 数据库文件
📁 data/logs/ - 详细运行日志
📁 data/output/ - 数据导出文件

🌟 项目亮点

🎨 用户体验

现代化设计: 借鉴 MyAnimeList、AniList 等知名站点的设计理念
响应式布局: 完美适配桌面、平板、手机等各种设备
智能交互: 悬停效果、加载状态、错误处理等细节优化
直观信息: 评分、标签、集数状态等一目了然

🏗️ 技术架构

全栈TypeScript: 前后端类型安全，减少运行时错误
API优先设计: RESTful接口设计，便于第三方集成
模块化开发: 松耦合架构，便于维护和功能扩展
缓存优化: 多层缓存机制，显著提升响应速度

🚀 扩展性

跨平台就绪: 为桌面端APP(Tauri)和移动端APP(Capacitor)奠定基础
API丰富: 完整的数据查询接口，支持第三方应用集成
配置驱动: 灵活的配置系统，适应不同使用场景
文档完善: 详细的API文档和使用说明

🎯 API使用指南

基础信息

API地址：http://localhost:8000
API文档：http://localhost:8000/docs (Swagger UI)
健康检查：http://localhost:8000/api/v1/health/

主要接口

1. 健康检查 & 统计

# 基础健康检查
GET /api/v1/health/

# 系统统计信息
GET /api/v1/health/stats

2. Bangumi相关

# 获取每日放送
GET /api/v1/bangumi/calendar

# 获取番剧详情
GET /api/v1/bangumi/subjects/{bangumi_id}

# 获取番剧章节信息
GET /api/v1/bangumi/subjects/{bangumi_id}/episodes

3. 动画资源

# 获取动画列表（支持分页、搜索）
GET /api/v1/animes/?page=1&per_page=20&q=关键词

# 获取动画详情
GET /api/v1/animes/{mikan_id}

# 获取动画资源
GET /api/v1/animes/{mikan_id}/resources

# 按Bangumi ID查询集数可用性
GET /api/v1/animes/bangumi/{bangumi_id}/episodes/availability

4. 资源管理

# 获取资源列表（支持过滤）
GET /api/v1/resources/?page=1&per_page=20&anime_id=123&resolution=1080p

# 获取最新资源
GET /api/v1/resources/latest/{count}

# 按分辨率搜索
GET /api/v1/resources/search/resolution/{resolution}

API响应格式

所有API响应都遵循统一格式：

{
  "success": true,
  "message": "操作成功",
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "pages": 5
  }
}

❓ 常见问题

🔧 依赖安装失败

确认 Python 版本 >= 3.12
确认已正确安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh
尝试清理缓存后重新安装：uv cache clean && uv sync

🌐 网络连接超时

确认本地网络可访问目标站点
检查代理设置或防火墙配置
适当增加 config.yaml 中的 download_delay 值

📚 更多问题

请查阅 docs/ 目录下的详细文档，或通过 GitHub Issues 反馈。

🛣️ 开发路线图

✅ 已完成的里程碑

Phase 1: 基础架构 ✅

✅ 数据库架构设计 - SQLite数据库，支持番剧、资源、集数信息
✅ 爬虫系统 - Scrapy框架，多模式采集策略
✅ 定时调度 - APScheduler集成，自动化数据更新
✅ 配置系统 - YAML配置文件，灵活参数管理

Phase 2: API服务层 ✅

✅ FastAPI框架 - 高性能异步API服务
✅ RESTful接口 - 完整的CRUD操作，支持分页、搜索、过滤
✅ Bangumi API集成 - 丰富的番剧元数据聚合
✅ 缓存优化 - 多层缓存机制，显著提升响应速度
✅ API文档 - 自动生成的Swagger UI文档

Phase 3: 前端界面 ✅

✅ Vue 3 + TypeScript - 现代化前端技术栈
✅ 响应式设计 - 适配各种设备的界面布局
✅ 核心页面 - 每日放送首页、番剧详情页
✅ 组件库 - 可复用的番剧卡片、集数展示等组件
✅ API集成 - 前后端完整打通，数据实时展示

🎯 下一阶段计划

Phase 4: 用户功能 (进行中)

📺 个人追番列表 - 用户可以标记正在追看的番剧
🔔 更新提醒 - 自动检测新集数并推送通知
⭐ 评分收藏 - 个人评分和收藏管理系统
📊 观看统计 - 追番进度和统计图表

Phase 5: 高级功能 (计划中)

🐧 RSS订阅 - 订阅特定番剧或字幕组的资源更新
⬇️ 下载集成 - 集成aria2/qBittorrent等下载器
🤖 智能推荐 - 基于观看历史的番剧推荐算法
📱 PWA支持 - 离线缓存和移动端APP体验

Phase 6: 跨平台扩展 (远期)

🖥️ 桌面应用 - 基于Tauri的原生桌面客户端
📱 移动应用 - 基于Capacitor的移动端APP
🔗 第三方集成 - 支持Jellyfin、Emby等媒体服务器
🌐 多用户支持 - 用户系统和权限管理

📈 技术演进方向

graph LR
    A[Web版本] --> B[桌面端]
    A --> C[移动端]
    B --> D[跨平台生态]
    C --> D
    D --> E[媒体中心集成]

代码复用率预期:

Web → 桌面端: 95% (仅添加系统集成功能)
Web → 移动端: 80% (UI适配和移动端优化)
整体维护成本: 显著降低

🎯 项目优势

技术选型先进: Vue 3 + FastAPI + SQLite，现代化全栈架构
开发效率高: 一套代码，多平台部署
维护成本低: 模块化设计，职责分离清晰
扩展性强: 为未来功能预留良好架构空间

💡 参与贡献: 欢迎通过GitHub Issues提出功能建议或报告问题！

🙏 鸣谢

感谢以下开源项目和资源：

🛠️ 核心技术栈

后端框架

FastAPI - 现代高性能Python Web框架
Scrapy - 强大的网页爬虫框架
APScheduler - Python 定时任务调度库
SQLite - 轻量级数据库引擎

前端框架

Vue 3 - 渐进式JavaScript框架
TypeScript - JavaScript的超集，提供静态类型
Vite - 极速前端构建工具
Axios - Promise化的HTTP客户端

开发工具

uv - 快速的 Python 包管理工具
ESLint - JavaScript/TypeScript代码检查工具
Prettier - 代码格式化工具

🎨 数据来源与灵感

Mikan Project - 动漫资源数据采集来源
Bangumi - 番剧元数据和评分信息
《孤独摇滚》 - 感谢归去来兮女士的命名灵感
MyAnimeList & AniList - UI设计参考

📞 联系方式

🐛 遇到问题？ 欢迎通过 GitHub Issues 反馈

💡 有好想法？ 随时提交 Pull Request

📧 其他交流 请在 Issue 区留言，作者会及时回复

Made with ❤️ by @归去来兮

Name		Name	Last commit message	Last commit date
Latest commit History 137 Commits
assets		assets
docs		docs
frontend		frontend
ikuyo		ikuyo
scripts		scripts
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
README.md		README.md
config.yaml		config.yaml
pyproject.toml		pyproject.toml
scrapy.cfg		scrapy.cfg
uv.lock		uv.lock

Niloux/IKuYo

Folders and files

Latest commit

History

Repository files navigation

🎬 IKuYo 动漫资源管理系统

📖 项目简介

✨ 核心特性

🎯 智能后端

🎨 现代前端

🔧 技术先进

🚀 快速开始

📋 环境要求

后端

前端

📥 一键启动

🎮 爬虫使用

🏗️ 技术架构

📊 整体架构图

🛠️ 技术栈详情

后端 (Python)

前端 (TypeScript)

开发工具

📁 项目结构

⚙️ 配置说明

后端配置 (config.yaml)

前端配置 (frontend/vite.config.ts)

🎯 核心功能

🖥️ Web界面功能

📺 首页 - 每日放送

📖 番剧详情页

🎪 交互体验

🤖 数据采集功能

⏰ 定时任务管理

💾 数据存储

🌟 项目亮点

🎨 用户体验

🏗️ 技术架构

🚀 扩展性

🎯 API使用指南

基础信息

主要接口

1. 健康检查 & 统计

2. Bangumi相关

3. 动画资源

4. 资源管理

API响应格式

❓ 常见问题

🛣️ 开发路线图

✅ 已完成的里程碑

Phase 1: 基础架构 ✅

Phase 2: API服务层 ✅

Phase 3: 前端界面 ✅

🎯 下一阶段计划

Phase 4: 用户功能 (进行中)

Phase 5: 高级功能 (计划中)

Phase 6: 跨平台扩展 (远期)

📈 技术演进方向

🎯 项目优势

🙏 鸣谢

🛠️ 核心技术栈

后端框架

前端框架

开发工具

🎨 数据来源与灵感

📞 联系方式

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

后端配置 (`config.yaml`)

前端配置 (`frontend/vite.config.ts`)

Packages