I IDEAICU

AI Engineering

OpenMAIC 部署实战：把 AI 课堂做成可维护的多智能体应用

OpenMAIC 的难点不在于把页面跑起来，而在于把一次生成演示变成可重复、可修改、可恢复的课堂系统。它同时包含多智能体编排、幻灯片 DSL、编辑器、渲染器、PPTX 导入、存储抽象、语音服务和可选的视频渲染。因此部署前要先决定课堂是单机实验、可信网络工具，还是需要身份隔离的多人服务。

从 workspace 结构开始

根应用采用 Next.js 16 和 React 19，仓库通过 pnpm workspace 维护多个包。@openmaic/dsl 负责幻灯片和资产契约，@openmaic/generation 管理生成管线契约，@openmaic/renderer 负责只读渲染，@openmaic/editor 负责编辑，@openmaic/importer 处理 PPTX 到 Slide[] 的导入，@openmaic/storage 则抽象 KV、资产、文档和运行时状态。

第一次启动不要一次打开所有能力

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install
cp .env.example .env.local
pnpm dev

Node.js 至少 20.9，pnpm 至少 10。先配置一个最熟悉的 LLM，生成一个短课堂，检查大纲、幻灯片、测验、刷新后的课程列表和导出结果。等基础链路稳定后，再加入搜索、TTS、ASR、图像和视频服务。

Provider 选择影响的不只是价格

OpenMAIC 支持大量云 provider、OpenAI 兼容接口以及 Ollama、Lemonade、FunASR 等本地路径。仓库的路由规则允许按阶段选择模型，服务端 provider 配置还可以覆盖客户端选择。实践中应把大纲生成、场景生成、视觉内容、搜索、TTS 和 ASR 分开记录，建立最小质量样本，避免某个 provider 返回格式异常时整堂课静默失败。

持久化部署必须先做威胁建模

server-persistence profile 只增加 PostgreSQL 和应用内持久化 API，但这不等于自动获得多用户安全。公开编译的 NEXT_PUBLIC token 可以被访问者提取，仓库明确说它没有保密性和用户隔离能力。它只适合本机或可信网络单用户实验。多人生产部署必须接入真实 session verification，让服务器从身份推导 learner partition，并重新设计文档、资产和管理接口的授权。

视频导出有独立资源账本

MP4 导出需要可选的 render-service，它包含 Chromium 和 FFmpeg，默认不启动。compose 文件将渲染服务放入 internal render network，并设计 egress lockdown、并发限制、共享内存和 8 GiB 标准资源 profile。部署时应单独测冷启动、长课堂、浏览器崩溃、磁盘占用和队列行为；不能把一次短课成功导出当作生产容量证明。

安全检查不能只看页面

官方安全文档要求漏洞通过 GitHub 私密渠道报告，最新 major release 和 active main 才有安全更新。源码和测试还覆盖 SSRF、CSP、iframe sandbox、持久化授权等边界。公网部署前至少确认 ACCESS_CODE、私有网络模型 URL 的开关、frame ancestors、数据库凭证、资产访问路径和日志脱敏。尤其不要把 .env.local 或 provider token 写入镜像层和构建参数。

验收顺序

  1. 固定教材和输入，跑一次标准课堂生成。
  2. 修改大纲和单页元素，确认编辑状态可保存。
  3. 导出 PPTX、HTML 和 ZIP，分别在目标环境打开。
  4. 启用 PostgreSQL 后测试刷新、重启和文档恢复。
  5. 最后才加入 OpenClaw、视频渲染和多人访问。

OpenMAIC 的优势是把课堂内容、编辑和导出放在同一个开放系统里；它的工程代价也正来自这里。越接近生产，越应该按数据、身份、资源和回滚逐项验收。