43 KiB
Sakura Downloader(樱云下载器)产品文档
版本:2.0.0 | 更新日期:2026-06-23 作者:kunkunxiaomao | 博客:http://blog.kunkunxiaomao.top
目录
- 产品介绍
- 系统架构总览
- 桌面端功能详解
- Sakura Cloud 云端平台
- Android 移动端功能详解
- 插件系统
- 本地图库与缩略图墙
- 云同步机制
- 每日提醒功能
- 代理与性能设置
- 安装与运行
- 打包与发布
- 完整使用指南
- 常见问题与排错
- 安全与风险控制
- 开发指南
- 更新日志
1. 产品介绍
1.1 产品概述
Sakura Downloader(樱云下载器) 是一套面向个人的多平台媒体采集、本地图库管理与跨设备云同步系统。它由三个核心端组成,提供从内容发现、采集下载、本地整理到跨设备阅读的完整工作流。
1.2 产品定位
| 端 | 角色 | 运行环境 | 技术栈 |
|---|---|---|---|
| Windows 桌面端 | 采集与整理中枢 | Windows 7+ (x64) | Python 3.8+ / CustomTkinter / SQLite / Playwright |
| Sakura Cloud | 数据与账号中心 | Linux 服务器 | FastAPI / PostgreSQL / JWT / Redis |
| Android 客户端 | 跨设备阅读与提醒 | Android 8.0+ | Flutter / Riverpod / Dio |
一句话总结:
- 桌面端 = 采集和整理中枢
- 云端 = 数据和账号中心
- 安卓端 = 个人阅读器
1.3 核心能力一览
| 能力 | 说明 |
|---|---|
| 🎨 多平台采集 | 支持 Pixiv、X(Twitter)、小红书、笔趣阁小说、长佩文学、AO3 等平台的图片、漫画、小说、视频下载 |
| 📚 本地图库管理 | SQLite 数据库管理作品元数据、作者、标签、收藏、关注作者 |
| 🖼️ 缩略图墙 | 本地 WebUI,浏览器端浏览图库、搜索标签、筛选作者、查看收藏 |
| ☁️ 云同步 | 下载内容自动上传至 Sakura Cloud,手机端实时访问 |
| 📱 跨设备阅读 | Android 端浏览图片、漫画、小说,支持阅读进度记录 |
| 🔌 插件系统 | 开放 Python 插件接口,支持自定义站点扩展 |
| 🔔 每日提醒 | 云端汇总关注作者更新,手机端「发现」页查看 |
| 🔍 OCR 文字识别 | 基于 PaddleOCR 的本地图片文字提取 |
| 🌐 代理池 | 支持手动代理列表、Quake 网络空间搜索引擎获取代理 |
| 📡 分布式爬虫 | 基于 Redis + aiohttp 的 Master-Worker 分布式架构(可选) |
1.4 支持的平台与模式
Pixiv
| 模式 | 说明 |
|---|---|
| 作者全部作品 | 输入作者 ID 或作品链接反查作者并批量下载 |
| 单个作品 | 下载指定作品(含多页)的原图 |
| 漫画 | 完整下载漫画作品的所有页面 |
| 文章/小说 | 下载小说内容并保存为 TXT 文件 |
| 关键词搜索 | 按关键词搜索作品并批量下载 |
X(Twitter)
| 模式 | 说明 |
|---|---|
| 作者媒体 | 输入用户名,抓取 /media 页的图片和视频 |
| 单个推文 | 解析单条推文中的媒体文件 |
| 搜索词媒体 | 搜索并抓取媒体内容 |
小红书
| 模式 | 说明 |
|---|---|
| 搜索关键词 | 搜索笔记并下载图片 |
| 单篇笔记 | 解析单篇笔记的图片 |
| 链接解析 | 支持 xiaohongshu.com 和 xhslink.com 分享链接 |
小说平台
| 平台 | 说明 |
|---|---|
| 笔趣阁小说 | 书名/作者/链接搜索,支持榜单页和列表页解析 |
| 长佩文学 | 书名/作者/ID/链接搜索,全章批量下载 |
插件自动识别
输入链接、ID 或关键词,程序自动匹配已导入插件处理。
2. 系统架构总览
2.1 整体架构图
┌──────────────────────────────────────────────────────────┐
│ Sakura Downloader 系统 │
├───────────────────────┬──────────────────────────────────┤
│ Windows 桌面端 │ Sakura Cloud 云端 │
│ ┌─────────────────┐ │ ┌────────────────────────────┐ │
│ │ CustomTkinter │ │ │ FastAPI REST API │ │
│ │ GUI 界面 │ │ │ /api/v1/auth/* │ │
│ ├─────────────────┤ │ │ /api/v1/gallery/* │ │
│ │ 插件管理器 │ │ │ /api/v1/upload/* │ │
│ │ (PluginManager) │ │ │ /api/v1/novels/* │ │
│ ├─────────────────┤ │ │ /api/v1/follows/* │ │
│ │ 下载引擎 │ │ │ /api/v1/sync/* │ │
│ │ (Downloader) │ │ │ /api/v1/push/* │ │
│ ├─────────────────┤ │ ├────────────────────────────┤ │
│ │ 本地图库 (SQLite) │ │ │ PostgreSQL 数据库 │ │
│ ├─────────────────┤ │ │ ├── users │ │
│ │ 云同步客户端 │──┼──│ ├── artworks │ │
│ │ (CloudSync) │ │ │ ├── novels │ │
│ ├─────────────────┤ │ │ ├── files │ │
│ │ 缩略图墙 WebUI │ │ │ ├── follows │ │
│ │ (GalleryAPI) │ │ │ ├── reminders │ │
│ ├─────────────────┤ │ │ └── push_devices │ │
│ │ 代理池 │ │ └────────────────────────────┘ │
│ │ (ProxyPool) │ │ │
│ └─────────────────┘ │ │
├───────────────────────┼────────────────────────────────────┤
│ Android 移动端 │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Flutter App │ │
│ │ ├── 发现页 (Feed) ├── 书架页 (书架) │ │
│ │ ├── 图片页 (Gallery) ├── 漫画页 (漫画) │ │
│ │ ├── 我的页 (Profile) ├── 提醒中心 │ │
│ │ └── 小说阅读器 (Reader) │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
2.2 目录结构
Pixiv/
├── main.py # 桌面端入口
├── requirements.txt # Python 依赖
├── pixiv_app/ # 桌面端核心模块
│ ├── gui/
│ │ ├── app.py # 主 GUI 窗口 (SakuraDownloaderGUI)
│ │ ├── plugin_panel.py # 插件管理面板
│ │ └── proxy_dialog.py # 代理设置对话框
│ ├── core/
│ │ ├── auth.py # Pixiv 认证 (Cookie/密码登录)
│ │ ├── downloader.py # 下载引擎核心
│ │ ├── library.py # 本地 SQLite 图库
│ │ ├── cloud_sync.py # 云同步客户端
│ │ ├── gallery_service.py # 缩略图墙 Web 服务
│ │ ├── orchestrator.py # 任务编排器
│ │ ├── proxy_pool.py # 代理池管理
│ │ ├── ocr.py # OCR 文字识别
│ │ ├── fingerprint.py # 浏览器指纹模拟
│ │ ├── cookie_import.py # Cookie 导入与解析
│ │ ├── x_media_service.py # X 媒体同步服务
│ │ ├── origin_follow_sync.py # 原始关注同步
│ │ ├── paths.py # 路径管理
│ │ └── plugin/ # 插件基础设施
│ │ ├── base.py # 插件基类 (BasePlugin)
│ │ ├── manager.py # 插件管理器
│ │ ├── generator.py # 插件模板生成器
│ │ └── market.py # 插件市场
│ ├── runtime/ # 任务运行时
│ │ ├── executor.py # 任务执行器
│ │ ├── worker_loop.py # 工作循环
│ │ └── enqueue.py # 任务队列
│ ├── services/ # 服务层
│ │ ├── gallery_api.py # 图库 API 服务
│ │ ├── run_gallery_api.py # 图库服务启动器
│ │ ├── x_login_flow.py # X 登录流程
│ │ └── x_auth_manager.py # X 认证管理
│ └── tasks/ # 任务系统
│ ├── models.py # 任务模型
│ ├── parser.py # 批量解析器
│ ├── queue.py # 任务队列
│ └── watermark.py # 水印/增量同步
├── plugins/ # 内置站点插件
│ ├── pixiv/plugin.py # Pixiv 插件
│ ├── x/ # X (Twitter) 插件
│ │ ├── plugin.py # X 主插件
│ │ ├── playwright_client.py # Playwright 客户端
│ │ ├── x_urls.py # URL 解析
│ │ ├── x_login.py # X 登录
│ │ ├── selectors.py # 页面选择器
│ │ ├── browser_opts.py # 浏览器选项
│ │ └── setup_plugin.py # 安装脚本
│ ├── xiaohongshu/plugin.py # 小红书插件
│ ├── ao3/plugin.py # AO3 插件
│ ├── biquge/plugin.py # 笔趣阁插件
│ └── changpei/plugin.py # 长佩文学插件
├── sakura_cloud/ # 云端 API
│ ├── main.py # FastAPI 入口
│ ├── api/
│ │ ├── deps.py # 依赖注入 (JWT 验证)
│ │ ├── middleware.py # 中间件
│ │ └── v1/
│ │ ├── router.py # 路由注册
│ │ └── endpoints/ # API 端点
│ │ ├── auth.py # 认证 (登录/注册/刷新Token)
│ │ ├── gallery.py # 图库查询
│ │ ├── upload.py # 文件上传
│ │ ├── novels.py # 小说管理
│ │ ├── follows.py # 关注管理
│ │ ├── sync.py # 数据同步
│ │ ├── push.py # 推送服务
│ │ ├── users.py # 用户管理
│ │ ├── me.py # 当前用户信息
│ │ ├── admin.py # 管理后台
│ │ └── health.py # 健康检查
│ ├── models/ # SQLAlchemy 模型
│ │ ├── user.py # 用户模型
│ │ ├── artwork.py # 作品模型
│ │ ├── novel.py # 小说模型
│ │ ├── file.py # 文件模型
│ │ ├── follow.py # 关注模型
│ │ ├── push.py # 推送模型
│ │ ├── ocr.py # OCR 模型
│ │ ├── admin.py # 管理模型
│ │ └── feed_cache.py # Feed 缓存
│ ├── schemas/ # Pydantic 数据模型
│ ├── services/ # 业务服务层
│ │ ├── storage.py # 存储服务
│ │ ├── reminders.py # 提醒服务
│ │ ├── push.py # 推送服务
│ │ ├── ocr.py # OCR 服务
│ │ ├── audit.py # 审计服务
│ │ └── thumbnails.py # 缩略图服务
│ ├── core/
│ │ ├── config.py # 配置管理
│ │ ├── security.py # 安全模块 (JWT/密码哈希)
│ │ ├── safety.py # 内容安全
│ │ └── logging.py # 日志配置
│ ├── db/ # 数据库连接
│ ├── migrations/ # Alembic 数据库迁移
│ ├── scripts/ # 运维脚本
│ └── docker-compose.yml # Docker 部署配置
├── sakura_mobile/ # Flutter 安卓端
│ └── lib/
│ └── src/
│ ├── app.dart # 应用入口
│ ├── main.dart # 主函数
│ ├── pages/ # 页面
│ │ ├── login_page.dart # 登录页
│ │ ├── home_page.dart # 主页
│ │ ├── explore_page.dart # 探索页
│ │ ├── novel_detail_page.dart # 小说详情
│ │ ├── novel_reader_page.dart # 本地小说阅读器
│ │ ├── online_novel_reader_page.dart # 在线小说阅读器
│ │ ├── online_manga_reader_page.dart # 在线漫画阅读器
│ │ ├── artwork_detail_page.dart # 插画详情
│ │ ├── favorites_page.dart # 收藏页
│ │ ├── reminder_center_page.dart # 提醒中心
│ │ ├── source_manager_page.dart # 书源管理
│ │ └── tabs/ # 底部标签页
│ │ ├── feed_tab.dart # 发现
│ │ ├── gallery_tab.dart # 图片
│ │ ├── novels_tab.dart # 书架
│ │ └── profile_tab.dart # 我的
│ ├── core/ # 核心逻辑
│ │ ├── api_client.dart # API 客户端
│ │ ├── session.dart # 会话管理
│ │ ├── providers.dart # Riverpod 状态
│ │ ├── online_shelf.dart # 在线书架
│ │ ├── online_cache.dart # 在线缓存
│ │ ├── online_reading_history.dart # 阅读历史
│ │ ├── manga_collections.dart # 漫画分组
│ │ ├── push_notifications.dart # 推送通知
│ │ ├── source_manager.dart # 书源管理器
│ │ ├── legado_engine.dart # Legado 规则引擎
│ │ ├── legado_rule_executor.dart # 规则执行器
│ │ ├── legado_rule_parser.dart # 规则解析器
│ │ ├── legado_models.dart # 规则数据模型
│ │ ├── unified_search.dart # 统一搜索
│ │ └── search_scheduler.dart # 搜索调度
│ ├── models/ # 数据模型
│ └── widgets/ # UI 组件
├── distributed_crawler/ # 分布式爬虫 (可选)
├── docs/ # 项目文档
├── scripts/ # 构建与运维脚本
│ ├── build_desktop_exe.bat # 打包桌面 EXE
│ ├── build_mobile_android.bat # 打包 Android APK
│ ├── copy_release_artifacts.bat # 复制成品
│ └── build_all.bat # 一键构建
├── releases/ # 可分发成品
│ ├── sakuradownloader.exe # Windows 桌面端 (~68 MB)
│ └── app-release.apk # Android 客户端 (~54 MB)
└── tools/ # 辅助工具
3. 桌面端功能详解
3.1 GUI 界面总览
桌面端采用 CustomTkinter 构建,主窗口 "Sakura 下载器" 尺寸 1160×860,薄荷蓝配色,分为以下功能区域:
- 登录方式卡片:管理 Pixiv 认证状态
- 抓取目标卡片:选择平台、模式和目标输入
- 性能设置卡片:线程、延迟、代理配置
- 云同步卡片:云端账号管理与同步开关
- 使用说明卡片:操作提示
- 任务概览卡片:统计数据和缩略图墙入口
- 实时进度卡片:进度条和阶段文本
- 抓取日志区域:实时日志输出
- 底部操作栏:开始/停止按钮
3.2 登录认证
Cookie 登录(推荐)
支持导入 Get cookies.txt 等浏览器插件导出的 Cookie 文件:
- 浏览器登录 Pixiv → 用插件导出 txt 或 json 文件
- 桌面端点击 「导入 cookies.txt / json」
- 点击 「检测会话」 验证有效性
- 点击 「保存会话」 持久化
Cookie 导入支持自动识别多站点 Cookie:
- Pixiv Cookie → 用于 Pixiv 下载
- X/Twitter Cookie → 写入
runtime/x_cookies.json - 小红书 Cookie → 写入
runtime/xiaohongshu_cookies.json - 长佩 Cookie → 写入
runtime/changpei_cookies.json
账号密码登录
输入邮箱/Pixiv ID 和密码后点「尝试登录」,成功后自动生成 Cookie。注意:可能被 Pixiv 风控/二步验证拦截,稳定性不如 Cookie 登录。
会话管理
- 「自动载入」:启动时自动读取上次保存的会话
- 「保存会话」:将 Cookie、云同步 Token 一并持久化到本地文件
3.3 抓取功能
平台选择
主界面通过下拉菜单切换平台,模式列表随之更新:
| 平台 | 可选模式 |
|---|---|
| Pixiv | 作者全部作品、单个作品、漫画、文章/小说、关键词搜索 |
| X / Twitter | 作者媒体、单个推文、搜索词媒体 |
| 小红书 | 搜索关键词、单篇笔记、链接解析 |
| 笔趣阁小说 | 搜索/书籍链接 |
| 长佩文学 | 搜索/书籍链接 |
| 插件自动识别 | 自动匹配 |
目标输入格式
| 模式 | 输入示例 |
|---|---|
| Pixiv 作者 | 12345678 或 https://www.pixiv.net/users/12345678 |
| Pixiv 作品 | https://www.pixiv.net/artworks/12345678 |
| Pixiv 小说 | https://www.pixiv.net/novel/show.php?id=12345678 |
| Pixiv 关键词 | 初音未来 或 猫耳 |
| X 作者 | nasa 或 @nasa |
| X 推文 | https://x.com/user/status/123456... |
| X 搜索 | anime art filter:media |
| 小红书笔记 | https://www.xiaohongshu.com/explore/... |
| 笔趣阁 | 斗破苍穹 或书籍/章节链接 |
| 长佩 | 书名 或 novel-{id}.html 链接 |
批量输入
开启「统一任务队列」后支持:
- 多行输入(每行一个目标)
- 逗号分隔
#标签形式混合编排- 作者模式可配合水印增量同步(只抓新图)
3.4 下载流程
- 选择平台和模式
- 填写目标内容
- 点击「开始抓取」
- 程序自动:
- 解析目标(支持 ID 反查、链接解析、关键词搜索)
- 批量下载图片/小说
- 写入本地 SQLite 图库
- 如需云同步则自动上传
- 实时显示进度:作品进度、成功数、新下载页数、跳过数
3.5 性能设置
参数配置
| 参数 | 范围 | 默认值 | 说明 |
|---|---|---|---|
| 下载线程 | 2 - 16 | 8 | 并发下载线程数 |
| 请求间隔 | 0 - 1.5s | 0.1s | 请求间延迟 |
代理池
支持两种代理来源:
- 手动代理列表:粘贴
protocol://ip:port格式的代理 - Quake 代理:通过 Quake 网络空间搜索引擎获取海外代理
- 可选国家过滤:
US, JP, KR, SG, HK, TW, DE, FR, GB, CA, AU
- 可选国家过滤:
- 支持代理预校验:自动检测可用性并回填
代理模式下线程数自动限制在 3-6 之间,降低触发限流概率。
4. Sakura Cloud 云端平台
4.1 概述
Sakura Cloud 是整个系统的数据中心,负责:
- 用户认证:JWT 登录/注册/Token 刷新
- 内容存储:图片、漫画、小说文件存储与分发
- 元数据管理:作品信息、作者、标签、收藏、关注
- 数据同步:桌面端上传 ↔ 手机端下载
- 关注管理:关注作者、更新检测
- 每日提醒:定时生成关注作者更新摘要
- 推送服务:设备 Token 管理
4.2 API 端点
| 分组 | 端点 | 方法 | 说明 |
|---|---|---|---|
| 认证 | /api/v1/auth/register |
POST | 用户注册 |
| 认证 | /api/v1/auth/login |
POST | 用户登录 |
| 认证 | /api/v1/auth/refresh |
POST | 刷新 Token |
| 用户 | /api/v1/users/me |
GET | 获取当前用户信息 |
| 图库 | /api/v1/gallery/ |
GET | 查询图库内容 |
| 图库 | /api/v1/gallery/artworks |
GET | 插画列表(分页/筛选) |
| 图库 | /api/v1/gallery/artworks/{id} |
GET | 插画详情 |
| 小说 | /api/v1/novels/ |
GET | 小说列表 |
| 小说 | /api/v1/novels/{id} |
GET | 小说详情 |
| 文件 | /api/v1/files/ |
POST | 上传文件 |
| 文件 | /api/v1/files/{id} |
GET | 下载文件 |
| 关注 | /api/v1/follows/ |
GET/POST | 关注列表 / 添加关注 |
| 关注 | /api/v1/follows/sync |
POST | 同步关注 |
| 同步 | /api/v1/sync/ |
POST | 数据同步 |
| 推送 | /api/v1/push/ |
POST | 推送管理 |
| 提醒 | /api/v1/push/reminders |
GET | 获取提醒 |
| 管理 | /api/v1/admin/ |
GET | 管理后台(需管理员权限) |
| 健康 | /api/v1/health |
GET | 健康检查 |
4.3 认证机制
- 使用 JWT (JSON Web Token) 认证
- Access Token 短期有效,Refresh Token 用于续期
- 桌面端和移动端登录同一账号即可共享数据
- Token 在桌面端保存后,云同步和缩略图墙自动使用
4.4 定时任务
| 任务 | 频率 | 说明 |
|---|---|---|
| 提醒摘要检查 | 每 5 分钟 | 检查已开启提醒的用户,生成每日摘要 |
| 关注更新检测 | 启动时 + 每 5 分钟 | 检测关注作者是否有新内容 |
| 推送清理 | 定期 | 清理过期推送记录 |
4.5 部署方式
# Docker Compose 部署
cd sakura_cloud
docker-compose up -d
# 或直接运行
pip install -r sakura_cloud/requirements.txt
uvicorn sakura_cloud.main:app --host 0.0.0.0 --port 8000
默认云端地址(项目中硬编码):http://api.kunkunxiaomao.top:8000
5. Android 移动端功能详解
5.1 底部导航
| 标签 | 功能 |
|---|---|
| 📍 发现 | 首页动态:最近浏览、最近阅读、更新提醒 |
| 🖼️ 图片 | 云端同步的插画浏览、详情查看、收藏、下载 |
| 📖 漫画 | 漫画按组展示,连续浏览,支持整组下载 |
| 📚 书架 | 三列彩色方块,按书名归档,章节选择,阅读进度排序 |
| 👤 我的 | 用户资料、云端空间、收藏管理、每日提醒设置 |
5.2 小说阅读器
功能强大的跨设备小说阅读器:
| 功能 | 说明 |
|---|---|
| 自动分页 | 根据屏幕尺寸和字体大小自动分页 |
| 阅读进度 | 自动记住阅读位置,最近阅读优先排序 |
| 收藏管理 | 收藏/取消收藏 |
| 翻译功能 | 当前页翻译、原文/译文切换 |
| 阅读设置 | 字体大小、行高、背景色 可调 |
| 章节切换 | 系列小说底部面板直接列出章节,点击切换 |
| 删除管理 | 删除小说 |
5.3 书源系统
移动端集成了 Legado 规则引擎,支持导入第三方书源规则:
- 书源管理器(source_manager_page):添加/管理书源
- 统一搜索(unified_search):跨书源搜索小说
- 在线书架(online_shelf):管理在线书籍
- 阅读历史(online_reading_history):记录阅读进度
- 源健康检查(source_health):检测书源可用性
5.4 我的页功能
| 功能 | 说明 |
|---|---|
| 用户资料 | 查看和编辑个人信息 |
| 云端空间 | 查看存储使用情况 |
| 我的收藏 | 收藏的图片和小说管理 |
| 每日更新提醒 | 开关 + 时间设置 + 链接到提醒中心 |
| 退出登录 | 清除会话 |
6. 插件系统
6.1 架构设计
插件系统基于 动态 Python 模块加载 实现。每个插件是一个包含 plugin.py 的目录,目录中可附带 manifest.json(可选)和 __init__.py。
6.2 核心接口
所有插件必须继承 BasePlugin 抽象基类:
class BasePlugin(ABC):
"""每个站点插件必须实现的接口"""
@property
def domain(self) -> str: # 主域名,如 "pixiv.net"
...
@property
def name(self) -> str: # 人类可读名称,如 "Pixiv"
...
@property
def version(self) -> str: # 语义版本号
...
def can_handle(self, url: str) -> bool:
"""判断是否可以处理该 URL"""
...
def parse(self, url: str) -> list[Resource]:
"""解析 URL 为一个或多个可下载资源"""
...
def download(self, resource: Resource, save_path: Path) -> list[Path]:
"""下载资源文件到指定路径"""
...
def get_headers(self) -> dict[str, str]:
"""HTTP 请求头(Cookie 等)"""
...
6.3 资源模型
@dataclass
class Resource:
id: str # 资源 ID
url: str # 原始 URL
title: str # 标题
author: str # 作者名
author_id: str # 作者 ID
files: list[dict] # 文件列表 [{url, page}, ...]
metadata: dict # 元数据
thumbnail: str # 缩略图 URL
created_at: str # 创建时间
6.4 插件清单 (manifest.json)
{
"name": "MyPlugin",
"version": "1.0.0",
"domain": "example.com",
"author": "Your Name",
"description": "站点描述",
"requires_auth": true,
"min_platform_version": "1.0.0",
"tags": ["illust", "manga"],
"dependencies": []
}
6.5 内置插件
| 插件名 | 域名 | 类型 | 技术特点 |
|---|---|---|---|
| Pixiv | pixiv.net | 图片/小说 | HTTP requests,支持 Cookie/代理,反查作者 |
| X | twitter.com | 图片/视频 | Playwright 浏览器渲染,速率限制,防封策略 |
| 小红书 | xiaohongshu.com | 图片/笔记 | Playwright,Cookie 持久化 |
| AO3 | archiveofourown.org | 小说 | HTTP requests |
| 笔趣阁 | 多源 | 小说 | 支持搜索、榜单解析、章节批量下载 |
| 长佩文学 | gongzicp.com | 小说 | 支持搜索、书籍选择、全章抓取 |
6.6 插件管理面板
桌面端提供完整的插件管理功能:
| 操作 | 说明 |
|---|---|
| 导入 .py | 导入第三方 Python 插件文件 |
| 生成模板 | 填写名称/域名/作者/描述,自动生成插件骨架代码 |
| 重新加载 | 从磁盘重载所有插件 |
| 重载 | 重载单个插件 |
| 从内存卸载 | 卸载内置插件 |
| 删除文件 | 删除用户导入的插件目录 |
| 状态显示 | 就绪/需配置 |
| 来源标识 | 内置插件 / 用户插件 |
6.7 编写自定义插件
最小示例
from pathlib import Path
from pixiv_app.core.plugin.base import BasePlugin, Resource
class MySitePlugin(BasePlugin):
domain = "example.com"
name = "ExampleSite"
version = "1.0.0"
def can_handle(self, url: str) -> bool:
return "example.com" in url
def parse(self, url: str) -> list[Resource]:
# 实现解析逻辑
return [
Resource(
id="123",
url=url,
title="示例标题",
author="作者名",
author_id="456",
files=[{"url": "https://example.com/img/1.jpg", "page": 0}],
metadata={"kind": "illust"},
)
]
def download(self, resource: Resource, save_path: Path) -> list[Path]:
# 实现下载逻辑
import requests
save_path.mkdir(parents=True, exist_ok=True)
downloaded = []
for item in resource.files:
resp = requests.get(item["url"], stream=True)
fname = item["url"].rsplit("/", 1)[-1]
dest = save_path / fname
dest.write_bytes(resp.content)
downloaded.append(dest)
return downloaded
def get_headers(self) -> dict[str, str]:
return {"User-Agent": "Mozilla/5.0 ..."}
plugin_class = MySitePlugin # 必须导出
插件事件钩子
from pixiv_app.core.plugin.manager import PluginManager, PluginEvent
manager = PluginManager(["plugins/"])
manager.on_event(PluginEvent.BEFORE_LOAD, lambda path: print(f"加载: {path}"))
manager.on_event(PluginEvent.AFTER_LOAD, lambda plugin: print(f"已加载: {plugin.name}"))
manager.on_event(PluginEvent.ERROR, lambda path, exc: print(f"错误: {path} {exc}"))
6.8 插件生命周期
- 发现:扫描
plugins/和用户插件目录 - 加载:动态 import,实例化
plugin_class - 验证:调用
validate()检查配置 - 使用:URL 匹配 →
parse()→download() - 重载:从 sys.modules 移除后重新加载
- 卸载:从内存移除,内置插件仅卸载不删除文件
7. 本地图库与缩略图墙
7.1 本地图库 (SQLite)
所有下载内容写入本地 SQLite 数据库,存储:
| 数据 | 字段 |
|---|---|
| 作品 | id, title, author, author_id, tags, description, created_at, downloaded_at |
| 文件 | path, size, sha256, mime_type, width, height |
| 收藏 | artwork_id, collected_at |
| 关注 | author_id, platform, followed_at |
| 标签 | name, category |
| OCR 文本 | artwork_id, text, confidence |
数据库路径:%LOCALAPPDATA%\PixivDownloader\library.db(打包版)/ data/library.db(源码版)
7.2 缩略图墙 WebUI
内嵌本地 Web 服务,默认端口 8765(自动降级 8766/8767),浏览器访问。
功能
| 功能 | 说明 |
|---|---|
| 缩略图浏览 | 网格展示所有图片和漫画 |
| 搜索 | 标题、作者、简介全文搜索 |
| 标签筛选 | 按标签分类浏览 |
| 作者视图 | 按作者聚合查看作品 |
| 作品详情 | 大图查看、信息展示 |
| 收藏管理 | 收藏/取消收藏作品 |
| 关注同步 | 添加/管理关注作者 |
| X 关注 | 管理 X 平台关注作者 |
技术实现
- HTTP 服务:纯 Python
http.server实现 - API 端点:
/api/artworks,/api/artworks/{id},/api/tags,/api/authors - 前端页面:Jinja2 模板渲染
8. 云同步机制
8.1 同步流程
桌面端下载完成
│
├──→ 写入本地 SQLite 图库
│
└──→ [云同步开启] → 上传至 Sakura Cloud
│
├──→ 上传文件 (图片/漫画页)
│
├──→ 上传元数据 (作品信息/标签/作者)
│
├──→ 上传关注信息 (follow)
│
└──→ 上传更新提醒 (alert)
手机端
│
└──→ [登录同一账号] → 从 Sakura Cloud 拉取数据
│
├──→ 图片页: 浏览插画
├──→ 漫画页: 浏览漫画
├──→ 书架页: 阅读小说
└──→ 发现页: 查看更新提醒
8.2 配置方法
- 勾选「启用 Sakura Cloud 同步」
- 点击「账号管理」→ 登录或注册
- 登录成功后 Token 自动保存
- 可点击「测试连接」验证
8.3 Token 管理
- 基于
CloudSession单例全局共享 - 自动检测 JWT 过期时间
- Token 即将过期时自动使用 Refresh Token 续期
- 刷新后的 Token 同步写回桌面会话文件
9. 每日提醒功能
9.1 工作机制
每日提醒 不是手机本地闹钟,而是云端摘要提醒:
- 桌面端关注作者 → 新内容下载 → 云同步上传
- 云端每 5 分钟检查已开启提醒的用户
- 有未读 alert 时生成「每日摘要提醒」
- 手机端「发现」页的
更新提醒区域显示 - 同一天内不会重复生成第二条摘要
9.2 设置方法
桌面端:
- 登录 Pixiv(Cookie 方式)
- 启用云同步并登录云端账号
- 打开缩略图墙 → 作品详情 → 「关注作者」(或在「关注同步」页手动添加)
- 对于 X 作者,在「X 关注」区域添加用户名后点「同步 X 关注」
手机端:
- 登录同一云端账号
- 进入「我的」页
- 打开「每日更新提醒」开关
- 设置提醒时间(HH:MM)
- 到「发现」页查看更新提醒
9.3 摘要格式
- 标题:
每日 09:00 更新提醒 - 内容:关注作者新增动态数量、来源平台、最近活跃作者名
10. 代理与性能设置
10.1 代理配置
桌面端「代理设置」对话框提供:
| 配置项 | 说明 |
|---|---|
| 启用代理池 | 开关 |
| 手动代理 | 文本区粘贴代理列表(protocol://ip:port 格式) |
| 使用 Quake | 启用网络空间搜索引擎获取代理 |
| Quake API Key | Quake 账号的 API 密钥 |
| Quake Cookie | Quake 登录 Cookie |
| Quake 模式 | api_v3 等 |
| 国家过滤 | 逗号分隔的国家代码 |
| 预校验 | 测试代理可用性并自动回填 |
10.2 性能建议
| 场景 | 推荐线程数 | 推荐延迟 |
|---|---|---|
| 日常少量下载 | 2-4 | 0.5s |
| 批量下载 | 6-8 | 0.2s |
| 使用代理 | 3-6(自动限制) | 0.3s |
| 高风险平台 | 1-2 | 1.0s+ |
11. 安装与运行
11.1 成品文件(推荐普通用户)
直接从 releases/ 目录获取:
| 文件 | 说明 | 大小 |
|---|---|---|
releases/sakuradownloader.exe |
Windows 桌面端,双击即用 | ~68 MB |
releases/app-release.apk |
Android 客户端 | ~54 MB |
11.2 源码运行(开发者)
环境要求
| 组件 | 版本要求 |
|---|---|
| Python | 3.8+ |
| Flutter | 3.x(仅 Android 端开发) |
| JDK | 17+(仅 Android 打包) |
| PostgreSQL | 14+(仅云端部署) |
桌面端
# 创建虚拟环境
python -m venv .venv
.\.venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 运行
python main.py
Pixiv 需要额外安装 Playwright 浏览器:
playwright install chromium
云端
pip install -r sakura_cloud/requirements.txt
uvicorn sakura_cloud.main:app --reload
移动端
cd sakura_mobile
flutter pub get
flutter run
12. 打包与发布
12.1 一键打包
# 仅桌面 EXE
scripts\build_desktop_exe.bat
# 仅 Android APK
scripts\build_mobile_android.bat
# 复制到 releases/
scripts\copy_release_artifacts.bat
# 一键全部
scripts\build_all.bat
12.2 构建产物
| 产物 | 路径 | 工具 |
|---|---|---|
| Windows EXE | dist/sakuradownloader.exe |
PyInstaller |
| Android APK | sakura_mobile/build/app/outputs/flutter-apk/app-release.apk |
Flutter build |
12.3 注意事项
- APK 当前为调试签名,仅供个人测试,不宜直接上架分发
- 正式分发建议重新生成正式 keystore 签名
- EXE 打包前需确认 Playwright Chromium 已安装
- 内置插件会自动打包进 EXE
13. 完整使用指南
13.1 桌面端首次使用
- 启动:双击
sakuradownloader.exe - 阅读须知:查看启动弹窗的用户须知(5 页)
- 导入 Cookie:
- 浏览器登录 Pixiv → 用
Get cookies.txt插件导出 - 回到桌面端 → 「导入 cookies.txt / json」
- 「检测会话」 → 「保存会话」
- 浏览器登录 Pixiv → 用
- 首次下载:
- 选择平台 =
Pixiv - 选择模式 =
作者全部作品 - 目标输入一个作者 ID 或作品链接
- 点击「开始抓取」
- 选择平台 =
- 浏览图库:下载完成后点击「打开缩略图墙」
13.2 配置云同步
- 桌面端勾选「启用 Sakura Cloud 同步」
- 点击「账号管理」→ 切换到「注册」→ 注册账号
- 切换到「登录」→ 登录
- 提示「登录成功,云同步凭证已自动保存」
- 点击「测试连接」验证
13.3 手机端首次使用
- 安装
app-release.apk - 打开应用 → 使用与桌面端相同的云端账号登录
- 等待数据同步完成
- 浏览各标签页内容
13.4 使用关注与提醒
- 桌面端:打开缩略图墙 → 作品详情点「关注作者」
- 或在「关注同步」页手动添加作者 ID
- 手机端:我的 → 打开「每日更新提醒」→ 设置时间
- 到点后去「发现」页查看
13.5 导入第三方插件
- 桌面端点击「插件管理」
- 点击「导入 .py」选择插件文件
- 验证状态显示「就绪」
- 回到主界面,选择「插件自动识别」平台
- 输入目标 URL/ID,程序自动匹配插件
14. 常见问题与排错
14.1 登录相关
| 问题 | 解决方案 |
|---|---|
| Cookie 登录失效 | 重新从浏览器导出最新 Cookie 并导入 |
| 账号密码登录失败 | 很可能被 Pixiv 风控拦截,改用 Cookie 登录 |
| 检测会话失败 | Cookie 可能已过期,重新导出导入 |
| X 登录失败 | 确认 Cookie 已同步到 runtime/x_cookies.json |
14.2 下载相关
| 问题 | 解决方案 |
|---|---|
| 下载速度为 0 | 检查网络连接,尝试启用代理 |
| 某些作品下载失败 | 可能是作品被删除或设为私密,跳过继续 |
| 关键词搜索无结果 | 尝试不同关键词或减少数量限制 |
| 代理模式下全部失败 | 代理可能不可用,先用「预校验」测试 |
14.3 云同步相关
| 问题 | 解决方案 |
|---|---|
| 连接失败 | 检查网络,确认 API 地址可访问 |
| Token 无效 | 重新登录云端账号 |
| 手机端没内容 | 确认桌面端云同步已开启,使用同一账号 |
| 上传失败 | 检查云端存储空间 |
14.4 移动端相关
| 问题 | 解决方案 |
|---|---|
| APK 安装被拦截 | 允许「未知来源应用安装」 |
| 登录后没数据 | 确认桌面端已开启云同步并上传了内容 |
| 提醒没出现 | 确认已关注作者、新内容已同步、已过提醒时间 |
14.5 提醒相关
| 问题 | 解决方案 |
|---|---|
| 开了提醒没内容 | 需要桌面端先关注作者 + 有新内容 + 已同步到云端 |
| 没收到推送通知 | 这是应用内提醒,不是系统推送,去「发现」页查看 |
| 提醒时间不对 | 检查时区设置(默认 Asia/Shanghai) |
15. 安全与风险控制
15.1 使用安全
| 措施 | 说明 |
|---|---|
| Cookie 本地存储 | Cookie 仅保存在本地文件,不会上传到第三方 |
| 密码不写入源码 | 账号密码仅在内存中使用,不会持久化到代码 |
| Token 加密存储 | JWT Token 保存到本地会话文件 |
| HTTPS 传输 | 云端 API 使用 HTTPS/TLS 加密 |
15.2 风险控制建议
| 建议 | 说明 |
|---|---|
| 合理频率 | 避免短时间内高频大批量下载 |
| 定期更新 Cookie | Cookie 失效时及时重新导入 |
| 使用代理 | 大批量下载时启用代理池分散 IP |
| 控制线程数 | 不要将线程数设置过高 |
| 间隔延迟 | 适当增加请求间隔 |
| 研究学习用途 | 本工具仅供个人研究学习使用 |
15.3 已知限制
| 限制 | 说明 |
|---|---|
| Pixiv 风控 | 高频访问可能触发验证码或临时封禁 |
| X 速率限制 | X API 有频率限制,插件已内置防封策略 |
| 小红书反爬 | 可能返回 404,作者持续优化中 |
| APK 调试签名 | 不适合正式分发,仅适合个人测试 |
| 提醒非系统推送 | 需要在应用内查看,不会弹出系统通知 |
16. 开发指南
16.1 技术栈
| 层 | 技术 |
|---|---|
| 桌面 GUI | Python / CustomTkinter 5.2+ |
| HTTP 客户端 | requests, httpx |
| 浏览器自动化 | Playwright 1.41+ |
| 本地数据库 | SQLite |
| OCR | PaddleOCR 2.7+ |
| 模板引擎 | Jinja2 3.1+ |
| 加密 | cryptography 45.0+ |
| 打包 | PyInstaller |
| 云端框架 | FastAPI |
| 云端 ORM | SQLAlchemy (async) |
| 云端数据库 | PostgreSQL |
| 云端迁移 | Alembic |
| 移动端框架 | Flutter 3.x |
| 移动端状态 | Riverpod |
| 移动端网络 | Dio |
16.2 项目依赖
# requirements.txt
customtkinter>=5.2.0
requests>=2.31.0
Pillow>=10.0.0
Jinja2>=3.1.0
playwright>=1.41.0
httpx>=0.27.0
cryptography>=45.0.0
firebase-admin>=6.5.0
paddleocr>=2.7.0
16.3 代码规范
- Python 代码使用
from __future__ import annotations延迟注解求值 - 所有插件必须继承
BasePlugin并导出plugin_class - 桌面端使用线程模型(非 asyncio)与 requests 配合
- 云端使用 async/await 全异步
- 移动端使用 Riverpod 进行状态管理
16.4 运行测试
cd tests
python -m pytest
16.5 贡献指南
- Fork 项目仓库
- 创建功能分支
- 如果添加新站点支持,建议编写为独立插件
- 提交 PR 前运行现有测试
- 更新相关文档
17. 更新日志
v2.0.0 (2026-06)
- ✨ 新增:笔趣阁小说插件
- ✨ 新增:长佩文学插件
- ✨ 新增:小红书链接解析模式
- ✨ 新增:插件模板生成器
- ✨ 新增:X 关注同步功能
- ✨ 新增:云端每日提醒系统
- ✨ 新增:移动端 Legado 规则引擎
- ✨ 新增:移动端漫画分组浏览
- ✨ 新增:移动端在线书架与统一搜索
- 🔧 优化:Cookie 导入支持多站点自动分流
- 🔧 优化:代理池预校验与自动回填
- 🔧 优化:云同步 Token 自动刷新机制
- 🔧 优化:任务队列支持批量 #标签输入
- 🔧 优化:移动端阅读器设置面板
- 🐛 修复:多项稳定性与 UI 问题
附录
A. 联系方式
- 作者 QQ:2811043066
- 博客:http://blog.kunkunxiaomao.top
- 项目仓库:请查看 README.md 中的链接
B. 相关文档
| 文档 | 说明 |
|---|---|
| 使用说明-桌面版与安卓版.md | 终端用户快速上手 |
| README.md | 项目概览与快速开始 |
| 项目文件/BUILD.md | 打包细节与排错 |
| docs/Sakura_Downloader_完整文档.md | 完整技术文档 |
| docs/login-and-auth.md | 登录认证详解 |
C. 许可说明
- 本工具仅供个人研究学习使用
- 请勿用于商业用途或非法搬运他人作品
- APK 为调试签名,仅适合个人测试
- 使用 X 插件前需安装 Playwright Chromium
- 尊重各平台的服务条款和版权规定
📝 最后更新:2026-06-23 💡 如有问题或建议,欢迎联系作者或提交 Issue