25 KiB
25 KiB
樱云下载器 — 优化方案与功能规划
版本:2.1.0-draft | 日期:2026-06-24 基于代码审计报告、产品文档、CHANGELOG 及全仓库源码分析制定
目录
0. 优先级定义
| 等级 | 含义 | 建议时间 |
|---|---|---|
| P0 | 安全漏洞 / 数据风险 / 系统崩溃 | 1 周内 |
| P1 | 核心功能阻断或严重缺陷 | 2–4 周 |
| P2 | 功能缺口 / 重要增强 | 1–2 月 |
| P3 | 体验优化 / 锦上添花 | 按需排期 |
| P4 | 架构演进 / 平台扩展 | 中长期规划 |
1. P0 — 安全与基础设施
来源:代码审计报告 Critical 项 + 其他发现
1.1 JWT 密钥强制生产配置
- 现状:
sakura_cloud/core/config.py中jwt_secret_key默认值为"change-this-secret-in-production",任何人都可伪造 JWT - 方案:启动时检测是否为已知默认值,若是则拒绝启动并输出明确的错误信息,引导运维设置
JWT_SECRET_KEY环境变量 - 影响范围:
sakura_cloud/core/config.py、sakura_cloud/core/security.py
1.2 数据库凭据与 MinIO 凭据硬编码
- 现状:
- PostgreSQL 默认凭据
sakura:sakura - MinIO 默认凭据
minioadmin:minioadmin
- PostgreSQL 默认凭据
- 方案:同 JWT 策略——启动时检测默认值,若未被覆盖则拒绝启动;为 MinIO 增加随机密码生成脚本
- 影响范围:
sakura_cloud/core/config.py、部署文档
1.3 桌面端 → 云端启用 HTTPS
- 现状:
DEFAULT_CLOUD_API = "http://api.kunkunxiaomao.top:8000"使用明文 HTTP,用户凭据和文件明文传输 - 方案:
- 短期:支持 HTTP 但增加显式警告弹窗("当前使用非加密连接,凭据可能被窃取")
- 长期:服务器配置 SSL 证书(Let's Encrypt / 自签名),客户端默认改为 HTTPS,初次连接时做证书校验引导
- 影响范围:
pixiv_app/gui/app.py、pixiv_app/core/cloud_sync.py、云端 nginx/Caddy 配置
1.4 登录接口限流
- 现状:
/api/v1/auth/login无限流,可暴力破解 - 方案:对
/login、/register、/token/refresh增加 IP 级别速率限制(如每分钟 5 次),使用 Redis 或内存计数器实现 - 影响范围:
sakura_cloud/api/v1/endpoints/auth.py、新增限流中间件
1.5 笔趣阁插件 AES 密钥随机化
- 现状:
plugins/biquge/plugin.py中 AES 密钥和 IV 从硬编码字符串经 MD5 派生,固定 IV 下的 CBC 模式可被已知明文攻击 - 方案:
- 每次加密使用随机 IV(
os.urandom(16)),与密文一起传输 - 密钥从用户配置或安全随机源派生,而非硬编码
- 每次加密使用随机 IV(
- 影响范围:
plugins/biquge/plugin.py
1.6 Chrome --no-sandbox 移除
- 现状:小红书插件使用
--no-sandbox禁用 Chromium 沙箱,浏览器以完整 OS 权限运行不受信任的外部内容 - 方案:移除
--no-sandbox。若在 Docker/root 环境下必须使用,改为配置--cap-add=SYS_ADMIN或 seccomp profile - 影响范围:
plugins/xiaohongshu/plugin.py
1.7 Firebase 初始化竞态修复
- 现状:
push_notifications.dart中_initialized = true在await Firebase.initializeApp()之前设置,若初始化失败则永久不再重试 - 方案:将
_initialized = true移到await Firebase.initializeApp()成功之后 - 影响范围:
sakura_mobile/lib/src/core/push_notifications.dart
1.8 ProxyPool 多线程数据竞争
- 现状:
current_index无锁读写、working_proxies并发修改、fail_count/success_count非原子递增 - 方案:引入
threading.Lock保护所有对共享数据的写操作;或将current_index改为itertools.cycle+ 原子计数器 - 影响范围:
pixiv_app/core/proxy_pool.py
1.9 敏感文件 .gitignore 完善
- 现状:
.env.cloud.example已提供模板,但不清楚.env是否在.gitignore中;会话文件app_session.json可能被误提交 - 方案:在
.gitignore中显式添加*.env(除.example)、app_session.json、runtime/、*.db、*.key - 影响范围:
.gitignore
2. P1 — 核心体验缺陷
来源:代码审计报告 High/Medium 项 + 已知 bug + 功能缺口
2.1 手机端 recentUpdatesOnly 死开关修复
- 现状:
gallery_tab.dart中recentUpdatesOnly状态变量只控制 Chip 高亮,从未作为 API 参数传入_load(),切换无实际效果 - 方案:在
_load()中将recentUpdatesOnly转换为order=updated_at或后端新增recent_only查询参数;或如果后端暂时不支持,先移除该 Chip - 影响范围:
sakura_mobile/lib/src/pages/tabs/gallery_tab.dart
2.2 Legado 书源搜索引擎完善
- 现状:6 个默认种子源
searchUrl/searchListRule全为 null,CSS 选择器解析不支持 class/ID/属性选择器,GBK 编码无容错 - 方案(分两步):
- 2.2a 引擎层:扩展 CSS 选择器支持 class(
.classname)、ID(#id)、属性([attr=val])、后代(A B)选择器;GBK 解码增加容错参数 - 2.2b 源数据层:用真实可用的书源 JSON 替换默认种子源,或提供从 Legado 仓库一键导入的引导流程
- 2.2a 引擎层:扩展 CSS 选择器支持 class(
- 影响范围:
legado_rule_parser.dart、legado_engine.dart、source_manager.dart
2.3 手机端发现页滚动卡死修复
- 现状:发现页 Feed 向上滚动时可能卡在底部
- 方案:排查
feed_tab.dart中的ScrollController和分页加载逻辑,确保加载更多后正确更新hasMore状态,以及ListView的addPostFrameCallback不产生死循环 - 影响范围:
sakura_mobile/lib/src/pages/tabs/feed_tab.dart
2.4 Web 管理后台页面完善
- 现状:普通用户 Web 端详情页已从占位改为真实加载,但管理后台可能仍有死角
- 方案:
- 完成管理员端用户管理、内容审核、统计面板页面
- 普通用户端确保图片/漫画/小说三种内容类型均有完整的列表+详情页
- 影响范围:
sakura_admin_web/
2.5 云同步上传失败队列与断点续传
- 现状:
SAKURA_CLOUD_V1_STATUS.md明确标注"上传失败队列与断点恢复细节"尚未完成 - 方案:
- 桌面端新增
sync_failures表记录上传失败的文件,支持自动/手动重试 - 上传分片支持断点续传(保存已上传分片索引)
- 云端
upload/complete接口增加分片校验
- 桌面端新增
- 影响范围:
pixiv_app/core/cloud_sync.py、sakura_cloud/api/v1/endpoints/upload.py
2.6 Alembic 数据库迁移完善
- 现状:SAKURA_CLOUD_V1_STATUS 标注 Alembic 迁移尚未完成
- 方案:补全所有模型的 Alembic migration 脚本,确保
alembic upgrade head一键建库;新增 CI 中检查迁移一致性 - 影响范围:
sakura_cloud/migrations/
2.7 手机端 App 正式签名
- 现状:APK 使用调试签名,不适合正式分发;README 和用户手册均强调此限制
- 方案:
- 生成正式 keystore
- 更新
sakura_mobile/android/app/build.gradle.kts签名配置 - 文档更新,区分 debug/release 构建流程
- 影响范围:
sakura_mobile/android/、构建脚本
2.8 桌面端 Cookie 过期自动检测与提醒
- 现状:Pixiv Cookie 过期后抓取静默失败,用户需手动排查
- 方案:
- 在每次抓取前自动检测会话有效性(已有「检测会话」按钮逻辑,改为自动调用)
- Cookie 将过期或已过期时弹窗提醒并引导重新导入
- 影响范围:
pixiv_app/core/auth.py、pixiv_app/gui/app.py
2.9 下载失败自动重试与错误分类
- 现状:
runtime/executor.py已有基本重试与错误分类,但未区分限流(429)、临时故障(5xx)、权限错误(403/404) - 方案:
- 429 → 自动退避重试(指数退避 + 抖动)
- 5xx → 有限重试(最多 2 次)
- 403/404 → 不重试,直接标记失败
- 失败原因写入
download_tasks表便于排查
- 影响范围:
pixiv_app/runtime/executor.py、pixiv_app/tasks/models.py
2.10 图库搜索性能优化
- 现状:图库 SQLite 查询在大数据量下(数万条作品)可能变慢,标签模糊搜索使用
LIKE '%keyword%'无法走索引 - 方案:
- 对
artworks.title、artists.name、tags.name建立索引 - 标签搜索改为 FTS5 全文索引
- 云端的
gallery查询为include_total参数已有优化,进一步对artworks.created_at、artworks.artist_id建立联合索引
- 对
- 影响范围:
pixiv_app/core/library.py、sakura_cloud/models/artwork.py
3. P2 — 功能完善与增强
3.1 手机端推送通知(FCM)
- 现状:Firebase 已集成但推送链路不完整;当前"每日提醒"仅是应用内摘要,非系统级推送
- 方案:
- 完成 FCM token 注册与服务端对接
- 云端提醒生成后通过 FCM 发送系统通知
- 点击通知直接跳转到对应内容
- 用户可配置"仅 Wi-Fi 下推送"、"免打扰时段"
- 影响范围:
sakura_mobile/lib/src/core/push_notifications.dart、sakura_cloud/services/push.py
3.2 插件市场在线对接
- 现状:
PluginMarketClient为占位类,仅支持本地文件系统发现插件 - 方案:
- 云端提供
/api/v1/plugins/端点(列表、下载、版本检查) - 桌面端「插件管理」面板增加"在线市场"标签页
- 支持一键安装/更新/卸载
- 插件版本兼容性检查
- 云端提供
- 影响范围:
pixiv_app/core/plugin/market.py、pixiv_app/gui/plugin_panel.py、sakura_cloud/新增端点
3.3 视频下载与播放支持
- 现状:X/Twitter 插件可抓取视频文件,但本地图库和缩略图墙未针对视频做优化;手机端无视频播放页
- 方案:
- 缩略图墙增加视频缩略图(自动截取首帧或使用平台提供的 thumbnail)
- 手机端新增视频播放页(基于
video_player插件) - 图库列表支持视频类型筛选
- 影响范围:
pixiv_app/core/gallery_service.py、sakura_mobile/新增页面
3.4 阅读进度跨设备同步
- 现状:手机端小说阅读器记录阅读进度,但仅本地存储(
online_reading_history.dart) - 方案:
- 云端新增
/api/v1/reading-progress/端点(GET/PUT) - 手机端在进度变更时自动上报云端
- 桌面端缩略图墙也可展示阅读进度
- 多设备间同账号自动同步阅读位置
- 云端新增
- 影响范围:
sakura_mobile/lib/src/core/online_reading_history.dart、sakura_cloud/新增端点
3.5 内容合集 / 专辑功能
- 现状:作品可以按作者、标签归类,但没有用户自定义合集的能力
- 方案:
- 桌面端和手机端均支持创建"合集",将任意作品(图片/漫画/小说)归入合集
- 合集支持排序、封面设置、备注
- 云端同步合集数据
- 影响范围:
pixiv_app/core/library.py(新增表)、sakura_cloud/models/(新增模型)、sakura_mobile/新增页面
3.6 漫画连续阅读模式增强
- 现状:手机端已有漫画分组与连续阅读,但体验可以更流畅
- 方案:
- 左右滑动翻页(当前可能仅支持上下滚动)
- 预加载下一页/上一页(当前页 ± 2 页)
- 阅读进度条(当前页/总页数)
- 双击缩放、长按保存
- 影响范围:
sakura_mobile/lib/src/pages/online_manga_reader_page.dart
3.7 批量导出功能
- 现状:用户可通过缩略图墙浏览,但无法批量导出原图
- 方案:
- 缩略图墙增加"批量选择 → 导出原图"功能
- 支持按作者/标签/收藏筛选后全选导出
- 导出格式:原图 ZIP 包或保持目录结构
- 影响范围:
pixiv_app/core/gallery_service.py、缩略图墙前端模板
3.8 X (Twitter) 作者时间线监控
- 现状:X 插件支持抓取作者媒体和单个推文,但缺少"监控作者新推文"的主动检测
- 方案:
- 桌面端新增"X 监控"面板,可添加监控的 X 用户名
- 定时轮询作者时间线,检测新推文 → 自动下载 → 写入云端关注提醒
- 与现有每日提醒系统打通
- 影响范围:
plugins/x/、pixiv_app/core/x_media_service.py
3.9 下载内容去重增强
- 现状:
download_tasks表有fingerprint唯一约束,artwork_files.content_hash字段已预留但默认空字符串 - 方案:
- 下载完成后计算文件 SHA256 并写入
content_hash - 新下载前先检查
content_hash是否已存在,跳过重复文件 - 缩略图墙可展示"重复文件"列表,支持清理
- 下载完成后计算文件 SHA256 并写入
- 影响范围:
pixiv_app/core/downloader.py、pixiv_app/core/library.py
3.10 代理池健康度评分
- 现状:代理有
fail_count/success_count但仅用于简单标记失败 - 方案:
- 引入代理健康度评分(成功率、响应延迟、可用性百分比)
- 代理按健康度排序,优先使用高分代理
- 健康度过低的代理自动移出池
- 代理池 UI 展示健康度统计
- 影响范围:
pixiv_app/core/proxy_pool.py
4. P3 — 体验优化与锦上添花
4.1 桌面端深色模式
- 现状:GUI 锁定
ctk.set_appearance_mode("light") - 方案:增加"外观"设置项——浅色 / 深色 / 跟随系统;
customtkinter原生支持dark模式,改动极小 - 影响范围:
pixiv_app/gui/app.py
4.2 缩略图墙 UI 现代化
- 现状:缩略图墙是本地 WebUI(Jinja2 模板),功能齐全但 UI 风格较为基础
- 方案:
- 引入轻量 CSS 框架(如 Pico.css 或 Water.css)美化
- 支持网格/列表视图切换
- 图片懒加载(当前可能一次性加载所有缩略图)
- 虚拟滚动(大量作品时性能优化)
- 影响范围:
pixiv_app/core/gallery_service.py、模板文件
4.3 手机端首页个性化配置
- 现状:发现页展示"最近浏览的图片/漫画/小说"和"更新提醒"
- 方案:
- 用户可选择发现页展示哪些模块(图片/漫画/小说/提醒)
- 支持拖拽排序模块
- "继续阅读"模块(直接从上次阅读位置进入)
- 影响范围:
sakura_mobile/lib/src/pages/tabs/feed_tab.dart
4.4 下载速度与流量统计
- 现状:桌面端有进度条但无历史统计
- 方案:
- 记录每次下载的文件大小、耗时
- 主界面增加"本次会话下载量"和"总计下载量"统计
- 可查看每日/每周下载量趋势图(可选,使用 matplotlib)
- 影响范围:
pixiv_app/gui/app.py、pixiv_app/core/library.py
4.5 国际化(i18n)支持
- 现状:GUI 和手机端 UI 均为中文硬编码
- 方案:
- 桌面端:提取所有 UI 字符串到 JSON 语言文件,支持中文/英文/日文
- 手机端:使用 Flutter
intl/easy_localization实现多语言 - 优先完成英文翻译以扩大用户群
- 影响范围:全局 UI
4.6 错误日志收集与诊断
- 现状:日志分散在
日志/目录和终端输出,排查问题需手动翻找 - 方案:
- 桌面端增加"一键导出诊断包"按钮(日志 + 配置 + 数据库状态摘要,压缩为 ZIP)
- 手机端增加"上传诊断日志"功能
- 云端增加错误聚合面板(按错误类型/时间统计)
- 影响范围:
pixiv_app/、sakura_mobile/、sakura_cloud/
4.7 桌面端系统托盘与后台运行
- 现状:关闭 GUI 窗口即退出程序
- 方案:
- 最小化到系统托盘(使用
pystray或customtkinter配合系统托盘库) - 托盘菜单:显示/隐藏窗口、开始/停止抓取、退出
- 下载完成后托盘气泡提示
- 最小化到系统托盘(使用
- 影响范围:
pixiv_app/gui/app.py
4.8 自动更新检查
- 现状:用户需手动关注 releases 目录获取新版本
- 方案:
- 桌面端启动时检查云端最新版本号
- 有新版本时提示下载,可选"自动下载 → 下次启动替换"
- 手机端同理(检查 APK 版本号)
- 影响范围:
pixiv_app/gui/app.py、sakura_mobile/lib/src/app.dart、sakura_cloud/新增版本检查端点
5. P4 — 长期架构演进
5.1 桌面端从 CustomTkinter 迁移到更现代化的 GUI 框架
- 理由:CustomTkinter 功能有限,深色模式、动画、富文本等支持较弱;Windows 11 下风格略显过时
- 候选方案:
- Tauri (Rust + Web 前端):体积小、性能好、现代 UI,但需重写全部 Python 逻辑为 Rust 或通过 sidecar 通信
- Electron + Python 后端:重用现有 Python 下载引擎,Electron 负责 UI,但体积大(~150MB+)
- PySide6 / PyQt6:纯 Python 方案,迁移成本最低,支持 QSS 样式和丰富控件
- Flet (Flutter for Python):用 Python 写 Flutter UI,可与现有 Flutter 移动端共享设计语言
- 建议:优先评估 Flet(与 Flutter 移动端风格统一、纯 Python)或 PySide6(迁移成本最低)。不宜急于重写,等 P0/P1 完成后评估
5.2 iOS 客户端
- 理由:当前仅支持 Android,iOS 用户无法使用
- 方案:
- Flutter 跨平台特性使得 iOS 适配成本较低(大部分 Dart 代码可复用)
- 需额外处理:iOS 文件系统权限、后台任务限制、APNs 推送替代 FCM
- 需要 Apple Developer Program 账号($99/年)用于签名分发
- 影响范围:
sakura_mobile/ios/(生成)、sakura_mobile/lib/(少量平台适配)
5.3 Web 端 PWA(渐进式 Web 应用)
- 理由:桌面端 EXE 体积大(~68MB),部分用户只希望轻量浏览
- 方案:
- 将缩略图墙升级为 PWA(Service Worker + 离线缓存 + 可安装到桌面)
- 或单独开发
sakura_web前端项目替代当前sakura_admin_web
- 影响范围:
sakura_admin_web/或新建sakura_web/
5.4 分布式爬虫完善
- 现状:
distributed_crawler/目录有 Master-Worker 架构但尚不完整 - 方案:
- 补全 Worker 节点注册、心跳、任务分配
- Master 面板(Web UI)展示各 Worker 状态和任务进度
- Docker Compose 一键部署 Master + N Workers
- 影响范围:
distributed_crawler/
5.5 AI 辅助功能
- 理由:PaddleOCR 已集成,可在其基础上扩展更多 AI 能力
- 方案:
- AI 标签自动生成:对下载的图片使用轻量视觉模型(如 MobileNet/EfficientNet)自动打标签
- 翻译增强:手机端小说翻译当前仅支持"当前页翻译",可升级为整本翻译 + 双语对照
- 图片去重:基于感知哈希(pHash/dHash)的相似图片检测
- 内容安全扫描:对上传至云端的内容进行自动安全审核(NSFW 检测)
- 影响范围:
pixiv_app/core/ocr.py、sakura_cloud/services/ocr.py
5.6 多用户/家庭共享
- 现状:云同步为单用户设计,无分享功能
- 方案:
- 云端新增"家庭组"/"共享空间"概念
- 用户可邀请其他账号加入共享空间
- 共享空间内的内容(图库/小说/漫画)成员均可访问
- 权限控制:管理员/编辑/只读
- 影响范围:
sakura_cloud/新增模型与端点、手机端新增分享页面
6. 实施路线图
第一阶段:安全加固(第 1–2 周)
P0-1 JWT 密钥强制生产配置 ████████░░░░░░░░ 1d
P0-2 数据库/MinIO 凭据强制覆盖 ████████░░░░░░░░ 1d
P0-3 HTTPS 支持 + 警告 ████████████░░░░ 1.5d
P0-4 登录接口限流 ████████░░░░░░░░ 1d
P0-5 笔趣阁 AES 随机化 ████░░░░░░░░░░░░ 0.5d
P0-6 Chrome --no-sandbox 移除 ████░░░░░░░░░░░░ 0.5d
P0-7 Firebase 初始化竞态修复 ████░░░░░░░░░░░░ 0.5d
P0-8 ProxyPool 线程安全 ████████░░░░░░░░ 1d
P0-9 .gitignore 完善 ████░░░░░░░░░░░░ 0.5d
────────────────────────────────────────────────────────
小计约 7.5 人天
第二阶段:体验修复(第 3–6 周)
P1-1 手机端死开关修复 ████░░░░░░░░░░░░ 0.5d
P1-2 Legado 搜索引擎完善 ████████████████ 4d
P1-3 发现页滚动卡死 ████████░░░░░░░░ 2d
P1-4 Web 管理后台完善 ████████████░░░░ 3d
P1-5 上传失败队列 + 断点续传 ████████████████ 4d
P1-6 Alembic 迁移 ████████░░░░░░░░ 2d
P1-7 正式签名 ████░░░░░░░░░░░░ 1d
P1-8 Cookie 过期自动检测 ████████░░░░░░░░ 2d
P1-9 下载失败重试优化 ████████░░░░░░░░ 2d
P1-10 图库搜索性能 ████████████░░░░ 3d
────────────────────────────────────────────────────────
小计约 23.5 人天
第三阶段:功能增强(第 7–14 周)
P2-1 FCM 推送通知 ████████████████ 5d
P2-2 插件市场在线对接 ████████████████ 5d
P2-3 视频下载与播放 ████████████░░░░ 4d
P2-4 阅读进度跨设备同步 ████████████░░░░ 4d
P2-5 内容合集/专辑 ████████████████ 5d
P2-6 漫画连续阅读增强 ████████░░░░░░░░ 3d
P2-7 批量导出 ████████████░░░░ 4d
P2-8 X 作者时间线监控 ████████████░░░░ 4d
P2-9 下载去重增强 ████████░░░░░░░░ 3d
P2-10 代理池健康度评分 ████████░░░░░░░░ 3d
────────────────────────────────────────────────────────
小计约 40 人天
第四阶段及以后(按需排期)
P3-1 深色模式 ████░░ 1d
P3-2 缩略图墙 UI 现代化 ██████ 2d
P3-3 首页个性化 ██████ 2d
P3-4 下载统计 ████░░ 1.5d
P3-5 国际化 ██████ 3d
P3-6 错误诊断包 ██████ 2d
P3-7 系统托盘 ██████ 2d
P3-8 自动更新 ██████ 2d
P4-X 长期架构演进 TBD
────────────────────────────────────────────────────────
小计约 15.5 人天
关键里程碑
| 里程碑 | 时间 | 交付物 |
|---|---|---|
| M1: 安全基线 | 第 2 周末 | 所有 P0 项修复完成,安全审计复测通过 |
| M2: 体验基线 | 第 6 周末 | 所有 P1 项修复完成,核心链路无阻断 |
| M3: 功能补全 | 第 14 周末 | P2 主要项完成,推送/插件市场/跨设备进度同步可用 |
| M4: 体验升级 | 第 20 周末 | P3 项完成,深色模式/国际化/自动更新上线 |
附录:已完成功能清单(便于对照)
| 模块 | 已具备能力 |
|---|---|
| 桌面端 | 多平台抓取、Cookie/密码登录、插件系统、本地图库 SQLite、缩略图墙 WebUI、云同步、代理池、任务队列 + 增量同步、OCR |
| 云端 | FastAPI REST API、JWT 认证、图库/小说/文件 CRUD、关注管理、每日提醒摘要、分片上传、健康检查 |
| 手机端 | 登录注册、发现/图片/漫画/书架/我的 五个标签页、小说阅读器(分页/收藏/翻译/进度)、漫画分组阅读、书源管理+Legado 引擎、在线搜索、FCM(部分) |
| 插件 | Pixiv、X/Twitter、小红书、笔趣阁、长佩文学、AO3 |
| DevOps | 一键构建 EXE/APK、Docker Compose 部署、Alembic 迁移 |
本文档由代码审计报告、产品文档、CHANGELOG、SAKURA_CLOUD_V1_STATUS 及全仓库源码分析综合生成,供开发排期与需求评审参考。