大文件接收网关

当企微 20MB 挡住你的资料 —— 一条绕开聊天通道的直传路径

20MB
通道硬限
企微入站不可协商的上限
767MB
单批实测
6 份 PPT 合计一次传完
16s
传 120MB
浏览器直连对象存储
0
失败
全程无重试、无中断

一套已验证的工程方案 · 根因定位 → 直传链路 → 踩坑实录

01 / 问题

文件为什么传不过来

用户看到的是「文件超过 100M 无法发送」。但这句话是企微客户端/服务端给出的, 文件从未到达 Hermes。链条上其实有三道不同的上限,把它们混为一谈, 就会走到错误的修法上去。

环节 真实上限 代码 / 配置位置
企微入站(用户 → 我) 20MB plugins/platforms/wecom/media.py:29
FILE_MAX_BYTES = 20MB,ABSOLUTE_MAX_BYTES 同值; 超出企微侧直接拒收
企微出站(我 → 用户) 文件 20MB / 图 10MB / 视频 10MB / 语音 2MB(AMR) 同上 26–30 行
Hermes 内部媒体上限 128MB 默认,可调 gateway.max_inbound_media_bytes
容器内存 cgroup 1.5GB(只读,容器内改不了) /sys/fs/cgroup/memory.max

关键教训:那句「超过 100M」不是我们发的

用户看到的提示来自企微客户端/服务端,文件从未到达 Hermes。 在日志里的表现是:有 Inbound callback msgtype='file', 但没有任何下载记录,随后出现 Empty WeCom message skipped。

没有下载记录 = 上游根本没把文件交过来。这条线索是整套诊断的分水岭。

诊断线索 · 日志序列
# 1) 回调到了,说明用户确实点了发送
Inbound callback msgtype='file'

# 2) 这里本该有下载记录 —— 但什么都没有
#    (文件从未到达,所以无从下载)

# 3) 于是消息体为空,被跳过
Empty WeCom message skipped

为什么「把 Hermes 上限调到 1GB」是无效药

这个改法看起来很对症 —— 毕竟 gateway.max_inbound_media_bytes 确实是可调的。 但它同时踩中两个独立的死结:

1 上游企微 20MB 门槛先拦住

企微入站在 20MB 处直接拒收。文件在到达 Hermes 之前就已经不存在了, 调 Hermes 侧的任何数字都没有意义 —— 它压根没机会做判断。

2 容器内存 1.5GB 撑不住

实测文件全量进内存,放大 3–5x。 100MB 文件峰值已达 321MiB;按此比例 1GB 约需 3.2GB —— 超过 1.5GB cgroup 上限, 结果是 OOM 崩掉网关。

就算上游放行,这一层也接不住。改了上限只是把「拒收」换成「崩溃」。

02 / 解法

浏览器直传对象存储

既然瓶颈在聊天通道,就不要再走聊天通道。文件从用户设备直连 OBS, 完全绕开企微,多大都行 —— 20MB 这道墙不再是链路的一部分。

用户设备 浏览器 · 任意大小 手机 / 电脑均可 PUT 直传 预签名 URL · 单个 key 对象存储 OBS 槽位 0000.bin … 不占容器内存 取回 扫描到位 → 下载 → 台账 我的收件箱 /opt/data/inbox/ + 登记台账 聊天通道(已弃用) 用户设备 企微入站 上限 20MB 此处阻断 · 文件从未到达 推荐路径

三步流程

生成页面

领 STS → 为 N 个槽位各签一条独立 PUT URL → 套模板产出 upload.html。一次性生成 100 个槽位、标称 48 小时。

发链接

部署后把 URL 发用户。页面与会话/登录态无关,手机电脑都能直接打开, 用户拖入文件即刻开始上传。

取回

上传完成后扫描槽位,按命名规则重命名归档到本地收件箱, 并登记台账(只记 key / 大小 / 本地路径)。

03 / 实现

