wangxuming/openmaic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0b4c45d696942c986c622ea3f3975740fbfe18a7
openmaic/docs/deployment-3-tier.md
inman 2d04197f3f chore: establish learning module baseline
2026-08-16 14:58:47 +08:00

21 KiB
Raw Blame History

麦洛学习三端部署与运维

事实基线：2026-08-15

当前是一份 Next.js 16.1.2 代码、三种部署角色，不是三个已经拆开的应用。 本手册先说明当前可运行方式，再给出 server → learner desktop → ops 的机械拆分顺序。

1. 角色解析与真实保护范围

值 用途 生产默认 大型课程运营能力
learner learner desktop 公共表面 未配置角色时采用 无
ops 内部运营工作台 必须显式配置 有，且生产必须配置 ACCESS_CODE
server 课件/课程清单服务端 必须显式配置 无；可用 Bearer token 接收课件
all 历史单体兼容 不建议生产使用 有

解析规则：

  • 服务端读取 OPENMAIC_DEPLOYMENT_ROLE，未设时才回退公开角色；
  • 客户端入口读取 NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE；
  • 生产未配置或配置非法时 fail closed 为 learner；
  • development/test 未配置时为 all，保留上游单体开发体验；
  • NEXT_PUBLIC_* 是构建期值，ops 与 learner 要做可靠 UI 隔离时应分别构建。

