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=`)。
This commit is contained in:
2026-09-17 03:40:27 +08:00
parent d9229fae5f
commit 76244d2d0d
+31 -29
View File
@@ -62,43 +62,45 @@ SHA256SUMS.txt
| 下载后可直接解压运行(`OpenDance.exe` + `.pck` 同目录),无需拼接 | ✅ 脚本解压自检覆盖 |
| `sha256sum -c SHA256SUMS` 通过 | ✅ 脚本打包后立即在同一目录自校验 |
## 实测记录(v0.2.0 发布时)
## 实测记录与一次误判更正(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 资产上传接口):
**真实且仍然存在的限制:IIS 的 `maxAllowedContentLength`(默认 30,000,000 字节 ≈ 28.6 MiB)**
| 上传体积 | 结果 |
|--|--|
| 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 秒** |
| 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)。
1. **与体积无关**:1 KB 也失败,而且是**瞬间**失败(不是读完请求体才判断),
所以不是 `MAX_SIZE` 这类体积限制;
2. **与仓库无关**:三个仓库的 Release 资产上传接口同样失败;
3. **其他写入通道正常**:创建 Release、PATCH Release 说明(纯 JSON)都成功;
4. **间歇性**:全部失败期间仍有 927 KB 的附件成功上传过一次。
**【更正】排查中曾把 500 误判为"Gitea 宿主机磁盘写满"** —— 那个结论是错的,原因是
**上传写法错误**:Gitea 的 Release 附件接口 multipart 字段名是 **`attachment`**,
用 `file=` 会得到 `HTTP 500 {"message":"","url":"…/api/swagger"}`(**空消息**,
极易误判为服务器故障)。实测对照(同一 1 KB 文件、同一 Release):
→ 最可能是 **Gitea 宿主机磁盘(或上传临时目录所在分区/tmpfs)几乎写满**:
Gitea 先把请求体写进数据目录的临时目录再落库,空间不足时返回 500 而不是 413。
运维需按 `opendance-web/deploy/proxy/README.md` 第九节:
①`df -h` 查数据盘 / `/tmp` / `data/tmp` ②看 Gitea 日志里这次 500 的真实错误
③清理临时文件与旧附件释放空间 ④把 `[attachment] MAX_SIZE` 设为 256 并重启。
| 写法 | 结果 |
|--|--|
| `-F "attachment=@probe.bin"` | **201** |
| `--data-binary @probe.bin`(`Content-Type: application/octet-stream`,URL 带 `?name=`) | **201** |
| `-F "file=@probe.bin"` | **500**(空消息) |
> 说明:本仓库 v0.1.0 的 `.part0/1/2` 分卷已被确认是交付缺陷(用户无法直接解压),
> 本仓库的打包脚本**不会**再生成分卷;整包与 `SHA256SUMS` 已就绪,
> 等上述空间问题解除后立即上传。
**正确的上传写法**(本仓库发布时照抄):
```bash
# 整包(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"
```
## 上传前检查清单