企业官网建设流程全解析

Gogs 通过 NGINX 推送大文件报 "413 Request Entity Too Large" 怎么处理

【免费下载链接】gogsThe painless way to host your own Git service项目地址: https://gitcode.com/GitHub_Trending/go/gogs

Gogs 部署在 NGINX 反向代理之后时，如果推送较大文件（git push、网页上传或 Git LFS 传输）时收到 HTTP413 Request Entity Too Large错误，原因通常不在 Gogs 本身：NGINX 对请求体的默认大小限制只有 1 MB。Gogs 官方文档 Reverse proxy 在 "Large file uploads" 一节直接给出了对应处理方式——在 NGINX 配置中调整client_max_body_size。

这篇文章适用于以下环境：

• Gogs 通过反向代理对外提供服务，反向代理是 NGINX；
• 推送超过 1 MB 的文件时开始报413 Request Entity Too Large。

如果你的反向代理是 Caddy 或 Apache，本文的配置不适用，文档中也未给出这两者的同类处理办法。

先确认要改的是哪个 server block

Gogs 的 NGINX 配置是一个serverblock，位于nginx.conf的http段内，或sites-available下的某个文件中。根据你当初的部署方式，它的形态有三种：

标准部署——直接代理到 Gogs 的 3000 端口：

server { listen 80; server_name gogs.example.com; location / { proxy_pass http://localhost:3000; } }

子路径部署——注意location和proxy_pass末尾的/必须成对出现：

server { listen 80; server_name example.com; location /gogs/ { proxy_pass http://localhost:3000/; } }

HTTPS 部署——通常由 Certbot 生成，监听 443 并带有proxy_set_header系列指令：

server { listen 443 ssl; server_name gogs.example.com; ssl_certificate /etc/letsencrypt/live/gogs.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/gogs.example.com/privkey.pem; location / { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

上三段配置是文档中的示例形态，你的实际文件里域名、证书路径等会有所不同——以本机文件为准，目标是找到proxy_pass指向 Gogs（localhost:3000）的那个 block。

添加 client_max_body_size 并重新加载

在确认的那个serverblock 中增加一行client_max_body_size。文档给出的完整示例如下（文档示例值50m）：

server { listen 80; server_name gogs.example.com; client_max_body_size 50m; location / { proxy_pass http://localhost:3000; } }

取值的原则文档写得很明确：client_max_body_size的值应等于或大于你预期用户会推送的最大文件大小；NGINX 的默认限制只有 1 MB。按你实际的推送需求确定数值，比如预期单文件不超过 50 MB 就取50m。

修改完成后重新加载 NGINX 配置使改动生效。

验证修复

413是推送时触发的错误，因此验证方式就是重新执行之前失败的那个推送：推送此前报413 Request Entity Too Large的文件，如果不再出现该错误，说明限制已生效。

如果调整后仍然报413，回查两点：

1. client_max_body_size的数值是否确实大于该文件的大小——文档要求该值"等于或大于预期推送的最大文件大小"，数值偏小就会继续被拒；
2. 改的是不是 Gogs 实际使用的那个serverblock——同一台机器上有多个 block（例如 HTTP 与 HTTPS 各一个）时，漏改其中一个，从对应端口进来的请求依然会受 1 MB 默认限制约束。

相关边界

• Git LFS 推送同样受此限制。根据 Git LFS 文档，Git LFS 客户端通过 HTTP/HTTPS 与 Gogs 通信，即使远程配置的是 SSH，LFS 对象传输也走 HTTP/HTTPS。因此 LFS 大文件推送经由 NGINX 时，同样落在client_max_body_size的限制之内，取值时要把 LFS 对象的实际大小一并考虑进去。
• 本条配置只解决请求体大小限制这一项。413之外如果还有推送异常（例如 hook 拒绝、SSH 回连超时等），属于其他问题，可参考 Troubleshooting 中按 SSH、Git、Database 等类别整理的条目。
• 反向代理场景下custom/conf/app.ini中的EXTERNAL_URL需要与用户实际访问的 URL 一致；若由代理做 TLS 终结，Gogs 侧保持PROTOCOL = http、EXTERNAL_URL写https://。这与413无关，但如果你借本次修改重新整理了代理配置，值得顺手核对。

【免费下载链接】gogsThe painless way to host your own Git service项目地址: https://gitcode.com/GitHub_Trending/go/gogs