Files
SakuraHub/docs/产品文档-樱云下载器.md
T

1187 lines
43 KiB
Markdown
Raw Normal View History

2026-11-16 20:45:22 +08:00
# 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