From 7037abf066209d4f871ea24777462d1f503675cd Mon Sep 17 00:00:00 2001 From: zijunchiang Date: Thu, 17 Sep 2026 01:51:32 +0800 Subject: [PATCH] =?UTF-8?q?docs(proxy):=20=E4=BF=AE=E6=AD=A3=20Gitea=20?= =?UTF-8?q?=E9=99=84=E4=BB=B6=E4=B8=8A=E4=BC=A0=E5=A4=B1=E8=B4=A5=E7=9A=84?= =?UTF-8?q?=E7=BB=93=E8=AE=BA=E2=80=94=E2=80=94=E4=B8=8E=E4=BD=93=E7=A7=AF?= =?UTF-8?q?=E6=97=A0=E5=85=B3=EF=BC=8C=E6=8C=87=E5=90=91=E5=AE=BF=E4=B8=BB?= =?UTF-8?q?=E6=9C=BA=E7=A3=81=E7=9B=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 上一版把失败记成「两阶段 + 约 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 边界」表述作废）。 --- deploy/proxy/README.md | 63 ++++++++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/deploy/proxy/README.md b/deploy/proxy/README.md index d2a4597..ca9f9a7 100644 --- a/deploy/proxy/README.md +++ b/deploy/proxy/README.md @@ -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 配置。