大文件上传问题排查与解决指南

日期: 2026-07-01
场景: OpenClaw WebChat 上传 113 MB docx 文件
状态: ✅ 已解决

---

问题概述

上传 113 MB 的 Word 文档时，遇到多层限制导致上传失败：

1. WebSocket payload 限制 (100 MB)
2. 附件大小限制 (20 MB)
3. Node.js 内存溢出 (OOM)

---

错误链路分析

错误 1: WebSocket payload 限制

错误信息:

warn gateway/ws error conn=... remote=192.168.121.114: Max payload size exceeded

原因: OpenClaw WebSocket 层的默认 payload 限制为 100 MB

排查命令:

grep -rn "maxPayload\|100.*1024.*1024" src/gateway/

解决方案:

• 修改 src/gateway/server-constants.ts 中的 MAX_PAYLOAD_BYTES
• 重新构建镜像：docker compose build

注意: 此限制在可能不是主要瓶颈，因为后续错误显示文件已经通过了 WebSocket 层。

---

错误 2: 附件大小限制（关键瓶颈）

错误信息:

Error: attachment 文件.docx: exceeds size limit (118512366 > 20971520 bytes)

原因: resolveChatAttachmentMaxBytes() 的默认值为 20 MB

定位文件: src/gateway/chat-attachments.ts

关键代码:

export const DEFAULT_CHAT_ATTACHMENT_MAX_MB = 20;

解决方案: 修改为 200 MB

// src/gateway/chat-attachments.ts
export const DEFAULT_CHAT_ATTACHMENT_MAX_MB = 200;  // 从 20 改为 200

验证命令:

grep -n "DEFAULT_CHAT_ATTACHMENT_MAX_MB" src/gateway/chat-attachments.ts

---

错误 3: Node.js 内存溢出

错误信息:

[8:0x215c3000] 103857 ms: Mark-Compact (reduce) 4034.8 (4100.1) MB

原因: 处理 113 MB 文件时 Node.js 内存耗尽，导致 WebSocket 连接超时断开

排查命令:

docker compose logs openclaw-agent3 --tail=100 | grep -E "GC|Mark-Compact|OOM"

解决方案: 增加 Node.js 内存限制

修改 docker-compose.yml:

openclaw-agent3:
  # ... 其他配置 ...
  command:
    - sh
    - -c
    - >
      python3 /home/node/.openclaw/workspace/scripts/file_server.py > /tmp/server.log 2>&1 &
      exec node --max-old-space-size=6144 dist/index.js gateway --bind "${OPENCLAW_GATEWAY_BIND:-lan}" --port 18789

关键参数: --max-old-space-size=6144 (6 GB)

---

完整解决步骤

1. 修改源码限制

# 编辑源码文件
vi src/gateway/chat-attachments.ts

# 找到并修改（第 64 行附近）
export const DEFAULT_CHAT_ATTACHMENT_MAX_MB = 200;  # 原值为 20

2. 修改 Docker 配置

# 编辑 docker-compose.yml
vi docker-compose.yml

# 在 openclaw-agent3 的 command 部分添加 Node.js 内存参数
command:
  - sh
  - -c
  - >
    python3 /home/node/.openclaw/workspace/scripts/file_server.py > /tmp/server.log 2>&1 &
    exec node --max-old-space-size=6144 dist/index.js gateway --bind "${OPENCLAW_GATEWAY_BIND:-lan}" --port 18789

3. 重新构建并重启

# 重新构建镜像
docker compose build openclaw-agent3

# 重启容器
docker compose up -d openclaw-agent3

# 查看日志确认启动成功
docker compose logs openclaw-agent3 | tail -30

4. 验证

重新上传大文件，确认：

• ✅ 不再报 “exceeds size limit” 错误
• ✅ 不再出现内存溢出
• ✅ WebSocket 连接稳定

---

配置对照表

限制类型	默认值	修改后	配置文件/源码位置	是否需要重启
WebSocket payload	100 MB	需源码修改	src/gateway/server-constants.ts	是（重构建）
Chat attachment	20 MB	200 MB	src/gateway/chat-attachments.ts	是（重构建）
Node.js heap	~4 GB	6 GB	docker-compose.yml command	是（重启容器）
hooks.maxBodyBytes	100 MB	200 MB	openclaw.json	是（重启）

---

排查命令速查

# 1. 查看限制相关代码
grep -rn "exceeds size limit\|DEFAULT_CHAT_ATTACHMENT_MAX_MB" src/

# 2. 查看内存使用
docker compose logs openclaw-agent3 | grep -E "GC|Mark-Compact|memory"

# 3. 查看容器内存限制
docker compose inspect openclaw-agent3 | grep -A5 Memory

# 4. 实时查看日志
docker compose logs -f openclaw-agent3

# 5. 检查 Node.js 内存参数
docker compose exec openclaw-agent3 ps aux | grep node

---

最佳实践建议

对于文件上传业务场景

文件大小	建议方案
< 20 MB	直接上传（无需修改）
20-100 MB	修改 DEFAULT_CHAT_ATTACHMENT_MAX_MB 为 100
100-200 MB	修改为 200 + 增加 Node.js 内存到 6 GB
> 200 MB	压缩后上传或使用外部存储

长期优化建议

1. 流式处理: 修改文件处理逻辑，使用流式读取而不是加载到内存
2. 分片上传: 实现大文件分片上传机制
3. 外部存储: 集成 OSS/S3，只上传 URL
4. 监控告警: 添加内存使用监控，提前预警

---

相关文件

• 源码: src/gateway/chat-attachments.ts
• Docker: docker-compose.yml
• 配置: openclaw.json
• 日志: .learnings/ERRORS.md

---

经验总结

1. 多层限制: 大文件上传涉及多层限制（WebSocket、应用层、系统层），需要逐层排查
2. 日志是关键: 通过错误日志可以精确定位限制位置
3. 内存是瓶颈: 处理大文件时，Node.js 内存往往是主要瓶颈
4. 源码修改必要: 某些限制是硬编码的，必须修改源码并重新构建

---

最后更新: 2026-07-01 17:05