上传「跳过已存在 / 改名保存」功能改造记录

• 日期：2026-09-12
• 对象：本机下载中心 download-server.js（端口 8899，DL_ROOT=dl-hub）
• 起因：用户提问「重新上传的时候，如果已经上传成功，是否会自动跳过？」
• 改动前结论：不会跳过 —— 同名文件一律全量重传并覆盖

---

一、改动前的行为（核查结论）

文件大小	上传路径	重传行为
≤ 64MB	一次 multipart POST 到当前目录	写临时文件后 renameSync 覆盖同名文件，无存在性检查
> 64MB	分块续传 /api/upload/chunk + /api/upload/complete	全量重传 + 覆盖：续传进度只存在于 .upload-parts/<hash>/，而上传成功后会 fs.rmSync 删掉会话，所以 status 恒返回 exists:false

唯一存在的「跳过」是块级断点续传：仅当上次上传中途中断、会话目录仍在，且 fileSize 与 totalChunks 都一致时，才会跳过已收到的块；不一致则 abort 后从零传。

二、本次改动（3 项）

1. 新增「同名且大小一致 → 跳过」（秒传式）

• 服务端 GET /api/upload/status 新增可选参数 size：当目标文件已存在且字节数一致时返回 {ok:true, done:true, skipped:true, target:"相对路径", size:N}，前端据此直接跳过，不重传、不覆盖。
• 前端上传区新增复选框 「同名且大小一致时跳过（不重传）」——默认勾选。
• 不带 size 调用时行为与旧版完全一致（向后兼容）。

2. 新增「同名但大小不同 → 改名保存（不覆盖）」

• 复选框 「同名但大小不同时改名保存（不覆盖）」——默认不勾选（默认仍是覆盖，保持旧习惯）。
• 小文件：multipart 上传带 ?rename=1；大文件：/api/upload/complete 请求体带 "rename":true。
• 命中同名时复用既有 uniqueDest() 退避规则，另存为 name (2).ext、name (3).ext…（与回收站恢复的改名规则一致），原文件保留；响应带 renamed:true 并在页面上提示「已存在同名文件，另存为 …」。

3. 修复：子目录里上传大文件会落到「用户上传」根目录（旧版 bug）

• 旧前端 uploadChunked() 的会话 key 为 rel + '/' + 文件名，缺少当前目录这一层前缀，而服务端以 用户上传 为基准解析 —— 因此在 用户上传/某子目录/ 页面上传 >64MB 文件，最终会落盘到 用户上传/根，而不是当前目录（小文件走 multipart 路径没有这个问题）。
• 修复：服务端向页面注入 window.__UP_REL__（当前目录相对 用户上传 根），前端拼出与服务端一致的目标路径。根目录下 __UP_REL__ 为空串 → 会话 key 与旧版完全一致，不影响任何在传会话。

三、测试结果（端到端，23/23 通过）

测试脚本 /tmp/up-test.mjs（对 127.0.0.1:8899 真实 HTTP 调用，测试目录用后即删）：

1. 小文件首次 multipart 上传 → 200 + 内容正确
2. 状态接口：同大小→done:true；大小不符→不跳过；不带 size→不跳过；目标不存在→不跳过
3. 小文件 ?rename=1 重传 → renamed:true，原文件保留为 v1，新文件 small (2).txt 为 v2
4. 小文件不带 rename 重传 → 覆盖成功（renamed:false）
5. 大文件 67MB 分块（2 块）→ 分块 200、会话记录 2/2、合并成功且落盘在当前子目录、内容逐字节一致、完成后 done:true、会话已清理（再 complete 返回 404）
6. 大文件合并时 rename:true → renamed:true，另存 big (2).bin 且原 big.bin 保留
7. 页面注入：子目录 __UP_REL__="zz-上传功能测试"、根目录为空串、桌面页与移动页均含两个复选框；页面内联 JS 通过 node --check

服务端 node --check 通过；已备份原文件为 ~/Downloads/download-server.js.bak-20260912-214503。

四、使用说明与注意事项

• 需刷新上传页面才能拿到新前端（旧页面仍跑旧 JS）。
• 跳过判定只依据 相对路径 + 文件字节数，不计算内容哈希。
  • 若「同名 + 同大小但内容不同」（例如等长改稿、重导出的同尺寸文件），默认设置会跳过，需先取消勾选「同名且大小一致时跳过」再上传。
• 勾选改名保存 + 取消跳过 = 每次上传都另存一份副本；只想更新文件时，两个都按默认（跳过开、改名关）即可正常覆盖。

五、运维提醒（重要）

• 自 2026-09-12 起，8899 服务已由 systemd 单元 dl-server.service 托管（Restart=always + 开机自启，cgroup 独立于工具会话）。此前 nohup 启动的进程仍留在瞬态工具 shell 的进程组里，会被静默杀死 —— 根因与修复详见同目录《2026-09-12-下载服务静默死亡根因与systemd托管.md》。
• 重启服务会中断正在进行的分块上传：在传的 chunk 请求 socket 被关闭，对应文件行会显示「❌ 网络中断」，需在页面上重新选择文件。已收到的块仍在 .upload-parts/ 中，重新选择后会从断点继续，不会从头传。
• 本次排查过程中重启了服务 2 次（18:41、21:45 左右），当时正有一批模型在上传，可能造成部分文件行中断。
• 当前（2026-09-12 21:47）该批次上传状态：45 个分块会话、.upload-parts 占用 63GB，目标为 用户上传/models/Stable-diffusion/**（已在传约 45 个模型，多数进行到 20~24/32~104 块）；models 目录下已完整落盘 13 个文件。
• 磁盘：/home 805G，已用 270G，可用 495G；dl-hub 共 72G，其中 用户上传 70G（含 63G 分块暂存）。
• 45 个文件并行上传受浏览器「同域 6 连接」限制，实际是排队串行，整体带宽被摊薄 —— 这是「上传只有 8MB/s」观感的主要原因之一，与 2026-09-10 的排查记录方向一致。

六、回滚方式

cp ~/Downloads/download-server.js.bak-20260912-214503 ~/Downloads/download-server.js
bash ~/Downloads/restart-dl-server.sh   # 注意：会中断在传分块

七、相关文件

• 服务端：~/Downloads/download-server.js（改动点：handleUploadStatus 跳过判定、handleUploadComplete 的 rename、handleUpload 的 finalize() 改名落盘、upRelJs() 注入、前端 UPLOAD_JS/UPLOAD_ZONE_HTML/UPLOAD_CSS）
• 备份：~/Downloads/download-server.js.bak-20260912-214503
• 测试脚本：/tmp/up-test.mjs（临时文件，重启后可能被清理）