市面上的 Web 端媒体管理器界面粗糙、交互笨重；体验优异的桌面客户端又绑定单机设备，无法满足自建服务器 / NAS 用户「集中托管、随时随地访问」的需求。 SakuManga 用一套开箱即用的程序，打通资源刮削 → 本地存储 → 高质感阅读的完整闭环。
- 原生感 Web 体验 — 浏览器打开即用，桌面级沉浸式阅读；可添加到手机主屏（PWA），人在外面也能随时浏览与收录资源。
- 为高效搜刮而生 — 列表小窗秒级预览详情、独立详情页避免层层跳转错过目标、自动规避 GP 消耗不阻塞下载。
- 线上线下双库联动 — 定期查询父画廊更新状态、本地 Hash 秒级查重去重、名称级疑似重复自动分组与一键忽略（误判可恢复），囤得再多也心中有数。
- 深度适配 E-hentai — 直接读取本地 ComicInfo 录入；未知文件联网反查 gid 自动补齐元数据与封面；标签汉化、联想补全、本地词典双轨维护。
- 类 E 站原生筛选 + 随机抽卡 — 正 / 负向关键词与 Tag 精确锚定范围；客制化随机骰子跳出「图书管理员效应」，常看常新。
- 多用户与稳定下载 — 管理员 / 成员 / 下载三级权限，阅读进度按账号云端同步；多线程并发、断点续传、优先级抢占，下载稳定不翻车。
- 部署即服务 — 单文件 exe 内置前后端与托盘，双击即用；
--headless纯后端模式适配 NAS / 无界面服务器。
[!NOTE]
项目更新状态（Project Status）
v2.0.0 为里程碑大版本：项目正式更名为 SakuManga（包名 / exe / 界面标题 / 文档全量同步），并一次性汇总 v1.4.0 以来的画质升级、搜刮书签、查重增强、阅读器升级等新能力，继续推进稳定性与体验主线。v2.0.1 为首次反馈收敛版：系统代理自动兜底、卡片语言角标与 3TAG 优化、E 站账号密码内部登录、搜索历史点击交互修复。v2.1.0 为本地库智能化版本：XP 词云与偏好推荐、搜刮书签多端同步与「锚定即记录」、维护查重忽略 / 删除即时生效。v2.1.1 起提供官方 Docker 镜像（GHCR，amd64 + arm64），NAS / Linux 服务器可直接部署。
v2.1.1（2026-09）：自 v2.1.0 以来的镜像发布版——正式提供官方 Docker 镜像 ghcr.io/yeonalbus/sakumanga（linux/amd64 + linux/arm64 双架构，NAS / 群晖 / 树莓派可直接部署），由 GitHub Actions 在推送 tag 或手动触发时自动构建发布；同时新增 build-docker.bat 本地一键构建脚本，常见问题手册补充「Docker 部署」章节。程序功能与 v2.1.0 一致，无功能与逻辑改动。
v2.1.0（2026-09）：自 v2.0.1 以来共 44 个提交——新增本地 XP 词云（库藏 / 阅读双口径，核心 XP · 角色原作 · 其他三段分组 + 画师社团 Top 20）与偏好推荐卡池（按词云权重加权采样，参数可调，在线部分保持纯随机）、搜刮书签多端同步（后端化按账号隔离，旧数据自动迁移）与**「锚定即记录」**（自动带出发布时间与位置）、离线长任务暂停 / 继续 / 取消、新版本检测提醒、阅读器页码角标；并修复搜刮书签数据静默丢失、维护查重「忽略后重进页面复活」与「删除后必须重新扫描」等问题。数据库结构由启动时 AutoMigrate 平滑迁移，升级仅需替换 exe。
v2.0.1（2026-08）：自 v2.0.0 以来的反馈收敛版——系统代理自动兜底（Clash 等「系统代理」模式零配置直连，未手动配置时自动跟随）、卡片语言角标（来源角标替换为中文 / 日本語 / English）、3TAG 显示优化（parody / character 各取一个、缺失用 female 补位，最多 3 个）、E 站账号密码内部登录（免 F12 复制 Cookie，验证码 / 风控时回退手动粘贴）、搜索历史点击改为填入搜索框（不再直接跳转搜索）。
v2.0.0（2026-08-29）：自 v1.4.0 以来共 71 个提交——项目更名为 SakuManga 并升入 2.x；新增图片质量升级（非归档原图自动检测并升级为归档原图，历史 / 书架 / 评分保留）、搜刮书签（首页 / 搜索快照 + 锚定卡片一键回场）、名称级疑似重复自动分组与忽略标记、阅读器书签 / 章节侧栏与大纲行内编辑、隐藏页软删除、下载方案四选一（画廊 / 归档 × 原图 / 压缩）、书架拖拽排序与批量移出、评论区 E 站链接直达、账号凭据可视化等；E 站请求自适应限流使全量在线核对耗时约减半，并完成安全凭据整改。
- 在线浏览：首页 / 热门 / 订阅 / 收藏 / 历史 / 排行榜（昨日 · 本月 · 本年 · All-Time 四种类型，评分对齐 E 站真实值）/ 随机抽卡 / 搜刮书签（点选卡片即记录发布时间与位置，一键恢复筛选并定位，多端同步）；卡片显示语言角标（中文 / 日本語 / English）与 3TAG 精选（parody / character / female）
- 详情体验：宽屏点卡自动开小详情、本地优先加载（已下载画廊自动走本地页图 + 一键切回在线）、默认收藏夹、取消收藏 web 弹窗、详情新标签导航 + 智能返回（恢复来源列表位置）、评论区 E-Hentai 链接点击直达画廊、点击上传者跳转搜索
- 阅读恢复：进度按账号同步后端；历史入口始终续看、非历史入口受「从上次位置开始」偏好控制；在线 token 缺失自动解析兜底；离线历史按 gid 合并去重（更新替换换 id 后不再重复显示同一本子）
- 下载系统：画廊 + 归档多线程并发、下载优先级 + 抢占式调度、归档并发数控制、断点续传（.part / .bits）、zip 校验失败自动重建会话重下、下载方案四选一（画廊 / 归档 × 原图 / 压缩）、归档分块 429 自动降线程重试、归档线程数 1-10 全选项、解压失败自动清理损坏包残留、下载完成自动消除更新标记、已下载/下载中画廊入口拦截
- 画质升级：自动检测本地非「归档原图」版本并提供升级入口，重新下载归档原图并原子替换（历史 / 书架 / 评分完整保留），所有登录用户可用
- 本地阅读：离线书架（拖拽排序 / 移动到第 X 位 / 快捷置顶 / 全部书架检索浮层 / 快捷加入扩大到手气不错与历史 / 多选批量移出）/ 历史 / 排行榜 / 更新检测（周扫描 + 365 天老化）/ 维护查重（双列对比、跨文件夹版本识别、失效画廊标记、名称级疑似重复自动分组（只建议不自动删除）、忽略标记与忽略清单恢复、忽略 / 恢复 / 删除即时生效（无需重新扫描）、进入页面不再自动扫描）/ 长任务暂停 / 继续 / 取消 / 阅读进度续看
- 本地库分析：XP 词云（本地排行榜页「阅读榜 | XP 词云」双视图——核心 XP（female / male / mixed）· 角色原作（character / parody）· 其他三段分组，库藏口径与阅读口径双统计，画师 / 社团剥离为 Top 20 榜单）；偏好推荐卡池（随机抽卡页「纯随机 | 偏好推荐」切换，按词云权重加权采样，偏好侧重 / 探索率 / 温度 / 排除已读 / 排除书架已有均可调，在线部分保持纯随机并明确标注）
- 在线搜索：f_search 自动修正为 E 站标准语法（多词
t:... s:...完整命中）、Tag 联想/点击统一按线上格式生成、点击联想保持输入焦点可连续输入多 tag、搜索配置持久化（搜索跳转后筛选不再重置）、联想按标签热度协同排序、搜索新标签打开、搜索历史点击填入搜索框（不直接跳转） - 智能筛选：Tag 联想补全 + 负向排除（
-tag / -关键词，离线过滤 + 在线本地丢弃）；离线/在线 tag 筛选统一——本地匹配理解female:"magical girl$"线上语法（$ 精确 / 无 $ 前缀） - Tag 维护：词典同步 / 翻译 / 双轨三态维护；调度时刻统一为系统本地时区
- 阅读器：颜色跟随主题（深色/浅色）、手柄翻页与确认/取消按键、书签 / 章节标记与侧栏、章节层级 / 大纲与行内编辑、物理索引重构页序稳定、顶栏与设置优化、右下角常驻页码角标、页面加载失败错误层（重试/返回）、离线 404 自动纠正为在线模式（无 token 也兜底解析）
- 本地管理：隐藏页软删除（自定义删除页面）、管理模式隐藏 / 恢复页面、原生 tag 叉除恢复、离线详情预览分批加载、主标题日文优先（可修改可恢复）
- iPad PWA：底部条/横屏黑边修复、返回不整页刷新（保留来源位置）、阅读器隐藏全局外壳、搜索历史键盘收起、视口诊断面板（/diag）
- 多用户：管理员 / 成员 / 下载许可三级权限，阅读记录按账号隔离
- 设置中心：分组收编为「账户 / E 站连接 / 阅读体验 / 下载与离线 / 标签管理 / 日志 / 关于」，每项设置均真实生效；账号设置支持 E 站账号密码内部登录（免 F12 复制 Cookie，验证码 / 风控时回退手动粘贴）、显示 pass_hash 并支持一键刷新凭证；网络设置显示当前生效代理与来源（手动 / 系统自动 / 直连）；关于软件集成 GitHub 新版本检测（发现新版红点提醒）；内置日志系统（更新 / 维护 / 下载 / 错误四类日志）
- 性能与安全：E 站请求自适应限流（连续成功提速至 500ms、429/503 自动退避，全量核对耗时约减半）；系统代理自动兜底（未手动配置时自动跟随注册表 / 环境变量代理，Clash 零配置直连）；调试工具 E 站凭据改环境变量注入，移除硬编码凭据
v2.1.0 落地本地库智能分析（XP 词云 / 偏好推荐）与搜刮书签多端同步，并让维护查重的忽略与删除即时生效。
后续将延续稳定性与体验主线：补全「疑似重复」簇的勾选删除、完善搜刮书签的更多页面类型与离线端支持（当前仅在线首页 / 搜索）、抽卡负向排除的后端采样补位、离线端更丰富的检索与维护能力，并持续收敛下载稳定性与资源占用、完善跨设备进度同步、多用户协调。
一键打包（单文件 exe：前端 + 后端 + 系统托盘）：
build-release.bat生成 SakuManga.exe：双击运行后最小化到系统托盘，右键托盘图标可选「打开界面 / 退出程序」；默认监听 http://127.0.0.1:8081，首次启动自动创建管理员 admin/admin123。打包脚本标题与前端「关于」页版本号均自动读取 package.json，发版只需修改一处。
纯后端运行（NAS / 无界面环境）：
SakuManga.exe --headlessDocker 部署（NAS / Linux 长期运行，自 v2.1.1 起提供官方镜像）：
docker run -d --name sakumanga --restart unless-stopped \
-p 8081:8081 \
-v /your/data/dir:/app \
ghcr.io/yeonalbus/sakumanga:2.1.1镜像同时提供 linux/amd64 与 linux/arm64（群晖 / 树莓派 / Apple Silicon 均可直接运行），标签策略为 2.1.1 / 2.1 / latest。数据（manga.db / config.json / data/ / logs/）全部保存在挂载目录，升级 = 换镜像标签重建容器。推送 SakuManga-X.Y.Z tag 时由 GitHub Actions 自动构建发布，也可在仓库 Actions 页面手动触发；本机想自己构建用 build-docker.bat。完整说明见 VerNotes/wiki.md「九、Docker 部署」。
开发模式：
npm install
cd backend && go run . # 后端 http://127.0.0.1:8081
npm run dev # 前端开发服务器（Vite 代理到后端 API）后端
//go:embed all:dist编译必需backend/webui/dist（前端构建产物，随仓库维护）：前端改动后请执行一次npm run build并将根目录dist/拷贝到backend/webui/dist，或直接运行一次build-release.bat。
设置页按主题分为 7 大分组，「账户 / EH 网站 / 样式 / 阅读 / 偏好 / 我的标签 / 关于软件」全员可见，带
| 分组 | 栏目 | 说明 |
|---|---|---|
| 账户 | 账户 | E 站账号密码内部登录（免 F12 复制）、Cookie 配置（含 pass_hash 展示与一键刷新凭证）、成员管理、服务器信息 |
| E 站连接 | EH 网站 | EH 站点访问配置 + Profile 设置 + 优先重定向至表站 |
| 网络 |
代理服务器地址（留空自动跟随系统代理）、请求超时时间；显示当前生效代理与来源 | |
| 阅读体验 | 样式 | 界面主题与外观 |
| 阅读 | 阅读方向等阅读体验 | |
| 偏好 | 默认启动菜单、隐藏快速回顶、显示评论、全屏启动、搜索选项继承、默认收藏夹、从上次位置开始、本地优先加载 | |
| 下载与离线 | 下载 |
保存路径、线程数、归档并发、下载优先级、更新方案（画廊/归档 × 原图/压缩） |
| 更新扫描 |
每周自动更新扫描时刻、365 天老化规则 | |
| 标签管理 | 我的标签 | 我的标签维护 |
| Tag 维护 |
本地 Tag 字典维护（双轨三态） | |
| 日志 | 日志 |
日志开关、前端错误上报、更新 / 维护 / 下载 / 错误日志查看与实时尾随 |
| 关于 | 关于软件 | 版本信息（自动读取）、GitHub 链接、视口诊断面板入口（/diag） |
SakuManga/
├── backend/ # Go 后端服务（Gin + GORM + SQLite，单 exe 打包）
│ ├── main.go # 程序入口（--headless 双模式 + 系统托盘 + 自动端口）
│ ├── config.json # 服务配置（本机代理地址等）
│ ├── internal/ # 核心逻辑（router / handlers / services / models / database / tray）
│ ├── webui/ # 内嵌前端（go:embed all:dist，打包时拷入前端 dist/）
│ └── cmd_debug/ # 调试用命令行小工具（不影响主程序）
├── src/ # Vue 3 前端核心源码（Vite + Pinia + Vue Router + TS）
│ ├── api/ # 领域 API 封装（comic / download）
│ ├── components/ # 通用 UI 组件（含 common/ settings/ 详情面板等）
│ ├── composables/ # Vue 组合式函数（toast/modal/手柄/布局/联想/批量选择）
│ ├── config/ # 接口基地址与 token 配置
│ ├── router/ # 路由配置 + 登录守卫 + 管理员校验
│ ├── stores/ # Pinia 全局状态（按领域分文件）
│ ├── types/ # 数据契约类型
│ ├── utils/ # 请求 / 存储 / 滚动记忆 / 错误上报 / 负向排除 / 详情导航 / 进度恢复等
│ ├── views/ # 页面级组件（online/offline/抽卡/下载/阅读/对比等）
│ ├── App.vue # 根组件
│ └── main.ts # 前端入口
├── public/ # PWA 静态资源（favicon / manifest）
├── scripts/ # 构建辅助脚本（verify-round*.mjs 回归验证、E2E 搜索回归）
├── plans/ # 功能开发方案文档（Round1~33 + 路线图与 Backlog）
├── VerNotes/ # 版本发布说明 + 发布流程
├── testdata_eh/ # E 站抓取测试样本（HTML）
├── 学习笔记/ # 个人学习笔记（已弃用）
├── 计划书/ # 早期规划文档（已弃用）
├── vite.config.ts / package.json / tsconfig*.json # 前端工程配置（package.json 为版本号唯一来源）
├── build-release.bat # 一键打包单 exe（版本号自动读取）
└── README.md # 项目说明文档
本项目在开发过程中借鉴与使用了以下优秀的开源项目及社区资源：
- JHentai：感谢其在界面交互与部分业务逻辑实现上提供的灵感与思路。
- EhTagTranslation：本项目的标签汉化与翻译数据库来源于 EhTagTranslation 社区。
- e-hentai-tag-count：本项目的标签联想来源于 e-hentai-tag-count 社区。
本项目集成的标签数据库内容由 EhTagTranslation 贡献者共同维护，数据依据 CC BY-NC-SA 3.0（署名-非商业性使用-相同方式共享 3.0）协议提供：
- 非商业性：本项目及标签数据仅供个人学习与交流使用，严禁任何形式的商业盈利行为。
- 署名与共享：对标签数据的二次分发或衍生使用均继承原协议条款。
- AI 辅助生成：本项目的架构设计与绝大部分代码由 AI 辅助编写与重构。
- 测试状态：项目可能存在未覆盖的边缘场景或缺陷，欢迎提交 Issue 或 PR 协助完善。
本项目采用 AGPL-3.0 License 开源。