zijunchiang
cbd5001e98
原先记的「16.4 MB 边界」是误判（当时磁盘正被失败的请求逐步填满）。补做隔离 测试后：1 KB 与 100 KB 也失败且是**瞬间**失败（不是读完请求体才判断），三个仓库的 Release 资产接口同样失败，而创建 Release / PATCH 说明（纯 JSON）都正常， 其间还有 927 KB 的附件成功过一次 —— 因此不是体积上限，而是「附件文件落盘」这条 通道坏了，最可能是 Gitea 宿主机磁盘/临时目录几乎写满（返回 500 而非 413）。 IIS 那一关已确认放开生效（38,245,661 字节请求体被完整接收，不再 413）。 整包与 SHA256SUMS 已就绪，待宿主机空间问题解除后立即上传（不生成分卷）。 详见 opendance-web/deploy/proxy/README.md 第九节 9.1。
113 lines
5.0 KiB
Markdown
113 lines
5.0 KiB
Markdown
# 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 的四条硬性要求：
|
||
|
||
1. **单个完整包**：产物只有 `opendance-windows-vX.Y.Z.zip` + `SHA256SUMS`；
|
||
脚本开头 `rm -f "$NAME.zip".part*` 清理历史分卷，
|
||
并且**超限时直接报警而绝不回退分卷**。
|
||
2. **`SHA256SUMS` 用裸文件名**，用户下载到同一目录后 `sha256sum -c SHA256SUMS` 直接可用。
|
||
3. **体积与完整性自检**：
|
||
- 源产物：`exe` 校验 PE 头 `MZ`、`pck` 校验魔数 `GDPC`；
|
||
- 解压后：必须同时存在 `OpenDance.exe` + `OpenDance.pck`（同目录）、
|
||
`README.txt`、`THIRD_PARTY.md`、`contracts/`，并再次校验 `MZ` / `GDPC`；
|
||
- `exe` 与 `pck` 主文件名必须一致（否则 Godot 找不到资源）；
|
||
- 上传前打印包体大小与 IIS 上限的对比结论。
|
||
4. **记录实测上限**：脚本内置 `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 发布时）
|
||
|
||
按文档 §5.7 硬性要求 4「若用 A 方案，先在发布文档里记录实测上限」记录。
|
||
|
||
| 上传体积 | 结果 | 说明 |
|
||
|--|--|--|
|
||
| 14 MB | 通过（HTTP 201） | 分卷时代的对照 |
|
||
| 30.5 MB / 40 MB | **HTTP 413** | IIS 默认 `maxAllowedContentLength` 未放开 |
|
||
| **38,245,661 B（本整包）** | 请求体被**完整接收**（115 s），随后 **Gitea 返回 HTTP 500** | IIS 上限已放开，瓶颈转移到 Gitea 侧 |
|
||
|
||
IIS 放开之后的隔离测试（同一 Release 资产上传接口）：
|
||
|
||
| 上传体积 | 结果 |
|
||
|--|--|
|
||
| 914 KB / 927 KB（web tar.gz） | 通过 |
|
||
| 16,372,427 B（android zip） | 通过 |
|
||
| 37 MB（本整包） | HTTP 500 |
|
||
| 24 / 21 / 18 / 16.5 / 16.4 MB | HTTP 500 |
|
||
| **100 KB / 1 KB** | **HTTP 500，0.14~0.3 秒** |
|
||
|
||
结论（与最初"体积上限"的猜测不同）：
|
||
|
||
1. **与体积无关**：1 KB 也失败，而且是**瞬间**失败（不是读完请求体才判断），
|
||
所以不是 `MAX_SIZE` 这类体积限制；
|
||
2. **与仓库无关**：三个仓库的 Release 资产上传接口同样失败；
|
||
3. **其他写入通道正常**：创建 Release、PATCH Release 说明（纯 JSON）都成功；
|
||
4. **间歇性**：全部失败期间仍有 927 KB 的附件成功上传过一次。
|
||
|
||
→ 最可能是 **Gitea 宿主机磁盘（或上传临时目录所在分区/tmpfs）几乎写满**：
|
||
Gitea 先把请求体写进数据目录的临时目录再落库，空间不足时返回 500 而不是 413。
|
||
运维需按 `opendance-web/deploy/proxy/README.md` 第九节：
|
||
①`df -h` 查数据盘 / `/tmp` / `data/tmp` ②看 Gitea 日志里这次 500 的真实错误
|
||
③清理临时文件与旧附件释放空间 ④把 `[attachment] MAX_SIZE` 设为 256 并重启。
|
||
|
||
> 说明：本仓库 v0.1.0 的 `.part0/1/2` 分卷已被确认是交付缺陷（用户无法直接解压），
|
||
> 本仓库的打包脚本**不会**再生成分卷；整包与 `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 两个资产。
|
||
```
|