问题现象

• Cloudflare 报错：返回 520 Unknown Error。

• Nginx 错误日志：

client sent too large header while reading client request headers

• 典型触发场景：
• 上传由 SingleFile 插件生成的超大 HTML 文件（几十 MB 以上）。
• 文件名过长（带完整标题和时间戳）。
• 搭配 JWT Token 或 Cookie 时，请求头进一步增大。
• 本地 Nginx 作为 反代 Karakeep 的网关，请求最终卡在 Nginx 层。

问题原因

large_client_header_buffers 4 8k;

• 4：最多 4 个缓冲区。

• 8k：单个缓冲区大小。

• 单个请求头最大 8KB。

• 总容量 = 4 × 8k = 32KB。

解决方案

1. 找到 nginx.conf
常见路径：
• /etc/nginx/nginx.conf
• /usr/local/nginx/conf/nginx.conf

2. 在 http {} 中添加配置

http {
    # 扩大请求头缓冲区，解决 headers 过大导致的 520 错误
    large_client_header_buffers 8 32k;

    # 其他已有配置...
    include /etc/nginx/conf.d/*.conf;
}

• 8：最多允许 8 个缓冲区。
• 32k：单个缓冲区大小 32KB，总容量 256KB。

⚠️ 提示：设置过大会浪费内存，一般 8 32k 就足够。

3. 重启 Nginx

nginx -t   # 测试配置是否正确
systemctl reload nginx

• 问题本质：Nginx 默认请求头缓冲区过小。

• 错误现象：Cloudflare 返回 520，Nginx 日志提示 header 过大。

• 解决办法：在宿主机的 Nginx 中调大 large_client_header_buffers（推荐 8 32k）。

• 案例背景：在 Docker 部署的 Karakeep 上传 SingleFile 导出文件时踩坑，验证了该问题并非应用 Bug，而是 Nginx 配置缺陷。

主要参考 暂无