# Sakura Downloader(樱云下载器)项目方案书 > 版本:v1.0 | 日期:2026-06-18 | 状态:已交付 --- ## 一、项目概述 ### 1.1 项目名称 **Sakura Downloader(樱云下载器)** — 个人媒体采集、本地图库管理与跨设备云同步系统。 ### 1.2 项目定位 一个面向个人用户的**多媒体内容采集-整理-阅读一体化平台**,解决"从多个内容平台采集插画/漫画/小说 → 本地归档整理 → 在手机/桌面等多设备上随时浏览阅读"的完整链路。 ### 1.3 核心价值 | 痛点 | 解决方案 | |------|----------| | 多平台内容分散(Pixiv、X、小红书、AO3、笔趣阁等) | 统一插件架构,一个入口采集所有平台 | | 下载后文件散乱、难以检索 | 本地图库 + SQLite 索引 + 缩略图墙 + 标签/作者搜索 | | 桌面下载了,手机上没法看 | Sakura Cloud 云端同步,手机端实时访问 | | 关注的作者更新了不知道 | 云端每日摘要提醒,手机端查看 | | 跨平台小说阅读体验差 | Flutter 移动端专为阅读优化:自动分页、进度记忆、翻译、字体调节 | --- ## 二、系统架构 ### 2.1 整体拓扑 ```text ┌─────────────────────────────────────────────────────────┐ │ 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 插件架构 ```text 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 采集下载流程 ```text 用户输入(ID/链接/关键词) │ ▼ 任务解析器 (parser.py) │ ▼ 任务队列 (queue.py) │ ▼ 插件调度 → 对应平台 plugin.py │ ▼ HTTP/Playwright 抓取 → 解析作品列表 │ ▼ 下载器 (downloader.py) → 保存到本地图库 │ ▼ SQLite 索引写入 + 缩略图生成 │ ▼ (可选) 云同步上传到 Sakura Cloud ``` ### 5.2 云同步流程 ```text 桌面端下载完成 │ ▼ 检查"启用云同步"开关 │ ▼ cloud_sync.py → POST /api/v1/media/upload │ ▼ Sakura Cloud 存储 + 生成缩略图 │ ▼ 移动端刷新 → GET /api/v1/media → 展示 ``` ### 5.3 每日提醒流程 ```text 桌面端同步关注作者的新作品到云端 │ ▼ 云端写入 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 云端部署 ```bash cd sakura_cloud docker-compose up -d # FastAPI :8000 + PostgreSQL :5432 ``` ### 6.4 构建打包 ```bash # 桌面 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*