Files

1103 lines
43 KiB
Markdown
Raw Permalink Normal View History

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