80 KiB
APK 端漫画/小说第三方源集成 + WEB 端认证修复方案
更新日期:2026-06-15 范围:Sakura Mobile (Flutter APK) + Sakura Cloud (FastAPI) + Sakura Admin Web (Vue.js) 说明:本文档提供完整的问题分析与实现方案,按模块划分,方便逐步实施。
目录
一、APK 端:漫画与小说第三方来源网站集成
1.1 现状分析
当前 Sakura Mobile Flutter 应用的画廊(Gallery)和小说(Novels)板块,数据来源仅限于:
- 自建 Sakura Cloud 后端(
api.kunkunxiaomao.top:8000)—— 即用户手动同步/上传到私有云的内容 - 移动端
api_client.dart中的gallery()和novels()方法直接调用云端 API - 没有接入任何第三方漫画/小说源
1.2 目标与核心约束
为漫画板块和小说板块分别接入多个第三方内容源,用户在 APP 内可选择不同来源站点浏览内容。
📌 核心设计原则
原则 1:三层漏斗模型 —— 6000+ 是仓库规模,不是搜索规模
源仓库 Repo(5 个预置入口) │ 用户按需导入 ▼ 源规则 Source(6000+ 条规则,按需存本地) │ 用户手动启用 ▼ 已启用源 Enabled Source(默认 6 个精选,用户自行扩展)
- 第一层:APP 内置 5 个源仓库 入口 URL(不内置规则本身)
- 第二层:用户从仓库导入规则后,规则存于本地(不自动启用)
- 第三层:用户手动勾选启用哪些源,只有已启用的源参与搜索
- 默认策略:首次安装仅启用 精选小说源 3 个 + 精选漫画源 3 个
原则 2:纯实时流式读取,不下载到云端或本地
所有第三方源的内容仅做实时流式浏览,不经过 Sakura Cloud 后端存储,也不写入手机本地持久化目录。
- 图片/文本在 APP 内存中临时加载,离开页面即释放
- 不使用
CachedNetworkImage的持久缓存(可用内存缓存,退出 APP 清空)- 不触发任何下载行为:不保存到系统图库、不写入本地文件、不同步到私有云
原则 3:跨源聚合搜索 + 安全限流
用户输入一个关键词 → 并行查询已启用的源,结果按来源分组展示。
- 搜索一次 = 并行请求已启用的源(默认 6 个,非 6000 个)
- 最大并发 10 个源、单源超时 5 秒、失败静默跳过
- 用户在"源管理"中可自行扩展启用的源数量
- 结果按来源分组,同作品在不同源中按源分别列出
原则 4:APK 不支持 Pixiv 实时查看(⚠️ 重要)
Pixiv 的反爬虫机制导致其图片/小说内容无法在移动端直接实时访问:
- Pixiv 图片服务器(
i.pximg.net)有严格的 Referer 检查,APP 内直接加载会 403- 因此 Pixiv 不接入第三方实时源,Pixiv 内容仍走现有的"桌面端下载 → 同步到私有云 → APP 浏览"流程
- 其他源(Legado 生态中的公开源)不受此限制
1.3 源站方案:基于 Legado(阅读)规则引擎 + 预置源仓库
与其为每个站点手写解析器(工作量大、维护成本高),更合理的方案是:在 Flutter 中内置一个轻量级 Legado 规则引擎,直接复用"阅读"生态已有的 6000+ 条书源规则。
推荐的预置源仓库
| 源名称 | 地址 | 规模 | 用途 |
|---|---|---|---|
| 全量综合源 | https://legado.aoaostar.com/ |
6000+ | 小说 + 漫画 + 有声,首页一键导入 |
| 精简高速源 | https://www.yckceo.com/yuedu/shuyuans/json/id/640.json |
~2200 | 已校验去重,稳定可靠 |
| 漫画专享源 | https://gcore.jsdelivr.net/gh/yuedu521/yiciyuan/1012.json |
208 | 纯漫画源,聚焦漫画场景 |
| 订阅源(推荐) | https://www.yckceo.com/yuedu/rss/json/id/193.json |
持续更新 | 自动推送最新源,一次配置永久省心 |
| Venera 漫画源 | https://git.nyne.dev/nyne/venera-configs/raw/branch/main/index.json |
精选 | 漫画专用配置,持续维护 |
Legado 源格式简介
每个源是一个 JSON 对象,核心字段:
{
"bookSourceName": "源名称",
"bookSourceUrl": "https://example.com",
"bookSourceType": 0,
"ruleSearch": {
"bookList": "...",
"name": "...",
"author": "...",
"coverUrl": "...",
"detailUrl": "..."
},
"ruleBookInfo": {
"name": "...",
"author": "...",
"coverUrl": "...",
"intro": "...",
"chapterList": "..."
},
"ruleContent": {
"content": "..."
},
"ruleToc": {
"chapterList": "...",
"chapterName": "...",
"chapterUrl": "..."
},
"httpUserAgent": "Mozilla/5.0 ...",
"header": "{\"Referer\": \"...\"}"
}
规则类型说明:
ruleSearch— 搜索规则(URL 模板 + 结果列表 CSS/JSONPath 选择器)ruleBookInfo— 书籍详情规则(封面、简介、作者等字段提取)ruleToc— 章节目录规则(章节列表 + 名称 + URL 提取)ruleContent— 正文内容规则(正文提取 + 广告/乱码清洗)- 支持 CSS 选择器、XPath、正则、JSONPath 四种规则语法
- 支持 JavaScript 预处理(高级源),但首版可先跳过
❌ 明确排除的源
| 来源 | 排除原因 |
|---|---|
| Pixiv (漫画+小说) | 图片服务器 i.pximg.net 有严格 Referer + Cookie 检查,APP 端直连 403;反爬机制频繁更新,绕过成本高。Pixiv 内容维持现有流程:桌面端下载 → 同步私有云 → APP 浏览 |
| 需要付费账号的源 | 首版先覆盖免费公开源 |
1.4 架构设计
┌──────────────────────────────────────────────────────────────────┐
│ Sakura Mobile (Flutter) │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ 三层漏斗模型 ──────────────────────────────────────────────┐ │
│ │ │ │
│ │ ① 源仓库 Repo ② 源规则 Source ③ 已启用源 │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │ │
│ │ │ 5 个预置入口 │ ──▶ │ 6000+ 条规则 │ ──▶ │ 6 个精选 │ │ │
│ │ │ (本地仅存URL) │ │ (用户按需导入)│ │ (默认启用) │ │ │
│ │ └──────────────┘ └──────────────┘ └────────────┘ │ │
│ │ 规模:5 规模:按需 规模:6~N(可控) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ 搜索时:仅 ③ 已启用源 参与,最大并发 10,单源超时 5s │
│ │
├──────────────────────────────────────────────────────────────────┤
│ │
│ GalleryTab / NovelsTab / ExplorePage(统一搜索页) │
│ │ │
│ ├── 云库 Tab:现有流程(Pixiv 同步内容) │
│ │ │
│ └── 在线 Tab:纯实时流 │
│ │ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ SourceManager │ ← 管理三层:仓库/规则/启用 │
│ │ - 预置仓库 URL │ │
│ │ - 导入/启用/禁用 │ │
│ │ - 默认精选源 6 个 │ │
│ └───────────┬────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ LegadoRuleEngine │ ← 规则引擎(纯 Dart) │
│ │ CSS / XPath / JSON │ │
│ └───────────┬────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ 搜索限流器:maxConcurrency=10, timeout=5s │ │
│ └────────────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 纯内存流式渲染 │ ← 不写磁盘、不入云库 │
│ │ (Memory Only) │ │
│ └──────────────────┘ │
│ │
│ ⚠️ Pixiv → 桌面端下载 → 同步云库 → APP 云库Tab 查看 │
└──────────────────────────────────────────────────────────────────┘
搜索并发控制:
| 参数 | 默认值 | 说明 |
|---|---|---|
| 最大并发源数 | 10 | 一次搜索最多同时请求 10 个源 |
| 单源超时 | 5s | 超时自动放弃,不阻塞其他源 |
| 失败策略 | 静默跳过 | 单个源失败不影响搜索整体结果 |
| 默认启用源 | 6 | 小说 3 个 + 漫画 3 个精选源 |
| 用户可扩展至 | N | 高级设置中手动启用更多,无硬上限但受并发限制 |
1.5 实现方案(Flutter 侧)
Step 1:Legado 规则引擎(核心)
在 sakura_mobile/lib/src/legado/ 新建规则引擎:
sakura_mobile/lib/src/legado/
├── legado_engine.dart # 引擎入口:加载源 → 执行搜索/详情/目录/正文
├── rule_parser.dart # 规则解析器:解析 CSS/XPath/JSONPath/Regex 规则
├── source_loader.dart # 源加载器:从 URL/文件/内置 assets 加载源 JSON
├── http_client.dart # HTTP 封装:自动添加 UA/Referer/Cookie
├── source_manager.dart # 源管理器:增删改查 + 启用禁用 + 订阅更新
└── models/
├── legado_source.dart # Legado 源数据模型
└── search_result.dart # 统一搜索结果模型
Legado 源数据模型:
// sakura_mobile/lib/src/legado/models/legado_source.dart
class LegadoSource {
final String bookSourceName; // 源名称
final String bookSourceUrl; // 源站点 URL
final int bookSourceType; // 0=文本 1=音频 2=图片(漫画)
final String? bookSourceGroup; // 分组标签
final String? bookSourceComment;// 备注
// 搜索规则
final SearchRule? ruleSearch;
// 书籍详情规则
final BookInfoRule? ruleBookInfo;
// 章节目录规则
final TocRule? ruleToc;
// 正文内容规则
final ContentRule? ruleContent;
// HTTP 配置
final String? httpUserAgent;
final Map<String, String>? headers;
// 元数据
final String? sourceUrl; // 来源 URL(远程导入时记录)
final DateTime? lastUpdated;
final bool enabled; // 用户可禁用某个源
// ... fromJson / toJson
}
class SearchRule {
final String? url; // 搜索 URL 模板,{{key}} 替换为关键词
final String? method; // GET/POST
final String? body; // POST body
final String? bookList; // 结果列表选择器
final String? name; // 书名选择器
final String? author; // 作者选择器
final String? coverUrl; // 封面选择器
final String? detailUrl; // 详情页 URL 选择器
final String? kind; // 规则类型:css/xpath/json/regex
}
class BookInfoRule {
final String? name;
final String? author;
final String? coverUrl;
final String? intro; // 简介
final String? kind;
final String? chapterList; // 目录列表选择器(部分源目录在详情页)
final String? chapterName;
final String? chapterUrl;
}
class TocRule {
final String? chapterList;
final String? chapterName;
final String? chapterUrl;
final String? kind;
final String? nextTocUrl; // 分页目录的下一页
}
class ContentRule {
final String? content; // 正文提取规则
final String? kind;
final String? replaceRegex; // 正则清洗(去除广告等)
final String? webJs; // JavaScript 预处理(高级,可延后支持)
}
规则引擎核心逻辑:
// sakura_mobile/lib/src/legado/legado_engine.dart
class LegadoEngine {
final LegadoHttpClient _http;
LegadoEngine({LegadoHttpClient? http}) : _http = http ?? LegadoHttpClient();
/// 根据搜索规则,发起搜索请求并解析结果
Future<List<UnifiedSearchResult>> search(
LegadoSource source,
String keyword, {
int page = 1,
}) async {
final rule = source.ruleSearch;
if (rule == null) return [];
// 1. 构建搜索 URL(替换 {{key}} 占位符)
final url = rule.url!
.replaceAll('{{key}}', Uri.encodeComponent(keyword))
.replaceAll('{{page}}', page.toString());
// 2. 发起 HTTP 请求
final body = await _http.request(
url: url,
method: rule.method ?? 'GET',
headers: source.headers,
userAgent: source.httpUserAgent,
);
// 3. 根据规则类型解析 HTML/JSON
final parser = RuleParser(body, baseUrl: source.bookSourceUrl);
final bookList = parser.selectList(rule.bookList!, kind: rule.kind);
// 4. 对每条结果提取字段
return bookList.map((item) {
return UnifiedSearchResult(
sourceName: source.bookSourceName,
title: parser.select(item, rule.name!, kind: rule.kind),
author: parser.select(item, rule.author, kind: rule.kind),
coverUrl: parser.select(item, rule.coverUrl, kind: rule.kind),
detailUrl: parser.select(item, rule.detailUrl!, kind: rule.kind),
);
}).toList();
}
/// 获取书籍详情(元信息 + 章节目录)
Future<BookDetail> getDetail(LegadoSource source, String detailUrl) async { ... }
/// 获取章节正文(提取 + 清洗)
Future<String> getContent(LegadoSource source, String chapterUrl) async { ... }
}
规则解析器(RuleParser)—— 支持四种语法:
// sakura_mobile/lib/src/legado/rule_parser.dart
// 利用现有 pub.dev 包实现(无需从零造轮子)
import 'package:html/dom.dart' as html_dom;
import 'package:html/parser.dart' as html_parser;
import 'package:xpath_parser/xpath_parser.dart';
import 'package:json_path/json_path.dart';
class RuleParser {
final String _body;
final String _baseUrl;
html_dom.Document? _doc;
dynamic _json; // lazy parse
RuleParser(this._body, {required String baseUrl}) : _baseUrl = baseUrl;
/// 选择单个文本
String select(String node, String? rule, {String? kind}) {
if (rule == null || rule.isEmpty) return '';
final parsed = _parseRule(rule);
switch (kind ?? parsed.type) {
case 'css':
return _cssSelectOne(node, parsed.expression);
case 'xpath':
return _xpathSelectOne(node, parsed.expression);
case 'json':
return _jsonPathSelectOne(node, parsed.expression);
case 'regex':
return _regexExtract(node, parsed.expression);
default:
return _cssSelectOne(node, rule);
}
}
/// 选择列表
List<String> selectList(String node, String? rule, {String? kind}) { ... }
// 内部实现,利用成熟的 pub 包…
String _cssSelectOne(String html, String selector) { ... }
String _xpathSelectOne(String html, String xpath) { ... }
String _jsonPathSelectOne(String json, String path) { ... }
}
依赖包:
html(HTML DOM 解析)、json_path(JSONPath)、已有 pub 上有成熟的 CSS 选择器和 XPath 包可用。这些包都是纯 Dart 实现,不依赖原生平台代码,可直接在 Flutter 中使用。
Step 2:源管理器 —— 三层漏斗 + 默认精选
// sakura_mobile/lib/src/legado/source_manager.dart
/// ┌─────────────────────────────────────────────────────┐
/// │ 三层漏斗模型 │
/// │ │
/// │ ① 源仓库 Repo ② 源规则 Source ③ 已启用源 │
/// │ 规模: 5 个预置 规模: 按需导入 规模: 6~N │
/// │ 仅存 URL 用户手动启用 参与搜索 │
/// └─────────────────────────────────────────────────────┘
class SourceManager {
// ============================================
// ① 源仓库层:5 个预置入口(仅存 URL,不含规则)
// ============================================
static const builtinSourceRepos = [
SourceRepo(
name: '全量综合源',
url: 'https://legado.aoaostar.com/',
description: '6000+ 站点,含小说、漫画、有声',
category: '综合',
),
SourceRepo(
name: '精简高速源',
url: 'https://www.yckceo.com/yuedu/shuyuans/json/id/640.json',
description: '约 2200 条,已校验去重,稳定可靠',
category: '综合',
),
SourceRepo(
name: '漫画专享源',
url: 'https://gcore.jsdelivr.net/gh/yuedu521/yiciyuan/1012.json',
description: '208 条漫画专用源',
category: '漫画',
),
SourceRepo(
name: '订阅源(推荐)',
url: 'https://www.yckceo.com/yuedu/rss/json/id/193.json',
description: '自动推送最新源,一次配置永久省心',
category: '订阅',
isSubscription: true,
),
SourceRepo(
name: 'Venera 漫画源',
url: 'https://git.nyne.dev/nyne/venera-configs/raw/branch/main/index.json',
description: '精选漫画配置,持续维护',
category: '漫画',
),
];
// ============================================
// ② 源规则层:所有已导入的规则(导入 ≠ 启用)
// ============================================
final List<LegadoSource> _importedSources = [];
// ============================================
// ③ 已启用源:默认仅 6 个精选源
// ============================================
/// 首次安装默认启用的精选源名称列表
static const defaultEnabledNovelSources = [
'全本玄幻小说', // 小说
'笔趣阁', // 小说
'妙笔阁', // 小说
];
static const defaultEnabledMangaSources = [
'包子漫画', // 漫画
'古风漫画网', // 漫画
'COCO漫画', // 漫画
];
/// 首次启动时自动执行:导入精选源 + 启用
Future<void> initializeIfFirstRun() async {
final prefs = await SharedPreferences.getInstance();
if (prefs.getBool('source_manager_initialized') == true) return;
// 从精简高速源仓库导入规则(2200 条)
await importFromRepo(builtinSourceRepos[1]); // 精简高速源
// 仅启用 6 个精选源
final allNovelNames = defaultEnabledNovelSources.toSet();
final allMangaNames = defaultEnabledMangaSources.toSet();
for (final source in _importedSources) {
if (allNovelNames.contains(source.bookSourceName) ||
allMangaNames.contains(source.bookSourceName)) {
_enabledSourceNames.add(source.bookSourceName);
}
}
await prefs.setBool('source_manager_initialized', true);
}
/// 获取参与搜索的源(仅 ③ 已启用源)
List<LegadoSource> get enabledSources =>
_importedSources.where((s) => _enabledSourceNames.contains(s.bookSourceName)).toList();
/// 从仓库导入规则(导入 ≠ 启用,用户需手动勾选)
Future<int> importFromRepo(SourceRepo repo) async { ... }
/// 从 URL 导入用户自定义源
Future<int> importFromUrl(String url) async { ... }
/// 从本地 JSON 文件导入
Future<int> importFromFile(String filePath) async { ... }
/// 手动启用/禁用某个源
Future<void> setEnabled(String sourceName, bool enabled) async { ... }
}
首次安装体验流程:
用户首次打开 APP
│
├─→ 自动从"精简高速源"仓库导入约 2200 条规则到本地
│
├─→ 自动启用 6 个精选源(小说 3 + 漫画 3)
│
├─→ 用户在探索页搜索 → 仅这 6 个源参与
│
└─→ 用户进入"源管理" → 可看到 5 个仓库入口
├─→ 点击"全量综合源" → 导入 6000+ 条到本地
├─→ 逐一手动勾选启用 → 启用源扩展到 N 个
└─→ 搜索时最多并发 10 个
搜索限流器:
// sakura_mobile/lib/src/legado/legado_engine.dart
class LegadoEngine {
static const maxConcurrency = 10; // 最多同时请求 10 个源
static const perSourceTimeout = Duration(seconds: 5); // 单源超时
/// 搜索入口:自动限制并发 + 超时
Future<List<UnifiedSearchResult>> searchAll(
List<LegadoSource> enabledSources,
String keyword,
) async {
// 只取前 N 个(如果用户启用了 >10 个源)
final batch = enabledSources.take(maxConcurrency).toList();
final results = <UnifiedSearchResult>[];
// 并行搜索,单源失败不影响其余
final responses = await Future.wait(
batch.map((source) =>
search(source, keyword)
.timeout(perSourceTimeout)
.catchError((_) => <UnifiedSearchResult>[]) // 静默跳过失败源
),
);
for (final list in responses) {
results.addAll(list);
}
return results;
}
}
#### Step 3:UI 层 —— 源管理页面(展示三层漏斗)
新建 `sakura_mobile/lib/src/pages/source_manager_page.dart`:
┌──────────────────────────────────────────────┐ │ ← 源管理 [+ 自定义导入] │ ├──────────────────────────────────────────────┤ │ │ │ 📊 统计:已导入 2200 条 | 已启用 6 个 │ │ │ │ ── ① 源仓库(5 个预置入口) ────────────── │ │ ┌──────────────────────────────────────────┐│ │ │ 📚 全量综合源 [导入 6000+ 条] ││ │ │ legado.aoaostar.com 未导入 ││ │ ├──────────────────────────────────────────┤│ │ │ 🚀 精简高速源 [已导入 2200 条] ││ │ │ yckceo.com ✓ 已导入 ││ │ ├──────────────────────────────────────────┤│ │ │ 🎨 漫画专享源 [导入 208 条] ││ │ │ 208 条漫画专用 未导入 ││ │ ├──────────────────────────────────────────┤│ │ │ 📡 订阅源(推荐) [订阅] ││ │ │ 自动推送最新源 未订阅 ││ │ ├──────────────────────────────────────────┤│ │ │ 🎌 Venera 漫画源 [导入] ││ │ │ 精选漫画配置 未导入 ││ │ └──────────────────────────────────────────┘│ │ │ │ ── ② 源规则(已导入 2200 条)──────────── │ │ ┌──────────────────────────────────────────┐│ │ │ 🔍 搜索已导入的源... ││ │ │ [✓ 已启用] [ ] 小说源 [ ] 漫画源 ││ │ ├──────────────────────────────────────────┤│ │ │ [✓] 全本玄幻小说 📖 小说 [禁用] ││ │ │ [✓] 笔趣阁 📖 小说 [禁用] ││ │ │ [✓] 妙笔阁 📖 小说 [禁用] ││ │ │ [✓] 包子漫画 🎨 漫画 [禁用] ││ │ │ [✓] 古风漫画网 🎨 漫画 [禁用] ││ │ │ [✓] COCO漫画 🎨 漫画 [禁用] ││ │ │ ── 以下未启用 ───────────────────────── ││ │ │ [ ] 笔趣阁2 📖 小说 [启用] ││ │ │ [ ] 顶点小说 📖 小说 [启用] ││ │ │ [ ] ... 共 2194 条未启用 ││ │ └──────────────────────────────────────────┘│ │ │ │ ── ③ 搜索配置 ────────────────────────── │ │ ┌──────────────────────────────────────────┐│ │ │ 最大并发源数: [■■■■■■■■■□] 10 ││ │ │ 单源超时时间: [■■■■■□□□□□] 5 秒 ││ │ │ 已启用源总数: 6 个(参与搜索) ││ │ │ ││ │ │ ⚠️ 启用源越多,搜索越慢。建议保持 ≤20 个 ││ │ └──────────────────────────────────────────┘│ │ │ │ 🔗 高级:自定义导入 │ │ ┌──────────────────────────────────────────┐│ │ │ [https://... ] [从URL导入] ││ │ │ [选择本地JSON文件] [从文件导入] ││ │ └──────────────────────────────────────────┘│ └──────────────────────────────────────────────┘
#### Step 4:跨源搜索入口
在 GalleryTab / NovelsTab / ExplorePage 中调用:
```dart
// 用户点击搜索后
final manager = ref.read(sourceManagerProvider);
final engine = ref.read(legadoEngineProvider);
final enabledSources = manager.enabledSources;
// 并行搜索所有已启用的源 + 云库
final results = await Future.wait([
// 云库搜索
api.gallery(search: query, ...),
// 所有第三方源并行搜索
...enabledSources.map((source) =>
engine.search(source, query).catchError((_) => <UnifiedSearchResult>[])
),
]);
二、APK 端:未保存内容的在线搜索与实时浏览
2.1 现状分析
当前移动端的搜索功能仅限于已同步到云端的内容:
GalleryTab._load()调用api.gallery(search: ...)→ 仅查询 Sakura Cloud 数据库中已有的 ArtworkNovelsTab._load()调用api.novels(search: ...)→ 仅查询 Sakura Cloud 数据库中已有的 Novel- 用户无法搜索尚未保存/同步到私有云的外部作品
2.2 目标
- 用户输入一个关键词 → 自动并行搜索所有第三方源 + 云库,结果聚合展示
- 搜索结果即时展示封面、标题、作者、来源等元信息
- 点击后纯内存流式浏览,不下载到本地,不同步到云库
- Pixiv 不参与实时搜索/浏览,Pixiv 内容仍走桌面端同步流程
2.3 跨源聚合搜索设计
用户输入 "鬼灭之刃"
│
▼
┌──────────────────────────────────────────────────────┐
│ CrossSourceSearch.aggregate() │
│ │
│ 仅搜索 ③ 已启用源(默认 6 个,非 6000 个) │
│ 并发限制 max=10, 单源超时 5s, 失败静默跳过 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 我的云库 │ │ 包子漫画 │ │ 古风漫画 │ ... │
│ │ (已有) │ │ (启用) │ │ (启用) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ AggregatedResults (按源分组) │ │
│ │ │ │
│ │ 📦 我的云库 (3条) ← Pixiv 同步内容 │ │
│ │ 📦 包子漫画 (5条) ← Legado 规则引擎 │ │
│ │ 📦 古风漫画网 (2条) │ │
│ │ 📦 全本玄幻小说 (8条) │ │
│ │ ...(共 6 个已启用源的结果) │ │
│ │ │ │
│ │ 💡 未找到?去 源管理 导入更多仓库并启用新源 │ │
│ │ ❌ Pixiv — 不参与实时搜索 │ │
│ └─────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
2.4 实现方案
Step 1:搜索 —— 跨源聚合搜索引擎
// sakura_mobile/lib/src/core/unified_search.dart (新增)
class UnifiedSearch {
final SakuraApiClient _cloudApi;
final SourceManager _sourceManager;
UnifiedSearch(this._cloudApi, this._sourceManager);
/// 统一漫画搜索:同步搜索云库 + 所有第三方源
Future<UnifiedSearchResults> searchManga(
String query, {
int page = 1,
Set<String>? enabledSources, // 用户选择启用的源
}) async {
final results = UnifiedSearchResults(
query: query,
sections: [],
);
// 1. 搜索私有云库(最快)
final cloudItems = await _cloudApi.gallery(
search: query,
page: page,
limit: 20,
contentType: 'manga',
);
if (cloudItems.isNotEmpty) {
results.sections.add(SearchSection(
sourceId: 'cloud',
sourceName: '我的云库',
items: _toCloudArtworks(cloudItems),
));
}
// 2. 搜索第三方源
final targetSources = _sourceManager.mangaSources
.where((s) => enabledSources == null || enabledSources.contains(s.sourceId));
final sourceResults = await Future.wait(
targetSources.map((source) =>
source.search(query, page: page, limit: 20)
.then((items) => SearchSection(
sourceId: source.sourceId,
sourceName: source.sourceName,
items: items,
))
.catchError((_) => null) // 单个源失败不影响其他
),
);
results.sections.addAll(sourceResults.whereType<SearchSection>());
return results;
}
}
/// 搜索结果容器
class UnifiedSearchResults {
final String query;
final List<SearchSection> sections;
// 所有 items 可展平为列表
const UnifiedSearchResults({required this.query, required this.sections});
}
/// 按来源分组的搜索结果
class SearchSection {
final String sourceId;
final String sourceName;
final List<dynamic> items; // MangaSearchResult | Artwork
const SearchSection({
required this.sourceId,
required this.sourceName,
required this.items,
});
}
Step 2:实时浏览 —— 在线漫画阅读器(纯内存、零下载)
新建 sakura_mobile/lib/src/pages/online_manga_reader_page.dart:
⚠️ 关键约束: 图片仅通过
Image.network()或Image.memory()在内存中渲染,不使用CachedNetworkImage的持久缓存,不调用downloadProtectedFile(),不写入任何本地文件。
// sakura_mobile/lib/src/pages/online_manga_reader_page.dart (新增)
import 'package:flutter/material.dart';
import '../core/source_interface.dart';
/// 在线漫画阅读器 —— 纯实时流式浏览
/// - 图片在内存中临时加载,离开页面即释放
/// - 不保存到系统图库、不写入本地文件、不同步到私有云
class OnlineMangaReaderPage extends StatefulWidget {
final MangaSource source;
final String mangaId;
final String chapterId;
final String title;
const OnlineMangaReaderPage({
super.key,
required this.source,
required this.mangaId,
required this.chapterId,
required this.title,
});
@override
State<OnlineMangaReaderPage> createState() => _OnlineMangaReaderPageState();
}
class _OnlineMangaReaderPageState extends State<OnlineMangaReaderPage> {
late Future<List<MangaPage>> _pagesFuture;
final _pageController = PageController();
int _currentPage = 0;
int _totalPages = 0;
@override
void initState() {
super.initState();
_pagesFuture = widget.source.getChapterPages(
widget.mangaId,
widget.chapterId,
);
}
@override
void dispose() {
_pageController.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: Text(widget.title),
actions: [
if (_totalPages > 0)
Center(
child: Padding(
padding: const EdgeInsets.only(right: 8),
child: Text(
'${_currentPage + 1} / $_totalPages',
style: const TextStyle(fontSize: 14),
),
),
),
],
),
body: FutureBuilder<List<MangaPage>>(
future: _pagesFuture,
builder: (context, snapshot) {
if (snapshot.hasError) {
return Center(child: Text('加载失败: ${snapshot.error}'));
}
if (!snapshot.hasData) {
return const Center(child: CircularProgressIndicator());
}
final pages = snapshot.data!;
_totalPages = pages.length;
return PageView.builder(
controller: _pageController,
scrollDirection: Axis.horizontal,
itemCount: pages.length,
onPageChanged: (page) => setState(() => _currentPage = page),
itemBuilder: (context, index) {
final page = pages[index];
return InteractiveViewer(
child: Center(
// ✅ 使用 Image.network(内存缓存),不用 CachedNetworkImage(磁盘缓存)
child: Image.network(
page.imageUrl,
headers: page.headers,
fit: BoxFit.contain,
loadingBuilder: (_, child, progress) {
if (progress == null) return child;
return const Center(child: CircularProgressIndicator());
},
errorBuilder: (_, __, ___) =>
const Center(child: Icon(Icons.broken_image, size: 48)),
),
),
);
},
);
},
),
);
}
}
Step 3:在线小说阅读器
新建 sakura_mobile/lib/src/pages/online_novel_reader_page.dart:
// 类似 OnlineMangaReaderPage,但渲染纯文本
// 从第三方源获取章节正文后,滚动显示文本内容
// 支持翻页、字体调整、夜间模式等
Step 4:搜索页 UI 整合
新建 sakura_mobile/lib/src/pages/explore_page.dart —— 探索/发现页:
┌──────────────────────────────────────┐
│ [🔍 搜索漫画或小说...] │ ← 搜索栏
├──────────────────────────────────────┤
│ 来源:[我的云库] [MangaDex] [漫画柜] │ ← 横向滚动来源选择
├──────────────────────────────────────┤
│ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ 封面 │ │ 封面 │ │ 封面 │ │
│ │ │ │ │ │ │ │ ← 瀑布流搜索结果
│ │ 标题 │ │ 标题 │ │ 标题 │ │
│ │ 来源 │ │ 来源 │ │ 来源 │ │
│ └────────┘ └────────┘ └────────┘ │
├──────────────────────────────────────┤
│ 点击 → 直接进入在线阅读(不保存) │
│ 长按 → 保存到我的云库 │
└──────────────────────────────────────┘
2.5 数据流总结
用户搜索 "关键词"
│
├─→ Sakura Cloud /gallery?search=xxx (已有云库内容)
│
├─→ MangaDexSource.search("xxx") (第三方漫画源)
├─→ CopymangaSource.search("xxx") (第三方漫画源)
├─→ NarouSource.search("xxx") (第三方小说源)
│
│ ❌ Pixiv — 不参与实时搜索
│ → UI 上显示提示:"Pixiv 内容请通过桌面端同步后查看"
│
▼
CrossSourceSearch.aggregate()
→ 并行请求,按源分组,合并返回
│
▼
统一 AggregatedResults
│
▼
用户点击某条结果
│
├─→ 云库内容 → 现有 ArtworkDetailPage / NovelReaderPage
│ (可收藏、可下载、可同步进度)
│
└─→ 第三方源内容 → OnlineMangaReaderPage / OnlineNovelReaderPage
│
├─→ Image.network() 逐页渲染(内存缓存,离开释放)
├─→ 文本流式加载到 Text widget(内存,离开释放)
│
├─→ ❌ 不调用 downloadProtectedFile()
├─→ ❌ 不写 SharedPreferences/本地文件
├─→ ❌ 不触发系统图库保存
└─→ ❌ 不同步到 Sakura Cloud
三、WEB 端:认证失败与登录页缺失修复
3.1 问题现象
部署新版 Sakura Admin Web 后,访问页面始终返回:
{"detail": "Not authenticated"}
没有出现登录页面,直接报错,无法正常使用。
3.2 根因分析
经过对全部相关代码的排查,问题涉及以下多个层面:
根因 1:CSP(内容安全策略)过于严格 —— 核心问题
文件位置: sakura_cloud/api/middleware.py 第 37-41 行
response.headers.setdefault(
"Content-Security-Policy",
"default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'self'",
)
问题:
connect-src 'self'限制了所有 API 请求只能发送到同源- 当开发环境前端运行在
localhost:5174,后端运行在localhost:8000时,前端通过 Vite proxy 代理 API 请求到后端,但浏览器会因为 CSP 限制而阻止跨域 API 调用 img-src 'self' data:限制了图片资源只能从同源加载,外部图片无法显示- 生产部署时,如果前端构建为静态文件通过 Nginx 部署,API 请求不同端口也会被 CSP 拦截
根因 2:SPA 路由未正确回退
文件位置: sakura_cloud/main.py 第 61-78 行
@app.get("/admin", response_class=HTMLResponse)
def admin_console() -> str:
if not settings.admin_frontend_enabled:
return "<h1>Admin console disabled</h1>"
return """<!doctype html>...""" # 硬编码的占位 HTML,不是真正的 SPA
问题:
- 后端只注册了
/admin这一个路由返回 HTML - Vue Router 使用了
createWebHistory()(sakura_admin_web/src/router/index.ts第 60 行),意味着 URL 如/login、/app、/admin/users等都是真实路径 - 当用户直接访问
/login或刷新/app/dashboard时,后端没有对应路由,返回 404 或触发认证检查 - SPA 需要所有非 API 路径回退到
index.html
根因 3:前端 API 路径与后端不一致
文件位置: sakura_admin_web/src/stores/auth.ts 第 7-8 行
const path = admin ? "/admin/login" : "/auth/login";
const response = await http.post(path, { ... });
文件位置: sakura_admin_web/src/api/http.ts 第 4 行
const API_BASE = import.meta.env.VITE_API_BASE_URL || "/api/v1";
实际 API 路径:
- 用户登录:
POST /api/v1/auth/login - 管理员登录:
POST /api/v1/admin/login - 获取当前用户:
GET /api/v1/me
问题: 前端 http.ts 的 API_BASE 默认是 /api/v1,而 Vite 的 proxy 配置是将 /api 代理到后端。这意味着前端的 /api/v1/auth/login 实际被代理为 http://127.0.0.1:8000/api/v1/auth/login —— 虽然这个路径是正确的,但当不通过 Vite dev server 访问(即生产部署)时,如果静态文件服务器没有正确配置代理,API 调用会失败。
根因 4:前端路由守卫在 token 不存在时无限循环
文件位置: sakura_admin_web/src/router/index.ts 第 64-70 行
router.beforeEach(async (to) => {
if (!to.meta.requiresAuth) return true;
const user = await loadMe().catch(() => null);
if (!user) return { path: "/login", query: { redirect: to.fullPath } };
if (to.meta.requiresAdmin && !isAdmin(authState.user?.role)) return "/403";
return true;
});
问题:
loadMe()调用GET /api/v1/me,需要 Bearer token- 如果 token 不存在或已过期,API 返回 401,前端捕获错误后
user为 null,重定向到/login - 但如果后端中间件在所有路由(包括
/login对应的 API 调用)都要求认证,用户永远看不到登录页 auth.ts中的login()在管理员登录时调用/admin/login,但后端admin_login端点有 IP 速率限制(admin_login_rate_limit_per_minute: 5),开发时频繁刷新容易触发
根因 5:缺少生产部署的静态文件服务配置
文件位置: sakura_cloud/main.py —— 没有挂载静态文件
后端没有配置 app.mount() 来服务前端构建产物。生产环境需要:
- 后端直接 serving SPA 静态文件(FastAPI
StaticFiles) - 或者 Nginx 反向代理 + 静态文件服务
3.3 解决方案
方案 A:修复 CSP 中间件(立即执行)
修改 sakura_cloud/api/middleware.py:
# sakura_cloud/api/middleware.py 修改后的 security_headers_middleware
async def security_headers_middleware(request: Request, call_next: Callable) -> Response:
response = await call_next(request)
response.headers.setdefault("X-Content-Type-Options", "nosniff")
response.headers.setdefault("X-Frame-Options", "DENY")
response.headers.setdefault("Referrer-Policy", "no-referrer")
response.headers.setdefault("Permissions-Policy", "camera=(), microphone=(), geolocation=(), payment=()")
# ===== 修复后的 CSP =====
# 开发环境 localhost:5174 / 生产环境根据 CORS 配置
api_origin = request.headers.get("origin", "")
allowed_connect = "'self'"
# 如果 CORS origins 中包含此 origin,允许 connect
cors_origins_str = ", ".join(settings.cors_origins) if settings.cors_origins else ""
csp = (
"default-src 'self'; "
"img-src 'self' data: https: http:; " # 允许外部图片
"style-src 'self' 'unsafe-inline'; "
"script-src 'self' 'unsafe-inline'; "
"connect-src 'self' http://localhost:* ws://localhost:*; " # 允许开发环境 API + WebSocket
"font-src 'self' data:; "
)
if settings.debug:
# 开发模式放宽 CSP
csp = csp.replace("connect-src 'self'", "connect-src *")
response.headers.setdefault("Content-Security-Policy", csp)
return response
方案 B:后端添加 SPA 回退路由
修改 sakura_cloud/main.py,将硬编码的占位 HTML 替换为真正的 SPA 静态文件服务:
# sakura_cloud/main.py 修改
import os
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse, FileResponse
from fastapi.staticfiles import StaticFiles
def create_app() -> FastAPI:
# ... 现有配置 ...
# === 新增:服务前端 SPA 静态文件 ===
frontend_dist = os.path.join(os.path.dirname(__file__), "..", "sakura_admin_web", "dist")
frontend_dist = os.path.abspath(frontend_dist)
if os.path.isdir(frontend_dist):
# 挂载静态资源(JS, CSS, 图片等)
assets_dir = os.path.join(frontend_dist, "assets")
if os.path.isdir(assets_dir):
app.mount("/assets", StaticFiles(directory=assets_dir), name="admin_assets")
# SPA 回退路由:所有非 API 路径返回 index.html
@app.get("/admin/{full_path:path}")
async def spa_fallback(full_path: str = ""):
index_path = os.path.join(frontend_dist, "index.html")
if os.path.isfile(index_path):
return FileResponse(index_path)
return HTMLResponse("<h1>Frontend not built. Run: cd sakura_admin_web && npm run build</h1>")
@app.get("/admin")
async def admin_root():
index_path = os.path.join(frontend_dist, "index.html")
if os.path.isfile(index_path):
return FileResponse(index_path)
return HTMLResponse("<h1>Frontend not built</h1>")
# 为 Vue Router 的 history mode 添加额外回退路由
@app.get("/login")
@app.get("/register")
@app.get("/forgot-password")
async def public_spa_fallback(request: Request):
"""公开页面回退(不需要认证)"""
index_path = os.path.join(frontend_dist, "index.html")
if os.path.isfile(index_path):
return FileResponse(index_path)
return HTMLResponse("<h1>Frontend not built</h1>")
@app.get("/app/{full_path:path}")
@app.get("/app")
async def app_spa_fallback():
index_path = os.path.join(frontend_dist, "index.html")
if os.path.isfile(index_path):
return FileResponse(index_path)
return HTMLResponse("<h1>Frontend not built</h1>")
# ... 其余配置 ...
return app
方案 C:Nginx 生产部署配置(推荐方案)
创建 sakura_admin_web/nginx.conf:
server {
listen 80;
server_name admin.your-domain.com;
# 前端静态文件
root /path/to/sakura_admin_web/dist;
index index.html;
# API 反向代理到后端
location /api/ {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# SPA History Mode 回退
location / {
try_files $uri $uri/ /index.html;
}
# 静态资源缓存
location /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
方案 D:修复前端路由守卫的正向逻辑
修改 sakura_admin_web/src/router/index.ts,确保 /login 页面不需要认证检查:
// sakura_admin_web/src/router/index.ts 路由守卫修改
const PUBLIC_PATHS = ['/login', '/register', '/forgot-password', '/403', '/404'];
router.beforeEach(async (to) => {
// 公开路径直接放行,不做任何 API 调用
if (PUBLIC_PATHS.includes(to.path) || to.path === '/') {
return true;
}
if (!to.meta.requiresAuth) return true;
// 只有受保护路径才检查 token
const user = await loadMe().catch(() => null);
if (!user) {
// 带上 redirect 参数,登录后可跳回
return { path: "/login", query: { redirect: to.fullPath } };
}
if (to.meta.requiresAdmin && !isAdmin(authState.user?.role)) {
return "/403";
}
return true;
});
方案 E:前端环境变量与构建配置
修改 sakura_admin_web/.env.production(新建):
# sakura_admin_web/.env.production
VITE_API_BASE_URL=/api/v1
修改 sakura_admin_web/vite.config.ts,添加生产构建选项:
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
export default defineConfig(({ mode }) => ({
plugins: [vue()],
server: {
port: 5174,
proxy: {
"/api": {
target: "http://127.0.0.1:8000",
changeOrigin: true
}
}
},
build: {
outDir: "dist",
assetsDir: "assets",
// 确保 Vite 构建的 base 路径正确
base: "/",
}
}));
3.4 修复后的访问流程
用户访问 http://admin.your-domain.com/login
│
▼
Nginx / FastAPI 返回 index.html(SPA 入口)
│
▼
Vue.js 加载,Vue Router 匹配到 /login → 渲染 LoginPage.vue
│
▼
用户输入账号密码,点击登录
│
▼
前端调用 POST /api/v1/auth/login
│
▼
Nginx 代理 → http://127.0.0.1:8000/api/v1/auth/login
│
▼
后端验证通过,返回 access_token + refresh_token
│
▼
前端保存 token 到 sessionStorage,调用 GET /api/v1/me
│
▼
路由守卫校验通过 → 跳转到 /app 或 /admin
3.5 快速验证清单
| 检查项 | 命令/方法 | 期望结果 |
|---|---|---|
| CSP 是否正确 | 浏览器 DevTools → Console | 无 CSP 错误 |
| API 代理是否正常 | curl -X POST http://localhost:8000/api/v1/auth/login -H "Content-Type: application/json" -d '{"username_or_email":"test","password":"test"}' |
返回 JSON(即使 401) |
| SPA 回退是否正常 | 浏览器访问 http://localhost:8000/login |
显示登录页 HTML,非 404 |
| 静态资源是否加载 | 浏览器 DevTools → Network | .js/.css 文件返回 200 |
| 登录流程是否打通 | 在登录页输入正确凭据 | 成功跳转到 Dashboard |
四、APK 端 UI 美化:配色统一、标题优化与选项卡样式修复
4.1 问题概述
根据用户反馈,当前 APK 端存在三个 UI 问题:
| # | 问题 | 现状 | 期望 |
|---|---|---|---|
| 1 | 登录页配色不和谐 | 使用蓝色系(#3A7BFF) |
改为粉色系,与 App 主题统一 |
| 2 | 选项卡选中样式错误 | 选中态填充整个方块区域 | 选中态只指示文字(下划线或紧凑 pill) |
| 3 | 各页面标题位置太低 | SliverAppBar.large 占用过多空间 |
压缩标题区域,内容更早上屏 |
4.2 问题一:登录页蓝色 → 粉色(统一品牌色)
4.2.1 现状分析
文件位置: sakura_mobile/lib/src/pages/login_page.dart
App 全局主题色定义在 app.dart 第 12-16 行:
final colorScheme = ColorScheme.fromSeed(
seedColor: const Color(0xFFE98AA6),
primary: const Color(0xFFD95A83), // 主色:玫瑰粉
secondary: const Color(0xFFF3A6B8), // 辅色:浅粉
surface: const Color(0xFFFFFBFD), // 表面色:暖白
);
但登录页完全硬编码了蓝色系,完全绕过了主题系统:
| 元素 | 当前值(蓝色) | 所在行 |
|---|---|---|
| 页面背景渐变 | #F4F8FF → #E6EEFF |
第 62-66 行 |
| 图标容器背景 | #3A7BFF 12% 透明度 |
第 95 行 |
| 图标颜色 | #3A7BFF |
第 98 行 |
| TabBar 背景 | #F1F5FD |
第 117 行 |
| TabBar 选中指示器 | #3A7BFF |
第 122 行 |
| 未选中文字色 | #5A6D80 |
第 126 行 |
4.2.2 修改方案
将登录页所有硬编码蓝色替换为主题粉色系:
// sakura_mobile/lib/src/pages/login_page.dart 修改后的 build 方法
@override
Widget build(BuildContext context) {
final session = ref.watch(sessionProvider);
final bannerText = session.error ?? _message;
final bannerIsError = session.error != null || _messageIsError;
final theme = Theme.of(context);
final primaryColor = theme.colorScheme.primary; // Color(0xFFD95A83)
return Scaffold(
body: DecoratedBox(
// ✅ 修改 1:背景渐变从蓝色改为粉色系
decoration: const BoxDecoration(
gradient: LinearGradient(
begin: Alignment.topCenter,
end: Alignment.bottomCenter,
colors: [Color(0xFFFFF5F8), Color(0xFFFFE8EE)], // 粉色渐变
),
),
child: SafeArea(
child: Center(
child: ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 520),
child: ListView(
padding: const EdgeInsets.fromLTRB(20, 24, 20, 28),
children: [
Container(
padding: const EdgeInsets.fromLTRB(22, 24, 22, 24),
decoration: BoxDecoration(
color: Colors.white.withValues(alpha: 0.96),
borderRadius: BorderRadius.circular(30),
boxShadow: const [
BoxShadow(
color: Color(0x18D95A83), // ✅ 阴影改为粉色基调
blurRadius: 28,
offset: Offset(0, 12),
),
],
),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
// ✅ 修改 2:图标容器颜色从蓝色改为粉色
Container(
width: 58,
height: 58,
decoration: BoxDecoration(
color: primaryColor.withValues(alpha: 0.12),
borderRadius: BorderRadius.circular(18),
),
child: Icon(Icons.cloud_done_outlined,
color: primaryColor, size: 30), // 使用主题色
),
const SizedBox(height: 18),
Text(
'樱云同步',
style: theme.textTheme.headlineMedium
?.copyWith(fontWeight: FontWeight.w800),
),
const SizedBox(height: 10),
Text(
'一个账号管理你的收藏、阅读进度和移动端浏览体验。',
style: theme.textTheme.bodyLarge?.copyWith(
color: const Color(0xFF8A6A74), // ✅ 辅助文字改为暖灰
height: 1.55,
),
),
const SizedBox(height: 20),
// ✅ 修改 3:TabBar — 背景和指示器改为粉色
// (详见问题二的完整重构)
_buildTabBar(theme),
// ... 其余内容不变
],
),
),
],
),
),
),
),
),
);
}
完整颜色映射表:
| 元素 | 旧值(蓝色) | 新值(粉色) |
|---|---|---|
| 页面渐变起点 | #F4F8FF |
#FFF5F8(与 scaffoldBackgroundColor 一致) |
| 页面渐变终点 | #E6EEFF |
#FFE8EE(浅樱色) |
| 卡片阴影 | #160F2740 |
#18D95A83(粉色阴影) |
| 图标背景 | #3A7BFF @12% |
ColorScheme.primary @12% |
| 图标颜色 | #3A7BFF |
ColorScheme.primary |
| 描述文字 | #607287(冷灰) |
#8A6A74(暖灰,与底部导航栏一致) |
| TabBar 背景 | #F1F5FD |
#FFEFF5(浅粉底) |
| TabBar 指示器 | #3A7BFF |
ColorScheme.primary |
| 未选中文字 | #5A6D80 |
#8A6A74 |
4.3 问题二:选项卡选中样式 —— 从「板块选择」改为「文字下划线」
4.3.1 现状分析
文件位置: sakura_mobile/lib/src/pages/login_page.dart 第 114-133 行
Container(
decoration: BoxDecoration(
color: const Color(0xFFF1F5FD), // 整个容器有背景色
borderRadius: BorderRadius.circular(18),
),
child: TabBar(
controller: _tabController,
indicator: BoxDecoration( // ← 问题核心:BoxDecoration 填充整个 tab
color: const Color(0xFF3A7BFF), // 看起来像两个按钮,而不是选项卡
borderRadius: BorderRadius.circular(14),
),
labelColor: Colors.white,
unselectedLabelColor: const Color(0xFF5A6D80),
dividerColor: Colors.transparent,
tabs: const [
Tab(text: '登录'),
Tab(text: '注册'),
],
),
),
问题: BoxDecoration 指示器把整个 tab 区域填满了颜色,视觉上看起来是"两个切换的按钮",而不是"登录/注册的文字选项卡"。用户期望选中态只是一个文字下方的指示条或紧凑的 pill 包裹文字。
4.3.2 修改方案:Underline 风格选项卡
// sakura_mobile/lib/src/pages/login_page.dart
// 将 TabBar 的 indicator 从 BoxDecoration 改为 UnderlineTabIndicator
Container(
// ✅ 去掉容器的背景色和圆角,让它更轻量
decoration: BoxDecoration(
border: Border(
bottom: BorderSide(
color: const Color(0xFFF1CAD7).withValues(alpha: 0.4),
width: 1,
),
),
),
child: TabBar(
controller: _tabController,
// ✅ 将方块指示器改为下划线 + 文字颜色变化
indicator: UnderlineTabIndicator(
borderSide: const BorderSide(
color: Color(0xFFD95A83), // 粉色下划线
width: 2.5,
),
insets: const EdgeInsets.symmetric(horizontal: 16), // 下划线比文字略宽
),
// ✅ 选中文字用主题色,不再白字(因为没有蓝色方块了)
labelColor: const Color(0xFFD95A83),
labelStyle: const TextStyle(
fontWeight: FontWeight.w700,
fontSize: 15,
),
unselectedLabelColor: const Color(0xFF8A6A74),
unselectedLabelStyle: const TextStyle(
fontWeight: FontWeight.w500,
fontSize: 15,
),
dividerColor: Colors.transparent,
indicatorSize: TabBarIndicatorSize.label, // ✅ 指示器宽度 = 文字宽度
tabs: const [
Tab(text: '登录'),
Tab(text: '注册'),
],
),
),
效果对比:
修改前(BoxDecoration 方块): 修改后(Underline 文字下划线):
┌──────────────────────────┐ ┌──────────────────────────┐
│ ┌─────────┬─────────┐ │ │ │
│ │ ■■■■■■ │ 登录 │ │ │ 登录 注册 │
│ │ ■登录■ │ │ │ │ ════ │
│ │ ■■■■■■ │ │ │ │ │
│ └─────────┴─────────┘ │ │ │
│ 蓝色方块填充整个tab │ │ 粉色下划线 + 文字变色 │
└──────────────────────────┘ └──────────────────────────┘
备选方案:Pill 风格(推荐用于需要更强视觉区分的场景)
如果希望保留一定视觉强度但不至于太"重",可以使用更紧凑的 pill 包裹文字:
indicator: BoxDecoration(
color: const Color(0xFFFFE8EE), // 浅粉底,不是深色方块
borderRadius: BorderRadius.circular(20),
),
labelColor: const Color(0xFFD95A83), // 文字用深粉,不用白色
4.4 问题三:标题位置太低(SliverAppBar.large 优化)
4.4.1 现状分析
当前 gallery_tab.dart 和 novels_tab.dart 均使用 SliverAppBar.large,这会渲染一个 Material 3 风格的大标题:
// gallery_tab.dart 第 312 行
SliverAppBar.large(
title: Text(selectionMode ? '已选 ${selectedIds.length} 项' : widget.pageTitle),
bottom: PreferredSize(
preferredSize: Size.fromHeight(selectionMode ? 266 : 178),
// 搜索栏 + 筛选 Chip 行...
),
),
具体问题:
SliverAppBar.large的 title 区域高度约 120-140px,仅用于显示"图片"或"漫画"两个字bottom的PreferredSize又占用 178-266px(搜索栏 56px + 搜索范围 chips 行 50px + 筛选 chips 行 50px + 可能的选区面板 88px)- 在 720px 高的手机上,标题+筛选区域合计占用约 300-400px,超过屏幕一半,核心内容(图片网格/列表)被严重挤压
home_page.dart中还嵌套了SafeArea(第 49 行),顶部再增加约 24-40px
4.4.2 修改方案:紧凑化 AppBar + 搜索栏外提
方案:将 SliverAppBar.large 改为标准 SliverAppBar + 将搜索栏提升到 AppBar 内部
// gallery_tab.dart build 方法修改
@override
Widget build(BuildContext context) {
final api = ref.watch(apiClientProvider);
return FutureBuilder<List<Artwork>>(
future: future,
builder: (context, snapshot) {
final items = snapshot.data ?? const <Artwork>[];
final mangaEntries = _isMangaShelfMode
? buildMangaCollections(items)
: const <MangaCollection>[];
return CustomScrollView(
slivers: [
// ✅ 修改 1:SliverAppBar.large → 标准 SliverAppBar(更紧凑)
SliverAppBar(
pinned: true, // 吸顶
floating: false,
snap: false,
// 使用标准高度(约 56px)而不是 large 的 120px+
title: Text(
selectionMode ? '已选 ${selectedIds.length} 项' : widget.pageTitle,
style: const TextStyle(
fontWeight: FontWeight.w700,
fontSize: 20, // 比 large title 的 28-32px 更紧凑
),
),
// ✅ 修改 2:bottom 压缩高度(-30px 从搜索范围行移除)
bottom: PreferredSize(
preferredSize: Size.fromHeight(
selectionMode ? 210 : 140, // 原 266/178 → 压缩约 20%
),
child: Padding(
padding: const EdgeInsets.fromLTRB(16, 0, 16, 12),
child: Column(
children: [
// 搜索栏
SearchBar(
controller: search,
hintText: '搜索标题、作者或标签',
leading: const Icon(Icons.search),
trailing: [
if (!selectionMode)
IconButton(
tooltip: '管理',
onPressed: () {
setState(() { selectionMode = true; });
},
icon: const Icon(Icons.checklist_rounded),
),
IconButton(
tooltip: '刷新',
onPressed: _refresh,
icon: const Icon(Icons.refresh),
),
],
onSubmitted: (_) => _refresh(),
),
const SizedBox(height: 8), // 原 10 → 8
// ✅ 修改 3:将搜索范围 Chips 和筛选 Chips 合并为一行
SingleChildScrollView(
scrollDirection: Axis.horizontal,
child: Row(
children: [
// 搜索范围(更紧凑的图标按钮)
_CompactToggle(
icon: Icons.search,
label: '全部',
selected: searchScope == 'all',
onTap: () => setState(() {
searchScope = 'all';
future = _load();
}),
),
_CompactToggle(
icon: Icons.title,
label: '标题',
selected: searchScope == 'title',
onTap: () => setState(() {
searchScope = 'title';
future = _load();
}),
),
_CompactToggle(
icon: Icons.label_outline,
label: '标签',
selected: searchScope == 'tags',
onTap: () => setState(() {
searchScope = 'tags';
future = _load();
}),
),
_CompactToggle(
icon: Icons.text_fields,
label: 'OCR',
selected: searchScope == 'ocr',
onTap: () => setState(() {
searchScope = 'ocr';
future = _load();
}),
),
const SizedBox(width: 12),
// 分隔符
Container(
width: 1,
height: 20,
color: const Color(0xFFF1CAD7),
),
const SizedBox(width: 12),
// 筛选条件
_CompactToggle(
icon: Icons.update,
label: '最近',
selected: recentUpdatesOnly && !favoritesOnly,
onTap: () => setState(() {
recentUpdatesOnly = true;
favoritesOnly = false;
future = _load();
}),
),
_CompactToggle(
icon: Icons.auto_awesome,
label: _allChipLabel,
selected: !recentUpdatesOnly &&
!favoritesOnly &&
(_effectiveContentType == null ||
_effectiveContentType == widget.fixedContentType),
onTap: () => setState(() {
recentUpdatesOnly = false;
favoritesOnly = false;
contentType = '';
future = _load();
}),
),
if (widget.showTypeFilters &&
widget.fixedContentType == null) ...[
_CompactToggle(
icon: Icons.menu_book_rounded,
label: '漫画',
selected: contentType == 'manga',
onTap: () => setState(() {
recentUpdatesOnly = false;
favoritesOnly = false;
contentType =
contentType == 'manga' ? '' : 'manga';
future = _load();
}),
),
_CompactToggle(
icon: Icons.brush,
label: '插画',
selected: contentType == 'illust',
onTap: () => setState(() {
recentUpdatesOnly = false;
favoritesOnly = false;
contentType =
contentType == 'illust' ? '' : 'illust';
future = _load();
}),
),
],
_CompactToggle(
icon: Icons.favorite,
label: '收藏',
selected: favoritesOnly,
onTap: () => setState(() {
recentUpdatesOnly = false;
favoritesOnly = !favoritesOnly;
future = _load();
}),
),
],
),
),
// 选区面板(仅在 selection mode 时显示)
if (selectionMode) ...[
const SizedBox(height: 8),
_SelectionPanel(
message: _selectionHint,
onCancel: _exitSelectionMode,
onDownload: selectedIds.isEmpty
? null
: () => _downloadSelected(items),
onDelete:
selectedIds.isEmpty ? null : _deleteSelected,
),
],
],
),
),
),
),
// ... 内容区域不变
],
);
},
);
}
// ✅ 新增紧凑型 Toggle 组件(替代原有的 ChoiceChip)
class _CompactToggle extends StatelessWidget {
const _CompactToggle({
required this.icon,
required this.label,
required this.selected,
required this.onTap,
});
final IconData icon;
final String label;
final bool selected;
final VoidCallback onTap;
@override
Widget build(BuildContext context) {
return Padding(
padding: const EdgeInsets.only(right: 6),
child: Material(
color: selected ? const Color(0xFFFFE8EE) : Colors.transparent,
borderRadius: BorderRadius.circular(20),
child: InkWell(
onTap: onTap,
borderRadius: BorderRadius.circular(20),
child: Padding(
padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 7),
child: Row(
mainAxisSize: MainAxisSize.min,
children: [
Icon(
icon,
size: 16,
color: selected
? const Color(0xFFD95A83)
: const Color(0xFF8A6A74),
),
const SizedBox(width: 5),
Text(
label,
style: TextStyle(
fontSize: 13,
fontWeight: selected ? FontWeight.w700 : FontWeight.w500,
color: selected
? const Color(0xFFD95A83)
: const Color(0xFF8A6A74),
),
),
],
),
),
),
),
);
}
}
4.4.3 空间节省对比
修改前:
┌─────────────────────────────────┐
│ SafeArea padding (~24px) │
│ SliverAppBar.large title │
│ "图片" 大标题 (~120px) │ ← 浪费!只显示2个字
│ 搜索栏 (~56px) │
│ 搜索范围 Chips 行 (~50px) │
│ 筛选 Chips 行 (~50px) │
├─────────────────────────────────┤
│ 内容区域仅剩 ~420px │ ← 被挤压
└─────────────────────────────────┘
修改后:
┌─────────────────────────────────┐
│ SliverAppBar (pinned, 56px) │
│ 搜索栏 + 合并 Chips 行 (~130px) │ ← 紧凑,图标+文字 Chip
├─────────────────────────────────┤
│ 内容区域恢复 ~534px │ ← 多出约 27% 空间
└─────────────────────────────────┘
4.4.4 novels_tab.dart 同理修改
对 novels_tab.dart 中 SliverAppBar.large(第 244 行)做相同的紧凑化处理:
// novels_tab.dart 修改
SliverAppBar(
pinned: true,
title: Text(
selectionMode ? '已选 ${selectedEntryIds.length} 项' : '系列书架',
style: const TextStyle(fontWeight: FontWeight.w700, fontSize: 20),
),
bottom: PreferredSize(
preferredSize: Size.fromHeight(selectionMode ? 174 : 118), // 原 212/126 → 压缩
child: Padding(
padding: const EdgeInsets.fromLTRB(16, 0, 16, 12),
child: Column(
children: [
SearchBar(
controller: search,
hintText: '搜索书名、作者或章节名',
leading: const Icon(Icons.search),
trailing: [
if (!selectionMode)
IconButton(
tooltip: '管理',
onPressed: () => setState(() { selectionMode = true; }),
icon: const Icon(Icons.checklist_rounded),
),
IconButton(
tooltip: '刷新',
onPressed: _refresh,
icon: const Icon(Icons.refresh),
),
],
onSubmitted: (_) => _refresh(),
),
if (selectionMode) ...[
const SizedBox(height: 8),
_NovelSelectionPanel(
message: selectedEntryIds.isEmpty
? '长按书架卡片开始多选,支持批量删除。'
: '已选 ${selectedEntryIds.length} 项,可以继续点选调整。',
onCancel: _clearSelection,
onDelete: selectedEntryIds.isEmpty
? null
: () => _deleteSelectedEntries(entries),
),
],
const SizedBox(height: 8),
],
),
),
),
),
4.5 修改涉及文件汇总
| 文件 | 修改内容 | 预计工时 |
|---|---|---|
sakura_mobile/lib/src/pages/login_page.dart |
蓝色→粉色配色替换、TabBar 指示器改为 underline | 1h |
sakura_mobile/lib/src/pages/tabs/gallery_tab.dart |
SliverAppBar.large → SliverAppBar 紧凑化、合并 Chips 行、新增 _CompactToggle |
1.5h |
sakura_mobile/lib/src/pages/tabs/novels_tab.dart |
SliverAppBar.large → SliverAppBar 紧凑化 |
0.5h |
sakura_mobile/lib/src/pages/tabs/feed_tab.dart |
检查是否也有标题过高问题 | 0.5h |
五、实施优先级与排期建议
| 优先级 | 任务 | 预计工时 | 依赖 |
|---|---|---|---|
| P0 | WEB 端认证修复(方案 A + B + D) | 2-3h | 无 |
| P0 | Nginx 生产部署配置(方案 C) | 1h | 方案 B |
| P0 | 登录页蓝→粉配色替换 | 1h | 无 |
| P0 | TabBar 指示器改为 underline 风格 | 0.5h | 无 |
| P1 | SliverAppBar.large → 紧凑化(gallery + novels) | 2h | 无 |
| P1 | Legado 规则引擎(RuleParser + Engine) | 8-12h | 无 |
| P1 | 源管理器(SourceManager + 预置源导入 + 用户自定义导入) | 3-4h | 规则引擎 |
| P1 | 源管理页面 UI(预置源列表 + 导入 + 启用/禁用) | 3-4h | 源管理器 |
| P2 | OnlineMangaReaderPage(纯内存漫画阅读器) | 2-3h | 规则引擎 |
| P2 | OnlineNovelReaderPage(纯内存小说阅读器) | 1-2h | 规则引擎 |
| P2 | 统一搜索页 ExplorePage(跨源聚合搜索) | 3-4h | 规则引擎 + 源管理器 |
| P2 | GalleryTab/NovelsTab 添加"在线"Tab 切换 | 2-3h | 以上全部 |
| P3 | 订阅源自动更新(后台定时拉取) | 1-2h | 源管理器 |
| P3 | 源校验/速度测试工具 | 2h | 规则引擎 |
建议执行顺序:
- P0(半天):WEB 端认证修复 + 登录页配色/TabBar → 立即可见改进
- P1(2-3 天):SliverAppBar 紧凑化 + Legado 规则引擎 + 源管理器 → 基础设施就绪
- P2(2-3 天):在线阅读器 + 跨源搜索页 + Tab 切换 → 功能闭环
- P3(按需):订阅更新 + 源校验工具
关键里程碑:
- P1 完成后:APP 即可导入 6000+ 条 Legado 源,在源管理页查看
- P2 完成后:用户可跨源搜索 + 在线浏览任意源的内容,不下载不留痕
- 整个方案无需手写任何单个源的解析器,完全依赖 Legado 社区生态