基础平台实际运行与验收指南¶
状态：2026-10-29 已在本机验证。Java/Maven 命名空间为 team.lab_edu，依据用户域名 lab-edu.team，见 ADR-004。本期实现鉴权、资源 × 操作授权、用户/角色/菜单管理；不包含实验业务。
1. 本地应用¶
- Prerequisites：Docker 引擎、Compose、Buildx；在
lab-edu/infra执行。常规 Docker CLI 使用下列命令，本机 Homebrew/Colima 的实际适配见第 5 节。 - Steps：
sh prepare-local-secrets.sh
docker compose -f compose.yaml -f compose.local.yaml -f compose.bootstrap.yaml config --quiet
docker compose -f compose.yaml -f compose.local.yaml -f compose.bootstrap.yaml up --build -d --wait
docker compose -f compose.yaml -f compose.local.yaml up -d --wait
docker compose -f compose.yaml -f compose.local.yaml ps
- Expected output：postgres/core/web/gateway 全部 healthy；访问
http://127.0.0.1:8088。首次访问可自助注册学生账户。初始化管理员为local-admin，初始密码来自本地infra/secrets/bootstrap_password，没有公开默认密码。该文件只记录初始化值，账户改密后不会自动更新它。 - Validation：正常模式 core 不再挂载 bootstrap_password；重复初始化不覆盖既有管理员。部署数据库不发布主机端口，应用和网关使用非 root、只读根与 tmpfs。
compose.local.yaml仅用于本机 HTTP，公网部署必须另行落实 TLS。
2. 独立验收栈¶
- Prerequisites：同一套镜像与受保护 secret；验收数据卷独立于第 1 节的本地应用。
- Steps：
LAB_EDU_HTTP_PORT=18088 docker compose -f compose.yaml -f compose.local.yaml -f compose.acceptance.yaml -f compose.acceptance-stack.yaml -f compose.bootstrap.yaml up --build -d --wait
LAB_EDU_HTTP_PORT=18088 docker compose -f compose.yaml -f compose.local.yaml -f compose.acceptance.yaml -f compose.acceptance-stack.yaml up -d --wait
- Expected output：验收入口
http://127.0.0.1:18088，独立数据库为lab_edu_acceptance/lab_edu_test，只向本机开放127.0.0.1:55432。额外测试桥接仅用于此栈，部署库仍保持内部网络。 - Validation：独立命名卷没有被替换或删除。Docker 此版本在仅内部网络上不会发布主机端口，acceptance-stack 专门补充测试桥接以支持宿主机 JVM 测试。
3. 后端完整验收¶
- Prerequisites：JDK 21、Maven 3.9.x、独立验收数据库；测试会重建测试夹具，必须先停止该验收栈的 core/web/gateway。不能对本地应用库或真实数据运行。
- Steps：从
lab-edu目录配置，随后进入 core：
export LAB_EDU_TEST_DATABASE_URL=jdbc:postgresql://127.0.0.1:55432/lab_edu_acceptance
export LAB_EDU_TEST_DATABASE_USER=lab_edu_test
export LAB_EDU_TEST_DATABASE_PASSWORD_FILE="$PWD/infra/secrets/database_password"
cd core
mvn clean verify
- Expected output：52 tests，failures/errors/skipped 均为 0；生成
target/lab-edu-core-0.1.0-SNAPSHOT.jar。 - Validation：数据库名保护、真实 PostgreSQL 事务与并发测试实际执行；没有用内存库或 skipTests 放行。测试完成后需要重新使用第 2 节 bootstrap overlay 初始化验收管理员，再移除该 overlay。原始验收证据见 core-verify-domain-20261029.json（本地资料，未发布）。
本机工具环境曾向 Java 注入 SOCKS 代理，直连数据库需对测试 JVM 清除这些属性。实际成功命令为 mvn -Dmaven.repo.local=/private/tmp/lab-edu-m2 '-DargLine=-DsocksProxyHost= -Dhttp.proxyHost= -Dhttps.proxyHost=' clean verify；其他环境不必添加。
4. 前端和真实浏览器¶
- Prerequisites：Node 24、npm、已初始化的第 2 节验收栈；不要把浏览器测试入口指向包含真实用户的应用。
- Steps：在
lab-edu/web：
npm ci --ignore-scripts
npm run lint
npm run typecheck
npm run build
PLAYWRIGHT_BROWSERS_PATH=/private/tmp/lab-edu-playwright npx playwright install chromium --only-shell
PLAYWRIGHT_BROWSERS_PATH=/private/tmp/lab-edu-playwright npm run test:acceptance
- Expected output：12 tests passed，单 worker、无自动重试、无跳过；使用真实 core/数据库，不使用兼容实验的固定 provider。
- Validation：注册/登录/刷新、双标签页和历史页退出、独立会话、网络故障、密码恢复和改密、操作级授权、25 条分页筛选、迟到响应隔离、角色变更和菜单恢复保护均实际执行。trace/录屏/自动截图关闭，避免把测试凭证写进常规交付证据。结果见 browser-verify-20261029.json（本地资料，未发布）。
测试默认管理员 local-admin，默认读取 ../infra/secrets/bootstrap_password；可用 LAB_EDU_E2E_BASE_URL、LAB_EDU_E2E_ADMIN_USERNAME、LAB_EDU_E2E_ADMIN_PASSWORD_FILE 显式覆盖，不把密码本身写进参数。
5. 本机 Colima 实际适配¶
本机专用 profile/context 为 lab-edu / colima-lab-edu，默认 context 未切换。Docker/Compose 在 Homebrew opt 目录。缺失的 Buildx v0.38.1 已由 Docker 官方 GitHub 资产 SHA-256 校验后隔离放在临时目录，没有写入用户 Docker 插件目录。
当前机器可用下列 shell 函数执行上文的 docker compose 参数：
lab_compose() {
env -u DOCKER_CONTEXT PATH=/opt/homebrew/opt/docker/bin:$PATH \
DOCKER_CONFIG=/private/tmp/lab-edu-docker-config \
DOCKER_HOST=unix:///Users/xv1r/.colima/lab-edu/docker.sock \
/opt/homebrew/opt/docker-compose/bin/docker-compose "$@"
}
lab_compose -f compose.yaml -f compose.local.yaml ps
临时目录被清理后，应安装常规 Buildx/Compose 或按记录的官方版本重新准备工具；产品没有依赖这些临时路径。Compose 的 build 和 up --build --wait 已用此入口实际通过。
6. 文档与契约¶
在 lab-edu：
python3 infra/scripts/validate-documentation.py
cd infra/tools
npm ci --ignore-scripts
npm run validate
预期：本地引用、表格、批准快照、63 项任务依赖、批准 ADR 与实施证据一致；OpenAPI 3.1 校验通过，19 paths / 23 operations / 26 schemas。工具代码与依赖位于 infra，不放进 docs。旧 draft 验证器的“全部未开始/Proposed”断言仅适用于初始设计快照，不再作为实施阶段入口。
7. 停止与交付边界¶
日常使用对应 Compose 文件执行 down，保留命名卷；不要添加 -v。secret 准备连续执行不会覆盖既有值，修改文件也不自动改变已初始化数据库的密码。
本地四服务运行和平台验收已经完成；新 GitLab 远端、CI、文档站及 Cloudflare 域名/TLS 发布仍是后续骨架交付，不能据此宣称整个 MVP 已公网部署。Boot BOM 内 Flyway 对 PostgreSQL 18.6 的上游已测试版本提示仍保留，迁移实际通过不等于上游正式兼容认证，详见后端场景映射（本地资料，未发布）。