关键实现

这一套里没有一步是「顺手就能写对」的。下面四点都是被现实逼出来的选择, 每一条都对应着一个具体的失败模式。

01SigV4 预签名自己实现

云函数 AlP56LCKFm 只能拿 STS,签 URL 要自己做。 实现要点:query 参数按字典序排列后算签名; X-Amz-Security-Token 需 URL 编码并参与签名; payload 用 UNSIGNED-PAYLOAD。

为什么不复用云函数的签名?因为云函数签出的 URL 只 5 分钟有效 (expires / ttl / expiresIn 全被忽略,恒定 282s), 根本不能拿来做上传页。必须用项目 STS(1h)自己签 SigV4。

02CORS 反射请求头

bucket 预检会把 Access-Control-Allow-Headers 回显你的请求头,所以自定义头(如 x-obs-acl)不会被拦。

签名参数走 query string,不触发额外预检 —— 这意味着整条上传链路 只经历一次预检,浏览器端不需要任何额外配置。

03单槽位 = 单文件位

预生成 N 个槽位(0000.bin、0001.bin …), 每个槽位含独立签名 URL + 公网读取 URL。

设计原因很直接:浏览器拿不到本地文件名。 所以槽位号是唯一的服务端信号 —— 它既是写入位置,也是「哪个位子有文件」的唯一凭据。 原始文件名不依赖页面回传,而是靠取回阶段的命名规则补回来。

04命名规则

取回归档时按用户钦定的格式重命名:

<前缀><NN>_<原文件名><原后缀>

前缀便于索引(如 YFSC = 誉夫战略咨询); 序号对齐槽位号;原名与后缀完整保留, 不做任何猜测性改写。

一条容易被忽略的边界:容器没有公网入口

容器跑在 NAT 内网(172.17.0.9),不能起 http 服务让用户传。 这也是「为什么必须是对象存储」而不是「起个接收服务」的硬性原因 —— 不是不想,是网络拓扑上做不到。

04 / 踩坑实录

踩坑实录

这一章是整套方案里最有价值的部分。下面每一条都是真实撞过的墙, 按「坑 / 现象 / 根因 / 修法」记下来,方便下次直接绕开。

坑 现象 根因 修法
CDN 回落陷阱
最大的坑
对不存在的路径返回 200 + text/html + 固定大小(如 35278B), 不是 404。100 个空槽位全被误判为「有文件」, collect.py --list 显示上百个「有文件」。 判「文件是否到位」时只看状态码,而 CDN 把不存在路径回落成了 一个成功的 HTML 页面。 必须排除 content-type: text/html。 仅凭 200 不足以判定文件存在。
STS 1 小时真实有效期 签名标称 X-Amz-Expires=172800(48h), 用户第二天来传,全部失败。 签名带 X-Amz-Security-Token(STS 令牌), STS 本身只 1 小时有效。 实际可用窗口 = min(48h, STS 1h) ≈ 1 小时。 用户说「明天再传」时,必须重新 mint + 重新部署, 不能沿用旧页面。
.obsutilconfig 占位符凭据 按配置文件里的 endpoint / AK / SK 去调用,直接失败。 该文件里是占位符凭据: http://your-endpoint 加假 AK/SK,不可用。 不要读它。凭据走项目 STS,签名走自己的 SigV4 实现。
容器无公网入口 想「起个 http 服务让用户直接传进来」,外部根本连不上。 容器在 NAT 内网(172.17.0.9),没有公网入口。 放弃自建接收端,改用对象存储中转 —— 这也是整套方案 采用「直传 + 取回」两段式的根本原因。
云函数签的 URL 只 5 分钟 拿云函数 AlP56LCKFm 签出的 URL 做上传页, 用户点开时链接早已失效。 expires / ttl / expiresIn 参数全被忽略,有效期恒为 282s。 不用云函数签名。只用它拿 STS(1h),签名由自己按 SigV4 实现。
页面未实测就发用户 用户打开后传不上去,问题只能回到「用户端」才发现, 来回沟通成本极高。 生成到部署之间有多道环节(签名、CORS、key 前缀、CDN 行为), 任何一环出错都只在真实上传时才暴露。 页面生成后必须先实测一次(真传一个小文件)再发用户。
站点 dist-deploy 重写规则 上传页放进站点项目后,写入的 key 与预期不符, 取回时扫不到文件。 站点 dist-deploy 的重写规则会给绝对路径加项目前缀。 上传页放在项目里时,注意 key 前缀要与之对齐。

