20 KiB
APP 端问题分析与解决方案
更新日期:2026-06-14 范围:Sakura Mobile (Flutter) + Sakura Cloud (FastAPI 后端) + Sakura Downloader (Python 桌面端) 说明:本文档仅提供问题分析和修改方案,不包含实际代码改动。
问题一:APP 莫名其妙跳转到 "dakura" 用户
问题现象
APP 在使用过程中会突然切换到 "dakura" 用户身份,导致看到的是其他用户的数据而并非自己的内容。
根因分析
经过对全部代码的排查,问题出在 Session 持久化缺少用户隔离机制。涉及以下关键位置:
1. 移动端 Session 存储无用户绑定 (sakura_mobile/lib/src/core/session.dart)
文件位置: sakura_mobile/lib/src/core/session.dart 第 44-52 行
static const _baseUrlKey = 'sakura.baseUrl';
static const _accessTokenKey = 'sakura.accessToken';
Future<void> _load() async {
final prefs = await SharedPreferences.getInstance();
state = SessionState(
baseUrl: prefs.getString(_baseUrlKey) ?? defaultCloudApi,
accessToken: prefs.getString(_accessTokenKey) ?? '',
);
问题: SharedPreferences 使用固定 key sakura.accessToken 存储 token,不绑定任何用户标识。当存在以下情况时会发生串号:
- 同一设备上先后登录过不同账号(如 "dakura" 和当前用户)
- SharedPreferences 中的旧 token 未完全清除
- App 从后台恢复时读取了旧的/缓存的 token
- 多进程/多任务环境下 SharedPreferences 跨进程同步延迟
2. 登录流程缺少旧 Session 清理 (sakura_mobile/lib/src/core/session.dart 第 70-86 行)
Future<void> login(String usernameOrEmail, String password) async {
state = state.copyWith(loading: true, error: null);
try {
final api = SakuraApiClient(baseUrl: state.baseUrl);
final tokens = await api.login(usernameOrEmail, password);
final accessToken = tokens['access_token']?.toString() ?? '';
final prefs = await SharedPreferences.getInstance();
await prefs.setString(_accessTokenKey, accessToken);
问题: 登录时直接覆盖 _accessTokenKey,但如果 SharedPreferences 写入失败或未完全刷盘,旧 token 仍然存在。没有先清除旧 token 再写入新 token 的原子操作。
3. Web 端使用 sessionStorage 同样缺少隔离 (sakura_admin_web/src/stores/session.ts 第 15-30 行)
const ACCESS_KEY = "sakura_access_token";
const REFRESH_KEY = "sakura_refresh_token";
export const authState = reactive({
accessToken: sessionStorage.getItem(ACCESS_KEY) || "",
refreshToken: sessionStorage.getItem(REFRESH_KEY) || "",
user: null as CurrentUser | null,
loading: false
});
问题: sessionStorage 的 key 是固定的,同一浏览器不同标签页可能共享或冲突。
4. 桌面端 Session 文件共享 (pixiv_app/core/paths.py 和 pixiv_app/core/auth.py)
Session 文件 pixiv_app_session.json 保存的是单一的 cookie 和 cloud_sync 配置,没有对应用户上下文。如果云端切换了用户但本地 session 文件未同步更新,可能导致不一致。
解决方案
方案 A:Token 绑定用户名校验(推荐)
修改位置:
| 文件 | 行号 | 修改内容 |
|---|---|---|
sakura_mobile/lib/src/core/session.dart |
第 44-52 行 | 在 _load() 后调用 /api/v1/users/me 校验 token 归属用户 |
sakura_mobile/lib/src/core/session.dart |
第 70-86 行 | login() 时先清除旧 token,写入后立即验证 |
sakura_mobile/lib/src/core/session.dart |
新增方法 | 添加 _validateAndFixSession() 方法,对比登录用户名与 token 归属 |
具体做法:
- 在
SessionController._load()中,加载 token 后立即调用api.me()获取当前 token 对应的用户名 - 将用户名也存入 SharedPreferences,key 使用
sakura.username - 每次
_load()后比对sakura.username与me()返回的 username,不一致则清除旧 token 强制重新登录 login()成功后立即存储用户名,防止与旧数据混淆
方案 B:增加 Token 失效主动检测
修改位置:
| 文件 | 行号 | 修改内容 |
|---|---|---|
sakura_mobile/lib/src/core/api_client.dart |
第 12-47 行 | 在 SakuraApiClient 中增加 401 拦截器 |
sakura_mobile/lib/src/core/session.dart |
第 100-108 行 | logout() 时增加确认清理 SharedPreferences 全部 key |
具体做法:
- 通过 Dio 拦截器全局捕获 401/403 响应,自动清除 token 并跳转登录页
- 在
logout()中不单删除_accessTokenKey,同时清理所有 sakura 相关 key - 增加
clearAllSakuraData()方法用于完全重置
方案 C:服务端 Token 版本号机制
修改位置: 后端 sakura_cloud/ (FastAPI) 相关认证模块
具体做法:
- 在用户表增加
token_version字段 - 每次重新登录时 token_version +1
- JWT payload 中嵌入 token_version
- 验证 token 时比对版本号,旧版本 token 直接拒绝
- 确保用户登出后旧 token 彻底失效
问题二:发现页查询过慢,需要加载缓冲或优化
问题现象
APP 打开"发现"页(FeedTab)时,整个页面长时间白屏/转圈,用户体验差。
根因分析
1. 五个 API 串行阻塞全部内容 (sakura_mobile/lib/src/pages/tabs/feed_tab.dart)
文件位置: sakura_mobile/lib/src/pages/tabs/feed_tab.dart 第 20-26 行
return FutureBuilder<List<Object?>>(
future: Future.wait([
api.galleryStat(), // 统计总数
api.galleryFeed(mode: 'created', limit: 36), // 今日新增
api.galleryFeed(mode: 'recent', limit: 24), // 最近更新
api.recentNovels(limit: 12), // 最近小说
api.unreadAlerts(limit: 12), // 未读提醒
]),
问题:
Future.wait等待所有 5 个请求完成才渲染页面- 任一接口慢(尤其是
galleryStat()和galleryFeed()),整个发现页都会卡住 galleryStat()可能后端做了全表 COUNT,数据量大时耗时数秒
2. 后端 gallery/feed 查询可能缺少优化
文件位置: 后端 API(sakura_cloud/ 目录下的 gallery/feed 路由)
galleryFeed 接口通常对应:
mode: 'created'→ 按创建时间排序的最近作品mode: 'recent'→ 按更新时间排序
如果后端 SQL 查询缺少合适的复合索引,或者做了全表扫描 + JOIN 多表,在数据量上千条后就会明显变慢。典型慢查询模式:
-- 可能的慢查询(缺少索引或 JOIN 过多)
SELECT a.*, ar.name, tc.thumbnail_path, ...
FROM artworks a
LEFT JOIN artists ar ON ...
LEFT JOIN thumbnail_cache tc ON ...
LEFT JOIN artwork_files af ON ...
LEFT JOIN favorites fav ON ...
ORDER BY a.created_at DESC
LIMIT 36
对比本地库查询 (pixiv_app/core/gallery_service.py 第 96-134 行) 同样有类似的多表 LEFT JOIN + GROUP BY + 复合搜索条件,这在 SQLite 上尤其慢:
total = library.connection.execute(
f"SELECT COUNT(DISTINCT a.artwork_id) AS total FROM artworks a {joins} {where_sql}",
params,
).fetchone()["total"]
先 COUNT 再 SELECT,等于两次大查询。
3. 图片缩略图同步加载阻塞渲染
文件位置: sakura_mobile/lib/src/pages/tabs/feed_tab.dart 第 385-389 行
CachedNetworkImage(
imageUrl: thumbUrl,
httpHeaders: api.authHeaders(),
fit: BoxFit.cover,
),
问题: 虽然使用了 CachedNetworkImage 做缓存,但如果后端 thumbnail_url 指向的是需要实时生成或大文件的原图,加载会很慢;且横向滚动的 ListView 会一次性构建多个图片 widget,造成网络拥塞。
解决方案
方案 A:渐进式加载 + 骨架屏(推荐,前端改动最小)
修改位置:
| 文件 | 行号 | 修改内容 |
|---|---|---|
sakura_mobile/lib/src/pages/tabs/feed_tab.dart |
第 20-26 行 | 将 Future.wait 拆分为独立请求,每个区块独立加载 |
sakura_mobile/lib/src/pages/tabs/feed_tab.dart |
第 62-137 行 | 为每个 _ArtworkStrip、_NovelStrip、_AlertStrip 增加独立的 loading/skeleton 状态 |
sakura_mobile/lib/src/pages/tabs/feed_tab.dart |
新增组件 | 增加 _SkeletonStrip 骨架屏组件 |
具体做法:
- 不再使用单个
FutureBuilder+Future.wait,改为每个 section 独立使用FutureBuilder - 统计卡片(
_TodayUpdateCard和_StatCard)优先加载 - 各内容条(插画、漫画、小说、提醒)各自独立加载,失败的只影响自己
- 加载中的条显示 shimmer 骨架屏而非空白
galleryStat()如果慢,可设置 3 秒超时,超时则降级显示 "--"
方案 B:后端增加 feed 缓存表(推荐,解决根本问题)
修改位置: 后端 sakura_cloud/
具体做法:
- 新增
feed_cache表:
CREATE TABLE feed_cache (
user_id UUID NOT NULL,
feed_type VARCHAR(32) NOT NULL, -- 'created', 'recent', 'stat'
payload_json JSONB NOT NULL,
generated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
PRIMARY KEY (user_id, feed_type)
);
- 在每次上传新作品、同步关注的定时任务完成后,异步刷新 feed_cache
/api/v1/gallery/feed和/api/v1/gallery/stat优先从feed_cache读取- 缓存有效期设为 5-10 分钟,过期后后台异步刷新,当前请求仍返回旧缓存
- 如果缓存不存在,降级为直接查询(首次慢但后续快)
方案 C:本地 SQLite 缓存 + 增量同步(移动端离线方案)
修改位置:
| 文件 | 行号 | 修改内容 |
|---|---|---|
sakura_mobile/lib/src/core/api_client.dart |
新增方法 | 增加本地缓存读写方法 |
sakura_mobile/lib/src/pages/tabs/feed_tab.dart |
第 20 行 | 优先读本地缓存,后台静默刷新 |
具体做法:
- 移动端使用
sqflite或drift建立轻量本地库 - 发现页数据缓存到本地,设置 30 分钟有效期
- 打开发现页时先展示缓存数据(秒开),同时后台请求新数据
- 新数据到达后平滑替换(
AnimatedSwitcher已就位) - 支持下拉强制刷新(
RefreshIndicator已就位)
方案 D:优化后端 gallery/feed 查询语句
修改位置: 后端 sakura_cloud/api/v1/ 中 gallery/feed 相关路由
具体做法:
- 分析慢查询日志,定位具体慢的 SQL
- 为
artworks表增加复合索引:CREATE INDEX idx_artworks_user_created ON artworks(user_id, created_at DESC); CREATE INDEX idx_artworks_user_updated ON artworks(user_id, updated_at DESC); - 将 COUNT + SELECT 两次查询合并为一次(用窗口函数或子查询)
- 限制
galleryStat()的统计精度,超过 10000 条时显示 "10000+" - 对缩略图 URL 确保使用 CDN 或 Nginx 静态文件服务,而非 Django/FastAPI 流式响应
问题三:提醒中心用户更新检测问题
问题现象
- 最近提醒显示的并非实际关注的作者名字,而是作者 ID 数字
- 已关注的作者有更新但未检测到,提醒中心未生成新提醒
根因分析
1. 提醒标题使用 author_id 而非 author_name
文件位置: pixiv_app/core/gallery_service.py 第 588-613 行
def _create_cloud_pixiv_update_alerts(self, artist_id: int, work_ids: list[int]) -> int:
...
for work_id in work_ids:
try:
manager.client.create_alert(
{
"platform": "pixiv",
"creator_id": str(int(artist_id)),
"title": f"Pixiv 作者 {int(artist_id)} 更新了作品 {int(work_id)}",
# ↑↑↑ 问题在这里:用的是 author_id 数字,而非 author name
"body": "你关注的 Pixiv 作者有新作品了",
...
}
)
问题详解:
_create_cloud_pixiv_update_alerts没有接收artist_name参数- 调用它的
sync_followed_artists(第 505-586 行)虽然能从library查到作者信息,但没传给 alert 创建函数 - 导致提醒标题变成 "Pixiv 作者 123456 更新了作品 789012",用户看到的是一串数字
- 移动端
reminder_center_page.dart直接展示alert['title'],所以显示的是数字 ID
2. 关注作者有更新但未检测到
文件位置: pixiv_app/core/gallery_service.py 第 505-586 行
def sync_followed_artists(self, *, cookie, max_new_per_artist=20, download=True, save_root="Sakura_Downloads"):
...
for row in followed:
artist_id = int(row["artist_id"])
# 获取已存在的作品 ID
existing = {
int(item["artwork_id"])
for item in library.connection.execute(
"SELECT artwork_id FROM artworks WHERE artist_id = ? AND type IN ('illust', 'manga')",
(artist_id,),
).fetchall()
}
# 获取远程作品 ID
_, work_ids = fetch_user_work_ids(user_id=artist_id, cookie=cookie)
# 只取本地没有的
new_ids = [work_id for work_id in work_ids if work_id not in existing][:max_new_per_artist]
问题详解:
fetch_user_work_ids需要有效的 Pixiv Cookie,如果 Cookie 已过期,API 调用静默失败- 对比逻辑只看
existing中的 artwork_id,但如果作品之前下载失败、入库未完成,可能漏掉 mark_artist_synced(artist_id, error=str(exc))在异常时记录了错误但未区分错误类型(Cookie 过期 vs 网络错误 vs 限流)- 没有"最近检查时间"的限流机制 —— 如果短时间内多次同步同一个作者,每次都做全量对比
3. 检查完成后未更新 last_checked_at
文件位置: pixiv_app/core/library.py 第 592-603 行
def mark_artist_synced(self, artist_id: int, *, error: str = "") -> None:
with self.connection:
self.connection.execute(
"""
INSERT INTO followed_artists (artist_id, enabled, last_synced_at, last_error)
VALUES (?, 1, CURRENT_TIMESTAMP, ?)
ON CONFLICT(artist_id) DO UPDATE SET
last_synced_at = CURRENT_TIMESTAMP,
last_error = excluded.last_error
""",
(artist_id, error),
)
问题: last_synced_at 只在本地 SQLite 更新,没有同步到云端 follows 表的 last_checked_at。移动端提醒中心展示的是云端 follows 数据:
文件位置: sakura_mobile/lib/src/pages/reminder_center_page.dart 第 22-27 行
Future<_ReminderCenterData> _load() async {
final api = ref.read(apiClientProvider);
final results = await Future.wait<Object?>([
api.me(),
api.follows(enabled: true), // ← 从云端读取 follows
api.alerts(limit: 50), // ← 从云端读取 alerts
]);
问题详解:
- 移动端显示的
last_checked_at来自云端 follows 表 - 桌面端
_upsert_cloud_follow只更新了 creator 基本信息,没有更新last_checked_at - 所以云端看到的"最近检查"时间永远是旧的甚至为空
- 用户无法判断哪个作者实际上被检查过
4. Alert 创建没有去重
文件位置: pixiv_app/core/gallery_service.py 第 588-613 行
for work_id in work_ids:
try:
manager.client.create_alert({...})
created += 1
except Exception:
continue
问题:
- 每次同步都会为同一个 work_id 创建新的 alert
- 如果多次同步同一批作品,会产生大量重复提醒
- 没有检查 "这个 work_id 是否已经发过 alert"
解决方案
方案 A:修复 Alert 标题——传入作者名(推荐,最小改动)
修改位置:
| 文件 | 行号 | 修改内容 |
|---|---|---|
pixiv_app/core/gallery_service.py |
第 588 行 | _create_cloud_pixiv_update_alerts 增加 artist_name 参数 |
pixiv_app/core/gallery_service.py |
第 562-565 行 | sync_followed_artists 传入作者名 |
pixiv_app/core/gallery_service.py |
第 599 行 | 修改 title 使用作者名 |
具体做法:
在 sync_followed_artists 方法中,从 followed_artists 或 artists 表获取作者名:
# 第 527-538 行之间,获取 followed 列表时同时获取 name
followed = library.connection.execute(
"SELECT fa.artist_id, COALESCE(NULLIF(fa.name,''), NULLIF(ar.name,''), '') AS name "
"FROM followed_artists fa "
"LEFT JOIN artists ar ON ar.artist_id = fa.artist_id "
"WHERE fa.enabled = 1 ORDER BY fa.artist_id"
).fetchall()
然后修改 _create_cloud_pixiv_update_alerts 签名:
def _create_cloud_pixiv_update_alerts(
self, artist_id: int, work_ids: list[int], artist_name: str = ""
) -> int:
title 改为:
"title": f"Pixiv 作者 {artist_name or str(artist_id)} 更新了 {len(work_ids)} 个新作品"
方案 B:同步云端 follows 的检查状态
修改位置:
| 文件 | 行号 | 修改内容 |
|---|---|---|
pixiv_app/core/gallery_service.py |
第 556-559 行 | mark_artist_synced 之后同步更新云端 follows 的 last_checked_at |
pixiv_app/core/cloud_sync.py |
第 167-168 行 | upsert_follow 增加 last_checked_at 和 latest_published_at 字段 |
pixiv_app/core/gallery_service.py |
第 415-447 行 | _upsert_cloud_follow 增加更新时间戳参数 |
具体做法:
- 在
_upsert_cloud_follow方法中增加last_checked_at和latest_published_at参数 - 每次同步完一个作者后,调用
_upsert_cloud_follow更新云端状态 - 在云端 follows API 的 upsert 逻辑中接受并存储这些时间字段
- 移动端
reminder_center_page.dart中_FollowTile就能显示正确的"最近检查"时间
方案 C:Alert 去重 & 按作者聚合
修改位置:
| 文件 | 行号 | 修改内容 |
|---|---|---|
pixiv_app/core/gallery_service.py |
第 588-613 行 | 重构 _create_cloud_pixiv_update_alerts 逻辑 |
后端 sakura_cloud/api/v1/follows.py |
alert 创建路由 | 增加去重逻辑 |
具体做法:
- 将每个作者的多个新作品合并为一条聚合 alert,而非每个作品一条
- Alert 的
source_id使用f"{artist_id}:{min(work_ids)}:{max(work_ids)}"生成唯一标识 - 创建 alert 前先检查是否存在相似 alert(同一作者 + 同一天内)
- 如果存在则更新而非新建
- title 格式改为:
"你关注的 {作者名} 更新了 {N} 个新作品"
方案 D:增加关注作者更新状态页面
修改位置:
| 文件 | 行号 | 修改内容 |
|---|---|---|
sakura_mobile/lib/src/pages/reminder_center_page.dart |
第 350-371 行 | 已关注作者列表增加"手动检查更新"按钮 |
| 后端新增接口 | - | POST /api/v1/follows/{follow_id}/check 触发单作者更新检测 |
具体做法:
- 在已关注作者列表中为每个作者增加状态标识:
- 🟢 最近 24h 内检查过
- 🟡 24h-7d 内检查过
- 🔴 超过 7 天未检查
- 增加"手动检查"按钮,调用后端触发单个作者的更新检测
- 检查完成后自动刷新提醒列表
总结优先级
| 优先级 | 问题 | 推荐方案 | 改动范围 | 预期效果 |
|---|---|---|---|---|
| P0 紧急 | 跳转到 dakura 用户 | 方案 A:Token 绑定用户名 | 移动端 session.dart | 根除串号问题 |
| P0 紧急 | Alert 显示数字而非作者名 | 方案 A:传入作者名 | gallery_service.py | 提醒可读 |
| P1 高 | 发现页加载慢 | 方案 A + B:渐进加载 + feed_cache | feed_tab.dart + 后端 | 首屏从 3-5s 降到 <1s |
| P1 高 | 关注作者未检测更新 | 方案 B:同步检查状态到云端 | gallery_service.py + cloud_sync.py | 状态准确可追溯 |
| P2 中 | Alert 重复创建 | 方案 C:去重 + 聚合 | gallery_service.py + 后端 | 减少重复提醒 |
| P2 中 | 查询性能优化 | 方案 D:SQL 索引 | 后端数据库 | 查询耗时降低 50%+ |