企业官网建设流程全解析

1. 项目概述：这不是一个视频剪辑软件，而是一套可编程的视频生产流水线

OpenMontage 这个名字刚看到时，我第一反应是“哦，又一个开源剪辑工具”，但真正花三天时间把它的 GitHub 仓库翻完、跑通 demo、重写了一个定制 pipeline 后，我才意识到自己完全想错了——它根本不是 Premiere 或 DaVinci Resolve 的平替，甚至不打算做传统意义上的“非线性编辑器”。OpenMontage 的本质，是一个以任务流（task graph）为骨架、以智能体（agent）为执行单元、面向视频内容工业化生产的可编排系统。核心关键词里那个 agentic，不是营销话术，而是整个架构的底层范式：每个视频处理环节——从镜头分析、语音转文字、字幕生成、场景分割、BGM 匹配，到最终合成——都由独立封装的智能体承担，它们通过标准化协议通信，接受中央调度器（orchestrator）的指令，完成各自职责后主动上报状态与产出物。这种设计直接绕开了传统 NLE（非线性编辑）里“时间线拖拽+轨道堆叠”的交互逻辑，转而用代码定义工作流：“如果检测到人物特写超过3秒且背景音量低于-20dB，则触发人脸增强+环境降噪+字幕高亮”——这类规则在 OpenMontage 里是原生支持的，不是靠插件或脚本硬塞进去的。

它解决的痛点非常具体：中小内容团队在批量处理短视频时，反复面对“同一套流程要手动点5次不同软件、中间还要人工校验、出错就得重来”的困境。比如一家做知识科普的MCN机构，每天要产出20条3分钟的口播视频，每条都要做语音转写、关键帧提取、自动打标、AI配音补录、多平台适配（横屏/竖屏/带字幕/无字幕）。用传统方式，一个剪辑师一天最多处理8条；换成 OpenMontage，他们用 YAML 定义了7个智能体串联的 pipeline，配合 AWS Batch 调度，20条视频在凌晨自动跑完，人工只需审核最终结果。这不是“自动化”，而是把视频生产从“手工作坊”升级为“数控机床”——你不再关心螺丝怎么拧，只关心加工图纸（即 workflow definition）画得准不准。适合谁？不是给单打独斗的UP主用的，而是给有明确内容SOP、需要稳定交付节奏、且团队里至少有一名能写 Python 和读 YAML 的同学的团队。如果你连 ffmpeg 命令行都记不住，那它对你就是一座金矿，但钥匙在隔壁房间。

2. 架构设计与核心思路拆解：为什么放弃时间线，选择智能体编排？

2.1 拒绝“时间线中心主义”：从编辑逻辑到生产逻辑的范式迁移

传统视频工具的设计哲学，是围绕“时间线”这个单一维度展开的：所有操作——剪切、拼接、调色、加特效——都必须锚定在时间轴上。这在单条精剪时很直观，但在批量处理时就成了枷锁。举个实际例子：某电商客户要求所有商品视频必须在“开箱动作出现后0.5秒插入价格弹窗，且弹窗持续时间严格等于语音中‘只要’二字的时长”。在 Premiere 里实现，你要先手动标记开箱帧，再听语音找“只要”起止点，再计算毫秒数，最后逐条设置弹窗时长——20条视频，光标定位就耗掉半天。OpenMontage 的解法是彻底剥离时间轴依赖：它内置的 SpeechSegmenter 智能体自动输出语音分段时间戳，SceneDetector 智能体输出开箱事件帧号，两者通过统一的 media context ID 关联；调度器收到“开箱事件”信号后，直接调用 OverlayGenerator 智能体，传入参数trigger_offset_ms=500, duration_source="speech_segment:just"，后者查数据库拿到“只要”的精确时长，自动生成弹窗素材。整个过程不碰时间线，所有逻辑都在配置文件里声明。这种“事件驱动+参数传递”的模式，让复杂规则变成可复用、可测试、可版本管理的代码块，而不是藏在时间轴里的隐形操作。

2.2 智能体（Agent）不是AI模型，而是有边界的自治服务单元

