1188 lines
43 KiB
Markdown
1188 lines
43 KiB
Markdown
# 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
|