OpenMAIC 如何用 Docker Compose 部署并检查服务可用性【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC如果你打算把 OpenMAIC一个用多智能体生成互动课堂的 Next.js 应用部署到自己的机器上而不是用 Vercel 一键部署那么仓库自带的 docker-compose.yml 就是官方推荐的路径在宿主机上跑 Docker Compose由镜像内部使用 Node.js 22 完成构建和运行应用监听 3000 端口。本文覆盖从准备.env.local、执行docker compose up --build到打开页面和请求健康检查接口确认服务可用的完整路径以及两个文档明确给出的可选分支服务端持久化PostgreSQLprofile 和慢网络构建加速。准备条件宿主机上可运行 Docker 与 Docker Compose。OpenMAIC 是标准 Next.js 应用仓库自带生产级 Dockerfile镜像内部使用 Node.js 22宿主机本身不需要安装 Node。一个 LLM 提供方的 API key。文档明确要求至少配置一个 LLM provider否则应用无法生成课堂内容。先取得仓库代码例如git clone之后进入 OpenMAIC 目录后续命令都在仓库根目录执行。配置.env.local仓库根目录有 .env.example 作为模板。按部署文档的操作cp .env.example .env.local # 编辑 .env.local填入至少一个 LLM provider 的 key.env.local里填什么取决于你选用的 provider。README Quick Start 给出的示例包括OPENAI_API_KEYsk-...或ANTHROPIC_API_KEYsk-ant-...也支持 Google Gemini、DeepSeek、Qwen、Kimi、MiniMax、Grok、OpenRouter、Azure OpenAI、Amazon Bedrock、GLM 等以及本地 providerOllama、Lemonade 等完整清单见 README.md 的 Quick Start 部分。这里有一个部署时容易踩的坑NEXT_PUBLIC_*前缀的功能开关是在 Docker构建时注入浏览器 bundle 的只写在运行时的.env.local里不会生效。需要启用这类功能时在启动命令前以环境变量方式传入例如NEXT_PUBLIC_ENABLE_VIDEO_EXPORTtrue \ NEXT_PUBLIC_ENABLE_PPTX_IMPORTtrue \ docker compose --profile video-export up --builddocker-compose.yml 已把NEXT_PUBLIC_PERSISTENCE、NEXT_PUBLIC_ENABLE_PPTX_IMPORT等常见开关声明为 build args命令行传入的值会覆盖默认的空值。启动默认部署docker compose up --build默认 Compose 部署只启动一个openmaic服务端口映射为3000:3000通过env_file: .env.local注入配置并挂载名为openmaic-data的命名卷到容器内/app/data。配置文件中还预设了RENDER_SERVICE_URLhttp://render-service:9000但 render 服务只在video-exportprofile 下才真正启动profile 未启用时应用探测不到渲染服务视频导出会退化为下载项目 ZIP 供本地渲染不影响课堂生成本身。如果拉取 Alpine 或 npm 依赖很慢例如中国大陆网络文档提供了两个可选的构建参数两者默认都为空加上它们不影响标准流程ALPINE_MIRRORmirrors.tuna.tsinghua.edu.cn \ NPM_REGISTRYhttps://registry.npmmirror.com \ docker compose up --build注意ALPINE_MIRROR只填镜像主机名不带https://NPM_REGISTRY填完整 URL。文档同时提醒这些参数不能加速 Docker Hub 的镜像拉取如node:22-alpine基础镜像需要的话要单独配置 Docker daemon 的 registry mirror并且不要在这些参数里嵌入用户名、密码或 tokenDocker 可能把它们记录进镜像元数据。检查服务可用性服务起来后有两层验证1. 打开应用页面。默认部署把容器 3000 端口映射到宿主机 3000浏览器访问http://localhost:3000远程机器则换成对应 IP应能看到 OpenMAIC 首页。README 的启动流程同样以打开 http://localhost:3000 并开始使用作为完成标志。2. 请求健康检查接口。仓库内置了 健康检查路由GET /api/health可直接用 curl 核对curl http://localhost:3000/api/health该路由返回的 JSON 结构为{ success: true, status: ok, version, capabilities }其中capabilities包含四个布尔字段webSearch、imageGeneration、videoGeneration、tts。按路由源码每个能力只有在至少一个对应 provider 被启用未设置disabled: true时才是true。因此这个接口能帮你确认两件事服务本身已响应status为ok以及.env.local里的 provider 配置是否被服务端正确加载——如果你的 provider 配置有误对应能力字段会显示为false这就是配置没生效的直观信号。可选分支启用服务端持久化PostgreSQL默认部署不依赖任何数据库课堂状态存在浏览器 IndexedDB 中。若要让运行时数据和课程文档落在服务端需要启用server-persistenceprofile它会在 Compose 中额外启动一个postgres:16容器数据保存在openmaic-postgres卷里。持久化 HTTP API 内嵌在 OpenMAIC 应用的/api/persistence中没有独立服务。先在.env.local中追加数据库连接与开发令牌下面为文档给出的示例值DATABASE_URLpostgres://openmaic:openmaic-devpostgres:5432/openmaic PERSISTENCE_DEV_TOKENopenmaic-local-dev然后以构建时变量启动NEXT_PUBLIC_PERSISTENCE1 \ NEXT_PUBLIC_PERSISTENCE_TOKENopenmaic-local-dev \ docker compose --profile server-persistence up --build启动后浏览器会走服务端持久化路径文档说明了故障现象供判断如果构建时打开了NEXT_PUBLIC_PERSISTENCE但运行时缺少匹配的DATABASE_URL/PERSISTENCE_DEV_TOKEN内嵌端点会返回配置、认证或初始化错误此时首页会显示持久化不可用的提示并保留原有的课程列表而不是显示空书库——看到这个提示就该回头核对上述变量是否成对、一致。这个 profile 的限制文档写得比较明确PERSISTENCE_DEV_TOKEN只适合本地或可信内网、单用户场景它不提供真正的用户隔离不能作为公开生产部署的认证方案PERSISTENCE_POSTGRES_PASSWORD只在数据库数据目录首次初始化时生效之后改环境变量不会修改已有数据库用户密码。文档给出的换密码方式是可弃库时用docker compose --profile server-persistence down -v清卷后重配需保留数据时以管理员连接执行ALTER ROLE openmaic WITH PASSWORD new-password;再更新DATABASE_URL。不设置NEXT_PUBLIC_PERSISTENCE就保持浏览器端持久化行为默认部署不需要关心这一节。限制与注意NEXT_PUBLIC_*开关只在构建时注入。改动这些开关后需要重新执行带--build的启动命令。容器内的localhost指向容器自身。如果 Ollama、Lemonade、VoxCPM、ComfyUI 这类服务跑在宿主机上地址要写host.docker.internal例如http://host.docker.internal:11434/v1Linux 上通常还要给openmaic服务加extra_hosts: [host.docker.internal:host-gateway]。ComfyUI 走的是客户端网络路径生产部署需另设ALLOW_LOCAL_NETWORKStrue否则 SSRF 防护会拒绝该地址。共享部署想加站点级密码门设置ACCESS_CODE即可此时所有 API 路由也受保护未设置则行为不变。通过docker build直接构建时上面提到的客户端开关要改用对应的--build-arg传入而不是命令行环境变量。参考部署文档英文 / 部署文档中文docker-compose.yml、Dockerfile、.env.example健康检查路由实现app/api/health/route.ts环境变量与 provider 完整配置配置说明【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考