Files
SakuraHub/使用说明-桌面版与安卓版.md
T

491 lines
13 KiB
Markdown
Raw Normal View History

2026-11-16 20:45:22 +08:00
# 樱云同步使用说明(桌面版与安卓版)
更新时间: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`