这里必须划重点：OpenMontage 里的 agent，和 LLM 应用里常说的“智能体”不是一回事。它不负责推理决策，不调大模型API，更不是个会聊天的机器人。每个 agent 是一个轻量级、职责单一、接口契约明确的微服务。比如 AudioDenoiser agent，它只做一件事：接收一段音频二进制流 + 降噪强度参数（0-100），返回处理后的音频流。它的内部可以是 RNNoise、Whisper VAD 或自研的 CNN 模型，但对外只暴露/process接口和 JSON Schema 定义的输入输出。这种设计带来三个硬性好处：
第一，可替换性。客户A觉得默认降噪太激进，换成自己训练的模型，只需重新打包 agent 镜像，改一行配置指向新地址，整个 pipeline 不动；
第二，可观测性。每个 agent 启动时自动上报健康检查端点，调度器能实时看到 AudioDenoiser 的 CPU 占用率、平均处理延迟、错误率，一旦超阈值就自动熔断并告警；
第三，资源隔离。VideoEncoder agent 用 GPU，SubtitleGenerator 用 CPU，它们跑在不同容器里，不会因为编码卡顿拖垮字幕生成。我实测过，在 4 核 16GB 的云服务器上，并行跑 3 个 VideoEncoder（H.264）+ 5 个 SubtitleGenerator（Whisper.cpp），系统负载平稳，而同等任务用 FFmpeg 脚本串行跑，CPU 瞬间飙到 95% 且频繁 OOM。原因很简单：agent 是受控的并发，脚本是裸奔的进程。

2.3 开源策略：不是放源码了事，而是构建可验证的生态信任链

OpenMontage 的开源不是“把代码扔到 GitHub 就完事”。它的仓库结构本身就在传递一种工程哲学：

• core/目录下只有调度器、agent 通信协议、workflow 解析器，不到 2000 行 Go 代码，清晰到可以手写单元测试；
• agents/目录是社区贡献的 agent 实现，每个子目录包含Dockerfile、schema.json（定义输入输出）、test/（含真实媒体样本的集成测试）；
• 最关键的是verifiable-builds/，这里存放所有官方发布镜像的 SBOM（软件物料清单）和签名证书，任何用户都能用cosign verify验证镜像未被篡改。
  这种设计让“开源”从口号变成可审计的动作。去年有家教育机构采购前，要求审计字幕生成 agent 的 Whisper 模型权重是否被植入后门，他们直接下载agents/subtitle-whisper-cpp的 SBOM，比对公开的 Whisper.cpp 仓库 commit hash，30 分钟内确认无异常。如果是闭源软件，这种审计根本无从谈起。所以它的开源价值，不在于你能改代码，而在于你能确信：你部署的每一个组件，其行为边界和供应链来源都是透明、可验证的。

3. 核心模块解析与实操要点：从零搭建一条可用的视频流水线

3.1 环境准备：别急着装 Docker，先搞懂网络拓扑

OpenMontage 对运行环境的要求看似简单（Linux + Docker + Python 3.9+），但实际部署中最常踩坑的，恰恰是网络配置。它的 agent 间通信走的是 gRPC over HTTP/2，且默认启用双向 TLS 认证。这意味着：

• 所有 agent 容器必须在同一 Docker 网络（bridge 或 overlay）内，不能靠 host 网络混用；
• 调度器（orchestrator）启动时会生成一套 CA 证书，所有 agent 必须挂载该证书并配置--tls-ca-cert参数；
• 如果你用 Kubernetes，必须确保 service mesh（如 Istio）不劫持 gRPC 流量，否则 agent 会报UNAVAILABLE: upstream request timeout。

我建议新手从 Docker Compose 入手，但别用官方示例的docker-compose.yml——它把所有 agent 写在一个文件里，调试时改一个参数就要全量重启。我的做法是：

1. 先建一个专用网络docker network create openmontage-net；
2. 单独启一个cert-manager容器，用cfssl生成根证书和签发密钥，输出到./certs/；
3. 每个 agent 用独立的docker-compose.agent.yml，例如audio-denoiser.yml：

