Files
SakuraHub/docs/APP端问题分析与解决方案.md
2026-11-16 20:45:22 +08:00

20 KiB
Raw Permalink Blame History

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 归属

具体做法:

  1. 在 SessionController._load() 中,加载 token 后立即调用 api.me() 获取当前 token 对应的用户名
  2. 将用户名也存入 SharedPreferences,key 使用 sakura.username
  3. 每次 _load() 后比对 sakura.username 与 me() 返回的 username,不一致则清除旧 token 强制重新登录
  4. 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

具体做法:

  1. 通过 Dio 拦截器全局捕获 401/403 响应,自动清除 token 并跳转登录页
  2. 在 logout() 中不单删除 _accessTokenKey,同时清理所有 sakura 相关 key
  3. 增加 clearAllSakuraData() 方法用于完全重置

方案 C:服务端 Token 版本号机制

修改位置: 后端 sakura_cloud/ (FastAPI) 相关认证模块

具体做法:

  1. 在用户表增加 token_version 字段
  2. 每次重新登录时 token_version +1
  3. JWT payload 中嵌入 token_version
  4. 验证 token 时比对版本号,旧版本 token 直接拒绝
  5. 确保用户登出后旧 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 骨架屏组件

具体做法:

  1. 不再使用单个 FutureBuilder + Future.wait,改为每个 section 独立使用 FutureBuilder
  2. 统计卡片(_TodayUpdateCard 和 _StatCard)优先加载
  3. 各内容条(插画、漫画、小说、提醒)各自独立加载,失败的只影响自己
  4. 加载中的条显示 shimmer 骨架屏而非空白
  5. galleryStat() 如果慢,可设置 3 秒超时,超时则降级显示 "--"

方案 B:后端增加 feed 缓存表(推荐,解决根本问题)

修改位置: 后端 sakura_cloud/

具体做法:

  1. 新增 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)
);
  1. 在每次上传新作品、同步关注的定时任务完成后,异步刷新 feed_cache
  2. /api/v1/gallery/feed 和 /api/v1/gallery/stat 优先从 feed_cache 读取
  3. 缓存有效期设为 5-10 分钟,过期后后台异步刷新,当前请求仍返回旧缓存
  4. 如果缓存不存在,降级为直接查询(首次慢但后续快)

方案 C:本地 SQLite 缓存 + 增量同步(移动端离线方案)

修改位置:

文件 行号 修改内容
sakura_mobile/lib/src/core/api_client.dart 新增方法 增加本地缓存读写方法
sakura_mobile/lib/src/pages/tabs/feed_tab.dart 第 20 行 优先读本地缓存,后台静默刷新

具体做法:

  1. 移动端使用 sqflite 或 drift 建立轻量本地库
  2. 发现页数据缓存到本地,设置 30 分钟有效期
  3. 打开发现页时先展示缓存数据(秒开),同时后台请求新数据
  4. 新数据到达后平滑替换(AnimatedSwitcher 已就位)
  5. 支持下拉强制刷新(RefreshIndicator 已就位)

方案 D:优化后端 gallery/feed 查询语句

修改位置: 后端 sakura_cloud/api/v1/ 中 gallery/feed 相关路由

具体做法:

  1. 分析慢查询日志,定位具体慢的 SQL
  2. 为 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);
    
  3. 将 COUNT + SELECT 两次查询合并为一次(用窗口函数或子查询)
  4. 限制 galleryStat() 的统计精度,超过 10000 条时显示 "10000+"
  5. 对缩略图 URL 确保使用 CDN 或 Nginx 静态文件服务,而非 Django/FastAPI 流式响应

问题三:提醒中心用户更新检测问题

问题现象

  1. 最近提醒显示的并非实际关注的作者名字,而是作者 ID 数字
  2. 已关注的作者有更新但未检测到,提醒中心未生成新提醒

根因分析

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 增加更新时间戳参数

具体做法:

  1. 在 _upsert_cloud_follow 方法中增加 last_checked_at 和 latest_published_at 参数
  2. 每次同步完一个作者后,调用 _upsert_cloud_follow 更新云端状态
  3. 在云端 follows API 的 upsert 逻辑中接受并存储这些时间字段
  4. 移动端 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 创建路由 增加去重逻辑

具体做法:

  1. 将每个作者的多个新作品合并为一条聚合 alert,而非每个作品一条
  2. Alert 的 source_id 使用 f"{artist_id}:{min(work_ids)}:{max(work_ids)}" 生成唯一标识
  3. 创建 alert 前先检查是否存在相似 alert(同一作者 + 同一天内)
  4. 如果存在则更新而非新建
  5. title 格式改为:"你关注的 {作者名} 更新了 {N} 个新作品"

方案 D:增加关注作者更新状态页面

修改位置:

文件 行号 修改内容
sakura_mobile/lib/src/pages/reminder_center_page.dart 第 350-371 行 已关注作者列表增加"手动检查更新"按钮
后端新增接口 - POST /api/v1/follows/{follow_id}/check 触发单作者更新检测

具体做法:

  1. 在已关注作者列表中为每个作者增加状态标识:
    • 🟢 最近 24h 内检查过
    • 🟡 24h-7d 内检查过
    • 🔴 超过 7 天未检查
  2. 增加"手动检查"按钮,调用后端触发单个作者的更新检测
  3. 检查完成后自动刷新提醒列表

总结优先级

优先级 问题 推荐方案 改动范围 预期效果
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%+