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