# Sakura Downloader(樱云下载器)产品文档 > 版本:2.0.0 | 更新日期:2026-06-23 > 作者:kunkunxiaomao | 博客:http://blog.kunkunxiaomao.top --- ## 目录 1. [产品介绍](#1-产品介绍) 2. [系统架构总览](#2-系统架构总览) 3. [桌面端功能详解](#3-桌面端功能详解) 4. [Sakura Cloud 云端平台](#4-sakura-cloud-云端平台) 5. [Android 移动端功能详解](#5-android-移动端功能详解) 6. [插件系统](#6-插件系统) 7. [本地图库与缩略图墙](#7-本地图库与缩略图墙) 8. [云同步机制](#8-云同步机制) 9. [每日提醒功能](#9-每日提醒功能) 10. [代理与性能设置](#10-代理与性能设置) 11. [安装与运行](#11-安装与运行) 12. [打包与发布](#12-打包与发布) 13. [完整使用指南](#13-完整使用指南) 14. [常见问题与排错](#14-常见问题与排错) 15. [安全与风险控制](#15-安全与风险控制) 16. [开发指南](#16-开发指南) 17. [更新日志](#17-更新日志) --- ## 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 目录结构 ```text 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 文件: 1. 浏览器登录 Pixiv → 用插件导出 txt 或 json 文件 2. 桌面端点击 「导入 cookies.txt / json」 3. 点击 「检测会话」 验证有效性 4. 点击 「保存会话」 持久化 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 下载流程 1. 选择平台和模式 2. 填写目标内容 3. 点击「开始抓取」 4. 程序自动: - 解析目标(支持 ID 反查、链接解析、关键词搜索) - 批量下载图片/小说 - 写入本地 SQLite 图库 - 如需云同步则自动上传 5. 实时显示进度:作品进度、成功数、新下载页数、跳过数 ### 3.5 性能设置 #### 参数配置 | 参数 | 范围 | 默认值 | 说明 | |------|------|--------|------| | 下载线程 | 2 - 16 | 8 | 并发下载线程数 | | 请求间隔 | 0 - 1.5s | 0.1s | 请求间延迟 | #### 代理池 支持两种代理来源: 1. **手动代理列表**:粘贴 `protocol://ip:port` 格式的代理 2. **Quake 代理**:通过 Quake 网络空间搜索引擎获取海外代理 - 可选国家过滤:`US, JP, KR, SG, HK, TW, DE, FR, GB, CA, AU` 3. 支持代理预校验:自动检测可用性并回填 代理模式下线程数自动限制在 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 部署方式 ```bash # 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` 抽象基类: ```python 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 资源模型 ```python @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) ```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 编写自定义插件 #### 最小示例 ```python 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 # 必须导出 ``` #### 插件事件钩子 ```python 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 插件生命周期 1. **发现**:扫描 `plugins/` 和用户插件目录 2. **加载**:动态 import,实例化 `plugin_class` 3. **验证**:调用 `validate()` 检查配置 4. **使用**:URL 匹配 → `parse()` → `download()` 5. **重载**:从 sys.modules 移除后重新加载 6. **卸载**:从内存移除,内置插件仅卸载不删除文件 --- ## 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 配置方法 1. 勾选「启用 Sakura Cloud 同步」 2. 点击「账号管理」→ 登录或注册 3. 登录成功后 Token 自动保存 4. 可点击「测试连接」验证 ### 8.3 Token 管理 - 基于 `CloudSession` 单例全局共享 - 自动检测 JWT 过期时间 - Token 即将过期时自动使用 Refresh Token 续期 - 刷新后的 Token 同步写回桌面会话文件 --- ## 9. 每日提醒功能 ### 9.1 工作机制 每日提醒 **不是手机本地闹钟**,而是**云端摘要提醒**: 1. 桌面端关注作者 → 新内容下载 → 云同步上传 2. 云端每 5 分钟检查已开启提醒的用户 3. 有未读 alert 时生成「每日摘要提醒」 4. 手机端「发现」页的 `更新提醒` 区域显示 5. 同一天内不会重复生成第二条摘要 ### 9.2 设置方法 **桌面端:** 1. 登录 Pixiv(Cookie 方式) 2. 启用云同步并登录云端账号 3. 打开缩略图墙 → 作品详情 → 「关注作者」(或在「关注同步」页手动添加) 4. 对于 X 作者,在「X 关注」区域添加用户名后点「同步 X 关注」 **手机端:** 1. 登录同一云端账号 2. 进入「我的」页 3. 打开「每日更新提醒」开关 4. 设置提醒时间(HH:MM) 5. 到「发现」页查看更新提醒 ### 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+(仅云端部署) | #### 桌面端 ```powershell # 创建虚拟环境 python -m venv .venv .\.venv\Scripts\activate # 安装依赖 pip install -r requirements.txt # 运行 python main.py ``` Pixiv 需要额外安装 Playwright 浏览器: ```bash playwright install chromium ``` #### 云端 ```powershell pip install -r sakura_cloud/requirements.txt uvicorn sakura_cloud.main:app --reload ``` #### 移动端 ```powershell cd sakura_mobile flutter pub get flutter run ``` --- ## 12. 打包与发布 ### 12.1 一键打包 ```powershell # 仅桌面 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 桌面端首次使用 1. **启动**:双击 `sakuradownloader.exe` 2. **阅读须知**:查看启动弹窗的用户须知(5 页) 3. **导入 Cookie**: - 浏览器登录 Pixiv → 用 `Get cookies.txt` 插件导出 - 回到桌面端 → 「导入 cookies.txt / json」 - 「检测会话」 → 「保存会话」 4. **首次下载**: - 选择平台 = `Pixiv` - 选择模式 = `作者全部作品` - 目标输入一个作者 ID 或作品链接 - 点击「开始抓取」 5. **浏览图库**:下载完成后点击「打开缩略图墙」 ### 13.2 配置云同步 1. 桌面端勾选「启用 Sakura Cloud 同步」 2. 点击「账号管理」→ 切换到「注册」→ 注册账号 3. 切换到「登录」→ 登录 4. 提示「登录成功,云同步凭证已自动保存」 5. 点击「测试连接」验证 ### 13.3 手机端首次使用 1. 安装 `app-release.apk` 2. 打开应用 → 使用与桌面端相同的云端账号登录 3. 等待数据同步完成 4. 浏览各标签页内容 ### 13.4 使用关注与提醒 1. 桌面端:打开缩略图墙 → 作品详情点「关注作者」 2. 或在「关注同步」页手动添加作者 ID 3. 手机端:我的 → 打开「每日更新提醒」→ 设置时间 4. 到点后去「发现」页查看 ### 13.5 导入第三方插件 1. 桌面端点击「插件管理」 2. 点击「导入 .py」选择插件文件 3. 验证状态显示「就绪」 4. 回到主界面,选择「插件自动识别」平台 5. 输入目标 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 运行测试 ```powershell cd tests python -m pytest ``` ### 16.5 贡献指南 1. Fork 项目仓库 2. 创建功能分支 3. 如果添加新站点支持,建议编写为独立插件 4. 提交 PR 前运行现有测试 5. 更新相关文档 --- ## 17. 更新日志 ### v2.0.0 (2026-06) - ✨ 新增:笔趣阁小说插件 - ✨ 新增:长佩文学插件 - ✨ 新增:小红书链接解析模式 - ✨ 新增:插件模板生成器 - ✨ 新增:X 关注同步功能 - ✨ 新增:云端每日提醒系统 - ✨ 新增:移动端 Legado 规则引擎 - ✨ 新增:移动端漫画分组浏览 - ✨ 新增:移动端在线书架与统一搜索 - 🔧 优化:Cookie 导入支持多站点自动分流 - 🔧 优化:代理池预校验与自动回填 - 🔧 优化:云同步 Token 自动刷新机制 - 🔧 优化:任务队列支持批量 #标签输入 - 🔧 优化:移动端阅读器设置面板 - 🐛 修复:多项稳定性与 UI 问题 --- ## 附录 ### A. 联系方式 - 作者 QQ:2811043066 - 博客:http://blog.kunkunxiaomao.top - 项目仓库:请查看 README.md 中的链接 ### B. 相关文档 | 文档 | 说明 | |------|------| | [使用说明-桌面版与安卓版.md](../使用说明-桌面版与安卓版.md) | 终端用户快速上手 | | [README.md](../README.md) | 项目概览与快速开始 | | [项目文件/BUILD.md](../项目文件/BUILD.md) | 打包细节与排错 | | [docs/Sakura_Downloader_完整文档.md](Sakura_Downloader_完整文档.md) | 完整技术文档 | | [docs/login-and-auth.md](login-and-auth.md) | 登录认证详解 | ### C. 许可说明 - 本工具仅供**个人研究学习**使用 - 请勿用于商业用途或非法搬运他人作品 - APK 为调试签名,仅适合个人测试 - 使用 X 插件前需安装 Playwright Chromium - 尊重各平台的服务条款和版权规定 --- > 📝 最后更新:2026-06-23 > 💡 如有问题或建议,欢迎联系作者或提交 Issue