docs(proxy): 修正 Gitea 附件上传失败的结论——与体积无关，指向宿主机磁盘
上一版把失败记成「两阶段 + 约 16.4 MB 边界」，那是**误判**： 当时磁盘正在被失败的请求逐步填满，所以看起来像有个体积阈值。补做与体积、 与仓库都无关的隔离测试后，结论要改： - 1 KB 与 100 KB 也失败，且**瞬间**失败（0.14~0.3 s，不是读完请求体才判断） -> 不是 [attachment] MAX_SIZE 这类体积上限； - opendance-web / opendance-windows / opendance-android 三个 Release 的资产 上传接口**同样**失败 -> 与仓库无关； - 创建 Release、PATCH Release 说明（纯 JSON）都成功 -> 只有「附件文件落盘」 这条通道坏掉； - 全部失败期间仍有 927 KB 的附件成功上传过一次 -> 间歇性。 最可能的原因：**Gitea 宿主机磁盘（或上传临时目录所在分区/tmpfs）几乎写满** （Gitea 先把请求体写入数据目录的临时目录，空间不足时返回 500 而非 413）。 同时确认：IIS 那一关**已经放开且生效**（38,245,661 字节的请求体被完整接收， 不再 413），因此若仍失败应直接排查 Gitea 宿主机，而不是继续改 IIS。 deploy/proxy/README.md 第九节的 9.1 重写为上述隔离结论，并给出运维排查顺序 （df -h / Gitea 日志里的真实错误 / 清理临时文件 / 最后再改 MAX_SIZE）。 Windows 端 tasks/014-full-package.md 同步修正（原先的「16.4 MB 边界」表述作废）。
This commit is contained in:
+36
-27
@@ -236,7 +236,7 @@ firewalld / ufw / iptables 的放行情况，并直接给出修复命令。
|
||||
> **Gitea**（源码仓库 + Release 附件）的站点。Windows 客户端的发布整包走 Gitea，
|
||||
> 因此**必须**单独放开 Gitea 站点的上限。
|
||||
|
||||
### 9.1 实测结论（两阶段）
|
||||
### 9.1 实测结论（IIS 放开之后：问题在 Gitea 侧，且与体积无关）
|
||||
|
||||
**第一阶段（IIS 上限未放开时）**
|
||||
|
||||
@@ -246,38 +246,43 @@ firewalld / ufw / iptables 的放行情况，并直接给出修复命令。
|
||||
| 30.5 MB | **失败 HTTP 413**（IIS「请求实体过大」页面） |
|
||||
| 40 MB | **失败 HTTP 413** |
|
||||
|
||||
**第二阶段（IIS 上限放开之后）** —— 放开的效果是**可验证**的：
|
||||
**第二阶段（IIS 上限放开之后）** —— 放开的效果**可验证**：
|
||||
38,245,661 字节的请求体被**完整接收**（耗时 115 s），不再出现 413，
|
||||
说明 IIS 的 `maxAllowedContentLength` 已经够用。但随后 **Gitea 自己返回 HTTP 500**
|
||||
（响应体是 Gitea 的 API 错误信封 `{"message":"","url":".../api/swagger"}`，
|
||||
`message` 为空）——即瓶颈已从 IIS 转移到 Gitea 侧。
|
||||
说明 IIS 的 `maxAllowedContentLength` 已经够用。但随后 **Gitea 自己返回 HTTP 500**，
|
||||
响应体是 Gitea 的 API 错误信封 `{"message":"","url":".../api/swagger"}`（`message` 为空）
|
||||
——瓶颈已经不在 IIS，而在 Gitea 侧。
|
||||
|
||||
同阶段的边界测量（同一个 Release 的资产上传接口）：
|
||||
随后做**与体积无关**的隔离测试（同一个 Release 资产上传接口）：
|
||||
|
||||
| 上传体积 | 结果 |
|
||||
|--|--|
|
||||
| 914 KB（web v0.7.1 tar.gz） | 通过 |
|
||||
| 914 KB / 927 KB（web v0.7.1 / v0.7.2 tar.gz） | 通过 |
|
||||
| 16,372,427 B（android v0.2.0 zip） | 通过 |
|
||||
| 16,400,000 B | **HTTP 500** |
|
||||
| 16,500,000 B / 18 MB / 21 MB / 24 MB | **HTTP 500** |
|
||||
| 100,000 B（在第一轮失败之后） | **HTTP 500，且仅耗时 0.3 s** |
|
||||
| 37 MB（windows 整包） | **HTTP 500** |
|
||||
| 24 MB / 21 MB / 18 MB / 16.5 MB / 16.4 MB | **HTTP 500** |
|
||||
| **100 KB** | **HTTP 500，0.3 秒** |
|
||||
| **1 KB** | **HTTP 500，0.14 秒** |
|
||||
|
||||
最后一行是关键：**在若干次大包失败之后，连 100 KB 都会在 0.3 秒内 500** ——
|
||||
这不符合"上传体积上限"的特征（上限判断会先读完请求体），
|
||||
更像**上传临时目录 / 数据盘已满**（Gitea 先把请求体写入 `data/tmp`，
|
||||
失败时可能在磁盘上留下残留临时文件）。
|
||||
关键结论：
|
||||
|
||||
> **因此运维侧需要按顺序检查两件事**：
|
||||
> 1. **Gitea 数据盘的剩余空间**（尤其是 `data/tmp`，以及它是否落在小容量的
|
||||
> tmpfs 上），并清理失败上传留下的临时文件；
|
||||
> 2. Gitea `app.ini` 的 `[attachment] MAX_SIZE`（下文第 3 条）。
|
||||
1. **与体积无关**：1 KB 也失败，且是**瞬间**失败（不是读完请求体才判断），
|
||||
所以**不是** `[attachment] MAX_SIZE` 这类"体积上限"（那样会先读完请求体）；
|
||||
2. **与仓库无关**：`opendance-web` / `opendance-windows` / `opendance-android`
|
||||
三个 Release 的资产上传接口**同样**失败；
|
||||
3. **写入通道的其他部分正常**：创建 Release、PATCH Release 说明（纯 JSON）都成功
|
||||
—— 只有**附件文件**的上传/落盘这一条路坏掉；
|
||||
4. **间歇性**：全部失败期间仍有 927 KB 的附件上传成功过一次。
|
||||
|
||||
> **最可能的原因：Gitea 宿主机的磁盘（或上传临时目录所在的分区/tmpfs）几乎写满。**
|
||||
> Gitea 会先把请求体写入数据目录下的临时目录，再落库/改名；空间不足时
|
||||
> 表现为 Gitea 返回 500 而**不是** 413。
|
||||
>
|
||||
> 只放开 IIS 是不够的：本节第 1 步之后仍然 500，说明还有 Gitea 侧的限制或磁盘问题。
|
||||
|
||||
→ 默认上限就是 **IIS 的 `maxAllowedContentLength = 30,000,000` 字节（≈28.6 MiB）**。
|
||||
Windows 客户端整包约 38 MB（`OpenDance.exe` ≈104 MB 未压缩 + `OpenDance.pck`），
|
||||
早先因此被拆成 `zip.part0/1/2`（每卷 13 MiB）才传上去 —— 用户拿到的是
|
||||
**无法直接解压的碎片**，必须自己拼接，属于交付缺陷。
|
||||
> **运维请按顺序检查**：
|
||||
> 1. Gitea 宿主机 `df -h`（数据盘、`/tmp`、以及 `data/tmp` 是否落在小容量 tmpfs 上）；
|
||||
> 2. Gitea 日志（`log/error.log` 或 journal）里这次 500 的真实错误
|
||||
> （大概率是 `no space left on device`）；
|
||||
> 3. 清理失败上传留下的临时文件与旧附件，释放空间；
|
||||
> 4. 再按 9.2 把 `[attachment] MAX_SIZE` 设为 **256**，重启 Gitea。
|
||||
|
||||
### 9.2 正确做法：放开 Gitea 站点上限到 256 MB
|
||||
|
||||
@@ -332,9 +337,9 @@ Windows 客户端整包约 38 MB（`OpenDance.exe` ≈104 MB 未压缩 + `OpenDa
|
||||
|
||||
5. 改完执行 `iisreset /noforce`（或只重启站点），再按下节复验。
|
||||
|
||||
> **注意**：`requestLimits` 只是第一道闸。IIS 放开后若仍为 500（而不是 413），
|
||||
> 说明请求体已经到达 Gitea，此时要按 9.1 的两件事继续排查
|
||||
> （Gitea 数据盘空间 / `[attachment] MAX_SIZE`）。
|
||||
> **注意**：`requestLimits` 只是第一道闸。IIS 放开后若变成 **500**（而不是 413），
|
||||
> 说明请求体已经到达 Gitea —— 此时按 9.1 的结论排查 **Gitea 宿主机磁盘空间**
|
||||
> （1 KB 也失败就说明与体积无关），然后再看 `[attachment] MAX_SIZE`。
|
||||
|
||||
### 9.3 复验方法
|
||||
|
||||
@@ -349,3 +354,7 @@ curl -i -X POST \
|
||||
|
||||
在放开上限之前，**不要**用分卷绕过：Windows 端 `build/package-release.sh`
|
||||
会拒绝生成 `.partN`，超限时直接告警并要求先放宽本节的配置。
|
||||
|
||||
另外提醒：本节第 1 条（IIS）已经**确认放开生效**（37 MB 请求体不再 413）。
|
||||
如果此时仍然上传失败，请直接跳到 9.1 的第 4 条 —— 问题在 Gitea 宿主机侧
|
||||
（磁盘/临时目录），而不是 IIS 配置。
|
||||
|
||||
Reference in New Issue
Block a user