Files
SakuraHub/docs/项目方案书.md
T
2026-11-16 20:45:22 +08:00

11 KiB
Raw Blame History

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 桌面端典型工作流

  1. 登录 → 导入 Pixiv Cookie(推荐)或账号密码登录
  2. 抓取 → 选择平台 → 选择模式 → 输入目标 → 开始抓取
  3. 浏览 → 打开缩略图墙 → 搜索/筛选/收藏
  4. 关注 → 在缩略图墙中关注作者 → 后续同步关注作者更新
  5. 云同步 → 登录 Sakura Cloud → 开启云同步 → 自动上传

6.2 移动端典型工作流

  1. 安装 → 安装 APK → 允许未知来源
  2. 登录 → 使用与桌面端相同的 Sakura Cloud 账号
  3. 浏览 → 底部 5 个页签切换(发现/图片/漫画/书架/我的)
  4. 阅读小说 → 自动分页 · 调节字体 · 翻译 · 章节切换
  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 可二次开发

八、技术亮点

  1. 插件化架构 — 新平台接入只需新增一个插件目录,不改动核心代码
  2. 多反爬策略 — Cookie 管理 · Playwright 无头浏览器 · 代理池 · 指纹伪装 · 限速退避
  3. 跨设备云同步 — 桌面采集 → 云端存储 → 手机阅读,全链路打通
  4. 沉浸式阅读体验 — 自动分页 · 进度记忆 · 即时翻译 · 个性化排版
  5. 智能提醒 — 关注作者更新云端汇总,非本地闹钟,静默不打扰
  6. 本地优先 — 所有数据本地 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