docs/deploy/ 是仓库内唯一正式部署入口。

• oilan/、jm/、hdu/ 是 3 套环境
• ci/ 是共享构建链路，不代表单独环境
• 历史副本 docs/docs/deploy/ 不再使用

按环境进入对应入口。

bash docs/deploy/ci/build_images.sh
bash docs/deploy/oilan/deploy_cluster.sh

bash docs/deploy/ci/build_images.sh
bash docs/deploy/jm/deploy_cluster.sh

bash docs/deploy/ci/build_images.sh
bash docs/deploy/oilan/deploy_cluster.sh
bash docs/deploy/jm/deploy_cluster.sh

bash docs/deploy/hdu/deploy_cluster.sh

补充说明：

• docs/deploy/ci/build_images.sh 的镜像构建统一在远端 master-node 执行
• 若看到 /run/containerd/containerd.sock 或 buildkitd.sock 报错，优先排查 89 节点运行时，不要误判为本地容器环境问题
• deploy-full.sh 只是 Oilan + JM 的便捷包装，不覆盖 HDU
• HDU 部署需在 235 或已准备好对应 kube/helm 环境的机器上执行

如果只更新其中一个集群：

• 先确认镜像是否已经推到主 Harbor
• 然后只跑对应的 deploy_cluster.sh

主站发布从现在开始统一遵循下面这条规则：

• 禁止把 latest 当作正式发布版本
• 正式发布必须使用固定版本号，推荐格式：
  • YYYYMMDD-HHMMSS-<git短sha>
  • 例如：20260427-frontend-classroom-fixes
• Helm 发布必须通过 values.images.lock.json 指定镜像版本
• 运行态临时 kubectl set image 只能用于应急，事后必须回写到 Git 中的部署真相源

当前 Oilan 主站镜像版本真相源：

• docs/deploy/oilan/cd/zhiyong/values.images.lock.json
• docs/deploy/oilan/cd/zhiyong-tools/values.images.lock.json

标准口径：

1. 先执行 bash docs/deploy/ci/build_images.sh
2. 让构建脚本写入固定版本 tag / digest 到锁文件
3. 再执行 bash docs/deploy/oilan/deploy_cluster.sh

不要再使用“构建一个 latest，然后 rollout restart”这种流程判断是否发布成功。

所有部署脚本通过 docs/deploy/lib/resolve_doops.sh 自动定位 DOOPS 二进制，无需手动 export。

当前环境 DOOPS 实际路径：

<仓库根>/.local/bin/doops

脚本自动搜索顺序（找到即停止）：

1. $DOOPS 环境变量（已设置且可执行时直接用）
2. ~/.agent/skills/doops/doops-cli
3. ~/.local/bin/doops
4. <仓库根>/.local/bin/doops ← 当前环境实际路径
5. <仓库根>/zhiyong-lab-api/platform-tools/doops/skills/doops-cli/doops（需先编译）

如以上都找不到，脚本会报错并列出已尝试的路径。

• 主站 / Oilan：docs/deploy/oilan/deploy.md
• JM / 228：docs/deploy/jm/deploy.md
• HDU / 235：docs/deploy/hdu/deploy.md

目录	作用
docs/deploy/ci/	全局 CI，统一构建并推送主 Harbor
docs/deploy/oilan/	Oilan 集群发布入口
docs/deploy/jm/	JM 集群发布入口
docs/deploy/hdu/	HDU 环境发布入口
docs/deploy/*/cd/	各集群自己的 Helm 配置真相源
docs/deploy/scripts/	跨环境数据同步/运维辅助脚本，不是标准发版入口
docs/deploy/lib/resolve_doops.sh	统一解析可执行 DOOPS 路径（各脚本 source）

• Oilan、JM、HDU 是 3 套独立环境
• Oilan 与 JM 共享 docs/deploy/ci/ 的构建产物
• HDU 有自己的集群内部署链路与运行时配置
• 三边数据库、中间件、Ingress、Node 标签配置不能混用

• 远端直接执行 Helm
• 不再保留本机 helm template + kubectl apply fallback
• 业务代码目录不再保留部署环境配置副本，部署配置统一在 docs/deploy/{oilan,jm,hdu}/cd/
• 正式发布必须通过锁文件固定镜像版本，不能依赖 values.yaml 里的 imageTag: latest

• zhiyong-manager-api 的标准构建口径是：通过 DOOPS 在远端构建机执行 Maven/镜像构建。
• 如果 manager-api 在本地、普通容器、临时 shell 或缺少私有仓库凭证的环境里 Maven 失败，不得直接得出“仓库本身不可构建”的结论。
• 涉及 WOPI / Collabora / 文档预览链路时，必须把 业务实现问题 和 构建链路问题 分开判断：
  • 先确认 manager-api 是否按 DOOPS 远端标准链路成功构建并部署
  • 再判断是否属于 WOPI 后端实现、配置或运行时问题
• 禁止使用类似“manager-api 仓库本身不可构建，因为它不知道是在 doops 里编译”这类表述。
• 正确表述应类似：
  • “本地 Maven 失败不代表 manager-api 仓库不可构建；标准口径应以 DOOPS 远端构建结果为准。”
  • “当前问题位于 WOPI/Collabora 运行链路，和 manager-api 是否能按标准链路构建是两个独立判断。”

• deploy/cd/... 只是历史兼容说法，当前一律以 docs/deploy/... 为准

2026-04 课堂管理修复上线时，除了常规镜像发布，还需要额外确认两件事：

1. 数据库迁移必须先执行

课堂设置、邀请码和成绩管理新增/依赖以下库变更，脚本位于：

zhiyong-manager-api/src/main/resources/sql/fix_classroom_p0_issues.sql

执行说明见：

docs/deploy/sql/CLASSROOM_FIX_MIGRATION.md

至少包含：

• teaching_classrooms.schedule_desc
• teaching_classrooms.current_task_id
• classroom_gradebook_manual_score 手工成绩覆盖表
• 相关唯一索引

如果不执行 SQL，以下功能不会真正落地：

• 班级设置中的“上课时间安排”保存
• 成绩管理中的手工录入 / 导入成绩

2. 前端构建口径

课堂修复对应前端以 zhiyong-frontend 为准，已验证命令：

cd zhiyong-frontend
npm run build:admin

当前会有若干 chunk size warning，但构建可成功完成。

3. manager-api 私有 Maven 依赖前置条件

zhiyong-manager-api 本地编译依赖私有仓库 maven.cnb.cool 的 cn.l8ai:l8ai-parent:4.0.0 及一组 l8ai-*starter。

已确认当前常见失败模式是：

• 401 Unauthorized
• invalid token or repo path

也就是 凭证 / 仓库路径不可用，不是业务代码编译错误。

在凭证恢复前，不要把 manager-api 的本地 Maven 失败误判为课堂修复回归。