Files
SakuraHub/docs/Sakura_Downloader_完整文档.md
T
2026-11-16 20:45:22 +08:00

1104 lines
43 KiB
Markdown
Raw 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(樱云下载器)完整文档
> 更新日期:2026-06-14
---
## 目录
1. [项目概述](#1-项目概述)
2. [系统架构](#2-系统架构)
3. [目录结构详解](#3-目录结构详解)
4. [桌面端功能详解](#4-桌面端功能详解)
5. [插件系统](#5-插件系统)
6. [本地图库系统](#6-本地图库系统)
7. [缩略图墙 WebUI](#7-缩略图墙-webui)
8. [云同步系统](#8-云同步系统)
9. [Sakura Cloud 云端 API](#9-sakura-cloud-云端-api)
10. [Android 移动端](#10-android-移动端)
11. [每日提醒功能](#11-每日提醒功能)
12. [分布式爬虫系统](#12-分布式爬虫系统)
13. [环境搭建与运行](#13-环境搭建与运行)
14. [打包与发布](#14-打包与发布)
15. [测试](#15-测试)
16. [使用指南](#16-使用指南)
17. [常见问题](#17-常见问题)
18. [风险控制](#18-风险控制)
---
## 1. 项目概述
Sakura Downloader 是一套**个人媒体采集、本地图库管理与跨设备云同步系统**。项目由三个核心部分组成:
| 端 | 角色 | 技术栈 |
|----|------|--------|
| **Windows 桌面端** | 采集与整理中枢 | Python 3.8+ / CustomTkinter / SQLite / Playwright |
| **Sakura Cloud** | 数据与账号中心 | FastAPI / PostgreSQL / JWT / Redis |
| **Android 客户端** | 跨设备阅读与提醒 | Flutter / Riverpod / Dio |
### 核心能力
- **多平台采集**:支持 Pixiv、X(Twitter)、小红书、笔趣阁小说、AO3 等平台的图片、漫画、小说、视频下载
- **本地图库管理**:SQLite 数据库管理作品、作者、标签、收藏、关注
- **缩略图墙**:本地 WebUI 浏览图库、搜索、标签筛选、关注同步
- **云同步**:下载内容自动上传到 Sakura Cloud,手机端实时访问
- **插件系统**:支持自定义 Python 插件扩展采集能力
- **每日提醒**:云端汇总关注作者更新,手机端查看
- **OCR 文字识别**:基于 PaddleOCR 的本地图片文字提取
- **代理池**:支持手动代理列表和 Quake 网络空间搜索引擎获取代理
- **分布式爬虫**:基于 Redis + aiohttp 的 Master-Worker 分布式架构
---
## 2. 系统架构
```
┌──────────────────────────────────────────────────────────────────┐
│ Windows 桌面端 │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ GUI 界面 │ │ 下载引擎 │ │ 本地图库 │ │ 缩略图墙 WebUI │ │
│ │(CustomTk│ │(多线程) │ │(SQLite) │ │(HTTP API+前端) │ │
│ │ inter) │ │ │ │ │ │ │ │
│ └────┬────┘ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
│ │ │ │ │ │
│ ┌────┴────────────┴─────────────┴──────────────────┴─────────┐ │
│ │ 插件系统 (Plugins) │ │
│ │ Pixiv │ X/Twitter │ 小红书 │ 笔趣阁 │ AO3 │ 用户自定义 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────┴──────────────────────────────────────────────────────┐ │
│ │ 云同步客户端 (Cloud Sync) │ │
│ │ 文件 SHA256 去重 → 分片上传 → 元数据同步 → 失败重试队列 │ │
│ └────────────────────────────────────────────────────────────┘ │
└───────────────────────────────┬──────────────────────────────────┘
│ HTTPS
▼
┌──────────────────────────────────────────────────────────────────┐
│ Sakura Cloud (FastAPI) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ 用户认证 │ │ 文件存储 │ │ 图库管理 │ │ 提醒摘要服务 │ │
│ │(JWT) │ │(分片上传) │ │(CRUD) │ │(定时任务) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────────┘ │
│ PostgreSQL 数据库 │
└───────────────────────────────┬──────────────────────────────────┘
│ HTTPS
▼
┌──────────────────────────────────────────────────────────────────┐
│ Android 移动端 (Flutter) │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ 发现页 │ │ 图片页 │ │ 漫画页 │ │ 书架页 │ │ 我的页 │ │
│ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │
│ Riverpod 状态管理 │
└──────────────────────────────────────────────────────────────────┘
```
---
## 3. 目录结构详解
```
Pixiv/
├── main.py # 桌面端入口,启动 GUI
├── requirements.txt # Python 依赖
├── README.md # 项目简介
├── 使用说明-桌面版与安卓版.md # 终端用户使用说明
│
├── pixiv_app/ # 桌面端核心模块
│ ├── gui/
│ │ ├── app.py # 主 GUI 窗口(2700+ 行)
│ │ ├── plugin_panel.py # 插件管理面板
│ │ └── proxy_dialog.py # 代理设置对话框
│ ├── core/
│ │ ├── auth.py # Pixiv 认证(Cookie/密码登录)
│ │ ├── downloader.py # 核心下载引擎
│ │ ├── library.py # 本地 SQLite 图库
│ │ ├── cloud_sync.py # 云同步客户端
│ │ ├── orchestrator.py # 插件任务编排
│ │ ├── proxy_pool.py # 代理池管理
│ │ ├── ocr.py # 本地 OCR 索引
│ │ ├── paths.py # 路径管理(开发/打包模式)
│ │ ├── cookie_import.py # Cookie 导入解析
│ │ ├── fingerprint.py # 浏览器指纹
│ │ ├── gallery_service.py # 本地图库服务层
│ │ ├── library_importer.py # 遗留数据导入
│ │ ├── origin_follow_sync.py # 原站关注同步
│ │ ├── thumbnails.py # 缩略图生成
│ │ ├── x_media_service.py # X 媒体服务
│ │ ├── browser_proxy_pool.py # 浏览器代理池
│ │ └── playwright_runtime.py # Playwright 运行时
│ ├── services/
│ │ ├── gallery_api.py # 缩略图墙 HTTP API 服务
│ │ ├── run_gallery_api.py # API 启动入口
│ │ ├── x_auth_manager.py # X 认证管理
│ │ └── x_login_flow.py # X 登录流程
│ ├── tasks/
│ │ ├── models.py # 任务数据模型
│ │ ├── parser.py # 输入解析器
│ │ ├── queue.py # SQLite 任务队列
│ │ └── watermark.py # 增量同步水印
│ ├── runtime/
│ │ ├── enqueue.py # 任务入队
│ │ ├── executor.py # 任务执行器
│ │ └── worker_loop.py # Worker 循环
│ ├── core/plugin/ # 插件基础设施
│ │ ├── base.py # BasePlugin 抽象基类
│ │ ├── manager.py # PluginManager 加载/匹配
│ │ └── generator.py # 插件模板生成器
│ └── webui/ # 缩略图墙前端静态文件
│
├── plugins/ # 内置插件
│ ├── pixiv/plugin.py # Pixiv 插件
│ ├── x/ # X/Twitter 插件
│ │ ├── plugin.py # 主插件逻辑
│ │ ├── browser_opts.py # 浏览器启动参数
│ │ ├── playwright_client.py # Playwright 客户端
│ │ ├── selectors.py # DOM 选择器
│ │ ├── x_login.py # X 登录
│ │ ├── x_urls.py # URL 构造
│ │ └── setup_plugin.py # 插件安装
│ ├── xiaohongshu/plugin.py # 小红书插件
│ ├── biquge/plugin.py # 笔趣阁小说插件
│ └── ao3/plugin.py # AO3 同人小说插件
│
├── sakura_cloud/ # 云端 API 服务
│ ├── main.py # FastAPI 应用入口
│ ├── api/
│ │ ├── v1/router.py # API 路由汇总
│ │ ├── deps.py # 依赖注入(认证)
│ │ └── middleware.py # 中间件
│ ├── core/
│ │ ├── config.py # 配置管理
│ │ ├── logging.py # 日志配置
│ │ ├── safety.py # 安全工具
│ │ └── security.py # JWT 与加密
│ ├── db/
│ │ ├── base.py # SQLAlchemy Base
│ │ └── session.py # 数据库会话
│ ├── models/ # SQLAlchemy 模型
│ │ ├── user.py # 用户
│ │ ├── artwork.py # 作品
│ │ ├── novel.py # 小说
│ │ ├── file.py # 文件
│ │ ├── follow.py # 关注
│ │ ├── push.py # 推送/提醒
│ │ ├── ocr.py # OCR
│ │ ├── device.py # 设备
│ │ ├── admin.py # 管理员
│ │ └── mixins.py # 混入
│ ├── schemas/ # Pydantic 请求/响应模型
│ ├── services/ # 业务逻辑
│ │ ├── storage.py # 文件存储
│ │ ├── audit.py # 审计
│ │ ├── push.py # 推送服务
│ │ ├── reminders.py # 提醒摘要
│ │ ├── ocr.py # OCR 服务
│ │ ├── thumbnails.py # 缩略图服务
│ │ └── migrations.py # 数据库迁移
│ ├── migrations/ # Alembic 迁移
│ └── scripts/
│ ├── init_db.py # 数据库初始化
│ └── create_admin.py # 创建管理员
│
├── sakura_mobile/ # Flutter Android 客户端
│ └── lib/src/
│ ├── app.dart # 应用入口
│ ├── core/
│ │ ├── api_client.dart # API 客户端
│ │ ├── session.dart # 会话管理
│ │ ├── providers.dart # Riverpod 状态
│ │ └── push_notifications.dart # 推送
│ ├── models/
│ │ ├── artwork.dart # 作品模型
│ │ └── novel.dart # 小说模型
│ └── pages/
│ ├── tabs/ # 底部导航页签
│ │ ├── feed_tab.dart # 发现
│ │ ├── gallery_tab.dart # 图片
│ │ ├── novels_tab.dart # 书架
│ │ └── profile_tab.dart # 我的
│ ├── login_page.dart # 登录/注册
│ ├── artwork_detail_page.dart # 作品详情
│ ├── novel_detail_page.dart # 小说详情
│ ├── novel_reader_page.dart # 小说阅读器
│ ├── favorites_page.dart # 收藏
│ └── reminder_center_page.dart # 提醒中心
│
├── distributed_crawler/ # 分布式爬虫(可选)
│ ├── crawler/
│ │ ├── master.py # Master 节点
│ │ ├── worker.py # Worker 节点
│ │ ├── spider.py # 爬虫逻辑
│ │ ├── queue.py # Redis 优先级队列
│ │ ├── scheduler.py # 调度器
│ │ ├── hash_ring.py # 一致性哈希
│ │ ├── bloom.py # 布隆过滤器去重
│ │ ├── circuit_breaker.py # 熔断器
│ │ ├── rate_limit.py # 速率限制
│ │ ├── backoff.py # 退避策略
│ │ ├── proxy.py # 代理管理
│ │ ├── sessions.py # 会话管理
│ │ ├── auth.py # 认证
│ │ ├── http.py # HTTP 客户端
│ │ ├── signatures.py # 请求签名
│ │ ├── config.py # 配置
│ │ ├── models.py # 数据模型
│ │ ├── state.py # 状态/检查点
│ │ └── results.py # 结果存储
│ └── scripts/
│ ├── run_master.py # 启动 Master
│ └── run_worker.py # 启动 Worker
│
├── build_assets/ # 打包资源
├── scripts/ # 构建脚本
├── tools/ # 辅助工具
├── tests/ # 测试文件
├── docs/ # 文档(本文件所在目录)
├── dist/ # PyInstaller 打包输出
├── releases/ # 发布成品
│ ├── sakuradownloader.exe # Windows 桌面端成品
│ └── app-release.apk # Android 成品
├── data/ # 运行时数据
├── profiles/ # Playwright 浏览器 profiles
├── runtime/ # 运行时文件(Cookie、日志等)
└── Sakura_Downloads/ # 默认下载目录
```
---
## 4. 桌面端功能详解
### 4.1 GUI 主界面 (`pixiv_app/gui/app.py`)
主界面基于 **CustomTkinter** 构建,采用浅色蓝色主题,包含以下功能卡片:
#### 登录方式卡片
| 登录方式 | 说明 |
|----------|------|
| **Cookie 登录**(推荐) | 从浏览器导出 cookies.txt/json,导入后自动解析为 JSON 保存。同时识别 Pixiv、X、小红书域名并分别存储 |
| **账号密码登录** | 直接使用 Pixiv 账号密码登录,但可能触发风控验证 |
#### 抓取目标卡片
| 平台 | 支持的模式 |
|------|-----------|
| **Pixiv** | 作者全部作品、单个作品、漫画、文章/小说、关键词图片 |
| **X / Twitter** | 作者媒体、单个推文、搜索词媒体 |
| **小红书** | 搜索关键词、单篇笔记、链接解析 |
| **笔趣阁小说** | 搜索/书籍链接(支持书名搜索、书籍页、章节页、榜单列表页) |
| **插件自动识别** | 自动匹配已导入插件中第一个 `can_handle()` 返回 True 的插件 |
#### 性能设置卡片
- **下载线程**:2-16 可调(代理模式下自动限制为 3-6)
- **请求间隔**:0.0-1.5 秒可调
- **代理设置**:手动代理列表 + Quake 网络空间搜索引擎
- **统一任务队列**:SQLite 持久化任务状态,支持多行/逗号混合输入和 `#标签`
- **作者增量同步(水印)**:只抓取上次同步之后的新作品
#### 云同步卡片
- 启用/禁用 Sakura Cloud 同步
- 账号管理(登录/注册/获取 Token)
- 测试连接按钮
#### 任务概览面板
- 作品进度(完成/总计)
- 成功项目数
- 新下载页数
- 已跳过页数
- 缩略图墙入口按钮
#### 实时进度与日志
- 进度条
- 统计信息(失败项目/失败页数)
- 实时日志输出(带时间戳)
### 4.2 登录认证 (`pixiv_app/core/auth.py`)
- **SessionStore**:本地会话持久化(JSON 文件)
- **PixivAuthClient**:
- `validate_cookie()`:请求 Pixiv 设置页验证 Cookie 有效性,提取用户名和 ID
- `login_with_password()`:模拟 Pixiv 登录流程,自动提取 CSRF Token
### 4.3 下载引擎 (`pixiv_app/core/downloader.py`)
核心下载能力:
| 功能 | 函数 | 说明 |
|------|------|------|
| 目标解析 | `parse_pixiv_target()` | 从链接或 ID 识别目标类型(用户/作品/小说) |
| 作者作品列表 | `fetch_user_work_ids()` | 获取作者全部作品 ID,支持从作品链接反查作者 |
| 作品详情 | `fetch_illust_details()` | 获取作品元信息 |
| 作品页面 | `fetch_illust_pages()` | 获取多页作品的原图 URL 列表 |
| 小说详情 | `fetch_novel_details()` | 获取小说元信息 |
| 小说正文 | `fetch_novel_text()` | 获取小说文本内容 |
| 小说系列 | `fetch_novel_series_ids()` | 解析小说系列的章节列表 |
| 关键词搜索 | `search_illust_ids_by_keyword()` | 按关键词搜索作品并返回 ID 列表 |
| 图片下载 | `download_binary()` | 带重试、断点检测的二进制下载 |
| 文本保存 | `save_text_file()` | 小说 TXT 保存(UTF-8 BOM) |
| 插画下载 | `download_illust()` | 单作品完整下载流程 |
| 小说下载 | `download_novel()` | 单小说完整下载流程 |
| 批量下载 | `_download_illust_batch()` | 线程池批量下载 |
| 关键词批量 | `download_keyword_works()` | 搜索 + 批量下载 |
| 作者批量 | `download_user_works()` | 获取列表 + 批量下载 |
**特性**:
- 自动重试(最多 3 次)
- 文件断点检测(已存在且 >1KB 自动跳过)
- 代理池支持(失败自动切换代理)
- 404 特殊处理(区分"不存在"和"无权限")
- 停止事件支持(可随时中止)
### 4.4 代理池 (`pixiv_app/core/proxy_pool.py`)
- **ProxyPool**:代理列表管理、并发验证、轮询选择、失败标记
- **QuakeClient**:对接 Quake 360 网络空间搜索引擎
- API v3 模式(需要 API Key)
- Web Assoc 模式(需要 Cookie)
- 按国家筛选代理(US/JP/KR/SG/HK 等)
- **parse_proxy_text()**:解析手动输入的代理文本
### 4.5 路径管理 (`pixiv_app/core/paths.py`)
智能路径解析,自动区分开发模式和打包模式:
| 环境 | 数据目录 |
|------|----------|
| 开发模式 | 项目根目录 |
| 打包 EXE | `%LOCALAPPDATA%\SakuraDownloader` |
| 自定义 | 设置 `SAKURA_APP_DATA_DIR` 环境变量 |
支持从旧版 `PixivDownloader` 目录自动迁移数据。
### 4.6 OCR 文字识别 (`pixiv_app/core/ocr.py`)
基于 PaddleOCR 的本地图片文字提取:
- 支持中文/英文/混合识别
- 大图自动缩放到 1800px 以内提高速度
- 结果存入 SQLite 数据库
- 支持并发控制(信号量)
- 可通过环境变量配置:`SAKURA_LOCAL_OCR_ENABLED`、`SAKURA_LOCAL_OCR_LANGUAGE` 等
---
## 5. 插件系统
### 5.1 插件架构
```
plugins/
├── pixiv/plugin.py # 内置 Pixiv 插件
├── x/plugin.py # 内置 X/Twitter 插件
├── xiaohongshu/plugin.py # 内置小红书插件
├── biquge/plugin.py # 内置笔趣阁插件
├── ao3/plugin.py # 内置 AO3 插件
└── [用户自定义]/ # 可通过"导入 .py"添加
```
每个插件继承 `BasePlugin`,需实现:
- `name`:插件名称
- `can_handle(url)`:判断是否处理该 URL
- `parse(url)`:解析目标,返回 `list[Resource]`
- `download(resource, save_path)`:下载资源,返回 `list[Path]`
- `validate()`:检查插件依赖是否就绪
### 5.2 插件管理面板
桌面端主界面 → "插件管理" 按钮,提供:
- 查看已加载插件列表
- 导入 `.py` 插件文件
- 生成插件模板(自动填充项目结构)
- 重新加载所有插件
### 5.3 各平台插件详情
#### Pixiv 插件
- 基于 HTTP API 直接请求
- 支持插画、漫画、小说下载
- 使用 Cookie 认证
#### X / Twitter 插件
- 基于 Playwright 浏览器自动化
- 支持作者媒体页解析
- 支持单条推文图片/视频下载
- 支持搜索词媒体抓取
- 登录态:`runtime/x_profile`(浏览器 profile)+ `runtime/x_cookies.json`
- DOM 选择器集中在 `selectors.py` 便于维护
#### 小红书插件
- 基于 Playwright 浏览器自动化
- 支持关键词搜索
- 支持单篇笔记图片提取
- 支持 xhslink.com 短链解析
#### 笔趣阁小说插件
- 支持书名/作者搜索
- 支持书籍页/章节页链接解析
- 支持榜单/列表页解析
- 多结果时弹出选择对话框
#### AO3 插件
- 同人小说平台 Archive of Our Own
- 支持作品解析和章节下载
---
## 6. 本地图库系统
### 6.1 数据库设计 (`pixiv_app/core/library.py`)
使用 SQLite 数据库(默认文件:`pixiv_app_library.db`),包含以下表:
| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `artists` | 作者信息 | artist_id, name, account, avatar_url, metadata_json |
| `artworks` | 作品信息 | artwork_id, artist_id, type, title, page_count, tags, thumbnail_url |
| `tags` | 标签 | tag_id, name, translated_name |
| `artwork_tags` | 作品-标签关联 | artwork_id, tag_id |
| `artwork_files` | 下载文件记录 | artwork_id, page_index, file_path, source_url, status |
| `download_history` | 下载历史 | artwork_id, status, downloaded/skipped/failed_pages |
| `favorites` | 收藏 | artwork_id, note, created_at |
| `followed_artists` | 关注作者 | artist_id, name, enabled, last_synced_at |
| `thumbnail_cache` | 缩略图缓存 | artwork_id, page_index, source_path, thumbnail_path |
| `artwork_ocr_texts` | OCR 识别文本 | artwork_id, language, ocr_text, confidence |
| `sync_state` | 同步状态 | key, value_json |
| `download_tasks` | 下载任务队列 | fingerprint, target_type, target_id, status, priority |
| `artist_sync_watermark` | 作者同步水印 | artist_id, last_synced_illust_id |
### 6.2 ID 编码规则
为避免不同平台 ID 冲突,系统使用统一编码:
| 类型 | 编码方式 | 示例 |
|------|----------|------|
| Pixiv 插画 | 原始 ID | `12345678` |
| Pixiv 小说 | 负数 ID | `-12345678` |
| AO3 作品 | 负数偏移(-200M - work_id) | `-201234567` |
### 6.3 关键功能
- **作品入库**:下载时自动写入/更新 artworks 和相关表
- **收藏管理**:添加/移除收藏
- **关注管理**:添加/移除关注作者,自动获取作者信息
- **增量同步水印**:记录每个作者上次同步的作品 ID
- **遗留数据导入**:扫描下载目录导入已有文件
---
## 7. 缩略图墙 WebUI
### 7.1 架构
- **后端**:本地 HTTP API 服务(`gallery_api.py`),默认端口 8765(端口占用自动尝试 8766/8767)
- **前端**:静态 HTML/JS 页面(`webui/` 目录)
- **服务层**:`gallery_service.py` 提供图库查询逻辑
### 7.2 API 接口
| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/health` | GET | 健康检查 |
| `/api/session/status` | GET | 会话状态(Pixiv/X Cookie 是否可用) |
| `/api/artworks` | GET | 作品列表(支持搜索、标签、作者、类型筛选) |
| `/api/artworks/{id}` | GET | 作品详情 |
| `/api/favorites` | GET/POST | 收藏列表 / 设置收藏 |
| `/api/tags` | GET | 标签列表(支持搜索) |
| `/api/artists` | GET | 作者列表(支持搜索) |
| `/api/artists/{id}` | GET | 作者详情与作品列表 |
| `/api/followed-artists` | GET/POST | 关注作者列表 / 添加/取消关注 |
| `/api/thumbnails/build` | GET | 批量生成缩略图 |
| `/api/import/legacy` | GET/POST | 导入遗留下载数据 |
| `/api/sync/followed` | GET/POST | 同步关注作者的新作品 |
| `/api/cookies/import` | POST | 导入 Pixiv/X Cookie |
| `/api/origin-follows/sync` | POST | 从原站同步关注列表 |
| `/api/x/local-media` | GET | X 本地媒体列表 |
| `/api/x/media/preview` | POST | X 作者媒体预览 |
| `/api/x/media/download` | POST | X 媒体下载 |
| `/api/x/follows` | GET/POST | X 关注管理 |
| `/api/x/follows/sync` | POST | X 关注同步 |
| `/api/xiaohongshu/preview` | POST | 小红书预览 |
| `/api/xiaohongshu/download` | POST | 小红书下载 |
| `/media/thumbnail/{id}/{page}` | GET | 缩略图文件 |
| `/media/source/{id}/{page}` | GET | 原图文件 |
### 7.3 功能特性
- 浏览本地图片和漫画(默认不显示小说)
- 搜索标题、作者、简介
- 按标签筛选
- 按作者查看
- 收藏/取消收藏作品
- 关注/取消关注作者
- 从原站同步关注列表(Pixiv / X)
- 导入 Pixiv/X Cookie
- 关注同步页(批量检查关注作者新作品)
---
## 8. 云同步系统
### 8.1 架构 (`pixiv_app/core/cloud_sync.py`)
```
下载完成
│
▼
SyncManager.sync_file()
│
├── SHA256 计算
├── 云端 check_file() ─── 已存在? → 直接关联元数据
│ │ 不存在
│ ▼
├── init_upload() ─── 获取 upload_id
├── 分片上传 (5MB/chunk)
├── complete_upload() ─── 获取 file_id
└── sync_metadata() ─── 关联作品元数据
│
▼
失败? → SyncFailureQueue(指数退避重试)
```
### 8.2 关键组件
| 组件 | 说明 |
|------|------|
| `CloudSyncConfig` | 配置(API 地址、Token、分片大小、超时) |
| `SakuraCloudClient` | REST API 客户端 |
| `SyncManager` | 同步管理器(上传 + 元数据关联) |
| `SyncFailureQueue` | 失败重试队列(JSON 文件持久化,指数退避) |
| `SyncMetadata` | 作品元数据(标题、作者、标签、系列信息等) |
### 8.3 默认云端地址
```
http://api.kunkunxiaomao.top:8000
```
---
## 9. Sakura Cloud 云端 API
### 9.1 技术栈
- **框架**:FastAPI
- **数据库**:PostgreSQL(SQLAlchemy + Alembic 迁移)
- **认证**:JWT(python-jose + passlib bcrypt)
- **缓存/队列**:Redis(分布式爬虫用)
### 9.2 API 路由
| 路由前缀 | 说明 |
|----------|------|
| `/api/v1/auth` | 用户注册、登录、Token 刷新 |
| `/api/v1/users` | 用户信息管理 |
| `/api/v1/gallery` | 图库 CRUD |
| `/api/v1/novels` | 小说 CRUD、阅读进度 |
| `/api/v1/upload` | 文件分片上传(init → chunk → complete) |
| `/api/v1/sync` | 文件检查、元数据同步 |
| `/api/v1/follows` | 关注管理、批量 upsert、更新提醒 |
| `/api/v1/admin` | 管理后台(需管理员权限) |
| `/api/v1/push` | 推送通知 |
| `/api/v1/ocr` | OCR 服务 |
| `/api/v1/devices` | 设备管理 |
### 9.3 安全特性
- JWT Bearer Token 认证
- 密码 bcrypt 哈希
- 跨用户数据隔离(所有 follows 操作以当前登录用户为准)
- 外部 URL 白名单
- 安全响应头中间件
- CORS 配置
- 请求追踪日志中间件
### 9.4 后台任务
| 任务 | 周期 | 说明 |
|------|------|------|
| 清理过期上传 | 每小时 | 删除超时未完成的分片上传 |
| 每日提醒摘要 | 每 5 分钟 | 检查并生成关注作者更新提醒 |
### 9.5 数据库迁移
使用 Alembic 管理数据库 schema 变更:
- `sakura_cloud/migrations/` 目录
- 启动时自动迁移(可通过 `auto_migrate_on_startup` 配置)
---
## 10. Android 移动端
### 10.1 技术栈
- **框架**:Flutter
- **状态管理**:Riverpod
- **HTTP 客户端**:Dio
- **平台**:Android(APK)
### 10.2 页面结构
| 页签 | 页面 | 功能 |
|------|------|------|
| **发现** | `feed_tab.dart` | 最近浏览图片/漫画/小说、更新提醒 |
| **图片** | `gallery_tab.dart` | 云端图片列表、搜索、筛选、详情 |
| **漫画** | 漫画分组浏览 | 按漫画分组入口、连续浏览、整组下载 |
| **书架** | `novels_tab.dart` | 三列彩色方块、系列归档、继续阅读、章节选择 |
| **我的** | `profile_tab.dart` | 用户资料、空间占用、收藏、每日提醒、退出登录 |
### 10.3 小说阅读器
- 自动分页
- 阅读进度记忆
- 收藏/取消收藏
- 当前页翻译(原文/译文切换)
- 底部阅读设置面板(字体大小、行高、背景色)
- 系列章节列表切换
### 10.4 登录流程
1. 打开 APP → 登录/注册页
2. 使用与桌面端云同步相同的账号登录
3. 注册成功后需手动回到登录页登录
4. 登录后即可查看云端同步的内容
---
## 11. 每日提醒功能
### 11.1 工作原理
每日提醒**不是手机本地闹钟**,也不是系统级推送通知。
实际工作流程:
```
桌面端关注作者 → 下载新作品 → 云同步上传
│
▼
云端记录 follow + update alert
│
▼
云端定时检查(每 5 分钟)
│
▼
到设定时间 → 生成"每日摘要提醒"
│
▼
手机端"发现"页的"更新提醒"区域展示
```
### 11.2 设置步骤
1. 桌面端登录 Pixiv 并启用云同步
2. 桌面端打开缩略图墙 → 关注作者
3. 关注作者的新作品经下载后同步到云端
4. 手机端登录同一云端账号
5. 手机端"我的"页 → 打开"每日更新提醒"开关
6. 设置提醒时间(默认时区 Asia/Shanghai)
7. 到点后去"发现"页查看更新提醒
### 11.3 关键事实
- 云端只会给已开启提醒的用户生成摘要
- 同一天内已发过一次摘要,不会重复生成
- 摘要格式:`每日 HH:MM 更新提醒` + 关注作者动态统计
- 当前主要覆盖 Pixiv 平台(X 关注链路已部分接通)
---
## 12. 分布式爬虫系统
### 12.1 架构
可选的分布式爬虫系统,基于 Master-Worker 架构:
```
┌──────────────────────────────────────────────────────┐
│ Master Node │
│ ┌──────────┐ ┌──────────┐ ┌────────────────────┐ │
│ │ 任务队列 │ │ 结果消费 │ │ 调度器 + 健康检查 │ │
│ │(Redis) │ │ │ │ │ │
│ └────┬─────┘ └──────────┘ └────────────────────┘ │
│ │ │
│ ┌────┴──────────────────────────────────────────┐ │
│ │ aiohttp Web API │ │
│ │ POST /tasks POST /heartbeat GET /dashboard │ │
│ └───────────────────────────────────────────────┘ │
└───────────────────────┬──────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Worker 1 │ │ Worker 2 │ │ Worker N │
│(Playwright) │(Playwright) │(Playwright)
└──────────┘ └──────────┘ └──────────┘
```
### 12.2 核心组件
| 组件 | 文件 | 说明 |
|------|------|------|
| Master | `master.py` | 任务分发、结果收集、Worker 管理、Dashboard |
| Worker | `worker.py` | 任务执行、心跳上报 |
| Spider | `spider.py` | 爬虫逻辑(Playwright 浏览器自动化) |
| RedisPriorityQueue | `queue.py` | 优先级任务队列 |
| ConsistentHashRing | `hash_ring.py` | 一致性哈希任务分配 |
| RedisBloomFilter | `bloom.py` | URL 去重 |
| CircuitBreaker | `circuit_breaker.py` | 熔断保护 |
| RateLimiter | `rate_limit.py` | 速率限制 |
| BackoffStrategy | `backoff.py` | 指数退避重试 |
| CheckpointManager | `state.py` | 检查点恢复 |
---
## 13. 环境搭建与运行
### 13.1 桌面端(源码运行)
```powershell
# 1. 创建虚拟环境
python -m venv .venv
# 2. 激活虚拟环境
.\.venv\Scripts\activate
# 3. 安装依赖
pip install -r requirements.txt
# 4. 安装 Playwright 浏览器(X 插件需要)
playwright install chromium
# 5. 运行
python main.py
```
### 13.2 云端 API(可选)
```powershell
# 安装依赖
pip install -r sakura_cloud/requirements.txt
# 配置环境变量(参考 .env.cloud.example)
# DATABASE_URL=postgresql://...
# JWT_SECRET_KEY=...
# ...
# 启动
uvicorn sakura_cloud.main:app --reload --host 0.0.0.0 --port 8000
```
### 13.3 移动端开发
```powershell
cd sakura_mobile
# 安装依赖
flutter pub get
# 运行(需连接 Android 设备或模拟器)
flutter run
# 静态分析
flutter analyze
# 构建 APK
flutter build apk --release
```
### 13.4 分布式爬虫(可选)
```powershell
# 启动 Redis(需先安装)
redis-server
# 启动 Master
python -m distributed_crawler.scripts.run_master
# 启动 Worker(可启动多个)
python -m distributed_crawler.scripts.run_worker
```
---
## 14. 打包与发布
### 14.1 桌面 EXE
```powershell
# 方式一:使用构建脚本
scripts\build_desktop_exe.bat
# 方式二:直接调用 PyInstaller
.\.venv\Scripts\python.exe -m PyInstaller --clean --noconfirm build_assets\PixivDownloader.spec
```
输出:`dist\sakuradownloader.exe`(约 68 MB)
### 14.2 Android APK
```powershell
scripts\build_mobile_android.bat
```
输出:`sakura_mobile\build\app\outputs\flutter-apk\app-release.apk`(约 54 MB)
### 14.3 复制发布产物
```powershell
scripts\copy_release_artifacts.bat
```
将 EXE 和 APK 复制到 `releases/` 目录。
### 14.4 一键打包
```powershell
scripts\build_all.bat
```
### 14.5 注意事项
- APK 当前为**调试签名**,仅供个人测试,不宜直接上架分发
- 正式分发需重新生成 keystore 和正式签名
- 打包时自动包含 `plugins/`、`webui/`、`build_assets/` 等资源
---
## 15. 测试
### 15.1 已覆盖的测试
| 测试文件 | 测试内容 |
|----------|----------|
| `test_origin_follow_sync.py` | 原站关注同步幂等性 |
| `test_sakura_cloud_security.py` | 云端安全回归(401 拦截、跨用户隔离、权限) |
| `test_cloud_follow_schema.py` | 云端 follows schema 和 bulk-upsert |
| `test_plugin_manager.py` | 插件管理器加载/匹配 |
| `test_admin_console.py` | 管理后台 |
| `test_daily_reminders.py` | 每日提醒逻辑 |
| `test_push_notifications.py` | 推送通知 |
| `test_library_artist_repair.py` | 图库作者修复 |
| `test_ocr_gallery_search.py` | OCR 图库搜索 |
| `test_ao3_plugin.py` | AO3 插件测试 |
### 15.2 运行测试
```powershell
# Python 测试
python -m unittest tests.test_origin_follow_sync tests.test_sakura_cloud_security tests.test_cloud_follow_schema
# Flutter 静态分析
cd sakura_mobile
flutter analyze
```
---
## 16. 使用指南
### 16.1 桌面端快速上手
#### 第一步:登录 Pixiv
1. 在已登录 Pixiv 的浏览器中使用 **Get cookies.txt** 插件导出 Cookie
2. 打开桌面端,在"登录方式"卡片中保持 **Cookie 登录**
3. 点击 **导入 cookies.txt / json**,选择导出的文件
4. 点击 **检测会话** 确认 Cookie 有效
5. 点击 **保存会话** 持久化
#### 第二步:下载内容
1. 选择平台:**Pixiv**
2. 选择模式:如"作者全部作品"
3. 输入目标:作者 ID 或作品链接
4. 点击 **开始抓取**
5. 观察右侧进度和日志
#### 输入示例
| 目标类型 | 输入示例 |
|----------|----------|
| 作者 ID | `12345678` |
| 作品链接 | `https://www.pixiv.net/artworks/12345678` |
| 小说链接 | `https://www.pixiv.net/novel/show.php?id=12345678` |
| 小说系列 | `https://www.pixiv.net/novel/series/123456` |
| 关键词 | `初音未来`、`猫耳` |
| X 作者 | `@nasa` 或 `nasa` |
| X 推文 | `https://x.com/user/status/123456` |
| 小红书链接 | `https://www.xiaohongshu.com/explore/...` |
#### 任务队列模式(推荐)
勾选 **统一任务队列(SQLite 状态)** 后支持:
- 多行输入(每行一个目标)
- 逗号分隔多个目标
- `#标签` 形式输入(如 `#keyword 初音未来`)
- 持久化任务状态,重启后继续
#### 作者增量同步
勾选 **作者增量同步(水印)** 后:
- 记录每个作者上次同步的最新作品 ID
- 下次下载时只抓取新作品
- 大幅减少重复请求
### 16.2 浏览本地图库
1. 点击主界面 **打开缩略图墙** 按钮
2. 自动在浏览器中打开本地图库页面
3. 可以:搜索、按标签筛选、查看作者、收藏作品、关注作者
### 16.3 配置云同步
1. 勾选 **启用 Sakura Cloud 同步**
2. 点击 **账号管理**
3. 在弹窗中注册或登录云端账号
4. 登录成功后自动保存凭证
5. 点 **测试连接** 验证
6. 之后下载的内容会自动上传到云端
### 16.4 使用 X / Twitter 采集
1. 在"平台"下拉选择 **X / Twitter**
2. 选择模式:
- **作者媒体**:输入作者名(如 `nasa` 或 `@nasa`),自动访问 /media 页
- **单个推文**:输入完整推文链接
- **搜索词媒体**:输入搜索词,自动搜索媒体
3. 输入目标后点击开始抓取
> 注意:X 采集需要 Playwright 浏览器,首次使用需 `playwright install chromium`
### 16.5 使用小红书采集
1. 选择平台:**小红书**
2. 导入包含小红书域名的 Cookie(同 Pixiv 导入方式)
3. 选择模式:搜索关键词 / 单篇笔记 / 链接解析
4. 输入目标后开始抓取
### 16.6 手机端使用
1. 安装 `releases/app-release.apk`
2. 使用与桌面端云同步相同的账号登录
3. 底部导航切换页面查看内容
4. 在"我的"页开启每日提醒
---
## 17. 常见问题
### 17.1 桌面端登录失败
1. 优先使用 **Cookie 登录**(不是账号密码登录)
2. 重新在浏览器导出最新 cookies.txt
3. 重新导入后再点 **检测会话**
4. Cookie 失效时重新操作以上步骤
### 17.2 下载失败
- 检查 Cookie 是否有效(点"检测会话")
- 降低线程数(2-4)
- 增大请求间隔(0.5-1.0 秒)
- 尝试启用代理池
- 确认目标内容是否设置了访问限制(R-18 等)
### 17.3 手机端看不到内容
1. 桌面端是否启用了 **云同步** 并登录了云端账号
2. 下载是否已完成(查看进度和日志)
3. 手机端是否使用同一云端账号
4. 尝试在手机端下拉刷新
### 17.4 每日提醒没有内容
1. 是否在桌面端关注了作者
2. 是否有新作品进入云端
3. 是否已超过设定的提醒时间
4. 手机端"发现"页查看"更新提醒"
### 17.5 X 采集失败
1. 是否已安装 Playwright Chromium:`playwright install chromium`
2. X Cookie 是否有效(重新导出包含 x.com/twitter.com 的 Cookie)
3. 尝试在浏览器中先登录 X,再导出 Cookie
### 17.6 APK 安装被拦截
- 允许"未知来源应用安装"
- 重新安装一次
- 当前 APK 是调试签名,这是正常现象
### 17.7 端口被占用
缩略图墙默认使用 8765 端口,如被占用会自动尝试 8766、8767。
---
## 18. 风险控制
### 18.1 已知风险
| 平台 | 风险 | 建议 |
|------|------|------|
| 小红书 | 短时间内连续下载同帖图片触发警告 | 增加随机延迟、模拟浏览行为 |
| Pixiv | 高频请求触发限流 | 控制线程数、使用代理池 |
| X | 异常访问模式检测 | 合理使用、避免长时间连续运行 |
### 18.2 使用建议
1. **合理控制下载频率**:不建议长时间连续运行批量任务
2. **使用代理池**:切换 IP 降低单 IP 请求密度
3. **Cookie 定期更新**:Cookie 过期后重新导入
4. **本工具仅供学习研究使用**:严禁非法搬运和商业用途
5. **X 插件特殊说明**:使用前需安装 Playwright Chromium,保持浏览器在后台勿关闭
### 18.3 技术保护措施
- 代理池自动切换失败代理
- 请求重试机制(最多 3 次)
- 可配置请求间隔延迟
- 404 区分处理(不重试不存在的内容)
- 分布式爬虫内置熔断器和速率限制
---
## 附录
### A. 环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `SAKURA_APP_DATA_DIR` | 应用数据目录 | 开发模式=项目根目录,打包=%LOCALAPPDATA%\SakuraDownloader |
| `SAKURA_LOCAL_OCR_ENABLED` | 启用本地 OCR | `false` |
| `SAKURA_LOCAL_OCR_LANGUAGE` | OCR 语言 | `ch` |
| `SAKURA_LOCAL_OCR_MAX_DIMENSION` | OCR 图片最大尺寸 | `1800` |
| `SAKURA_LOCAL_OCR_MAX_CONCURRENCY` | OCR 最大并发 | `1` |
### B. 依赖列表
```
customtkinter>=5.2.0 # GUI 框架
requests>=2.31.0 # HTTP 请求
Pillow>=10.0.0 # 图片处理
Jinja2>=3.1.0 # 模板引擎
playwright>=1.41.0 # 浏览器自动化
httpx>=0.27.0 # 异步 HTTP
cryptography>=45.0.0 # 加密
firebase-admin>=6.5.0 # Firebase 推送(移动端)
paddleocr>=2.7.0 # OCR 文字识别
```
### C. 开发者联系方式
- **博客**:http://blog.kunkunxiaomao.top
- **QQ**:2811043066
### D. 许可说明
- 本项目仅供学习研究使用
- APK 为调试签名,仅供个人测试
- 严禁非法搬运和商业用途
- 使用 X 插件前需安装 Playwright Chromium
---
*最后更新:2026-06-14*