# Web 端详情加载、手机端搜索与加载性能优化方案 > 更新日期:2026-06-15 > 范围:Sakura Admin Web (Vue.js) + Sakura Mobile (Flutter) + Sakura Cloud (FastAPI) > 说明:本文档提供问题分析与优化方案,不包含实际代码改动。 --- ## 目录 1. [管理员账号密码](#一管理员账号密码) 2. [Web 端详情数据按需加载问题](#二web-端详情数据按需加载问题) 3. [Web 端缺少漫画板块问题](#三web-端缺少漫画板块问题) 4. [Web 端列表加载性能问题](#四web-端列表加载性能问题) 5. [手机端搜索不到图书问题](#五手机端搜索不到图书问题) 6. [手机端加载过慢问题](#六手机端加载过慢问题) 7. [实施优先级与排期建议](#七实施优先级与排期建议) --- ## 一、管理员账号密码 ### 1.1 现状 本项目**没有预设的默认管理员账号密码**。数据库初始化脚本(`sakura_cloud/scripts/init_db.py`)仅创建空表结构,不插入任何种子数据。 管理员账号需要**部署后手动创建**,使用后端提供的 CLI 脚本。 ### 1.2 创建管理员账号的方法 **脚本位置:** `sakura_cloud/scripts/create_admin.py` **使用方法:** ```bash # 在后端服务器上执行(需在 sakura_cloud 可导入的环境下) python -m sakura_cloud.scripts.create_admin \ --username admin \ --email admin@example.com \ --password YourPassword123 ``` **参数说明:** | 参数 | 必填 | 说明 | |------|------|------| | `--username` | 是 | 管理员用户名 | | `--email` | 是 | 管理员邮箱 | | `--password` | 否 | 密码(最少 8 位)。如不传,运行时会交互式提示输入(不显示在终端) | **脚本逻辑:** 1. 检查是否已存在 `SUPER_ADMIN` 角色的用户 2. 如果数据库中没有匹配用户名/邮箱的用户 → 创建新的 SUPER_ADMIN 3. 如果已存在该用户但角色不是 SUPER_ADMIN,且已有其他 SUPER_ADMIN → 拒绝提升(防止越权) 4. 如果已存在该用户且尚无 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 如果忘记了管理员密码 由于没有预设账号,如果忘记密码: 1. **方法一(推荐):** 重新运行 `create_admin.py` 脚本,指定相同的 `--username` 和 `--email`,输入新密码即可覆盖。 2. **方法二:** 直接在数据库中修改 `password_hash` 字段(需要先用 Python 生成 bcrypt/pbkdf2_sha256 哈希)。 3. **方法三:** 如果数据库中有其他管理员账号,可以用该账号登录后在管理后台重置密码。 --- ## 二、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` 当前完整代码: ```vue ``` **缺失的关键要素:** - ❌ 没有 `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 行 ```typescript { path: "gallery/:id", component: UserDetailPage, props: { kind: "gallery" } }, { path: "novels/:id", component: UserDetailPage, props: { kind: "novels" } }, ``` `props` 被设置为**静态对象** `{ kind: "gallery" }`,这意味着: - `props.id` 始终为 `undefined` - 即便组件内部添加了 API 调用,也无法知道要请求哪个 ID 的作品 正确做法应使用以下之一: ```typescript // 方式一:自动传递所有 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` 工作正常 ```typescript import { onMounted, ref } from "vue"; import { useRoute } from "vue-router"; import { apiData, http } from "../../api/http"; const route = useRoute(); const user = ref | null>(null); async function load() { const response = await http.get(`/admin/users/${route.params.id}`); user.value = apiData>(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`) ```typescript // 将: { 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` 模式) 1. 导入 `onMounted`、`ref`、`http`、`apiData` 2. 在 `props` 类型中增加 `id?: string` 3. 在 `onMounted` 中根据 `props.kind` 调用不同的 API: - `kind === "gallery"` → `GET /api/v1/gallery/${props.id}` - `kind === "novels"` → `GET /api/v1/novels/${props.id}` - `kind === "profile"` → 保持现有逻辑(使用 `authState.user`) 4. 添加 loading 和 error 状态 5. 更新模板,将 `{{ content }}` 替换为结构化展示(标题、作者、标签、缩略图等) **步骤 3(可选):在后端添加 `/me/` 前缀的详情路由** 在 `sakura_cloud/api/v1/endpoints/me.py` 中添加: ```python @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` 路由子节点: ```typescript 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 行 ```vue 概览 图片 小说 提醒 我的 ``` 侧边栏没有"漫画"导航项。 #### 根因 2:UserListPage 的 `kind` 类型不包含 manga **文件位置:** `sakura_admin_web/src/views/app/UserListPage.vue` 第 27 行 ```typescript const props = defineProps<{ kind: "gallery" | "novels" | "alerts" }>(); ``` `kind` 的 TypeScript 类型仅为 `"gallery" | "novels" | "alerts"`,不包含 `"manga"`。 第 31 行的标题映射也缺少 manga: ```typescript const title = computed(() => ({ gallery: "图片", novels: "小说", alerts: "提醒中心" }[props.kind])); ``` 第 41 行的 API 调用路径硬编码了 `kind`: ```typescript 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`) ```typescript // 在 /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`) ```vue 漫画 ``` **步骤 3:UserListPage 增加 manga 支持** ```typescript // 将 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 = {}; 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(response); items.value = Array.isArray(data) ? data : data.items || []; } finally { loading.value = false; } } ``` **步骤 4:UserDetailPage 增加 manga 详情加载**(与方案二中详情页修复合并实施) 在 `loadDetail()` 逻辑中增加: ```typescript if (props.kind === "manga") { const response = await http.get(`/gallery/${props.id}`); item.value = apiData(response); } ``` > **设计说明:** 漫画和图片在后端共用 `gallery` API(同一张 `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 行 ```typescript 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(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 行 ```python 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 行 ```vue ``` **问题:** - 用户按 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 行 ```typescript 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 控件、分页加载逻辑 | **具体做法:** 1. 在 `