自托管GitLab 15.0.2上传大体积artifacts返回404错误如何排查

小体积工件上传正常、11GB大工件返回404且Rails侧无日志，本质是大文件长连接上传过程中被中间层提前断开，Workhorse收到不完整的请求后无法匹配到有效的上传接口上下文，最终返回404状态码，和上传路径配置无关。由于请求在到达Rails服务之前就被前置层截断，所以你在production.log中查不到相关错误记录是正常现象。

1. Nginx反向代理全链路配置 #

你之前只修改了请求体大小限制，漏了大文件长上传必需的超时、转发规则配置，在Nginx的GitLab站点配置中补全以下参数：

# 已配置过的请求体大小限制，确认值大于11GB，建议设为12g预留冗余
client_max_body_size 12g;

# 以下三个超时参数默认值仅60s，远不足以支撑11GB文件上传，同步调大
proxy_connect_timeout 300;
proxy_send_timeout 600;
proxy_read_timeout 600;

# 关闭Nginx请求体缓冲，直接将请求透传给后端Workhorse
# 若开启缓冲，Nginx会先把完整11G文件缓存到本地临时目录再转发，不仅速度慢，临时目录空间不足、缓存超时都会直接中断请求
proxy_request_buffering off;
proxy_http_version 1.1;
proxy_set_header Connection "";

配置修改完成后执行nginx -t校验语法无误，重载Nginx服务生效。

2. GitLab Workhorse 配置校验 #

源码部署模式下大文件上传优先由Workhorse处理，不会直接打到Rails服务，需要确认两个配置：

• 检查Workhorse启动参数中的-max-artifact-size项，单位为字节，11GB对应值需大于11811160064，建议设为12884901888（即12GB）
• 如果Workhorse前还有额外的TCP代理层，需要同步调整该层的请求体大小限制、长连接超时参数，避免中间层断连

3. GitLab Rails侧配置补全 #

确认工件大小限制没有漏配：

• 登录实例管理员账号，进入「设置 > CI/CD > 持续集成和部署 > 工件」，将最大工件大小设置为12GB
• 检查对应项目的CI/CD设置，确认项目级配置没有覆盖实例级的大小限制，若项目单独设置了更小的阈值需同步调整
• 检查GitLab主配置文件gitlab.yml中artifacts: max_size参数，和面板配置保持一致，修改完成后重启Rails服务生效

4. GitLab Runner侧配置调整 #

在Runner所在服务器的配置文件config.toml中，给对应Runner补充超时配置，避免Runner侧主动断开上传连接：

[[runners]]
  # 保留原有已配置的参数
  output_limit = 4096
  [runners.docker]
    # 保留原有docker相关配置
    shm_size = 0
  [runners.helper]
    # 调大helper镜像的上传超时时间，默认值过短无法支撑大文件传输
    upload_timeout = 600

修改完成后重启gitlab-runner服务生效。

所有配置调整完成后，不要直接上传11GB文件测试，可以先传1GB左右的中等体积文件验证链路正常，再逐步测试更大体积的文件，避免每次等待数分钟重试浪费时间。

补充：11GB的单工件体积偏大，后续如果频繁传输这类大体积构建产物，建议在CI步骤中先对public目录做压缩分卷再上传，或者直接使用你规划的SSH rsync方式部署，降低GitLab的存储和传输压力。

内容的提问来源于stack exchange，提问作者emu