49 KiB
Web 端详情加载、手机端搜索与加载性能优化方案
更新日期:2026-06-15 范围:Sakura Admin Web (Vue.js) + Sakura Mobile (Flutter) + Sakura Cloud (FastAPI) 说明:本文档提供问题分析与优化方案,不包含实际代码改动。
目录
一、管理员账号密码
1.1 现状
本项目没有预设的默认管理员账号密码。数据库初始化脚本(sakura_cloud/scripts/init_db.py)仅创建空表结构,不插入任何种子数据。
管理员账号需要部署后手动创建,使用后端提供的 CLI 脚本。
1.2 创建管理员账号的方法
脚本位置: sakura_cloud/scripts/create_admin.py
使用方法:
# 在后端服务器上执行(需在 sakura_cloud 可导入的环境下)
python -m sakura_cloud.scripts.create_admin \
--username admin \
--email admin@example.com \
--password YourPassword123
参数说明:
| 参数 | 必填 | 说明 |
|---|---|---|
--username |
是 | 管理员用户名 |
--email |
是 | 管理员邮箱 |
--password |
否 | 密码(最少 8 位)。如不传,运行时会交互式提示输入(不显示在终端) |
脚本逻辑:
- 检查是否已存在
SUPER_ADMIN角色的用户 - 如果数据库中没有匹配用户名/邮箱的用户 → 创建新的 SUPER_ADMIN
- 如果已存在该用户但角色不是 SUPER_ADMIN,且已有其他 SUPER_ADMIN → 拒绝提升(防止越权)
- 如果已存在该用户且尚无 SUPER_ADMIN → 将其提升为 SUPER_ADMIN 并更新密码
1.3 基础设施凭证(仅供参考,非管理员登录)
以下凭证出现在配置文件和 docker-compose.yml 中,但这些是基础设施组件的凭证,不能用于 Web/APP 登录:
| 组件 | 用户名 | 密码 | 用途 |
|---|---|---|---|
| PostgreSQL | sakura |
sakura |
数据库连接 |
| MinIO | minioadmin |
minioadmin |
对象存储 |
| JWT Secret | - | change-this-secret-in-production |
JWT 签名密钥(生产环境务必修改) |
⚠️ 安全提醒: 以上均为默认值,生产部署前务必修改,特别是 JWT Secret 和数据库密码。
1.4 如果忘记了管理员密码
由于没有预设账号,如果忘记密码:
- 方法一(推荐): 重新运行
create_admin.py脚本,指定相同的--username和--email,输入新密码即可覆盖。 - 方法二: 直接在数据库中修改
password_hash字段(需要先用 Python 生成 bcrypt/pbkdf2_sha256 哈希)。 - 方法三: 如果数据库中有其他管理员账号,可以用该账号登录后在管理后台重置密码。
二、Web 端详情数据按需加载问题
2.1 问题现象
在 Web 管理前端(sakura_admin_web)中,用户点击列表中的画廊(gallery)或小说(novels)项目后,跳转到详情页面,但页面只显示:
详情数据由现有 API 按需加载。
页面不会展示任何实际内容,用户无法看到作品详情。
2.2 根因分析
问题出在 UserDetailPage.vue 是一个未实现的占位组件,它从始至终没有发起任何 API 请求来获取详情数据。
根因 1:UserDetailPage.vue 未调用任何 API
文件位置: sakura_admin_web/src/views/app/UserDetailPage.vue
当前完整代码:
<template>
<main class="content">
<header class="page-head">
<div>
<p class="eyebrow">详情</p>
<h1>{{ title }}</h1>
</div>
</header>
<section class="panel">
<pre>{{ content }}</pre>
</section>
</main>
</template>
<script setup lang="ts">
import { computed } from "vue";
import { authState } from "../../stores/auth";
const props = defineProps<{ kind: string }>();
const title = computed(() => (props.kind === "profile" ? "我的资料" : "作品详情"));
const content = computed(() =>
props.kind === "profile"
? JSON.stringify(authState.user, null, 2)
: "详情数据由现有 API 按需加载。"
);
</script>
缺失的关键要素:
- ❌ 没有
import { http, apiData } from "../../api/http"— 未导入 HTTP 客户端 - ❌ 没有
import { useRoute } from "vue-router"— 未获取路由参数 - ❌ 没有
onMounted生命周期钩子 — 不会在组件挂载时加载数据 - ❌ 没有任何
ref()存储数据 — 没有响应式数据容器 - ❌ 当
kind === "gallery"或kind === "novels"时,content只是一段固定死的中文字符串
注:
kind === "profile"能显示用户资料,仅因为authState.user已在路由守卫router.beforeEach中通过loadMe()提前加载了。这是"碰巧能用",并非设计意图。
根因 2:路由未传递 id 参数给组件
文件位置: sakura_admin_web/src/router/index.ts 第 30-32 行
{ path: "gallery/:id", component: UserDetailPage, props: { kind: "gallery" } },
{ path: "novels/:id", component: UserDetailPage, props: { kind: "novels" } },
props 被设置为静态对象 { kind: "gallery" },这意味着:
props.id始终为undefined- 即便组件内部添加了 API 调用,也无法知道要请求哪个 ID 的作品
正确做法应使用以下之一:
// 方式一:自动传递所有 params
props: true
// 方式二:函数合并 params 与自定义 props
props: (route) => ({ kind: "gallery", id: route.params.id })
根因 3:后端其实已有详情 API(但前端没调用)
后端已经实现了详情接口:
| 方法 | 路径 | 文件 | 行号 |
|---|---|---|---|
| GET | /api/v1/gallery/{artwork_id} |
sakura_cloud/api/v1/endpoints/gallery.py |
230 |
| GET | /api/v1/novels/{novel_id} |
sakura_cloud/api/v1/endpoints/novels.py |
222 |
但是:
- 这些接口在
/api/v1/gallery/{id}路径下,而非/api/v1/me/gallery/{id} - 前端
UserListPage.vue列表调用的是GET /me/gallery和GET /me/novels - 详情页如果想保持和列表页一致的
/me/前缀,后端缺少GET /me/gallery/{id}和GET /me/novels/{id}路由 - 但这不影响功能——直接调用
/api/v1/gallery/{id}和/api/v1/novels/{id}即可
对比:相同模式的 AdminUserDetail.vue 工作正常
import { onMounted, ref } from "vue";
import { useRoute } from "vue-router";
import { apiData, http } from "../../api/http";
const route = useRoute();
const user = ref<Record<string, any> | null>(null);
async function load() {
const response = await http.get(`/admin/users/${route.params.id}`);
user.value = apiData<Record<string, any>>(response);
}
onMounted(load);
这说明代码库中已有正确的详情加载模式,UserDetailPage.vue 只需要参照 AdminUserDetail.vue 的模式来实现即可。
2.3 修复方案
方案(推荐):按 AdminUserDetail 模式实现 UserDetailPage
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_admin_web/src/views/app/UserDetailPage.vue |
完整重写,添加数据加载逻辑和详情展示模板 |
sakura_admin_web/src/router/index.ts 第 30、32 行 |
修改 props 配置,传递 id 参数 |
(可选)sakura_cloud/api/v1/endpoints/me.py |
新增 GET /me/gallery/{id} 和 GET /me/novels/{id} 路由 |
具体做法:
步骤 1:修复路由传参(router/index.ts)
// 将:
{ path: "gallery/:id", component: UserDetailPage, props: { kind: "gallery" } },
{ path: "novels/:id", component: UserDetailPage, props: { kind: "novels" } },
// 改为(推荐方式一,保持简洁):
{ path: "gallery/:id", component: UserDetailPage, props: (route) => ({ kind: "gallery", id: route.params.id }) },
{ path: "novels/:id", component: UserDetailPage, props: (route) => ({ kind: "novels", id: route.params.id }) },
步骤 2:重写 UserDetailPage.vue(参照 AdminUserDetail.vue 模式)
- 导入
onMounted、ref、http、apiData - 在
props类型中增加id?: string - 在
onMounted中根据props.kind调用不同的 API:kind === "gallery"→GET /api/v1/gallery/${props.id}kind === "novels"→GET /api/v1/novels/${props.id}kind === "profile"→ 保持现有逻辑(使用authState.user)
- 添加 loading 和 error 状态
- 更新模板,将
{{ content }}替换为结构化展示(标题、作者、标签、缩略图等)
步骤 3(可选):在后端添加 /me/ 前缀的详情路由
在 sakura_cloud/api/v1/endpoints/me.py 中添加:
@router.get("/gallery/{artwork_id}")
def my_gallery_detail(artwork_id: str, current_user: CurrentUser, db: DbSession):
"""获取当前用户的单个画廊作品详情"""
from sakura_cloud.api.v1.endpoints.gallery import get_artwork
return get_artwork(artwork_id, current_user, db)
@router.get("/novels/{novel_id}")
def my_novel_detail(novel_id: str, current_user: CurrentUser, db: DbSession):
"""获取当前用户的单个小说作品详情"""
from sakura_cloud.api.v1.endpoints.novels import get_novel
return get_novel(novel_id, current_user, db)
2.4 预期效果
- 用户从列表页点击任意画廊/小说作品,详情页正常展示作品信息(标题、作者、标签、图片、描述等)
- 加载过程中显示 loading 状态,加载失败显示错误提示
kind === "profile"的个人资料页不受影响
三、Web 端缺少漫画板块问题
3.1 问题现象
在 Web 管理前端(sakura_admin_web)中,侧边栏导航只有以下入口:
- 概览(
/app) - 图片(
/app/gallery) - 小说(
/app/novels) - 提醒(
/app/alerts) - 我的(
/app/profile)
缺少"漫画"板块,用户无法在 Web 端独立浏览、搜索漫画类型的内容。漫画作品即使已同步到云端,也只能混在"图片"板块中与其他插画(illust)混合展示,无法单独筛选。
3.2 根因分析
根因 1:前端路由和侧边栏缺少 manga 入口
文件位置: sakura_admin_web/src/router/index.ts 第 27-35 行
当前 /app 路由子节点:
children: [
{ path: "", component: UserDashboard },
{ path: "gallery", component: UserListPage, props: { kind: "gallery" } },
{ path: "gallery/:id", component: UserDetailPage, props: { kind: "gallery" } },
{ path: "novels", component: UserListPage, props: { kind: "novels" } },
{ path: "novels/:id", component: UserDetailPage, props: { kind: "novels" } },
{ path: "alerts", component: UserListPage, props: { kind: "alerts" } },
{ path: "profile", component: UserDetailPage, props: { kind: "profile" } }
]
没有 manga 路由,也没有对应的列表页和详情页路由。
文件位置: sakura_admin_web/src/views/app/AppLayout.vue 第 4-9 行
<RouterLink to="/app">概览</RouterLink>
<RouterLink to="/app/gallery">图片</RouterLink>
<RouterLink to="/app/novels">小说</RouterLink>
<RouterLink to="/app/alerts">提醒</RouterLink>
<RouterLink to="/app/profile">我的</RouterLink>
侧边栏没有"漫画"导航项。
根因 2:UserListPage 的 kind 类型不包含 manga
文件位置: sakura_admin_web/src/views/app/UserListPage.vue 第 27 行
const props = defineProps<{ kind: "gallery" | "novels" | "alerts" }>();
kind 的 TypeScript 类型仅为 "gallery" | "novels" | "alerts",不包含 "manga"。
第 31 行的标题映射也缺少 manga:
const title = computed(() => ({ gallery: "图片", novels: "小说", alerts: "提醒中心" }[props.kind]));
第 41 行的 API 调用路径硬编码了 kind:
const response = await http.get(`/me/${props.kind}`, { params });
如果 kind === "manga",会请求 /me/manga,但后端 me.py 中没有这个路由。
根因 3:后端其实已支持按 content_type 筛选漫画
关键事实:后端不区分 gallery 和 manga,它们共用同一张 artworks 表。
Artwork.content_type字段默认值为"illust",但也支持"manga"(漫画)等值/api/v1/gallery接口已支持content_type查询参数(gallery.py第 35 行)/api/v1/me/gallery透传了content_type参数(me.py第 39-50 行)
这意味着为 Web 端增加漫画板块,后端几乎不需要改动——只需要在调用 /me/gallery 时传入 content_type=manga 即可。
根因 4:UserDetailPage 同样不支持 manga 类型
UserDetailPage.vue 的 kind prop 类型(第 26 行)和路由传参同样缺少 manga 支持。即使添加了列表页路由,详情页也会因 kind === "manga" 时 content 返回固定字符串 "详情数据由现有 API 按需加载。" 而无法显示内容。
3.3 修复方案
方案(推荐):前端 4 处修改即可新增漫画板块
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_admin_web/src/router/index.ts |
新增 /app/manga 和 /app/manga/:id 路由 |
sakura_admin_web/src/views/app/AppLayout.vue |
侧边栏新增"漫画"导航项 |
sakura_admin_web/src/views/app/UserListPage.vue |
kind 类型和标题映射增加 manga |
sakura_admin_web/src/views/app/UserDetailPage.vue |
详情加载逻辑增加 manga 分支 |
具体做法:
步骤 1:新增路由(router/index.ts)
// 在 /app 的 children 数组中增加两条新路由
{ path: "manga", component: UserListPage, props: { kind: "manga" } },
{ path: "manga/:id", component: UserDetailPage, props: (route) => ({ kind: "manga", id: route.params.id }) },
步骤 2:侧边栏增加入口(AppLayout.vue)
<RouterLink to="/app/manga">漫画</RouterLink>
<!-- 插入在"图片"和"小说"之间 -->
步骤 3:UserListPage 增加 manga 支持
// 将 kind 类型扩展为:
const props = defineProps<{ kind: "gallery" | "manga" | "novels" | "alerts" }>();
// 标题映射增加:
const title = computed(() => ({
gallery: "图片",
manga: "漫画", // ← 新增
novels: "小说",
alerts: "提醒中心"
}[props.kind]));
// API 调用逻辑修改(第 38-48 行):
async function load() {
loading.value = true;
try {
const params: Record<string, any> = {};
if (props.kind === "alerts") {
// 提醒列表保持不变
} else {
if (search.value) params.search = search.value;
// 关键:manga 和 gallery 共用同一个后端接口,通过 content_type 区分
if (props.kind === "manga") params.content_type = "manga";
else if (props.kind === "gallery") params.content_type = "illust";
}
const apiPath = props.kind === "manga" ? "/me/gallery" : `/me/${props.kind}`;
const response = await http.get(apiPath, { params });
const data = apiData<any>(response);
items.value = Array.isArray(data) ? data : data.items || [];
} finally {
loading.value = false;
}
}
步骤 4:UserDetailPage 增加 manga 详情加载(与方案二中详情页修复合并实施)
在 loadDetail() 逻辑中增加:
if (props.kind === "manga") {
const response = await http.get(`/gallery/${props.id}`);
item.value = apiData(response);
}
设计说明: 漫画和图片在后端共用
galleryAPI(同一张artworks表),只是content_type字段值不同("illust"vs"manga")。因此前端通过传入content_type=manga参数来筛选漫画类型,无需新增后端接口。这与移动端 APP 的处理方式一致。
3.4 预期效果
- Web 端侧边栏新增"漫画"入口,与"图片""小说"并列
- 点击进入后展示所有
content_type=manga的作品 - 支持搜索漫画标题/作者/标签
- 漫画详情页正常展示作品信息
- "图片"板块默认展示
content_type=illust的内容,与漫画分离 - 如果以后需要更多内容类型(如
ugoira动图),按相同模式扩展即可
四、Web 端列表加载性能问题
4.1 问题现象
Web 管理前端在浏览图片列表时,用户感知加载较慢:
- 打开"图片"或"小说"列表页时,页面需要等待数秒才显示内容
- 搜索时每次输入都触发后端请求,响应不够即时
- 列表没有分页控件,所有数据一次性加载,数据量大时尤其慢
- 缩略图使用后端
/api/v1/files/{id}/thumbnail接口,未使用 CDN 或缓存策略
4.2 根因分析
根因 1:列表页没有前端分页(🔴 最直接影响)
文件位置: sakura_admin_web/src/views/app/UserListPage.vue 第 38-48 行
async function load() {
loading.value = true;
try {
const params = props.kind === "alerts" ? {} : { search: search.value || undefined };
const response = await http.get(`/me/${props.kind}`, { params });
const data = apiData<any>(response);
items.value = Array.isArray(data) ? data : data.items || [];
} finally {
loading.value = false;
}
}
问题:
- 请求未传入
page和limit参数 - 后端
/api/v1/me/gallery的默认 limit 是 30(gallery.py第 31 行),但如果后端默认值被修改或数据量大,前端仍会慢 - 更关键的是:后端每次都会执行
COUNT(*)查询(gallery.py第 100 行),数据量大时COUNT本身就是慢查询 - UI 层面没有分页控件(上一页/下一页按钮),用户无法翻页浏览更多内容
- 搜索框在每次
@keyup.enter时触发请求,但没有防抖(debounce)机制
根因 2:后端 COUNT 查询每次都是全表扫描(🔴 核心性能瓶颈)
文件位置: sakura_cloud/api/v1/endpoints/gallery.py 第 43-100 行
count_query = select(func.count()).select_from(Artwork).where(Artwork.user_id == current_user.id)
# ... 应用相同的 filters ...
total = int(db.scalar(count_query) or 0)
问题:
- 每次列表请求都执行
COUNT(*)查询 COUNT(*)在有大量数据时需要进行全表或索引扫描- 虽然
gallery.py第 46-47 行使用了ILIKE(ilike(f"%{search_text}%")),但带通配符的ILIKE无法利用 B-tree 索引,需要全表遍历每一行进行模式匹配 - 搜索 + COUNT 组合是 O(n) 复杂度,数据量上万条后耗时明显增加
- 即使是不搜索的普通列表请求,COUNT 也需要扫描用户的所有作品
根因 3:列表和搜索没有防抖(🟡)
文件位置: sakura_admin_web/src/views/app/UserListPage.vue 第 8 行
<input v-if="kind !== 'alerts'" v-model.trim="search" placeholder="搜索" @keyup.enter="load" />
问题:
- 用户按 Enter 才触发搜索,看似没问题
- 但如果用户快速输入后多次按 Enter,或配合其他筛选条件多次修改,会发起多次后端请求
- 没有防抖/节流机制,连续快速操作会产生冗余请求
根因 4:缩略图加载策略未优化(🟡)
文件位置: sakura_admin_web/src/views/app/UserListPage.vue — 模板中完全没有图片
当前列表页只显示作品的 title 和 author 文本,没有缩略图展示,所以缩略图加载不是 Web 端的瓶颈。但如果未来改进详情页展示缩略图(当前详情页是占位组件),需要注意:
- 后端缩略图接口
/api/v1/files/{id}/thumbnail是同步读取 MinIO + 实时返回,没有 CDN 缓存 - 如果列表页展示 30 张缩略图,就是 30 次后端文件读取请求
根因 5:Axios 超时 15 秒可能不够(🟢)
文件位置: sakura_admin_web/src/api/http.ts 第 8 行
export const http = axios.create({
baseURL: API_BASE,
timeout: 15000,
withCredentials: false
});
15 秒超时对于慢速服务器场景来说偏紧张,但影响相对较小。
4.3 修复方案
方案 A:前端增加分页控件(🔴 最重要,直接解决加载慢)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_admin_web/src/views/app/UserListPage.vue |
增加分页状态、分页 UI 控件、分页加载逻辑 |
具体做法:
- 在
<script setup>中增加分页状态:
const page = ref(1);
const limit = 30;
const total = ref(0);
const totalPages = ref(0);
- 修改
load()方法,传入分页参数:
async function load() {
loading.value = true;
try {
const params: Record<string, any> = { page: page.value, limit };
if (props.kind !== "alerts" && search.value) params.search = search.value;
if (props.kind === "manga") params.content_type = "manga";
else if (props.kind === "gallery") params.content_type = "illust";
const apiPath = props.kind === "manga" ? "/me/gallery" : `/me/${props.kind}`;
const response = await http.get(apiPath, { params });
const data = apiData<any>(response);
items.value = Array.isArray(data) ? data : data.items || [];
total.value = data.pagination?.total || data.total || items.value.length;
totalPages.value = data.pagination?.pages || Math.ceil(total.value / limit);
} finally {
loading.value = false;
}
}
- 在模板底部增加分页控件:
<div v-if="totalPages > 1" class="pagination">
<button :disabled="page <= 1" @click="page--; load()">上一页</button>
<span>第 {{ page }} / {{ totalPages }} 页(共 {{ total }} 条)</span>
<button :disabled="page >= totalPages" @click="page++; load()">下一页</button>
</div>
- 搜索或切换
kind时重置page为 1:
watch(() => props.kind, () => { page.value = 1; load(); });
// 搜索时也重置页码
function onSearch() { page.value = 1; load(); }
方案 B:后端 COUNT 查询优化(🔴 解决根本性能瓶颈)
修改位置: sakura_cloud/api/v1/endpoints/gallery.py 第 100 行
具体做法:
选项 1:使用估算计数(推荐,适用于"大概有多少条"的场景)
# 对于 PostgreSQL,使用 pg_stat_user_tables 的估算值替代精确 COUNT
# 仅在不搜索且不需要精确 total 时使用
if not search_text and not any([source_platform, author, tag, content_type, is_favorite]):
# 快速估算
total = int(db.scalar(
select(func.reltuples).select_from(func.pg_class).where(
func.pg_class.c.relname == 'artworks'
)
) or 0)
else:
total = int(db.scalar(count_query) or 0)
选项 2:去掉 COUNT 查询,改为"是否有下一页"模式
# 查询 limit+1 条,如果有第 limit+1 条则说明有下一页
rows = db.scalars(query.limit(limit + 1)).all()
has_next = len(rows) > limit
data = PageResponse(
items=[ArtworkOut.model_validate(row) for row in rows[:limit]],
pagination=Pagination(page=page, limit=limit, total=None, has_next=has_next),
)
这种方式完全避免了 COUNT 查询,大幅降低数据库负载。
选项 3:对 COUNT 查询添加超时保护
# 设置 statement_timeout 防止 COUNT 查询拖垮整个请求
db.execute(text("SET LOCAL statement_timeout = '2000ms'"))
total = int(db.scalar(count_query) or 0)
db.execute(text("RESET statement_timeout"))
方案 C:搜索增加防抖(🟡 改善交互体验)
修改位置: sakura_admin_web/src/views/app/UserListPage.vue 第 8 行
具体做法:
- 增加防抖逻辑:
let debounceTimer: ReturnType<typeof setTimeout> | null = null;
function onSearchInput() {
if (debounceTimer) clearTimeout(debounceTimer);
debounceTimer = setTimeout(() => {
page.value = 1;
load();
}, 400); // 400ms 防抖
}
- 修改模板,从
@keyup.enter改为实时防抖:
<input v-model.trim="search" placeholder="搜索..." @input="onSearchInput" />
方案 D:缩略图使用 CDN / 缓存策略(🟡 前瞻性优化)
修改位置: 后端 sakura_cloud/api/v1/endpoints/files.py
具体做法:
- 在 Nginx 或 MinIO 前面加一层缩略图缓存
- 缩略图生成后保存到 MinIO 的
thumbnails/bucket,设置公开读权限 - 前端直接使用 MinIO 的公开 URL 而非后端代理 URL
- 为缩略图响应添加
Cache-Control: public, max-age=86400头
方案 E:后端查询结果缓存(🟢 锦上添花)
修改位置: 后端 sakura_cloud/api/v1/endpoints/gallery.py
具体做法:
- 使用 Redis 缓存(如项目已有 Redis)或内存 LRU 缓存
- 缓存 key =
gallery_list:{user_id}:{page}:{limit}:{search}:{filters_hash} - 缓存有效期 1-2 分钟
- 用户上传新作品或修改作品时,清除该用户的列表缓存
4.4 预期效果
- 列表页首屏加载时间从 2-5 秒降到 500ms 以内(分页 + 去掉 COUNT)
- 搜索响应从"按 Enter 等待"变为输入即搜(防抖 400ms)
- 分页控件使用户可以浏览全部数据,而非仅前 30 条
- 后端 COUNT 查询优化后,
galleryStat()和列表请求的数据库负载显著降低
五、手机端搜索不到图书问题
3.1 问题现象
用户在手机 APP 中搜索中文图书/漫画/小说时:
- 搜索中文关键词(如"樱花"、"海贼王"),返回结果为空或极少
- 同一关键词在英文搜索中可能有结果
- 自建云库中的内容搜索也可能不命中
3.2 根因分析
手机端搜索有两条独立路径,各有不同的问题。以下按影响程度从大到小排列。
路径 A:第三方在线源搜索(Legado Engine)—— 最可能出问题
涉及文件:
sakura_mobile/lib/src/core/legado_engine.dart(搜索引擎主逻辑)sakura_mobile/lib/src/core/legado_rule_parser.dart(HTML/JSON 解析器)sakura_mobile/lib/src/core/source_manager.dart(源管理)
根因 1:HTTP 响应编码不匹配(🔴 最可能的原因)
文件位置: sakura_mobile/lib/src/core/legado_engine.dart 第 11-17 行(Dio 实例)和第 40-52 行(search 方法)
static final Dio _http = Dio(BaseOptions(
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 10),
));
// search 方法中:
final response = await _http.get<String>(
url,
options: Options(
responseType: ResponseType.plain,
headers: {...source.headers ?? {}},
),
);
问题详解:
Dio 的 ResponseType.plain 默认以 UTF-8 解码响应体。然而大量中国漫画/小说网站(如笔趣阁、包子漫画、全本玄幻小说等)的服务端返回的是 GBK/GB2312 编码的 HTML 页面。
当 Dio 用 UTF-8 解码 GBK 编码的中文内容时,会产生大量的乱码(如 ä½ å¥½ 代替 你好)。随后 RuleParser 使用 CSS 选择器、正则表达式或 JSONPath 解析这些乱码内容时:
- CSS 选择器匹配不到任何元素(因为实际的 HTML 结构在乱码后仍然存在,但文本节点的内容已损坏)
- 正则表达式无法匹配中文关键词
- 搜索结果被过滤掉(因为
searchNameRule提取到的标题是乱码)
证据:
LegadoEngine.search()有.catchError((_) => <UnifiedSearchResult>[])的静默错误吞没逻辑(第 86 行),用户看不到任何编码错误的提示- 默认启用的 6 个精选源(笔趣阁、全本玄幻小说、妙笔阁、包子漫画、古风漫画网、COCO漫画)全部是中国大陆网站,大概率使用 GBK 编码
根因 2:URL 百分号编码可能不匹配目标网站(🟡)
文件位置: sakura_mobile/lib/src/core/legado_engine.dart 第 38 行
final url = searchUrl
.replaceAll('{{key}}', Uri.encodeComponent(keyword))
Uri.encodeComponent() 始终使用 UTF-8 进行百分号编码。例如 你好 → %E4%BD%A0%E5%A5%BD。
部分老式中国网站的搜索接口基于 GBK 后端,期望收到 GBK 百分号编码的查询参数(你好 → %C4%E3%BA%C3)。编码不匹配时,服务端收到乱码查询词,返回空结果。
根因 3:错误静默吞没,用户看不到诊断信息(🟡)
文件位置: sakura_mobile/lib/src/core/legado_engine.dart 第 76-89 行
Future<List<UnifiedSearchResult>> searchAll(...) async {
final futures = <Future<List<UnifiedSearchResult>>>[];
for (final source in enabledSources.take(maxConcurrency)) {
futures.add(
search(keyword, source: source, page: page)
.catchError((_) => <UnifiedSearchResult>[]), // ← 静默丢弃所有错误
);
}
// ...
}
每个源的搜索错误都被静默丢弃,返回空列表。用户无法区分:
- "该源确实没有这个关键词的结果"
- "该源搜索失败了(编码错误/超时/网络不通)"
根因 4:默认种子源使用占位 URL(🟡)
文件位置: sakura_mobile/lib/src/core/source_manager.dart 第 274-317 行
// 预置的 6 个精选源使用 example.invalid 占位 URL
const _seedSources = [
_SeedSource(name: '全本玄幻小说', ...),
_SeedSource(name: '笔趣阁', ...),
// ...
];
这些内置源的 URL 是 https://example.invalid/...(不可访问的占位地址)。它们的作用仅仅是预留名称和 ID,真正的 URL 需要从在线源仓库导入后才能获得。如果用户没有手动导入源仓库,这 6 个默认源将永远返回空结果。
根因 5:5 秒超时可能不够(🟢)
static const perSourceTimeout = Duration(seconds: 5);
中国小说/漫画网站服务器响应可能很慢(尤其是免费站点),5 秒超时后搜索被中断。
路径 B:自建云库搜索(Sakura Cloud API)—— 后端工作正常
涉及文件:
sakura_mobile/lib/src/core/api_client.dart(移动端 API 客户端)sakura_cloud/api/v1/endpoints/gallery.py(画廊搜索)sakura_cloud/api/v1/endpoints/novels.py(小说搜索)
后端分析结论:云库搜索的中文处理是正确的
后端(FastAPI + PostgreSQL)的搜索全部使用 ILIKE(不区分大小写的 LIKE),这是完全 Unicode 感知的匹配方式。中文搜索在后端层面不应该有问题。
# gallery.py 中的搜索逻辑
condition = Artwork.title.ilike(f"%{search_text}%")
如果云库搜索不到中文内容,更可能是:
- 云库中确实没有该关键词的内容(数据未同步或上传)
- 移动端的 API 调用参数传递问题(下面分析)
根因 6:移动端 API 客户端未显式设置编码(🟡)
文件位置: sakura_mobile/lib/src/core/api_client.dart 第 13-19 行
static Dio _dio(String baseUrl) => Dio(BaseOptions(
baseUrl: baseUrl,
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 15),
));
Dio 默认使用 UTF-8 处理查询参数。FastAPI 也默认使用 UTF-8 解析查询参数。只要两端都是默认配置,编码应该保持一致。但如果:
- 云服务器前面有 Nginx 做了编码转换
- 或
baseUrl配置的值与实际后端不一致 - 这些都可能导致请求未到达正确的后端
根因 7:搜索参数条件性发送(🟢)
文件位置: sakura_mobile/lib/src/core/api_client.dart 第 98-106 行
if (search != null && search.trim().isNotEmpty) 'search': search.trim(),
if (search != null && search.trim().isNotEmpty) 'search_scope': searchScope,
search_scope 只在 search 非空时才发送。这意味着不能单独按 search_scope 过滤(如只看有 OCR 文本的作品),但这并非搜索不到的问题。
3.3 修复方案
方案 A:修复 Legado Engine 编码检测(🔴 最重要,解决第三方源搜索)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/core/legado_engine.dart |
添加响应编码检测和 GBK 解码支持 |
具体做法:
-
为 Dio 实例添加
responseDecoder:检测 HTTP 响应头中的Content-Typecharset 字段,如果指定了gbk/gb2312/gb18030,使用对应编码解码;如果没有指定 charset,尝试用 UTF-8 解码,失败则回退到 GBK。 -
代码位置参考(legado_engine.dart ~第 11-14 行):
// 当前 Dio 实例配置应增加 responseDecoder
static final Dio _http = Dio(BaseOptions(
connectTimeout: const Duration(seconds: 10),
receiveTimeout: const Duration(seconds: 10),
// 新增:响应解码器
responseDecoder: _decodeResponse,
));
// 新增:智能编码检测函数
static String _decodeResponse(List<int> bytes, Headers headers, String contentType) {
// 1. 从 Content-Type header 提取 charset
final charset = _extractCharset(contentType);
if (charset != null) {
return _decodeWithCharset(bytes, charset);
}
// 2. 尝试 UTF-8 解码
try {
return utf8.decode(bytes);
} catch (_) {
// 3. UTF-8 失败 → 尝试 GBK
try {
return gbk.decode(bytes);
} catch (_) {
return latin1.decode(bytes); // 保底:按字节原样保留
}
}
}
- 添加
gbk或gbk_codec依赖:Flutter 的dart:convert不包含 GBK 编解码器。需要在pubspec.yaml中添加gbk_codec或其他 GBK 解码包。
方案 B:增加源级别的编码配置(🟡 补充方案 A)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/core/legado_models.dart |
LegadoSource 增加 charset 字段 |
sakura_mobile/lib/src/core/legado_engine.dart |
搜索时根据源的 charset 选择解码器 |
具体做法:
- 在
LegadoSource模型中增加可选字段charset?: string(值为utf-8、gbk、gb2312、auto等) - 在线源仓库(如 legado.aoaostar.com)的 JSON 中许多已包含
charset字段,导入时保留 - 搜索时如果源指定了 charset,直接使用对应编码;未指定则使用方案 A 的自动检测
方案 C:增加 URL 编码选项(🟡 补充方案 A)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/core/legado_engine.dart 第 38 行 |
搜索 URL 构建支持 GBK 百分号编码 |
具体做法:
根据源的 charset 配置选择 URL 编码方式:
utf-8或未指定 → 使用Uri.encodeComponent()(当前行为)gbk/gb2312/gb18030→ 使用 GBK 编码后再百分号编码
方案 D:增加错误诊断信息(🟡 改善用户体验)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/core/legado_engine.dart 第 86 行 |
不再静默丢弃错误 |
具体做法:
searchAll()中的.catchError()不再返回空列表,而是返回带有错误标记的结果- 在
UnifiedSearchResult中增加errorMessage?: string字段 - UI 层(
explore_page.dart)对有错误的源显示灰色提示(如"搜索失败:编码错误")而非静默消失
方案 E:延长超时时间(🟢 简单调整)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/core/legado_engine.dart 第 12-13 行 |
增加超时时间 |
将 perSourceTimeout 从 5 秒增加到 10-15 秒,适应慢速中网站点。
方案 F:确认云库搜索正常(🟢 排查步骤)
如果用户反馈云库("我的云库"板块)搜索也失败,请排查:
- 确认 baseUrl 配置正确:在 APP 设置中检查服务器地址是否为实际运行的云端 API(默认
http://api.kunkunxiaomao.top:8000) - 检查网络连通性:在手机浏览器中访问
http://api.kunkunxiaomao.top:8000/api/v1/health确认可访问 - 确认数据已同步:在桌面端检查是否已将作品同步到云端
- 查看后端日志:检查 FastAPI 的请求日志,确认搜索请求是否到达后端、参数是否正确
3.4 预期效果
- 第三方在线源(笔趣阁、包子漫画等)搜索中文关键词能正常返回结果
- 搜索"海贼王"、"斗罗大陆"、"三体"等常见中文书名能命中
- 搜索失败的源在 UI 上有提示,而非静默显示"无结果"
- 自建云库搜索保持不变(本身已支持中文)
六、手机端加载过慢问题
6.1 问题现象
手机 APP 多个页面加载缓慢,用户感知明显:
- 发现页(FeedTab): 打开后长时间转圈,白屏等待
- 画廊页(GalleryTab): 浏览图片列表时响应慢,尤其是翻页后
- 小说书架(NovelsTab): 首次进入时等待明显
- 图片缩略图: 列表中的图片逐个缓慢出现
6.2 根因分析
6.2.1 发现页(FeedTab)—— 5 个 API 全部完成才渲染(已部分优化,仍有问题)
文件位置: sakura_mobile/lib/src/pages/tabs/feed_tab.dart 第 22-41 行
当前代码已经做了初步优化(拆分为独立 Future + stat 3 秒超时),但仍存在问题:
_statFuture ??= api.galleryStat().timeout(const Duration(seconds: 3),
onTimeout: () => <String, dynamic>{});
_todayFuture ??= api.galleryFeed(mode: 'created', limit: 36)...;
_recentFuture ??= api.galleryFeed(mode: 'recent', limit: 24)...;
_novelFuture ??= api.recentNovels(limit: 12)...;
_alertFuture ??= api.unreadAlerts(limit: 12)...;
问题:
galleryFeed两个模式(created/recent)都调用同一个后端接口,只是排序不同,后端可能做了全表扫描- 5 个请求首次触发时同时发出,没有任何优先级排序,会造成服务端瞬时压力
_ensureFutures()在build()中调用,但有??=缓存机制,切换 tab 后回来不会刷新(除非手动下拉)
6.2.2 画廊页(GalleryTab)—— 单次全量拉取,无分页预加载
文件位置: sakura_mobile/lib/src/pages/tabs/gallery_tab.dart 第 98-110 行
Future<List<Artwork>> _load() async {
final rows = await ref.read(apiClientProvider).gallery(
search: search.text.trim().isEmpty ? null : search.text.trim(),
searchScope: searchScope,
isFavorite: favoritesOnly ? true : null,
contentType: _effectiveContentType,
);
final items = rows
.map((item) => Artwork.fromJson(item as Map<String, dynamic>))
.toList();
items.sort(_compareArtworkNewestFirst);
return items;
}
问题:
- 没有分页参数传入 —— 检查
api_client.dart中gallery()方法(第 88-109 行),虽有page和limit参数,但_load()调用时未传入,导致默认拉取全部数据 - 如果云库中有上千张图片,一次请求拉全部数据 + JSON 解析 + 客户端排序,会非常慢
- 默认
limit在后端只设了 60 条,但如果后端分页参数默认值较高,仍可能拉到大量数据 - 每次切换搜索/筛选条件都触发全量重新加载
6.2.3 小说书架(NovelsTab)—— 3 个请求串行等待全部完成
文件位置: sakura_mobile/lib/src/pages/tabs/novels_tab.dart 第 30-52 行
Future<_NovelShelfData> _load() async {
final api = ref.read(apiClientProvider);
final query = search.text.trim();
final results = await Future.wait<List<dynamic>>([
api.novels(search: query.isEmpty ? null : query),
query.isEmpty
? api.novelSeries(includeChapters: false)
: Future.value(<dynamic>[]),
query.isEmpty ? api.continueReadingNovels() : Future.value(<dynamic>[]),
]);
问题:
- 使用
Future.wait阻塞等待 3 个请求全部完成才渲染 novelSeries和continueReadingNovels的返回速度决定了整个页面的渲染速度- 搜索模式下虽跳过了后两个请求,但搜索本身可能返回大量结果
6.2.4 图片缩略图加载拥塞
涉及文件:
sakura_mobile/lib/src/pages/tabs/feed_tab.dartsakura_mobile/lib/src/pages/tabs/gallery_tab.dart
两个页面都在 ListView / 横向滚动列表中使用 CachedNetworkImage 加载缩略图。Flutter 的 ListView 会预构建视口外一定数量的 item,导致:
- 几十张缩略图同时发起网络请求
- 带宽争抢,每张图都很慢
CachedNetworkImage虽然缓存了磁盘,但首次加载仍需网络
6.2.5 后端 galleryStat() 可能全表 COUNT
后端 /api/v1/gallery/stat 接口如果对 artworks 表做全表 COUNT(*),数据量上万后单次查询就需要数百毫秒甚至数秒。虽然 FeedTab 已经加了 3 秒超时,但这只是掩盖问题而非解决。
6.2.6 后端复合索引可能缺失
artworks 表可能存在以下慢查询场景:
- 按
created_at DESC排序但没有复合索引 galleryFeed可能需要 JOIN 多表(文件表、OCR 表、标签表等)- 每次请求都做全表排序再 LIMIT
6.3 修复方案
方案 A:画廊页分页加载 + 无限滚动(🔴 最重要)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/pages/tabs/gallery_tab.dart |
改为分页加载,滚动到底部自动加载下一页 |
具体做法:
- 在
_GalleryTabState中增加_page、_hasMore、_isLoadingMore状态 - 首次加载只拉 20-30 条
- 给
ListView添加ScrollController,滚动到接近底部时自动加载下一页 - 搜索/筛选条件变化时重置为第 1 页
- 使用
_allItems列表累加各页数据
方案 B:小说书架渐进式加载(🔴 重要)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/pages/tabs/novels_tab.dart 第 30-38 行 |
拆散 Future.wait,各区块独立加载 |
具体做法:
- 将
Future.wait拆为 3 个独立的FutureBuilder - 小说列表(
api.novels)优先渲染 - 系列分组(
api.novelSeries)和继续阅读(api.continueReadingNovels)各自独立加载 - 每个区域有独立的骨架屏/loading 指示器
- 某个区域加载失败不影响其他区域
方案 C:发现页 API 优先级排序(🟡 重要)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/pages/tabs/feed_tab.dart 第 28-41 行 |
按优先级分批发请求 |
具体做法:
- 第一批(立即):统计卡片 + 最近更新(用户最关心的内容)
- 第二批(200ms 后):今日新增
- 第三批(500ms 后):最近小说 + 未读提醒
- 这样首屏在第一批返回后就能展示,而非等 5 个全部完成
方案 D:后端增加 feed 缓存(🟡 解决根本问题)
修改位置: 后端 sakura_cloud/
具体做法:
- 新增
feed_cache表缓存 feed 查询结果 - 上传新作品 / 同步后异步刷新缓存
- 缓存有效期 5-10 分钟,过期后后台刷新
- 首次无缓存时降级直接查询
方案 E:缩略图懒加载优化(🟡 简单有效)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/pages/tabs/gallery_tab.dart |
GridView 使用 addRepaintBoundaries + 更激进的懒加载 |
sakura_mobile/lib/src/pages/tabs/feed_tab.dart |
横向滚动列表限制同时可见的图片数量 |
具体做法:
- 使用
ListView.builder的addRepaintBoundaries: true(默认已开启) - 为
CachedNetworkImage增加placeholder和低分辨率占位图 - 将
cacheWidth/cacheHeight限制为实际显示尺寸(如缩略图只需 300px 宽),避免下载原图再缩放 - 横向滚动条限制预加载数量(
cacheExtent调小)
方案 F:后端优化数据库索引(🟢 性能增强)
修改位置: 后端数据库迁移
具体做法:
- 为
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);
CREATE INDEX idx_artworks_content_type ON artworks(user_id, content_type, created_at DESC);
- 为
novels表添加索引:
CREATE INDEX idx_novels_user_updated ON novels(user_id, updated_at DESC);
CREATE INDEX idx_novels_series ON novels(series_id, chapter_order);
galleryStat()使用估算而非精确 COUNT(如 PostgreSQL 的pg_stat_user_tables.n_live_tup),或缓存统计结果
方案 G:本地缓存优先(🟢 移动端离线方案)
修改位置:
| 文件 | 修改内容 |
|---|---|
sakura_mobile/lib/src/core/api_client.dart |
新增本地缓存读写方法 |
sakura_mobile/lib/src/pages/tabs/feed_tab.dart |
优先读本地缓存,后台静默刷新 |
具体做法:
- 使用
sqflite或hive存储首页 / 画廊列表的缓存数据 - 打开页面时先展示缓存(秒开),同时后台请求新数据
- 新数据到达后平滑替换
- 缓存有效期 30 分钟
6.4 预期效果
- 发现页首屏从 3-5 秒降到 1 秒以内(缓存命中时秒开)
- 画廊页从一次性加载全部变为分页 20-30 条,首屏加载时间减半
- 小说书架各区块独立呈现,不再互相阻塞
- 缩略图加载拥塞缓解,滚动时图片更快出现
七、实施优先级与排期建议
| 优先级 | 问题 | 推荐方案 | 改动范围 | 预期效果 |
|---|---|---|---|---|
| 🔴 P0 紧急 | Web 端详情不显示 | 重写 UserDetailPage.vue + 修复路由 | Web 前端 2 个文件 | 详情页正常展示内容 |
| 🔴 P0 紧急 | Web 端缺少漫画板块 | 新增 manga 路由 + 侧边栏入口 + content_type 筛选 | Web 前端 3 个文件 | 漫画内容独立展示和搜索 |
| 🔴 P0 紧急 | Web 端列表页无分页 + COUNT 慢 | 方案 A + B:前端分页控件 + 后端去掉 COUNT | Web 前端 1 文件 + 后端 1 文件 | 列表加载从 2-5s 降到 <500ms |
| 🔴 P0 紧急 | 第三方源中文搜索失败 | 方案 A:Legado Engine 编码修复 | 移动端 1-2 个文件 + 新增依赖 | 搜索中文返回正确结果 |
| 🔴 P0 紧急 | 画廊页全量加载过慢 | 方案 A:分页加载 + 无限滚动 | 移动端 1 个文件 | 首屏加载从秒级降到毫秒级 |
| 🔴 P0 紧急 | 小说书架阻塞等待 | 方案 B:渐进式加载 | 移动端 1 个文件 | 各区块独立渲染不阻塞 |
| 🟡 P1 高 | Web 端搜索无防抖 | 方案 C:搜索 400ms 防抖 | Web 前端 1 个文件 | 输入即搜,减少冗余请求 |
| 🟡 P1 高 | URL 编码不匹配旧站点 | 方案 C(搜索):源级别编码配置 | 移动端 2-3 个文件 | 兼容 GBK 后端的老网站 |
| 🟡 P1 高 | 搜索错误无提示 | 方案 D(搜索):错误诊断信息 | 移动端 3-4 个文件 | 用户能区分"无结果"和"搜索失败" |
| 🟡 P1 高 | 发现页 API 无优先级 | 方案 C(加载):API 优先级排序 | 移动端 1 个文件 | 首屏更快展示核心内容 |
| 🟡 P1 高 | 后端 feed 查询慢 | 方案 D(加载):feed_cache 表 | 后端新增表 + 定时刷新 | 发现页加速 50%+ |
| 🟢 P2 中 | 缩略图拥塞 | 方案 E:缩略图懒加载优化 | 移动端 2 个文件 | 图片加载更流畅 |
| 🟢 P2 中 | 数据库索引缺失 | 方案 F:后端优化索引 | 后端 migration | 查询耗时降低 50%+ |
| 🟢 P2 中 | 超时太短 | 方案 E(搜索):延长超时 | 移动端 1 行 | 慢速站点有足够时间响应 |
| 🟢 P2 中 | 本地缓存 | 方案 G:移动端本地缓存 | 移动端新增缓存层 | 二次打开秒开 |
| 🟢 P2 中 | Web 端缩略图缓存 | 方案 D(加载):CDN/MinIO 公开 URL + Cache-Control | 后端 1 文件 | 缩略图加载更快 |
附录:关键文件索引
| 文件 | 用途 |
|---|---|
sakura_admin_web/src/views/app/UserDetailPage.vue |
Web 详情页(占位组件需重写) |
sakura_admin_web/src/views/app/UserListPage.vue |
Web 列表页(无分页、无防抖、无漫画筛选) |
sakura_admin_web/src/views/app/AppLayout.vue |
Web 侧边栏(缺少漫画入口) |
sakura_admin_web/src/router/index.ts |
Web 路由配置(缺少 manga 路由、id 未传递) |
sakura_admin_web/src/api/http.ts |
Web 端 HTTP 客户端(Axios 配置) |
sakura_admin_web/src/views/admin/AdminUserDetail.vue |
参考实现——正确的详情加载模式 |
sakura_mobile/lib/src/core/legado_engine.dart |
移动端第三方搜索引擎(编码问题) |
sakura_mobile/lib/src/core/legado_rule_parser.dart |
HTML/JSON 解析器 |
sakura_mobile/lib/src/core/api_client.dart |
移动端云 API 客户端 |
sakura_mobile/lib/src/core/source_manager.dart |
第三方源管理 |
sakura_mobile/lib/src/pages/tabs/feed_tab.dart |
发现页(加载性能问题) |
sakura_mobile/lib/src/pages/tabs/gallery_tab.dart |
画廊页(全量加载/分页缺失) |
sakura_mobile/lib/src/pages/tabs/novels_tab.dart |
小说书架(阻塞等待) |
sakura_cloud/api/v1/endpoints/gallery.py |
后端画廊 API(COUNT 慢查询、content_type 筛选) |
sakura_cloud/api/v1/endpoints/novels.py |
后端小说 API(含详情和搜索) |
sakura_cloud/api/v1/endpoints/me.py |
后端用户个人 API(缺少详情路由) |
sakura_cloud/api/v1/endpoints/files.py |
后端文件 API(缩略图无缓存策略) |
sakura_cloud/models/artwork.py |
Artwork 模型(content_type 已支持 manga) |
sakura_cloud/scripts/create_admin.py |
管理员账号创建脚本 |
sakura_cloud/core/config.py |
后端配置(含数据库/MinIO/JWT 凭证) |