43 KiB
43 KiB
Sakura Downloader(樱云下载器)完整文档
更新日期:2026-06-14
目录
- 项目概述
- 系统架构
- 目录结构详解
- 桌面端功能详解
- 插件系统
- 本地图库系统
- 缩略图墙 WebUI
- 云同步系统
- Sakura Cloud 云端 API
- Android 移动端
- 每日提醒功能
- 分布式爬虫系统
- 环境搭建与运行
- 打包与发布
- 测试
- 使用指南
- 常见问题
- 风险控制
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 有效性,提取用户名和 IDlogin_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):判断是否处理该 URLparse(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 登录流程
- 打开 APP → 登录/注册页
- 使用与桌面端云同步相同的账号登录
- 注册成功后需手动回到登录页登录
- 登录后即可查看云端同步的内容
11. 每日提醒功能
11.1 工作原理
每日提醒不是手机本地闹钟,也不是系统级推送通知。
实际工作流程:
桌面端关注作者 → 下载新作品 → 云同步上传
│
▼
云端记录 follow + update alert
│
▼
云端定时检查(每 5 分钟)
│
▼
到设定时间 → 生成"每日摘要提醒"
│
▼
手机端"发现"页的"更新提醒"区域展示
11.2 设置步骤
- 桌面端登录 Pixiv 并启用云同步
- 桌面端打开缩略图墙 → 关注作者
- 关注作者的新作品经下载后同步到云端
- 手机端登录同一云端账号
- 手机端"我的"页 → 打开"每日更新提醒"开关
- 设置提醒时间(默认时区 Asia/Shanghai)
- 到点后去"发现"页查看更新提醒
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 桌面端(源码运行)
# 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(可选)
# 安装依赖
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 移动端开发
cd sakura_mobile
# 安装依赖
flutter pub get
# 运行(需连接 Android 设备或模拟器)
flutter run
# 静态分析
flutter analyze
# 构建 APK
flutter build apk --release
13.4 分布式爬虫(可选)
# 启动 Redis(需先安装)
redis-server
# 启动 Master
python -m distributed_crawler.scripts.run_master
# 启动 Worker(可启动多个)
python -m distributed_crawler.scripts.run_worker
14. 打包与发布
14.1 桌面 EXE
# 方式一:使用构建脚本
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
scripts\build_mobile_android.bat
输出:sakura_mobile\build\app\outputs\flutter-apk\app-release.apk(约 54 MB)
14.3 复制发布产物
scripts\copy_release_artifacts.bat
将 EXE 和 APK 复制到 releases/ 目录。
14.4 一键打包
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 运行测试
# 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
- 在已登录 Pixiv 的浏览器中使用 Get cookies.txt 插件导出 Cookie
- 打开桌面端,在"登录方式"卡片中保持 Cookie 登录
- 点击 导入 cookies.txt / json,选择导出的文件
- 点击 检测会话 确认 Cookie 有效
- 点击 保存会话 持久化
第二步:下载内容
- 选择平台:Pixiv
- 选择模式:如"作者全部作品"
- 输入目标:作者 ID 或作品链接
- 点击 开始抓取
- 观察右侧进度和日志
输入示例
| 目标类型 | 输入示例 |
|---|---|
| 作者 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 浏览本地图库
- 点击主界面 打开缩略图墙 按钮
- 自动在浏览器中打开本地图库页面
- 可以:搜索、按标签筛选、查看作者、收藏作品、关注作者
16.3 配置云同步
- 勾选 启用 Sakura Cloud 同步
- 点击 账号管理
- 在弹窗中注册或登录云端账号
- 登录成功后自动保存凭证
- 点 测试连接 验证
- 之后下载的内容会自动上传到云端
16.4 使用 X / Twitter 采集
- 在"平台"下拉选择 X / Twitter
- 选择模式:
- 作者媒体:输入作者名(如
nasa或@nasa),自动访问 /media 页 - 单个推文:输入完整推文链接
- 搜索词媒体:输入搜索词,自动搜索媒体
- 作者媒体:输入作者名(如
- 输入目标后点击开始抓取
注意:X 采集需要 Playwright 浏览器,首次使用需
playwright install chromium
16.5 使用小红书采集
- 选择平台:小红书
- 导入包含小红书域名的 Cookie(同 Pixiv 导入方式)
- 选择模式:搜索关键词 / 单篇笔记 / 链接解析
- 输入目标后开始抓取
16.6 手机端使用
- 安装
releases/app-release.apk - 使用与桌面端云同步相同的账号登录
- 底部导航切换页面查看内容
- 在"我的"页开启每日提醒
17. 常见问题
17.1 桌面端登录失败
- 优先使用 Cookie 登录(不是账号密码登录)
- 重新在浏览器导出最新 cookies.txt
- 重新导入后再点 检测会话
- Cookie 失效时重新操作以上步骤
17.2 下载失败
- 检查 Cookie 是否有效(点"检测会话")
- 降低线程数(2-4)
- 增大请求间隔(0.5-1.0 秒)
- 尝试启用代理池
- 确认目标内容是否设置了访问限制(R-18 等)
17.3 手机端看不到内容
- 桌面端是否启用了 云同步 并登录了云端账号
- 下载是否已完成(查看进度和日志)
- 手机端是否使用同一云端账号
- 尝试在手机端下拉刷新
17.4 每日提醒没有内容
- 是否在桌面端关注了作者
- 是否有新作品进入云端
- 是否已超过设定的提醒时间
- 手机端"发现"页查看"更新提醒"
17.5 X 采集失败
- 是否已安装 Playwright Chromium:
playwright install chromium - X Cookie 是否有效(重新导出包含 x.com/twitter.com 的 Cookie)
- 尝试在浏览器中先登录 X,再导出 Cookie
17.6 APK 安装被拦截
- 允许"未知来源应用安装"
- 重新安装一次
- 当前 APK 是调试签名,这是正常现象
17.7 端口被占用
缩略图墙默认使用 8765 端口,如被占用会自动尝试 8766、8767。
18. 风险控制
18.1 已知风险
| 平台 | 风险 | 建议 |
|---|---|---|
| 小红书 | 短时间内连续下载同帖图片触发警告 | 增加随机延迟、模拟浏览行为 |
| Pixiv | 高频请求触发限流 | 控制线程数、使用代理池 |
| X | 异常访问模式检测 | 合理使用、避免长时间连续运行 |
18.2 使用建议
- 合理控制下载频率:不建议长时间连续运行批量任务
- 使用代理池:切换 IP 降低单 IP 请求密度
- Cookie 定期更新:Cookie 过期后重新导入
- 本工具仅供学习研究使用:严禁非法搬运和商业用途
- 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