version: '3.8' services: audio-denoiser: image: openmontage/agent-audio-denoiser:v1.2.0 volumes: - ./certs:/app/certs:ro environment: - OM_TLS_CA_CERT=/app/certs/ca.pem - OM_AGENT_ID=audio-denoiser-01 networks: - openmontage-net

这样改一个 agent 的配置，只需docker compose -f audio-denoiser.yml up -d，不影响其他服务。实测下来，这种拆分让调试效率提升 3 倍以上，尤其当你需要对比 RNNoise 和 NVIDIA RNNNoise 两种降噪效果时，不用反复删重建整个 stack。

3.2 Workflow 定义：YAML 不是配置文件，而是视频生产的领域特定语言（DSL）

OpenMontage 的 workflow 文件（.omw后缀）看着像 YAML，实则是精心设计的 DSL。它的语法强制约束了视频生产的因果逻辑。举个典型例子：

name: "e-commerce-product-video" version: "1.0" inputs: - name: "raw_video" type: "video/mp4" required: true outputs: - name: "final_output" type: "video/mp4" source: "video-encoder.output" tasks: - id: "scene-detect" agent: "scene-detector" inputs: video: "{{ inputs.raw_video }}" outputs: scenes: "scenes.json" - id: "speech-to-text" agent: "subtitle-whisper-cpp" inputs: video: "{{ inputs.raw_video }}" language: "zh" outputs: subtitles: "subtitles.srt" - id: "overlay-price" agent: "overlay-generator" depends_on: ["scene-detect", "speech-to-text"] inputs: video: "{{ inputs.raw_video }}" scenes: "{{ tasks.scene-detect.outputs.scenes }}" subtitles: "{{ tasks.speech-to-text.outputs.subtitles }}" trigger_keyword: "只要" outputs: annotated_video: "price-overlay.mp4" - id: "video-encoder" agent: "video-encoder-h264" depends_on: ["overlay-price"] inputs: video: "{{ tasks.overlay-price.outputs.annotated_video }}" preset: "fast" outputs: output: "final.mp4"

这段代码里藏着三个关键设计：
第一，depends_on不是简单的执行顺序，而是数据依赖图。overlay-price必须等scene-detect输出scenes.json且speech-to-text输出subtitles.srt后才启动，调度器会实时监控这些文件是否就位；
第二，{{ }}语法不是模板渲染，而是数据流绑定。{{ tasks.scene-detect.outputs.scenes }}指向的是 agent 实际写入的文件路径（如/tmp/om/scene-detect-abc123/scenes.json），调度器会把这个路径作为参数传给下一个 agent；
第三，outputs字段定义了产物契约。overlay-generator必须生成price-overlay.mp4，否则 pipeline 直接失败，不会用空文件凑数。这种强契约让错误定位变得极其简单：如果video-encoder报错“找不到 input file”，你直接去overlay-price的日志里搜price-overlay.mp4是否成功生成，而不是在时间轴里盲猜哪一步漏了。

3.3 Agent 开发实战：如何为你的私有需求编写一个新 agent

OpenMontage 最强大的地方，是让你能快速接入自有能力。比如客户要求所有视频结尾必须插入公司 logo，且 logo 大小随视频分辨率动态缩放。官方没有现成 agent，但开发一个只需 4 步：
Step 1：定义接口契约
新建schema.json：

