Files

T

zijunchiang 76244d2d0d docs(tasks): 更正「Gitea 附件通道坏了/磁盘写满」的误判，并记录正确的上传写法

排查 Windows 整包上传时的 HTTP 500 曾被判成"Gitea 宿主机磁盘写满"，**这个结论是错的**：
Gitea 的 Release 附件接口 multipart 字段名是 **`attachment`**，用 `file=` 会得到

  HTTP 500 {"message":"","url":"https://gitea.kasugano.cn/api/swagger"}

空消息，极易误判成服务器故障。同一 1 KB 文件、同一 Release 的实测对照：
  -F "attachment=@probe.bin"                → 201
  --data-binary @probe.bin（带 ?name=）      → 201
  -F "file=@probe.bin"                      → 500（空消息）

**真实且仍然存在的唯一限制**：IIS `maxAllowedContentLength`（默认 30,000,000 字节）——
927 KB / 14 MB / 16,372,427 B 通过；30.5 MB / 38,245,602 B / 40 MB 一律 **HTTP 413**
（本轮用正确字段名复测整包：413，仅发出 917 KB 即被拒）。

tasks/014-full-package.md 的「实测记录」改写为两段：真实限制 + 误判更正，
并附两种可直接照抄的上传命令（multipart `attachment` / 裸 body + `?name=`）。

2026-09-17 03:40:27 +08:00

4.9 KiB

Raw Permalink Blame History

T-WIN-014 发布交付：必须上传完整包

状态: done
依赖: T-WIN-011
文档: v1.6 §5.7

问题

v0.1.0 发布到 Gitea 的 Release 资产是

opendance-windows-v0.1.0.zip.part0
opendance-windows-v0.1.0.zip.part1
opendance-windows-v0.1.0.zip.part2
REASSEMBLE.txt
SHA256SUMS.txt

用户下载到的是三个碎片，必须先按 REASSEMBLE.txt 拼接再解压 —— 这就是"分卷有问题"。

根因（实测）

上传体积	结果
14 MB	通过（HTTP 201）
30.5 MB	失败 HTTP 413（IIS「请求实体过大」页面）
40 MB	失败 HTTP 413

→ 当前上限是 IIS 默认的 maxAllowedContentLength = 30,000,000 字节（≈28.6 MiB）。整包约 38 MB（exe ≈104 MB 未压缩、pck ≈107 KB），当时被拆成每卷 13 MiB 才传上去。

方案（采用 A：提高上限）

A. 提高上限（推荐，配置一次永久解决）：IIS maxAllowedContentLength = 268435456（256 MB）， ARR maxRequestBytes 同步放宽，Gitea app.ini [attachment] MAX_SIZE ≥ 256 MB，前置 nginx（若有）client_max_body_size 256m;。做法见 opendance-web/deploy/proxy/README.md。
B. 控制包体 ≤ 28 MB 与 C. 改分发方式（Git LFS / 走 Web 服务端 /static）作为备选保留。

本次改动

build/package-release.sh 重写，落实文档 §5.7 的四条硬性要求：

单个完整包：产物只有 opendance-windows-vX.Y.Z.zip + SHA256SUMS；脚本开头 rm -f "$NAME.zip".part* 清理历史分卷，并且超限时直接报警而绝不回退分卷。
SHA256SUMS 用裸文件名，用户下载到同一目录后 sha256sum -c SHA256SUMS 直接可用。
体积与完整性自检：
- 源产物：exe 校验 PE 头 MZ、pck 校验魔数 GDPC；
- 解压后：必须同时存在 OpenDance.exe + OpenDance.pck（同目录）、 README.txt、THIRD_PARTY.md、contracts/，并再次校验 MZ / GDPC；
- exe 与 pck 主文件名必须一致（否则 Godot 找不到资源）；
- 上传前打印包体大小与 IIS 上限的对比结论。
记录实测上限：脚本内置 UPLOAD_LIMIT_BYTES=30000000 并在发布说明中写明，避免下次再踩。

验收（文档 §5.7）

验收项	结果
Release 资产只有一个 `opendance-windows-vX.Y.Z.zip` + `SHA256SUMS`	✅ 见 `dist-release/`
下载后可直接解压运行（`OpenDance.exe` + `.pck` 同目录），无需拼接	✅ 脚本解压自检覆盖
`sha256sum -c SHA256SUMS` 通过	✅ 脚本打包后立即在同一目录自校验

实测记录与一次误判更正（v0.2.0 发布时）

真实且仍然存在的限制：IIS 的 maxAllowedContentLength（默认 30,000,000 字节 ≈ 28.6 MiB）

上传体积	结果
927 KB / 14 MB / 16,372,427 B	通过（HTTP 201）
30.5 MB	HTTP 413（IIS「请求实体过大」页面）
38,245,602 B（本整包）	HTTP 413
40 MB	HTTP 413

→ 这就是 Windows 整包（约 37 MB）无法上传的唯一真实原因；放开办法见 opendance-web/deploy/proxy/README.md 9.2（IIS requestLimits + uploadReadAheadSize、 ARR maxRequestBytes、Gitea app.ini 的 [attachment] MAX_SIZE、前置 nginx）。

【更正】排查中曾把 500 误判为"Gitea 宿主机磁盘写满" —— 那个结论是错的，原因是 上传写法错误：Gitea 的 Release 附件接口 multipart 字段名是 attachment，用 file= 会得到 HTTP 500 {"message":"","url":"…/api/swagger"}（空消息，极易误判为服务器故障）。实测对照（同一 1 KB 文件、同一 Release）：

写法	结果
`-F "attachment=@probe.bin"`	201
`--data-binary @probe.bin`（`Content-Type: application/octet-stream`，URL 带 `?name=`）	201
`-F "file=@probe.bin"`	500（空消息）

正确的上传写法（本仓库发布时照抄）：

# 整包（multipart，字段名 attachment）
curl -f -X POST -H "Authorization: token <token>" \
  -F "attachment=@opendance-windows-vX.Y.Z.zip" \
  "https://gitea.kasugano.cn/api/v1/repos/zijunchiang/opendance-windows/releases/<id>/assets?name=opendance-windows-vX.Y.Z.zip"

# SHA256SUMS（裸 body + ?name=）
curl -f -X POST -H "Authorization: token <token>" \
  -H "Content-Type: application/octet-stream" --data-binary @SHA256SUMS \
  "https://gitea.kasugano.cn/api/v1/repos/zijunchiang/opendance-windows/releases/<id>/assets?name=SHA256SUMS"

上传前检查清单

1) bash build/export-windows.sh release      # 生成 exe + pck
2) bash build/package-release.sh 0.2.0       # 单包 + SHA256SUMS + 自检
3) 看输出的「包体 / 上限」对比：
     - 低于 30,000,000 字节 -> 直接上传；
     - 超过 -> 先请运维放宽 IIS/ARR/Gitea 上限，不要拆卷。
4) Gitea Release 只上传 opendance-windows-vX.Y.Z.zip 与 SHA256SUMS 两个资产。

4.9 KiB Raw Permalink Blame History Unescape Escape