05 / 实测性能

实测性能

浏览器直连对象存储,吞吐取决于用户上行带宽而非我们的服务器。 实测覆盖 120MB 到 767MB,全程没有出现失败或重试。

文件 耗时 备注
120MB 16s 单文件
150MB 20s 单文件
767MB ~90s 6 份 PPT 合计,单批

对比原来的处境

这 767MB 在聊天通道上的结局是:一个字节都传不进来。 现在的瓶颈只剩用户自己的上行带宽 —— 而这是可以等的事情。

06 / 可复用性

可复用性

这不是一次性脚本,而是一套可复用的链路。工具已落在固定目录, 命令三行,任何「通道限制挡住大文件」的场合都能照搬。

工具目录

/opt/data/tools/bigfile-gateway/ ├── mint.py 生成上传页(领 STS → 签 N 个槽位 → 套模板) ├── upload.template.html 页面模板 ├── upload.html 产物(部署用) ├── collect.py 取回器(扫描到位文件 → 下载 → 登记台账) ├── fetch_batch.py 按命名规则重命名归档 └── mint.json 槽位映射(含签名 URL,0600)

三段可复制命令

① 生成页面(100 个槽位)
cd /opt/data/tools/bigfile-gateway
PYTHONPATH=/opt/data/.pylibs python3 mint.py --slots 100 --hours 48
② 取回(下载到 /opt/data/inbox/ + 台账)
PYTHONPATH=/opt/data/.pylibs python3 collect.py
③ 只看(不下载)
PYTHONPATH=/opt/data/.pylibs python3 collect.py --list

完整流程:生成页面 → 部署(用站点项目 STS,走 fmode-static-publish 流程) → 把 URL 发用户 → 用户传完 → 取回。

适用的其他场景

任何「通道限制挡住大文件」的场合

只要链路上有一道不可协商的大小上限,而两端都能访问对象存储, 这套「预签名直传 + 扫描取回」就能原样套用。

替代:自建接收服务

当接收方没有公网入口(如本容器的 NAT 内网)时, 自建 http 接收端这条路根本走不通 —— 对象存储中转是唯一可行解。

大体积素材回收

单批 767MB / 6 份文件的实测说明:需要用户一次性交付多份大体积素材 (PPT、视频、设计稿)时,槽位化批量收取完全够用。

07 / 安全边界

安全边界与话术

这套方案的权限面比直觉更窄,但页面本身是公开的 —— 两边都要说清楚。

01预签名 URL 的权限范围

只对单个指定 key 有 PUT 权限: 不能读、不能列、不能删其他对象。

也就是说,即使链接被完全公开,拿到它的人也只能往那一个槽位里写, 拿不到任何已有资料。

02页面公开性的风险与应对

页面 URL 本身是公开的。最坏情况: 别人覆盖这批空槽位。

资料敏感时用 --hours 2 短效链接,并告知用户 用完即焚。

03台账只记元数据

台账只记 key / 大小 / 本地路径, 不记内容。

另有两条硬性建议:mint.json 含签名 URL, 权限 0600;页面生成后先实测再发用户。

「企微文件通道上限 20MB,这是通道限制不是你操作的问题。用这个链接直传存储,多大都行。」 给用户的一句话话术 —— 先卸掉对方的心理负担,再给路径