# 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*