{ "input": { "video_path": {"type": "string", "description": "输入视频路径"}, "logo_path": {"type": "string", "description": "logo 图片路径"}, "position": {"type": "string", "enum": ["top-left", "bottom-right"], "default": "bottom-right"} }, "output": { "output_path": {"type": "string", "description": "输出视频路径"} }

Step 2：编写核心逻辑（Python 示例）

import cv2 import os from pathlib import Path def add_logo(video_path, logo_path, position): cap = cv2.VideoCapture(video_path) fps = cap.get(cv2.CAP_PROP_FPS) width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)) height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)) # 动态计算 logo 尺寸：占视频短边的 8% short_side = min(width, height) logo_size = int(short_side * 0.08) logo = cv2.imread(logo_path, cv2.IMREAD_UNCHANGED) logo = cv2.resize(logo, (logo_size, logo_size)) # 计算位置坐标 if position == "top-left": x, y = 20, 20 else: # bottom-right x = width - logo_size - 20 y = height - logo_size - 20 # 创建输出视频 fourcc = cv2.VideoWriter_fourcc(*'avc1') out = cv2.VideoWriter( f"{Path(video_path).stem}_with_logo.mp4", fourcc, fps, (width, height) ) while cap.isOpened(): ret, frame = cap.read() if not ret: break # 叠加 logo（带 alpha 通道） if logo.shape[2] == 4: alpha_s = logo[:, :, 3] / 255.0 alpha_l = 1.0 - alpha_s for c in range(0, 3): frame[y:y+logo_size, x:x+logo_size, c] = ( alpha_s * logo[:, :, c] + alpha_l * frame[y:y+logo_size, x:x+logo_size, c] ) out.write(frame) cap.release() out.release() return f"{Path(video_path).stem}_with_logo.mp4" if __name__ == "__main__": import argparse parser = argparse.ArgumentParser() parser.add_argument("--video-path", required=True) parser.add_argument("--logo-path", required=True) parser.add_argument("--position", default="bottom-right") args = parser.parse_args() output = add_logo(args.video_path, args.logo_path, args.position) print(f"OUTPUT_PATH={output}") # OpenMontage 通过 stdout 解析输出

Step 3：制作 Docker 镜像
Dockerfile：

FROM python:3.9-slim RUN apt-get update && apt-get install -y libglib2.0-0 libsm6 libxext6 && rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip install -r requirements.txt COPY . /app WORKDIR /app CMD ["python", "logo_inserter.py"]

Step 4：注册到系统
在agents/目录下建logo-inserter文件夹，放入schema.json、Dockerfile、logo_inserter.py，然后运行openmontage-cli register-agent --path ./agents/logo-inserter。注册后，你就能在 workflow 里用agent: "logo-inserter"了。整个过程不到 1 小时，比学 Premiere 插件开发快 10 倍。我用这套方法为客户定制了 7 个 agent，包括“自动添加课程编号水印”、“根据脚本情绪匹配 BGM”、“生成抖音竖版画中画”，全部上线即用，零兼容性问题。

4. 实操全流程演示：从原始素材到多平台成品的一键交付

4.1 场景设定：知识类博主的周更视频批量处理

我们模拟一个真实场景：博主“科技小张”每周三更新 5 条 8-10 分钟的技术讲解视频，原始素材是 OBS 录制的 MP4（1080p@30fps），要求产出：

• 主站高清版（1080p，带中英双语字幕，片头片尾固定）；
• 抖音竖版（1080x1920，自动裁切主体区域，加动态字幕）；
• B站横版（16:9，带章节标记，评论区引导文案）；
• 所有版本需插入“订阅按钮”动画（3 秒，位于右下角）。

传统方式：用 Premiere 做主站版 → 导出 → 用 DaVinci 做调色 → 用 CapCut 做抖音版 → 用 FFmpeg 加水印…… 5 条视频，至少 8 小时。用 OpenMontage，我们构建一条 pipeline，一次提交，四份成品自动产出。

4.2 Pipeline 设计：四个分支并行，共享基础分析

核心思想是避免重复计算。语音转写、场景分割、人脸检测这些高成本操作，只做一次，结果供所有分支复用。Workflow 结构如下：

raw_video ──┬─ [speech-to-text] ──┬─ [subtitle-render: main] ──┬─ [video-encoder: main] │ ├─ [subtitle-render: douyin] ──┼─ [video-encoder: douyin] │ └─ [subtitle-render: bilibili] ─┼─ [video-encoder: bilibili] ├─ [scene-detect] ────────┬─ [crop-douyin] ────────────┘ │ └─ [chapter-mark: bilibili] └─ [face-detect] ──────────── [subscribe-overlay]

对应的.omw文件关键片段：

