把重依赖关进沙箱：一个 10GB 镜像引发的重构

写在前面 这篇讲的是一个很不性感但很真实的工程问题：当你的产品需要处理 PDF、Office、图片、音视频时，系统依赖会重到什么程度，以及怎么办。

一、依赖是怎么膨胀的

辣椒AI 提供上百款文件处理工具。为了支撑它们，需要这些底层能力：

把这些全部打进主服务镜像，结果是：镜像超过 10GB，构建一次要很久，部署一次要拉很久，任何一个系统库版本冲突都能让整个服务起不来。

更糟的是，这些依赖和业务逻辑的迭代节奏完全不同。改一行业务代码，要重新构建一个 10GB 的镜像。

镜像膨胀的连锁反应

10GB 的镜像不只是"占地方"这么简单：

• CI 流水线：每次构建拉基础镜像、安装依赖、推送镜像——全流程 15-20 分钟，改一行代码也得等这么久
• 部署回滚：线上出问题需要紧急回滚，拉 10GB 的镜像意味着回滚耗时按分钟计
• 开发环境：新同事第一天，拉镜像可能就花掉半小时
• 版本管理：因为构建太慢，开发者倾向于减少构建次数——这意味着多个改动攒在一起发布，出问题时更难定位是哪个改动引入的

二、隔离成独立沙箱

我们把所有重依赖的底层执行能力抽出来，做成一个独立服务。它的定位很明确：

• 只做执行，不懂业务。 输入文件，输出结果，不知道用户是谁。
• 只在内网暴露。 不对公网开放。
• 接口按资源类型分流：文档、图片、音频、视频、通用文件、知识、设计，各走各的处理入口。

主服务和文档中台变回了纯粹的业务服务，镜像回到正常尺寸，构建和部署速度恢复正常。

沙箱本身也提供健康检查和模型就绪状态查询——可以查到各模块的加载状态、模型下载百分比和磁盘占用。这在部署和排障时非常有用，否则你只能盯着日志猜它到底起好了没有。

沙箱的接口设计原则

沙箱的接口不暴露"你用什么工具处理的"这种细节，只暴露"输入什么文件、要什么输出"这种业务语义。调用方不需要知道沙箱内部是用 LibreOffice 还是用其他转换器——它只关心"给我这份 Word 的 Markdown 版本"。

这个封装的好处是：沙箱内部可以随时替换实现，调用方代码不需要动。 比如我们从 LibreOffice 切到了一个更快的 Word 转换方案，只需要改沙箱内部的路由规则，所有调用方无感知。

三、模型权重不进镜像

隔离之后还有个问题：沙箱镜像里如果打包了几个 G 的模型权重，它自己就变成了那个 10GB 的镜像。

我们的解决办法是宿主机卷挂载 + 首次自动下载：

容器启动
  → 检查挂载的模型目录
  → 目录非空？直接加载，秒级启动
  → 目录为空？从模型仓库下载并缓存到该目录

模型权重存在宿主机上，容器只是挂载它。这样：

• 镜像里不含模型，体积可控
• 容器重建、升级、回滚时不需要重新下载模型
• 同一台机器上多个容器实例可以共享同一份权重

第一次部署仍然要等下载，但那是一次性成本。之后的每一次重启都是秒级。

模型版本管理

卷挂载引入了一个新问题：模型权重不是容器镜像的一部分，那版本怎么管？

我们的做法是：挂载目录按模型版本组织（如 /models/v1.2.0/），沙箱服务的环境变量里指定使用的版本号。升级模型时：

1. 先把新版本下载到一个新目录
2. 修改环境变量指向新版本
3. 重启容器
4. 验证正常后，删除旧版本目录

这个流程的关键是：升级和回滚都只需要改环境变量 + 重启，不需要重新构建镜像。 这是卷挂载方案最大的运维收益。

四、音视频的处理策略

这块有两个具体的取舍值得记录：

音频——各种编码格式先统一转成标准格式再处理，避免下游为每种编码写分支。转码有开销，但比维护十几条格式分支划算得多。

视频——不可能把每一帧都送给模型。我们的策略是按固定间隔抽帧并设置总帧数上限，再把抽出的关键帧交给多模态模型做时序描述。

抽帧策略是典型的效果与成本平衡：抽得太密，成本高且信息冗余；抽得太疏，会漏掉关键内容。固定间隔加上限是个粗糙但有效的起点，后续可以按内容变化程度做自适应。

音视频处理的安全考虑

音视频处理和文档处理有一个关键差别：音视频文件更容易触发资源耗尽。 一个看似不大的视频文件，解压后的原始帧数据可能是几十 GB 级别。

我们在沙箱层做了限制：

• 单次处理的视频最长 30 分钟
• 抽帧总数上限 120 帧
• 每个处理任务的内存上限 4GB
• 超时时间按视频时长动态计算

这些限制不是拍脑袋定的，是根据线上实际数据中 95 分位的资源消耗反推出的安全线。

五、依赖锁定

重依赖服务最怕的就是"昨天还能跑，今天构建就挂了"。这类服务的依赖树深，任何一个间接依赖发布新版本都可能引入不兼容。

我们用锁文件精确锁定整个 Python 运行时的依赖版本，构建时严格按锁文件安装。升级依赖是一个需要显式操作并重新验证的动作，而不是构建时自动发生的事。

这条规则让我们避免了很多次"不知道为什么突然坏了"。

依赖升级的流程

1. 在测试环境手动升级依赖锁文件
2. 跑完整的测试套件
3. 对关键格式各选 100 个文件做解析回归测试
4. 确认无退化后，提 PR 合并锁文件的变更
5. 生产环境用新锁文件构建

整个流程没有自动化，"手动的"操作其实是故意的——对沙箱这种重度依赖的服务，每次依赖变更都值得一个人的注意力。

六、什么时候该做这种隔离

判断标准很简单：

• 依赖体积是否已经影响到迭代速度？ 构建和部署慢到让人不想改代码，就该拆。
• 依赖和业务的迭代节奏是否差异很大？ 差异大就该拆。
• 是否有版本冲突困扰？ 系统级依赖互相打架，隔离是最省事的解法。

如果这三条都不成立，合在一起完全没问题。工程上的分层从来不是越多越好，只是在特定问题面前的一种解法。