当前强制保护的范围：

  • /courses、/courses/、/api/courses、/api/courses/ 和 /api/ops/** 需要 manage_courses；
  • 生产 ops 若没有 ACCESS_CODE 返回 503；
  • 运营 API 除 middleware 外，还逐 route 调用 requireOpsAccess 校验 HMAC cookie；
  • learner 请求运营 API 返回 403，访问运营页面回到首页；
  • server 是无头服务：所有非 API 页面直接返回 404，/api/courses/、 /api/ops/ 和 /api/access-code/** 也返回 API 404；provider 探测/验证、 MP4 export、开发态 persistence、usage、全局 job 列表与 /api/proxy-media 也不在专用 server 公开面；
  • 全局 job 列表的 GET/HEAD 都会返回 404； /api/internal/course-publish 只允许 POST，尾斜杠不会绕过方法边界；
  • POST /api/coursewares 在 ops 同源部署校验 ACCESS_CODE 会话，在 server 部署校验 COURSEWARE_PUBLISH_TOKEN Bearer token，在 learner 部署拒绝；
  • 公开 courseware、course manifest 读取仍是服务端的静态数据 API。

远程发布成功后，ops 通过当前 CourseRecord.publication 回执识别本地未挂载 registry 的已发布 source classroom，并拒绝覆写或随 job 删除。发布与删除还 共用同进程 source 互斥，避免在最终复核与回执落盘之间竞态删除。该保护只覆盖 当前回执且不跨进程；重生清除回执后，旧已发布源是否永久保留尚未定义， 多实例仍需持久发布历史和分布式锁/事务。

重要限制：上述是针对明确非课堂必需端点的部分 deny，不是完整的 learner identity/capability allowlist； 物理拆分之前，还应在反向代理层只暴露该角色需要的路由。

learner 身份、classroom/job owner、资源级授权、课程权益与成本额度尚未完成。 无头 server 边界只隐藏页面和运营 API，不代表其他生成、Chat、TTS、搜索等 高成本 API 已可安全向匿名公网开放。上线前必须先完成身份与授权设计， 并由网关执行最小 API allowlist。

2. 三端部署矩阵

项目 learner desktop ops server
角色 env learner ops server
面向用户 学习者/单课件作者 内部运营 learner 与 ops
单课件双路径 主能力 同构代码中仍存在 当前承载后台生成与模型 API
大型课程创建/确认/重试 隐藏且拒绝 主能力 不提供运营 UI
大课学习 主能力 验收可用 提供 manifest/bundle
原 Stage 学习和编辑 模块审阅 不渲染
ACCESS_CODE 可选全站访问码 生产必配 通常不配，发布走 token
COURSEWARE_PUBLISH_TOKEN 不配 当前课程发布内部必配 跨实例发布必配
LLM/TTS/媒体 provider 单课件生成与原课堂按需 主 Agent、模块生成、TTS、媒体 仅其实际承载的模型端点按需
文件数据目录 可读课程缓存为浏览器数据 classroom、job、framework courseware、bundle、manifest
多实例 UI 可横向，但生成任务仍受状态约束 不可并发写文件 repo 当前不可并发写文件 repo

learner desktop 不是“无模型 key 的纯静态站”。它保留单课件生成和原课堂教学 Agent： 当前同构部署可通过 server-configured provider 提供模型；物理 desktop 拆分后可改为调用 受控 server API。只有目录、manifest 和 bundle 下载属于零 LLM 热路径。

3. 环境变量

3.1 角色与鉴权

变量 作用 learner ops server
OPENMAIC_DEPLOYMENT_ROLE 服务端角色：all/ops/server/learner 必配 必配 必配
NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE 同一非敏感角色名，控制 UI affordance 必配 必配 可配
ACCESS_CODE HMAC 会话口令 可选 生产必配 可选
ACCESS_CODE_SESSION_TTL_SECONDS 会话 TTL，默认 604800 秒（7 天） 按需 可配 不配
OPS_PUBLIC_ORIGIN ops 同源写校验的 canonical origin 不配 反代部署必配 不配
COURSEWARE_PUBLISH_TOKEN 服务端发布凭据 不配 当前课程发布必配 跨实例接收必配
COURSE_PUBLISH_SERVER_BASE_URL 固定的跨进程发布 origin 不配 独立部署必配 不配
COURSEWARE_PUBLIC_BASE_URL learner 可访问的课件公开 origin 不配 不配 生产必配

不存在受支持的 NEXT_PUBLIC_COURSEWARE_PUBLISH_TOKEN。不要把发布密钥放入浏览器构建。

ACCESS_CODE cookie 使用 HMAC 签名并带签发时间，Edge 中间件与 Node route 使用 同一 TTL 规则，拒绝过期或未来时间 token。POST /api/access-code/verify 只接受 同源 application/json，对 Content-Length 和实际 chunked stream 都强制 8 KiB 上限， 并对失败尝试做有界进程内限流。所有使用该 cookie 的 ops 写操作也要通过 Origin 同源校验。进程内限流不能代替网关级的分布式限流。 同源校验不信任 X-Forwarded-Host；如果 ops 位于反向代理后，必须把浏览器真实 origin（例如 https://ops.example.com）配置为 OPS_PUBLIC_ORIGIN。

3.2 生成与模型

变量 作用 备注
MODEL_ROUTES 按 stage 路由模型 至少按需配置 generate-classroom、course-framework、scene-content、scene-actions
各 PROVIDER_API_KEY / BASE_URL / MODELS LLM provider 以 .env.example 为准
各 TTS_* 讲解音频与原课堂语音 大课发布要求每个 speech 有持久化音频
IMAGE_* / VIDEO_* 可选媒体生成 未生成或无法解析的媒体会在发布时 fail closed
Web search provider 变量 可选框架研究/单课件联网 未配置时相应生成路径降级
OPENMAIC_ENABLE_VOCATIONAL 服务端职教 task-engine 门 客户端开关本身不是安全边界
NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI 显示实验入口 仅 UI
NEXT_PUBLIC_PI_CHAT_ENABLED 原 Pi 课堂 Chat 开关 属于受保护课堂能力
OPENMAIC_ENABLE_PI_WEB_SEARCH Pi Director 联网门 独立于 Pi Chat 开关

主 Agent 模型示例：

MODEL_ROUTES={"course-framework":"openai:gpt-4o-mini","generate-classroom":"openai:gpt-4o"}

实际 provider:model 格式应与当前 server provider 配置保持一致，不要照搬旧文档中的 provider/model 斜杠写法。

3.3 文件仓库

变量 默认目录 角色
CLASSROOM_DATA_DIR data/classrooms learner/ops 当前生成服务
CLASSROOM_JOBS_DIR data/classroom-jobs learner/ops 当前生成服务
COURSE_FRAMEWORK_DIR data/course-frameworks ops
COURSEWARE_DATA_DIR data/coursewares server；当前同源发布也直接写
COURSEWARE_BUNDLE_DIR data/courseware-bundles server
COURSE_MANIFEST_DIR data/course-manifests server；当前 ops 同进程提交
COURSEWARE_MAX_UPLOAD_BYTES 314572800 server；单模块 ZIP 上限
COURSE_PUBLISH_MAX_UPLOAD_BYTES 943718400 ops/server；整批 multipart 上限
COURSE_PUBLISH_TIMEOUT_MS 600000 ops 调用 server 的超时
COURSE_PUBLISH_ALLOW_INSECURE_HTTP false 仅可在受信私网显式开启

3.4 通用持久化

变量 作用 当前边界
NEXT_PUBLIC_PERSISTENCE=1 浏览器改用 HTTP persistence backend 构建期变量
NEXT_PUBLIC_PERSISTENCE_TOKEN 开发共享 token 不提供用户隔离，不得作为公网生产鉴权
PERSISTENCE_DEV_TOKEN 与公开开发 token 配对 仅开发
DATABASE_URL 通用 document/runtime/asset Postgres backend 没有替换 courseware/manifest repo
ASSET_S3_BUCKET 通用 asset 字节存储 没有替换 frozen bundle byte store

不要因为配置了 DATABASE_URL 或 ASSET_S3_BUCKET，就把发布仓库描述为已经使用 Postgres/S3。

4. 当前启动方式

每个角色应使用独立构建目录或独立构建流水线，因为公开角色会在构建时内联。

Docker Compose

Dockerfile 把 NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE 声明为 builder ARG/ENV， Compose 为 learner、ops、server 分别构建独立镜像上下文，并在运行时固定同值的 OPENMAIC_DEPLOYMENT_ROLE。不要只在 container 启动时改 NEXT_PUBLIC 角色；那不会重写已经内联的 浏览器 bundle。

# learner：默认端口 3000
docker compose up --build learner

# ops：默认端口 3102，.env.local 必须有 ACCESS_CODE
docker compose --profile ops up --build ops

# server：默认端口 3103
docker compose --profile server up --build server

可分别用 OPENMAIC_LEARNER_PORT、OPENMAIC_OPS_PORT、OPENMAIC_SERVER_PORT 改写宿主机端口。 .env.local 仍负责 provider key、ACCESS_CODE 和 COURSEWARE_PUBLISH_TOKEN；Compose 中的硬编码角色会 覆盖 env_file 中同名角色，防止服务端权限与客户端入口不一致。learner、ops 和 server 默认使用 独立数据卷。ops 配置 COURSE_PUBLISH_SERVER_BASE_URL 后使用跨实例整批发布； 未配置时仅保留历史同进程共享文件库 fallback。

直接启动 Next.js

learner desktop 表面

OPENMAIC_DEPLOYMENT_ROLE=learner
NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE=learner
pnpm build
pnpm start -p 3101

若要使用单课件生成和原课堂模型能力，还需配置相应 provider 与 MODEL_ROUTES。 若只做发布课程的读取 smoke，可不配置模型，但这不代表完整 learner 产品无需模型。

ops

OPENMAIC_DEPLOYMENT_ROLE=ops
NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE=ops
ACCESS_CODE=<strong-secret>
OPS_PUBLIC_ORIGIN=https://ops.example.com
COURSEWARE_PUBLISH_TOKEN=<server-only-secret>
COURSE_PUBLISH_SERVER_BASE_URL=https://course-server.example.com
pnpm build
pnpm start -p 3102

ops 还需主 Agent、单课件生成、TTS 和媒体 provider，以及可持久化的 classroom、 job、framework 数据卷。

server

OPENMAIC_DEPLOYMENT_ROLE=server
NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE=server
COURSEWARE_PUBLISH_TOKEN=<same-server-only-secret>
COURSEWARE_PUBLIC_BASE_URL=https://learn.example.com
COURSEWARE_DATA_DIR=/srv/openmaic/coursewares
COURSEWARE_BUNDLE_DIR=/srv/openmaic/courseware-bundles
COURSE_MANIFEST_DIR=/srv/openmaic/course-manifests
pnpm build
pnpm start -p 3103

跨进程大课发布契约

ops 在本地 persisted classroom 上执行完整冻结和二次快照校验，然后向固定路径 POST /api/internal/course-publish 发送一个 multipart 请求：metadata JSON 加全部模块 ZIP。 该路由只在 server/all 角色开放，即使 server 环境意外带有 ACCESS_CODE，也只认 COURSEWARE_PUBLISH_TOKEN Bearer，不认 ops cookie。

server 在一个 course 单进程互斥边界内：

  1. 对全部 incoming ZIP 运行与单课件发布相同的完整门禁；幂等命中前还会读取 exact 已存 ZIP，复核存在、内部 id/version/hash、重算 hash 与 complete；缺失或篡改会发布新版本， 不会返回伪成功；
  2. 调用原 publishCourseware 逐模块分配/重写版本并以 unpublished 暂存；
  3. 全部通过后切换 published，再调用原 publishCourse 写 schema-v2 manifest；
  4. 大课 courseware record 私有携带 courseId/moduleIndex；公共 catalog、detail、download 只有在任一已提交 schema-v2 manifest 包含 exact id/version/hash pin 时才可见，因此 promote 到 manifest 提交之间以及失败补偿期间均返回 404/不进入列表；
  5. 任一失败将本批状态补偿回 unpublished；
  6. ops 只在回执的 module id/version/hash 与本地 ZIP 逐项一致后写入 publication receipt； receipt 还保存每模块的 sourceRevisionHash。查询状态会重读完整 classroom 并比较该哈希；任意源修改或模块重生都使 receipt 失效。

contentHash v2 明确忽略 manifest.json 的 exportedAt。相同 metadata + 课堂内容的 远程超时重试、重复点击，以及同源共享文件 fallback 都幂等返回既有 manifest。无 contentHashVersion 的历史包仍使用 v1 原始字节哈希；learner 的旧内部 version 兼容只对能通过精确 registry 与重算 v1 hash 的真正旧包生效。若要 强制产生新版本，必须先改变课程内容，当前契约没有 forceNewVersion 开关。

安全约束：目的地由 server-only COURSE_PUBLISH_SERVER_BASE_URL 固定，不接受浏览器输入； URL 禁止凭据/path/query/fragment，fetch 禁止 redirect；非 loopback HTTP 默认拒绝。server 在 formData 缓冲前对实际 stream 封顶，且解析后再校验每个 File.size。公开 bundleUrl 仅由 COURSEWARE_PUBLIC_BASE_URL 派生，不使用内网 request Host。失败响应稳定包含 errorCode、phase（request/ staging/commit/rollback）、可选 moduleIndex 和 details。

未配置 COURSE_PUBLISH_SERVER_BASE_URL 时，当前单仓运行仍使用同源共享文件库，但复用同一 批量事务/幂等/visibility helper；该 fallback 是迁移兼容，不是多实例事务。

5. 文件仓库为何只能单实例

当前正确性依赖以下进程内状态：

  • courseware publishLocks；
  • CourseRecord courseLocks；
  • CourseManifest manifestLocks；
  • 大课 runningRuns、AbortController 和当前 classroom job 集合；
  • 版本号先读历史、再加一、再写回的 read-modify-write。

文件层虽使用原子 rename，bundle 使用 link 实现 create-if-absent，但 Map mutex 只在单进程内 有效。两个容器可能同时读到相同 nextVersion，或覆盖彼此刚写的 JSON history。 当前“事务”是失败后把本批记录补偿回 unpublished，不具有数据库事务的跨进程隔离性、 原子提交或崩溃一致性。

当前生产约束：

  1. courseware、manifest、framework 的写入实例都保持 1；
  2. 不用多副本共享 NFS 来伪装数据库事务；
  3. 发布和生成期间避免滚动重启；
  4. 备份整个版本历史 JSON 与 bundle 目录，并保持二者一致；
  5. classroom/course runner 重启后需要通过记录自愈，再由运营点击继续/重试。

这些限制意味着：只要计划公网生产上线或多副本扩容，下述 Postgres 事务、 唯一约束与私有对象存储就是硬前置，不是可选性能优化。

未来多实例的最低实现：

  • Postgres 表为 courseware_versions 和 course_manifest_versions 建唯一键；
  • 在同一事务内锁定 course/courseware、分配 next version、写 metadata 与状态；
  • bundle 写对象存储，key 包含 id/version/hash，使用 put-if-absent；对象在 manifest commit 前必须保持私有，CDN/签名 URL 也必须执行等价的 exact-pin visibility gate；
  • manifest 只在全部对象与 metadata 可读后提交；
  • 下载 URL 指向对象存储/CDN；
  • 生成任务进入持久队列，worker 使用租约/幂等键；
  • 失败补偿只改变本批 staged 记录，不覆盖历史已发布版本。

6. legacy manifest 重发操作

识别方式：

  • GET /api/learn/courses/{id} 返回 409；
  • 错误为 legacy course manifest must be republished；
  • 文件可能是旧 singleton，也可能已经进入 history envelope，但记录本身没有 schemaVersion=2 或模块缺 version/hash。

安全重发流程：

  1. 保留旧 manifest 文件并备份，不直接编辑旧版本。
  2. 在 ops 打开对应 CourseRecord，确认 framework 和模块 classroom 仍存在。
  3. 运行发布校验；如提示 MODULE_OUTPUT_UNVERIFIED、CONTINUITY_UNVERIFIED、 CONTINUITY_STALE、INTERACTIVE_HTML_MISSING 或缺音频/媒体，从最早失败模块开始 按顺序重生成。
  4. 人工审阅修复后的模块，再由 ops 执行“发布课程”。
  5. 新发布会生成下一 manifest 版本，schemaVersion=2，每模块固定 coursewareId + coursewareVersion + contentHash。
  6. 用精确 manifest version 访问 learner 页进行 smoke。
  7. 旧无 pin 版本保留审计，但继续拒绝 learner；不要把当前 latest 手工写成旧历史 pin。

若原 CourseRecord/classroom 已丢失，不能伪造历史身份。应按新课程重新生成、审阅、发布。

7. 机械拆分顺序与每步门槛

Step 0：冻结基线

  • 固定 bundle format、manifest schema v2、CourseRecord compat 和 protected core 清单；
  • 保存当前针对性测试结果；
  • 不在拆分 PR 中改变 Chat、Stage、Scene、Action、PBL 或白板语义。

回滚门槛：任何 learner bundle 无法进入原 Stage，立即停止拆分。

Step 1：共享契约

  • 移动 bundle types/hash/serialize、course manifest types、API DTO；
  • 把环境读取留在应用 adapter，纯契约包不读取 process.env；
  • ops、server、learner 同时消费同一版本，禁止复制类型。

回滚门槛：同一 fixture 的 contentHash 或 imported document 发生变化。

Step 2：先拆 server

  • 搬 app/api/coursewares/、app/api/learn/courses/、 lib/courseware-repo、lib/course-manifest-repo 和 bundle byte store；
  • 新增只接受 server token 的 course manifest 提交接口；
  • 现有 ops 先通过 HTTP adapter 调新 server，保留同源 adapter 作为短期回滚；
  • reader 先迁、writer 后迁，确认旧 manifest 409 策略一致。

回滚门槛：精确 version/hash 查询、不可变下载头或发布门禁不一致。

Step 3：先完成 DB/对象存储，再扩 server

  • 文件 repo 双写只用于迁移核对，不作为长期架构；
  • 对比记录数、版本历史、hash 与对象字节；
  • 切读后保留文件只读备份，确认稳定再停双写；
  • 未完成事务和唯一键前保持单实例。

Step 4：再拆 learner desktop

  • 整体搬 app/page、generation-preview、tasks、learn、classroom 和其依赖；
  • 原 Stage 与 protected core 作为一个共享包/工作区依赖整体复用，不 fork；
  • 只替换 API base URL、鉴权 adapter 与文件路径；
  • 保留首页普通后台与材料/Interactive/职教前台双路径。

回滚门槛：出现第二套助教、发布课堂带 outlines、或 learner 不再进入原 Stage。

Step 5：最后拆 ops

  • 搬 courses UI、course-framework、publish-validation、module-digest 和发布发起端；
  • classroom 生成/审阅仍使用同一单课件 agent 与 protected core；
  • 浏览器只持 ACCESS_CODE 会话，不持 server token；
  • 完成 ops → server 的 bundle 与 manifest transport。

Step 6：收口

  • 删除 all 的生产支持和同源 repo 直写；
  • 给每个 app 配置显式 route allowlist、独立构建和最小 provider key；
  • 做一次 legacy 重发、并发发布、失败回滚和旧 manifest 固定版本演练。

8. 验收命令

在 /Users/inmanw/项目/麦洛学习/OpenMAIC 执行。

类型与格式

pnpm exec tsc --noEmit
pnpm exec prettier ../docs/architecture-3-tier.md ../docs/deployment-3-tier.md ../docs/large-course-mode.md ../docs/handover.md --check

三端、大课、冻结发布定向回归

pnpm exec vitest run \
  tests/config/deployment-role.test.ts \
  tests/server/ops-access.test.ts \
  tests/generation/foreground-session.test.ts \
  tests/server/classroom-outline-mode.test.ts \
  tests/server/classroom-generation-retry.test.ts \
  tests/course-framework \
  tests/bundle \
  tests/courseware

learner/ops 浏览器边界

pnpm exec playwright test \
  e2e/tests/home-to-generation.spec.ts \
  e2e/tests/deployment-role-boundary.spec.ts \
  --project=chromium

Playwright 默认 webServer 已显式固定 learner 角色。若本机已有 3002 端口的旧 dev server， 先确认它的角色，避免 reuseExistingServer 让边界测试误连 all/ops。

构建

pnpm build

读路径压测

node scripts/load-test-reads.mjs +      --base http://localhost:3103 +      --courseware <published-id> +      --concurrency 20 +      --requests 400

9. 已知受保护 Chat 基线漂移

隔离诊断命令：

pnpm exec vitest run \
  tests/lib/chat/pi/director-tool-wiring.test.ts \
  tests/lib/chat/pi/route-cue-user.test.ts \
  tests/lib/chat/pi/prompts.test.ts

当前结果为 3 files 中 40 passed / 3 failed；失败正好是：

  • prompts：keeps concept and mechanism questions teacher-led before student reactions
  • route-cue-user：hands successful web evidence to one child and clears it before later delegations
  • route-cue-user：does not leak consumed web evidence after the selected child fails

它们属于既有 protected Chat director 的 prompt/evidence 断言漂移，本次三端改造未触及 lib/chat/** 或 /api/chat/pi。验收报告应原样记录这 3 项；不要在本改造中修改 Chat 内核或放宽测试来掩盖它们。