tasks: # 基础分析（只执行一次） - id: "speech-to-text" agent: "subtitle-whisper-cpp" inputs: { video: "{{ inputs.raw_video }}" } outputs: { subtitles: "subtitles.srt" } - id: "scene-detect" agent: "scene-detector" inputs: { video: "{{ inputs.raw_video }}" } outputs: { scenes: "scenes.json" } - id: "face-detect" agent: "face-detector" inputs: { video: "{{ inputs.raw_video }}" } outputs: { faces: "faces.json" } # 主站分支 - id: "subtitle-main" agent: "subtitle-render" depends_on: ["speech-to-text"] inputs: { srt_file: "{{ tasks.speech-to-text.outputs.subtitles }}", style: "main" } outputs: { subtitle_video: "main-subtitled.mp4" } # 抖音分支（复用 speech-to-text 输出） - id: "crop-douyin" agent: "crop-processor" depends_on: ["scene-detect", "face-detect"] inputs: { video: "{{ inputs.raw_video }}", scenes: "{{ tasks.scene-detect.outputs.scenes }}", faces: "{{ tasks.face-detect.outputs.faces }}" } outputs: { cropped_video: "douyin-cropped.mp4" } - id: "subtitle-douyin" agent: "subtitle-render" depends_on: ["speech-to-text", "crop-douyin"] inputs: { srt_file: "{{ tasks.speech-to-text.outputs.subtitles }}", style: "douyin", base_video: "{{ tasks.crop-douyin.outputs.cropped_video }}" } outputs: { subtitle_video: "douyin-subtitled.mp4" } # 订阅按钮（所有分支复用） - id: "subscribe-overlay" agent: "subscribe-overlay" depends_on: ["face-detect"] inputs: { video: "{{ inputs.raw_video }}", faces: "{{ tasks.face-detect.outputs.faces }}" } outputs: { output: "with-subscribe.mp4" }

4.3 执行与监控：如何读懂调度器的日志和指标

提交 workflow 后，不要盯着终端看输出。OpenMontage 提供了三层次监控：

• Level 1：CLI 实时流
  openmontage-cli submit --workflow video-weekly.omw --input ./raw/tech-001.mp4会输出类似：

[2024-06-15 14:22:03] SUBMITTED: workflow_id=wk-7a8b9c [2024-06-15 14:22:05] STARTED: task=scene-detect, agent=scene-detector-v1.1 [2024-06-15 14:22:18] COMPLETED: task=scene-detect, duration=13.2s, output=scenes.json [2024-06-15 14:22:19] STARTED: task=speech-to-text, agent=subtitle-whisper-cpp-v2.0 ...

这是最粗粒度的状态，告诉你当前卡在哪一步。

• Level 2：Prometheus 指标
  访问http://localhost:9090（默认端口），查询关键指标：

• om_task_duration_seconds{task="speech-to-text", status="success"}：查看语音转写平均耗时，如果突然从 45s 涨到 120s，说明 Whisper 模型加载异常；

• om_agent_cpu_usage_percent{agent="video-encoder-h264"}：GPU 编码器 CPU 占用率，若长期 >80%，需增加实例或调低 preset；

• om_workflow_queue_length：等待调度的 workflow 数量，超过 5 说明调度器瓶颈，需扩容。

• Level 3：Agent 日志深度追踪
  每个 agent 启动时会生成唯一 trace ID。当video-encoder报错“无法打开输入文件”，你不必猜是哪个上游没传好，直接在日志里搜trace_id=tr-xyz789，就能看到完整链路：

[tr-xyz789] scene-detect: output written to /tmp/om/scenes.json [tr-xyz789] speech-to-text: output written to /tmp/om/subtitles.srt [tr-xyz789] crop-douyin: ERROR failed to read /tmp/om/scenes.json: permission denied

立刻定位到crop-douyin容器的 volume 挂载权限错了，而不是去检查video-encoder的代码。

4.4 成品交付与质量校验：自动化验收的三个硬性关卡

OpenMontage 的 pipeline 不是“跑完就完事”，它内置了质量门禁（quality gate）。我们在 workflow 末尾加入三个校验 task：

1. 格式校验：用ffprobe检查输出视频是否符合平台要求。抖音要求codec_name=h264且pix_fmt=yuv420p，B站要求duration>300（5分钟以上）。校验失败则 pipeline 标记为FAILED_QUALITY，不生成成品；
2. 字幕同步校验：用pysubs2解析 SRT，计算每条字幕的end_time - start_time，若平均时长 <1.2s 或 >8s，视为节奏异常，触发人工审核；
3. 视觉完整性校验：用 OpenCV 抽帧检测黑场/绿屏/静止画面。连续 30 帧像素标准差 <5，判定为“画面冻结”，自动重跑该 segment。

