Files
SakuraHub/使用说明-桌面版与安卓版.md
2026-11-16 20:45:22 +08:00

492 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 樱云同步使用说明(桌面版与安卓版)
更新时间:2026-06-05
## 1. 成品文件位置
建议直接使用 `releases/` 目录下的成品:
- `releases/sakuradownloader.exe`
- `releases/app-release.apk`
- `使用说明-桌面版与安卓版.md`(本文件,位于项目根目录)
对应原始产物来源如下:
- Windows EXE 来源:`dist/sakuradownloader.exe`
- Android APK 来源:`sakura_mobile/build/app/outputs/flutter-apk/app-release.apk`
说明:
- `releases/app-release.apk` 与 `sakura_mobile/build/app/outputs/flutter-apk/app-release.apk` 为同一构建产物;重新打包后请运行 `scripts\copy_release_artifacts.bat` 同步到 `releases/`。
- 当前 Android `release` 包仍然是调试签名,适合自测和个人使用,不建议直接用于正式分发或上架。
## 2. 这个项目现在能做什么
这个项目目前可以分成两部分来理解:
- 桌面端 `sakuradownloader.exe`
负责登录、抓取、下载、整理本地图库、打开缩略图墙、关注作者,以及把内容同步到云端。
- 安卓端 `app-release.apk`
负责登录同一个云端账号后,在手机上浏览图片、漫画、小说、收藏、阅读进度和提醒。
一句话版本:
- 桌面端更像“采集和整理中枢”
- 安卓端更像“个人阅读器”
## 3. Windows 桌面版使用方法
### 3.1 启动
双击 `releases/sakuradownloader.exe` 即可启动。
如果你只是想直接用成品,优先用 `releases/` 里的 EXE,不需要再去 `dist` 里找。
### 3.2 登录 Pixiv
桌面端支持两种方式:
- `Cookie 登录`
- `账号密码登录`
当前项目里更推荐 `Cookie 登录`,也是代码里明确提示的稳定方案。
推荐流程:
1. 在已经登录 Pixiv 的浏览器里,用 `Get cookies.txt` 之类的插件导出 `txt` 或 `json`
2. 打开桌面端
3. 在“登录方式”卡片里保持 `Cookie 登录`
4. 点击 `导入 cookies.txt / json`
5. 导入后可点击 `检测会话`
6. 确认没问题后点击 `保存会话`
补充说明:
- `账号密码登录` 仍可尝试,但 Pixiv 额外验证、二步验证或风控时更容易失败。
- 如果后续抓取突然失效,优先重新导入一次最新 Cookie。
### 3.3 下载 Pixiv 内容
桌面端主界面有“抓取目标”卡片,核心是三项:
- `平台`
- `模式`
- `目标`
Pixiv 常用模式:
- `作者全部作品`
目标里可以填作者 ID,也可以直接贴任意该作者作品链接,程序会自动反查作者。
- `作品 / 漫画`
目标里填作品 ID 或作品链接。
- `文章 / 小说`
目标里填小说 ID、小说链接,或者小说系列链接。
- `关键词`
目标里填关键词,程序先搜索再下载。
常见输入例子:
- 作者 ID
- Pixiv 作品链接
- Pixiv 小说链接
- 小说系列链接
操作步骤:
1. 选择 `平台 = Pixiv`
2. 选择合适的 `模式`
3. 在 `目标` 输入框里填 ID 或链接
4. 点击 `开始抓取`
5. 等待右侧日志和进度完成
下载后的内容会进入本地图库,同时写入本地数据库,后续缩略图墙、收藏和作者视图都会用到这些数据。
### 3.4 打开缩略图墙
桌面主界面有一个明显按钮:
- `打开缩略图墙`
点它后,程序会在本机启动一个本地服务,并用浏览器打开本地图库页面。
默认本地地址通常是:
- `http://127.0.0.1:8765`
如果端口被占用,程序会自动尝试 `8766` 或 `8767`。
缩略图墙适合做这些事:
- 浏览本地图片和漫画
- 默认不显示小说
- 搜索标题、作者、简介
- 按标签筛选
- 查看作者
- 收藏作品
- 进入“关注同步”页维护关注作者
- 进入“X 关注”页维护 X 作者
### 3.5 在缩略图墙里关注作者
“每日提醒”要先有“关注作者”这一步。
当前仓库里,明确可见的关注入口在桌面端缩略图墙。
有两种常用方式:
- 方式一:在作品详情里点 `关注作者`
- 方式二:进入 `关注同步` 页,手动填写 `作者 ID`,再点 `添加关注`
`关注同步` 页面里还能做两件事:
- 导入 `Pixiv Cookie`
- 点击 `同步关注作者`
注意:
- 当前这套“关注同步”页面还是围绕 Pixiv 作者 ID 和 Pixiv Cookie 做的。
- 另外已经新增了 `X 关注` 区域,可以手动添加 X 用户名并做同步。
### 3.6 云同步
如果你想让手机端看到桌面端内容,必须用到云同步。
桌面端左侧有 `云同步` 卡片,使用方法如下:
1. 勾选 `启用 Sakura Cloud 同步`
2. 点击 `账号管理`
3. 在弹窗里登录或注册云端账号
4. 登录成功后,云同步凭证会自动保存
5. 回到主界面后可以点 `测试连接`
项目当前代码里写死的默认云端地址是:
- `http://api.kunkunxiaomao.top:8000`
登录成功并开启云同步后:
- 新下载完成的 Pixiv 内容会自动上传到 Sakura Cloud
- 手机端登录同一个账号后就能刷新看到内容
## 4. Android 安卓版使用方法
### 4.1 安装
安装 `releases/` 目录下的 APK:
- `releases/app-release.apk`
如果系统拦截安装,按 Android 的常规流程允许“未知来源应用安装”即可。
再次提醒:
- 当前 APK 是调试签名,不适合正式上架,只适合自测和个人使用。
### 4.2 登录
安卓端打开后会先进入登录/注册页。
使用方法:
1. 用和桌面端云同步相同的账号登录
2. 如果没有账号,可以先注册
3. 注册成功后不会自动登录,需要回到登录页手动登录一次
只有登录同一个云端账号,桌面端同步上去的图片、漫画、小说、收藏和提醒才能在手机上看到。
### 4.3 安卓端底部导航
当前底部共有 5 个页签:
- `发现`
- `图片`
- `漫画`
- `书架`
- `我的`
各页作用如下。
### 4.4 发现页
`发现` 页更像首页和动态页,主要展示:
- 最近浏览的图片
- 最近浏览的漫画
- 最近阅读的小说
- 更新提醒
如果你开启了“每日提醒”,提醒摘要会出现在这里的 `更新提醒` 区域。
### 4.5 图片页
`图片` 页展示云端同步过来的插画内容。
可以做的操作包括:
- 看缩略图列表
- 点进详情
- 收藏 / 取消收藏
- 下载到本地
- 编辑图片信息
- 删除图片
### 4.6 漫画页
`漫画` 页现在是按漫画分组进入,不再是单张图散着看。
实际体验上会更像:
- 先看到一组漫画入口
- 点进去后连续浏览整组内容
- 支持整组下载
这也是当前项目里已经调整过的重点之一。
### 4.7 书架页
`书架` 页现在是三列彩色方块风格。
特点:
- 固定三列
- 系列小说会优先按书名归档
- 单篇小说也能单独展示
- 点击系列后会先弹出章节选择
- 阅读记录会影响排序,最近看的更靠前
### 4.8 小说阅读页
小说阅读器已经改成更适合长期阅读的样子,主要能力有:
- 自动分页
- 记住当前阅读进度
- 收藏 / 取消收藏
- 当前页翻译
- 原文 / 译文切换
- 底部阅读设置面板
- 系列章节列表切换
阅读页右上角常用功能:
- 收藏
- 翻译当前页
- 删除小说
底部阅读设置面板支持:
- `字体大小`
- `行高`
- `背景色`
- `章节切换`
如果是系列小说,底部面板里会直接列出章节,点一下就能切换。
### 4.9 我的页
`我的` 页负责这些内容:
- 用户资料
- 云端空间占用
- 我的收藏
- 收藏图片
- 收藏小说
- 每日更新提醒
- 退出登录
其中“每日更新提醒”就在这里设置开关和时间。
## 5. 每日提醒功能的真实使用链路
这一节我按当前仓库里的真实实现来写,不按想象写。
### 5.1 先说结论
当前“每日提醒”不是手机本地闹钟,也不是系统级推送通知。
它更准确的工作方式是:
- 云端保存你关注作者产生的更新 alert
- 云端到点后把这些未读 alert 汇总成一条“每日摘要提醒”
- 手机端在 `发现` 页的 `更新提醒` 区域把它显示出来
也就是说:
- 它是“云端摘要提醒”
- 不是“手机本地定时弹通知”
### 5.2 开关位置
安卓端位置:
1. 登录后进入 `我的`
2. 找到 `每日更新提醒`
3. 打开开关
4. 点 `提醒时间 HH:MM` 选择时间
5. 需要看最近提醒或已关注作者时,点 `打开提醒中心`
当前支持保存的字段包括:
- 是否开启
- 小时
- 分钟
- 时区
默认时区是:
- `Asia/Shanghai`
### 5.3 提醒真正依赖什么
要让提醒真正有内容,至少要满足下面这些条件:
1. 你已经在桌面端维护了“关注作者”
2. 桌面端已经登录并启用了云同步
3. 手机端和桌面端用的是同一个云端账号
4. 关注作者确实有新内容进入了云端 alert 流程
5. 到了你设定的提醒时间
如果只是把手机上的提醒开关打开,但桌面端没有把作者更新同步进云端,那么手机端不会凭空出现提醒。
### 5.4 推荐使用步骤
按当前代码,最稳妥的使用顺序建议这样走:
1. 在桌面端登录 Pixiv,优先用 Cookie
2. 在桌面端启用 `云同步`,并登录 Sakura Cloud 账号
3. 打开 `缩略图墙`
4. 在作品详情里点 `关注作者`,或者在 `关注同步` 页面手动 `添加关注`
5. 如果要同步 X,就到 `X 关注` 区域添加用户名后再点 `同步 X 关注`
6. 让关注作者的新作品经过桌面端下载,并同步到云端
7. 在手机端登录同一个云端账号
8. 到 `我的` 页打开 `每日更新提醒`,或者直接进入 `提醒中心`
9. 设定提醒时间
10. 到点后去 `发现` 页查看 `更新提醒`
### 5.5 当前代码里已经确认到的事实
我在仓库里确认到了下面几件事:
- 手机端“我的”页明确有 `每日更新提醒` 开关和时间选择
- 手机端“发现”页明确会展示 `更新提醒`
- 云端会每 5 分钟检查一次提醒摘要
- 云端启动时也会先跑一次提醒摘要检查
- 云端只会给已开启提醒的用户生成摘要
- 同一天内已经发过一次摘要,就不会重复生成同一天第二条摘要
摘要标题格式类似:
- `每日 09:00 更新提醒`
摘要正文内容类似:
- 你关注的作者有多少条新动态
- 这些动态来自哪些平台
- 还会尽量带上最近几个作者名字
### 5.6 一个很重要的现实限制
虽然手机端文案写的是:
- `Pixiv / X 博主`
现在仓库里已经同时接通了 `Pixiv` 和 `X` 的关注管理:
- 桌面端既有 Pixiv 风格的作者关注,也有 X 关注同步入口
- 桌面端向云端写入 follow / alert 的代码路径也已经覆盖 Pixiv 和 X
换句话说:
- 后端模型和提醒摘要对 `Pixiv / X` 是通用设计
- 但当前仓库里我真正看到的、已经接上的前端入口和 alert 创建链路,主要落在 Pixiv
所以更稳妥的理解是:
- 现在请把“每日提醒”当成 `Pixiv / X 关注作者更新摘要` 来使用
- X 的判新依赖作者时间线,稳定性通常比纯媒体页更好
### 5.7 关于“同步关注作者”按钮的补充说明
缩略图墙里的 `同步关注作者` 按钮,当前明确作用是:
- 用已保存的 Pixiv Cookie 去拉取关注作者的新作品
- 把新作品下载到本地图库
- `同步 X 关注` 会按时间线检查 X 作者的新动态,并把结果写到云端 follow / alert
当前我能明确确认的提醒写入路径,是:
- 桌面端 Pixiv / X 内容在云同步过程中
- 如果作者已经在本地关注列表里
- 程序就会向云端写入 follow 和 update alert
因此更稳妥的使用建议是:
- 把 `同步关注作者` 当作“本地补新”功能
- 把 `同步 X 关注` 当作“X 作者新动态补新”功能
- 把“真正用于手机提醒的数据来源”理解为“已经被桌面端同步进云端的更新记录”
## 6. 常见问题
### 6.1 桌面端登录失败怎么办
优先做这几件事:
1. 改用 `Cookie 登录`
2. 重新导出最新 cookies.txt
3. 重新导入后再点 `检测会话`
账号密码登录不是不能用,但稳定性不如 Cookie。
### 6.2 手机端登录了还是没内容
通常优先排查下面几点:
1. 桌面端是否启用了 `云同步`
2. 桌面端是否真的登录了云端账号
3. 下载是否已经完成
4. 下载完成后是否已经同步到云端
5. 手机和桌面是否是同一个账号
### 6.3 每日提醒开了却看不到提醒
按顺序检查:
1. 是否已经在桌面端关注了作者
2. 是否有新作品真的进入云端
3. 是否已经超过你设置的提醒时间
4. 手机端是否登录同一账号
5. 是否去 `发现` 页看 `更新提醒`
再强调一次:
- 这不是手机本地闹钟
- 开关打开后不会立刻弹系统通知
- 它是云端汇总后的应用内提醒
### 6.4 安卓安装被拦截
这是常见现象,尤其是未上架、未正式签名的测试包。
当前处理方式通常是:
- 允许未知来源安装
- 再重新安装一次
### 6.5 Android 包能不能直接拿去正式发给别人
不建议。
原因很直接:
- 当前 `app-release.apk` 仍是调试签名
- 更适合自测或小范围个人使用
- 如果要正式分发,最好重新做正式 keystore 和正式签名
## 7. 当前版本的整理结果
分发成品时,建议使用 `releases/` 目录:
- `releases/sakuradownloader.exe`
- `releases/app-release.apk`
用户手册位于项目根目录:`使用说明-桌面版与安卓版.md`