lionwebsite-backend/docs/REVIEW_FIXES_2026-09-08.md

2026-09-08 审查修复与编译交接

本批源码已在本机按问题分别提交，尚未推送、后端编译或部署。编译机恢复后，需要先取得下列仓库的提交，再按现有发布手册构建、验证与上线。此次没有调整鉴权或数据库表结构。

提交清单

仓库	提交	内容
storageNode	cbfd634	压缩临时文件、ZIP 完整性校验、失败保留源目录并恢复可重试状态
lionwebsite-backend	f65c5ad	下发节点前持久化任务，超时保留记录，原子累加用量
lionwebsite-backend	7f823b6	修复 Range 解析、读取长度、空文件和越界处理
lionwebsite-backend	1e6e3a1	上游订阅下载移出全局锁，设置超时，拒绝旧配置/旧请求的刷新结果
lionwebsite-backend	b15eeaf	复用连接线程组，登记等待对象后再发送，统一超时/失败/关闭清理
lionwebsite-backend	60facae	关闭图片和 TAR 文件流，合并同图请求，完成后发布缓存，检查转换结果
lionwebsite-frontend-desktop	287dc09	图片失败继续加载，单图重试，忽略旧页面图片事件
lionwebsite-frontend-desktop	b0f832c	退避重连、连接状态提示、唤醒后重连、重连与提交后的全量刷新
lionwebsite-frontend-desktop	d0eb2f0	链接 GID 类型匹配，补充任务提交回归测试
lionwebsite-backend	a9ba631	连接反复断开时重新安排监听，验证缓存失败后可重试
lionwebsite-backend	d3b18f9	修复图片 Key 缓存递归更新与 null 写入，异常时关闭 HTTP 响应

各仓库分别保留了原有历史。前端原先未提交的 index.html、vite.config.js、llm_readme.md 以及未跟踪的 dist/、node_modules/ 未纳入本批提交。

已验证与待验证

已完成：

• 前端 node --test tests/*.test.mjs：9 项通过。
• 前端生产构建：成功，产物输出到 /tmp/lionwebsite-review-build，没有覆盖现有 dist/ 或线上资源。构建提示主包体积超过 500 kB，本批未做依赖拆包。
• 各次提交的 git diff --check 与最终源码调用链检查。

尚未执行：

• 主站、存储节点的 Java 编译及 JUnit 测试。
• GraalVM 原生构建、真实节点断连、真实上游下载和生产端到端验证。

以下 Java 测试仅在编译机的独立工作副本执行，不在生产主站或存储机执行。两个仓库依次运行 mvn test，通过后再按现有部署手册构建原生程序。 新增测试均使用临时目录、Mock 或内存通道，不需要生产数据库和真实上游。

主站新增测试：GallerySubmissionTest、FileDownloadTest、SubscriptionRefreshServiceTest、RemoteServiceTest、PersonalArchiveTest、ImageFileCacheTest、GalleryKeyCacheTest。

存储节点新增测试：DownloadCheckServiceTest。两个仓库已有的订阅快照测试也应一起运行。

行为与接口说明

HTTP 路由、参数名和节点消息格式保持兼容，任务状态继续使用 已提交、下载中、等待压缩、压缩中、下载完成。

• POST /GalleryManage：先保存任务再下发。节点未确认时返回业务 failure，但任务记录仍在，前端刷新后可以重试；不会把已经收到的完成状态写回已提交。新增任务时即计入本周用量，重试不重复计量。
• 存储节点压缩失败：保留源文件，回到等待压缩状态，30 秒后可自动重试；手动重试会取消等待。仅完整校验通过的 ZIP 才视为完成。
• 使用 FileDownload.export 的文件接口：支持单个普通范围、后缀范围和开放结尾范围；非法或不可满足范围返回 416，Content-Range: bytes */<size>；多个范围回退为完整 200 响应；HEAD 不输出正文；普通完整响应不再带 Content-Range。
• 图片缓存：同一图片的并发请求共享下载，临时文件关闭且转换成功后才发布。下载连接超时 5 秒、读取超时 15 秒，转换超时 60 秒。图片缺失或下载失败仍返回 404，中断可返回 503。
• 订阅刷新：连接和连接池等待超时 5 秒，读取超时 15 秒；网络操作不占用订阅状态锁。上游 Key、过滤选项或启用状态改变后会使旧缓存失效，旧刷新结果不能重新发布。仅名称修改且刷新失败时保留原有缓存。
• WebSocket：连接失败按 1/2/4/8/16/30 秒退避，建立连接超时 10 秒；重连后重新读取任务列表和用量。页面恢复可见或网络恢复时重新连接。

上线验证重点

按现有发布手册安排存储节点、主站和前端上线，避开正在运行的生产任务。源码修复本身不代表生产已经更新。

1. 新建任务，模拟节点已有归档或立即返回状态，确认数据库与页面均保留完成状态且没有重复行。
2. 使用临时测试目录制造一次压缩失败，确认源文件保留，恢复目录可写后能重试，损坏 ZIP 不会标记完成。
3. 下载完整文件和小范围/尾部范围，确认响应字节数；验证空文件和越界请求。
4. 在测试上游阻塞刷新时修改其他账号/读取快照，确认操作不被网络等待阻塞；旧请求结束后不能覆盖新配置。
5. 阅读器人为令一张图片失败，确认后续图片继续加载、单图重试有效。
6. 浏览器断网、恢复网络、切后台再返回，确认连接提示和进度能够恢复。

根目录 /home/lionwebsite/API_DOCUMENTATION.md 已追加待发布说明；本文件是这部分接口行为变更的仓库内交接记录。