这些校验不是附加功能，而是 workflow 的一等公民。比如video-encoder输出后，自动触发quality-check-douyintask，它失败了，整个抖音分支就停在那里，主站分支不受影响。这种“故障隔离”能力，让批量处理不再是一荣俱荣、一损俱损的赌博，而是可控的工业化流水线。

5. 常见问题与排查技巧实录：那些文档里不会写的血泪经验

5.1 “Agent 启动后立即退出”——八成是证书挂载问题

这是新手遇到的第一道墙。现象：docker logs audio-denoiser显示FATAL: failed to load TLS CA certificate: open /app/certs/ca.pem: no such file or directory，但你明明ls ./certs/看到文件存在。原因几乎总是 Docker volume 挂载路径不匹配。OpenMontage 的 agent 镜像里，证书默认期望在/app/certs/，但你的docker-compose.yml写的是：

volumes: - ./certs:/certs:ro # 错！这里挂载到了 /certs，不是 /app/certs

正确写法必须是：

volumes: - ./certs:/app/certs:ro # 对！路径必须完全一致

更隐蔽的坑是 Windows/macOS 用户用 Docker Desktop，主机路径中的反斜杠\或空格会被转义，导致容器内路径失效。我的解决方案是：在./certs/目录下放一个test.txt，然后进容器docker exec -it audio-denoiser ls -l /app/certs/，亲眼确认文件存在且权限为644。别信文档，信ls。

5.2 “Pipeline 卡在某个 task，日志没报错”——检查数据依赖的隐式条件

现象：scene-detect显示COMPLETED，但overlay-price一直不启动，日志里只有WAITING_FOR_DEPENDENCIES。你以为是scene-detect没输出，其实它输出了scenes.json，但内容是空数组[]。OpenMontage 的依赖检查只看文件是否存在，不校验内容有效性。overlay-price需要scenes.json里至少有一个 scene，否则后续逻辑无法进行。解决方案有两个：

• 在scene-detectagent 的输出逻辑里，强制写入一个默认 scene（如"start": 0, "end": 1000000），保证文件非空；
• 在 workflow 中为overlay-price添加precondition：

- id: "overlay-price" agent: "overlay-generator" depends_on: ["scene-detect", "speech-to-text"] precondition: | import json with open("{{ tasks.scene-detect.outputs.scenes }}") as f: scenes = json.load(f) assert len(scenes) > 0, "No scenes detected"

这个 Python 片段会在 task 启动前执行，失败则直接跳过，避免 pipeline 卡死。

5.3 “多平台输出画质差异大”——根源在编码器 preset 的误解

现象：主站版视频清晰锐利，抖音版却模糊发虚，明明用的都是video-encoder-h264agent。查参数发现，主站用preset=slow，抖音用preset=ultrafast。很多人以为ultrafast只是速度快，画质损失可忽略。实测数据打脸：用 PSNR 和 SSIM 评测，ultrafast相比medium，PSNR 下降 4.2dB，SSIM 降低 0.15——肉眼可见的细节丢失。OpenMontage 的 preset 不是 FFmpeg 的原生 preset，而是做了二次封装：ultrafast强制crf=28且关闭 B-frame，slow则用crf=18+bframes=3。所以抖音版模糊，不是算法问题，是你选错了 preset。正确做法：抖音版用preset=fast（平衡速度与画质），再配合vf=scale=1080:1920:force_original_aspect_ratio=decrease:flags=lanczos保证缩放质量。记住：preset 是画质承诺，不是性能开关。

5.4 “自定义 agent 总是超时”——别怪调度器，先看你的进程模型

现象：你写的logo-inserter.py在本地跑得飞快，但放进 OpenMontage 就报TASK_TIMEOUT。原因通常是 agent 进程模型不匹配。OpenMontage 要求 agent 是短时进程：启动 → 处理输入 → 输出结果 → 退出。如果你的代码里写了while True:或time.sleep(300)，调度器会认为它卡死了。更隐蔽的是 Python 的multiprocessing：默认 spawn 方式在容器里可能卡住。解决方案：

