Files
SakuraHub/docs/产品文档-樱云下载器.md
2026-11-16 20:45:22 +08:00

1188 lines
43 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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