11 KiB
11 KiB
Sakura Downloader(樱云下载器)项目方案书
版本:v1.0 | 日期:2026-06-18 | 状态:已交付
一、项目概述
1.1 项目名称
Sakura Downloader(樱云下载器) — 个人媒体采集、本地图库管理与跨设备云同步系统。
1.2 项目定位
一个面向个人用户的多媒体内容采集-整理-阅读一体化平台,解决"从多个内容平台采集插画/漫画/小说 → 本地归档整理 → 在手机/桌面等多设备上随时浏览阅读"的完整链路。
1.3 核心价值
| 痛点 | 解决方案 |
|---|---|
| 多平台内容分散(Pixiv、X、小红书、AO3、笔趣阁等) | 统一插件架构,一个入口采集所有平台 |
| 下载后文件散乱、难以检索 | 本地图库 + SQLite 索引 + 缩略图墙 + 标签/作者搜索 |
| 桌面下载了,手机上没法看 | Sakura Cloud 云端同步,手机端实时访问 |
| 关注的作者更新了不知道 | 云端每日摘要提醒,手机端查看 |
| 跨平台小说阅读体验差 | Flutter 移动端专为阅读优化:自动分页、进度记忆、翻译、字体调节 |
二、系统架构
2.1 整体拓扑
┌─────────────────────────────────────────────────────────┐
│ Sakura Cloud (FastAPI) │
│ PostgreSQL + JWT Auth │
│ api.kunkunxiaomao.top:8000 │
└──────┬──────────────────────┬───────────────────────────┘
│ REST API │ REST API
▼ ▼
┌──────────────┐ ┌──────────────────┐
│ Windows 桌面端 │ │ Android 移动端 │
│ Python + │ │ Flutter + │
│ CustomTkinter │ │ Riverpod + Dio │
│ (采集/整理中枢) │ │ (阅读/提醒终端) │
└──────┬─────────┘ └──────────────────┘
│ 本地 SQLite │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ 本地图库文件 │ │ 本地缓存/下载 │
│ (图片/漫画/小说)│ │ (离线阅读) │
└──────────────┘ └──────────────┘
2.2 技术栈总览
| 层级 | 技术选型 |
|---|---|
| Windows 桌面端 | Python 3.8+ · CustomTkinter · SQLite · Playwright · Pillow |
| 云端 API | FastAPI · PostgreSQL · SQLAlchemy · Alembic · JWT · Docker |
| Android 移动端 | Flutter 3.x · Dart · Riverpod · Dio · shared_preferences |
| 管理后台 Web | Vite · TypeScript · Vue/React · Nginx |
| 插件系统 | Python 动态加载 · manifest.json · 统一 PluginBase 接口 |
| 打包分发 | PyInstaller (EXE) · Flutter build (APK) |
三、客户端种类与职责
3.1 Windows 桌面端(pixiv_app/ + main.py)
角色:采集与整理中枢
| 功能模块 | 说明 |
|---|---|
| 多平台采集 | 通过插件系统支持 Pixiv、X (Twitter)、小红书、AO3、笔趣阁等 |
| Cookie/密码登录 | 支持 Cookie 导入(推荐)和账号密码登录 |
| 灵活抓取模式 | 作者全部作品、单作品/漫画、小说/系列、关键词搜索 |
| 本地图库 | SQLite 索引 + 文件系统存储,支持缩略图生成 |
| 缩略图墙 | 本地 Web 服务(127.0.0.1:8765),浏览器中浏览、搜索、筛选、收藏 |
| 关注同步 | Pixiv 关注作者管理 + X 关注同步 |
| 云同步 | 一键上传到 Sakura Cloud,自动同步新下载内容 |
| 代理池 | 浏览器代理池 + HTTP 代理,规避反爬 |
| Playwright 集成 | 无头浏览器渲染 JS 页面(X 插件依赖) |
| 指纹伪装 | 浏览器指纹随机化,降低封禁风险 |
打包产物:sakuradownloader.exe (~68 MB, PyInstaller 单文件)
3.2 Sakura Cloud 云端(sakura_cloud/)
角色:数据与账号中心
| 功能模块 | 说明 |
|---|---|
| 用户系统 | 注册/登录/邮箱验证/JWT Token 鉴权 |
| 媒体存储 | 图片/漫画/小说上传、存储、缩略图生成 |
| 收藏系统 | 跨设备收藏同步 |
| 关注与提醒 | 关注作者管理 + 每日更新摘要提醒 |
| 阅读进度 | 小说阅读进度云端存储,跨设备同步 |
| 管理后台 | SPA 管理控制台(可选) |
| 自动运维 | 启动自动 migrate、定时清理过期上传、每 5 分钟检查提醒摘要 |
部署方式:Docker Compose(FastAPI + PostgreSQL)
3.3 Android 移动端(sakura_mobile/)
角色:跨设备阅读与提醒终端
| 功能模块 | 说明 |
|---|---|
| 发现页 | 最近浏览 + 更新提醒摘要 |
| 图片页 | 缩略图列表 · 详情 · 收藏 · 下载 · 编辑 · 删除 |
| 漫画页 | 按漫画分组浏览,整组连续阅读,整组下载 |
| 书架页 | 三列彩色方块风格,系列小说按书名归档,章节选择 |
| 小说阅读器 | 自动分页 · 阅读进度记忆 · 收藏 · 当前页翻译 · 原文/译文切换 · 字体/行高/背景色调节 · 章节切换 |
| 我的页 | 用户资料 · 云端空间 · 收藏管理 · 每日提醒开关/时间 · 提醒中心 |
| 搜索 | 图片/漫画/小说全局搜索 |
打包产物:app-release.apk (~54 MB, 调试签名)
3.4 管理后台 Web(sakura_admin_web/)
角色:云端管理控制台
- 基于 Vite + TypeScript 的 SPA 单页应用
- 通过 Sakura Cloud 的
/admin路由挂载 - 提供可视化的数据和用户管理界面
- 可选部署(
admin_frontend_enabled配置项)
四、插件体系
4.1 插件架构
plugins/
├── pixiv/ # Pixiv 插画/漫画/小说
│ ├── manifest.json
│ └── plugin.py
├── x/ # X (Twitter) 媒体
│ ├── manifest.json
│ ├── plugin.py
│ ├── playwright_client.py
│ └── x_login.py
├── xiaohongshu/ # 小红书
├── ao3/ # Archive of Our Own
└── biquge/ # 笔趣阁(小说)
4.2 插件接口规范
每个插件只需实现 PluginBase 抽象类,包含:
platform_name— 平台标识supports_modes— 支持的抓取模式列表search()— 搜索fetch_work()— 获取作品详情fetch_author_works()— 获取作者全部作品download()— 下载媒体文件
通过 manifest.json 声明元数据,桌面端启动时自动发现并加载。
五、核心数据流
5.1 采集下载流程
用户输入(ID/链接/关键词)
│
▼
任务解析器 (parser.py)
│
▼
任务队列 (queue.py)
│
▼
插件调度 → 对应平台 plugin.py
│
▼
HTTP/Playwright 抓取 → 解析作品列表
│
▼
下载器 (downloader.py) → 保存到本地图库
│
▼
SQLite 索引写入 + 缩略图生成
│
▼
(可选) 云同步上传到 Sakura Cloud
5.2 云同步流程
桌面端下载完成
│
▼
检查"启用云同步"开关
│
▼
cloud_sync.py → POST /api/v1/media/upload
│
▼
Sakura Cloud 存储 + 生成缩略图
│
▼
移动端刷新 → GET /api/v1/media → 展示
5.3 每日提醒流程
桌面端同步关注作者的新作品到云端
│
▼
云端写入 follow + update_alert 记录
│
▼
reminder_digest_loop (每5分钟检查)
│
▼
到达用户设定的提醒时间 → 生成每日摘要
│
▼
移动端"发现"页展示更新提醒
六、用法概览
6.1 桌面端典型工作流
- 登录 → 导入 Pixiv Cookie(推荐)或账号密码登录
- 抓取 → 选择平台 → 选择模式 → 输入目标 → 开始抓取
- 浏览 → 打开缩略图墙 → 搜索/筛选/收藏
- 关注 → 在缩略图墙中关注作者 → 后续同步关注作者更新
- 云同步 → 登录 Sakura Cloud → 开启云同步 → 自动上传
6.2 移动端典型工作流
- 安装 → 安装 APK → 允许未知来源
- 登录 → 使用与桌面端相同的 Sakura Cloud 账号
- 浏览 → 底部 5 个页签切换(发现/图片/漫画/书架/我的)
- 阅读小说 → 自动分页 · 调节字体 · 翻译 · 章节切换
- 提醒 → 我的 → 每日更新提醒 → 开启并设置时间
6.3 云端部署
cd sakura_cloud
docker-compose up -d
# FastAPI :8000 + PostgreSQL :5432
6.4 构建打包
# 桌面 EXE
scripts\build_desktop_exe.bat
# Android APK
scripts\build_mobile_android.bat
# 复制到 releases/
scripts\copy_release_artifacts.bat
七、项目交付物
| 交付物 | 路径 | 说明 |
|---|---|---|
| Windows EXE | releases/sakuradownloader.exe |
双击即用,~68 MB |
| Android APK | releases/app-release.apk |
调试签名,~54 MB |
| 用户使用说明 | 使用说明-桌面版与安卓版.md |
终端用户操作手册 |
| 项目方案书 | docs/项目方案书.md |
本文档 |
| 开发文档 | 项目文件/BUILD.md |
构建与排错 |
| 构建脚本 | scripts/ |
一键打包脚本 |
| 云端 API | sakura_cloud/ |
Docker 部署 |
| 源码 | 全部 Python/Dart/TypeScript | 可二次开发 |
八、技术亮点
- 插件化架构 — 新平台接入只需新增一个插件目录,不改动核心代码
- 多反爬策略 — Cookie 管理 · Playwright 无头浏览器 · 代理池 · 指纹伪装 · 限速退避
- 跨设备云同步 — 桌面采集 → 云端存储 → 手机阅读,全链路打通
- 沉浸式阅读体验 — 自动分页 · 进度记忆 · 即时翻译 · 个性化排版
- 智能提醒 — 关注作者更新云端汇总,非本地闹钟,静默不打扰
- 本地优先 — 所有数据本地 SQLite 存储,云端为可选项,离线也能用
九、后续演进方向
| 方向 | 说明 |
|---|---|
| iOS 客户端 | Flutter 已预留 iOS 平台支持,补充苹果开发者账号与签名 |
| 正式应用签名 | APK 替换调试签名为正式 keystore,支持上架分发 |
| 更多平台插件 | 持续扩充插件库(如 Fantia、Fanbox、DeviantArt 等) |
| AI 能力增强 | OCR 文字识别(代码已预留)· AI 翻译优化 · 智能标签 |
| 分布式爬取 | distributed_crawler/ 目录已有 Master-Worker 架构原型 |
| PWA 移动端 | 缩略图墙升级为 PWA,支持手机浏览器直接访问 |
十、许可与免责
- 本项目仅供个人学习、研究及合法使用。
- 使用 X 插件需自行承担对应平台的使用条款风险。
- APK 当前为调试签名,仅供个人测试,不宜正式分发。
- 请遵守各内容平台的用户协议,合理使用爬取功能。
文档生成于 2026-06-18 · Sakura Downloader Project