• 所有 agent 必须用if __name__ == "__main__":包裹主逻辑；
• 禁用 multiprocessing，改用concurrent.futures.ThreadPoolExecutor（I/O 密集型）或subprocess.run（CPU 密集型）；
• 在代码开头加超时保护：

import signal def timeout_handler(signum, frame): raise TimeoutError("Agent execution exceeded 300 seconds") signal.signal(signal.SIGALRM, timeout_handler) signal.alarm(300) # 5分钟硬超时

这行代码能让你的 agent 在失控时优雅退出，而不是让整个 pipeline 等待。

5.5 “批量提交时部分 workflow 失败”——并发控制的隐形陷阱

现象：一次提交 20 个视频，15 个成功，5 个失败，错误全是RESOURCE_EXHAUSTED。你以为是服务器不够，其实是调度器的并发限制。OpenMontage 默认max_concurrent_tasks=10，意思是同时最多跑 10 个 task（不是 10 个 workflow）。一个 workflow 有 8 个 task，20 个 workflow 就需要 160 个并发槽位。解决方案：

• 临时调高：openmontage-cli config set max_concurrent_tasks=50；
• 更优解：在提交时指定队列优先级，用--queue high把紧急任务插队；
• 终极方案：按 workload 类型分队列。比如video-encoder占用 GPU，单独设gpu-queue，subtitle-whisper-cpp占用 CPU，设cpu-queue，互不抢占。命令：

openmontage-cli queue create gpu-queue --resource-type gpu --max-concurrent 8 openmontage-cli queue create cpu-queue --resource-type cpu --max-concurrent 20 # 提交时指定 openmontage-cli submit --queue gpu-queue --workflow encode.omw

这样，GPU 密集型任务不会饿死 CPU 任务，系统资源利用率提升 40%。

6. 生产环境部署与扩展：从单机 demo 到百 T 视频库的平滑演进

6.1 存储架构：为什么 NFS 是起步阶段的最优解，而非对象存储

很多团队一上来就想对接 S3，结果被权限、签名、分块上传搞崩溃。OpenMontage 的存储设计是分层的：

• 临时存储（/tmp）：所有 agent 的中间文件（帧图片、字幕文本、场景 JSON）都存这里，生命周期与 task 绑定，task 结束自动清理；
• 持久存储（inputs/outputs）：用户上传的原始视频和最终成品，需要长期保存。

起步阶段，我强烈推荐用 NFS（如 Synology NAS 或 Linux NFS server），理由有三：

1. 路径一致性：NFS 挂载后，所有容器看到的路径都是/mnt/nfs/openmontage/inputs，无需处理 S3 的s3://bucket/keyURI 转换；
2. 权限直通：Linux 文件权限（uid/gid）在容器内外一致，避免 S3 SDK 的 credential chain 冲突；
3. 调试友好：ls /mnt/nfs/openmontage/outputs/直接看到文件，ffmpeg -i xxx.mp4直接播放验证，不用写临时下载脚本。

只有当视频库突破 50TB、并发请求超 100QPS 时，才考虑迁移到对象存储。那时的方案是：用 MinIO 自建 S3 兼容服务，OpenMontage 的 storage adapter 会自动处理 multipart upload 和 presigned URL 生成，平滑过渡。

6.2 水平扩展：Agent 实例的弹性伸缩不是 K8s 的专利

OpenMontage 的调度器内置了 agent 实例管理。你不需要 K8s 的 HPA（Horizontal Pod Autoscaler），只需配置：

# agents/video-encoder-h264/config.yaml autoscale: min_instances: 2 max_instances: 10 target_cpu_utilization: 70 scale_up_delay: 60 # CPU >70% 持续60秒才扩容 scale_down_delay: 300 # CPU <50% 持续300秒才缩容

调度器会定期调用docker ps查看当前 running 的video-encoder-h264容器数，根据 CPU 指标决定启停。实测在 16 核服务器上，当并发 encoding 任务从 3 个涨到 12 个，实例数从 2 自动扩到 8，全程无任务