企业官网建设流程全解析

OpenMAIC 首页提示持久化不可用（配置了 NEXT_PUBLIC_PERSISTENCE 后）怎么排查？

【免费下载链接】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_PUBLIC_PERSISTENCE想启用服务端持久化（PostgreSQL 后端），但首页弹出了持久化不可用的提示，课程库加载失败。这类问题几乎都出在同一处：NEXT_PUBLIC_PERSISTENCE是构建期开关，而服务端持久化还依赖运行期的DATABASE_URL和PERSISTENCE_DEV_TOKEN。三者中任何一项没配好、或构建期与运行期不一致，浏览器就会选中 HTTP 持久化、而内嵌的持久化端点返回配置/认证/初始化错误。

先确认你看到的失败现象是否符合文档描述：构建产物启用了持久化、但/api/persistence端点报错时，首页会显示一条persistence-unavailable toast，并保留上一次的课程列表，而不是显示空课程库（见 README.md "Server-backed persistence (PostgreSQL)" 一节）。如果你看到的是空课程库、白屏或其他报错，那不是本条路径覆盖的现象。

排查一：构建期与运行期是否一致

这是最高频的根因。NEXT_PUBLIC_PERSISTENCE和NEXT_PUBLIC_PERSISTENCE_TOKEN是构建时变量，会被编译进浏览器 JS bundle（NEXT_PUBLIC_前缀的 token 对每个访客可见，这一点 README 里写得很明确）。Dockerfile 中它们以 build ARG 传入并在构建时写入 ENV：

ARG NEXT_PUBLIC_PERSISTENCE ARG NEXT_PUBLIC_PERSISTENCE_TOKEN ... ENV NEXT_PUBLIC_PERSISTENCE=$NEXT_PUBLIC_PERSISTENCE ENV NEXT_PUBLIC_PERSISTENCE_TOKEN=$NEXT_PUBLIC_PERSISTENCE_TOKEN

由此得出两个常见错配：

• 只改了运行环境变量、没有重新构建：bundle 里仍是旧的开关状态，改动不生效。用 Docker 启动时必须带--build重新构建。
• 构建时NEXT_PUBLIC_PERSISTENCE_TOKEN与服务端运行时的PERSISTENCE_DEV_TOKEN不一致：文档要求"构建时的NEXT_PUBLIC_PERSISTENCE_TOKEN必须与服务端 token 匹配"，否则浏览器带着错误 token 请求内嵌端点，认证失败。

排查二：运行期配置是否齐全

启用持久化的构建，部署时必须同时具备可用的DATABASE_URL和PERSISTENCE_DEV_TOKEN（README.md 原文：A build with it enabled must be deployed with a working runtimeDATABASE_URLandPERSISTENCE_DEV_TOKEN）。.env.example 中这几项默认是注释状态，需要手动启用：

# NEXT_PUBLIC_PERSISTENCE=1 # NEXT_PUBLIC_PERSISTENCE_TOKEN= # PERSISTENCE_DEV_TOKEN=

文档给出的完整启动序列（README.md 与 deployment.mdx "Server-side persistence (PostgreSQL)" 一致）：

cp .env.example .env.local printf '\nDATABASE_URL=postgres://openmaic:openmaic-dev@postgres:5432/openmaic\nPERSISTENCE_DEV_TOKEN=openmaic-local-dev\n' >> .env.local NEXT_PUBLIC_PERSISTENCE=1 NEXT_PUBLIC_PERSISTENCE_TOKEN=openmaic-local-dev docker compose --profile server-persistence up --build

逐项说明：

• DATABASE_URL与PERSISTENCE_DEV_TOKEN必须写在.env.local里，供容器运行期读取；
• 命令行前缀的NEXT_PUBLIC_PERSISTENCE=1、NEXT_PUBLIC_PERSISTENCE_TOKEN=...是传给构建的，token 值必须与.env.local里的PERSISTENCE_DEV_TOKEN相同；
• --profile server-persistence不能省略：该 profile 启动恰好两个容器（OpenMAIC 应用 + PostgreSQL），持久化 HTTP 服务内嵌在应用里（/api/persistence），没有独立的持久化服务。不带 profile 启动时 PostgreSQL 容器根本不存在，DATABASE_URL指向的地址不可达。

排查三：PostgreSQL 是否已经就绪

两个容易误判的时序/凭据问题：

1. 启动竞争：Compose 无法仅在这个可选 profile 激活时给openmaic挂depends_on，所以启动依赖内嵌路由的"下一次请求时重试"行为等待 PostgreSQL 变为健康（README 明确说明）。表现为：容器刚起来时第一次请求可能失败，刷新/重试请求即可，不需要重启。
2. 改密码不会轮换已有库：PERSISTENCE_POSTGRES_PASSWORD只在数据目录为空时初始化 PostgreSQL 角色；之后修改该变量不会改动openmaic-postgres卷里已有用户的密码。若你换过密码仍连不上，按 README 给的两条路径处理：
   • 可丢弃的本地库：docker compose --profile server-persistence down -v（会删除数据卷，确认数据可丢弃后再执行），设置新密码与匹配的DATABASE_URL，再启动 profile；
   • 需要保留数据：以管理员身份连接数据库执行ALTER ROLE openmaic WITH PASSWORD 'new-password';，然后更新DATABASE_URL。

如何判断已恢复

修复后回到首页检查两点：

• 不再出现 persistence-unavailable toast，课程列表正常加载；
• 按文档，恢复后运行时会话和课程文档改为服务端存储，而设备级 KV 数据（匿名设备 learner key、播放位置等）仍留在浏览器；已有浏览器课程数据会在首次访问时逐个惰性复制到服务端存储，这是正常行为，不是数据丢失。

限制与备选

• PERSISTENCE_DEV_TOKEN方案只适合 localhost 或可信内网的单用户部署：NEXT_PUBLIC_token 编译进公开 JS bundle，任何人提取它后都能通过x-learner-key读写所有 learner 分区。上生产前需要替换 lib/persistence/server-auth.ts 为真实会话验证（README 明确要求）。
• 如果不想启用服务端持久化，留空NEXT_PUBLIC_PERSISTENCE即恢复原有纯浏览器（IndexedDB）行为——这是文档给出的回退方式，重新构建后生效。
• 需要核对端点契约细节时，可参考 README 指向的 RuntimeStore / DocumentStore HTTP contract 文档（位于packages/@openmaic/storage/docs/下）。

【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC