文档站构建与发布

当前边界见 ADR-006：docs 仓库独立拥有主题、构建工具和 Pages CI；infra 仅负责部署编排。

独立构建

以下从 docs 仓库根目录执行，不需要检出 infra 或 web。

python3 -m venv /tmp/lab-edu-docs-venv
/tmp/lab-edu-docs-venv/bin/pip install --require-hashes -r tools/site/requirements.lock
/tmp/lab-edu-docs-venv/bin/python tools/site/build.py --source . --output /tmp/lab-edu-docs-public --bundle /tmp/lab-edu-docs.tar.gz
/tmp/lab-edu-docs-venv/bin/python -m unittest discover -s tools/site -p test_build.py
python3 -m http.server 8090 --bind 127.0.0.1 --directory /tmp/lab-edu-docs-public

输出末行 result 为 passed。预览 http://127.0.0.1:8090/；搜索“权限”应返回标题结果。构建输出必须位于来源目录之外。

Docker

独立 docs 仓库可运行 docker build -t lab-edu-docs:local .。多仓库部署从项目根运行 docker compose -f infra/compose.docs.yaml up --build -d --wait，访问 8089。Compose 以 docs 为构建上下文，镜像只读运行并不连接数据库。

Pages

根目录 .gitlab-ci.yml 安装本仓库 tools/site/requirements.lock 并运行本仓库构建器；MR 生成静态目录和发布包，main 额外执行 Pages 发布。不再配置 infra 构建器提交或跨仓库 token。CI_PAGES_URL 用于站点地址，可通过 LAB_EDU_DOCS_SITE_URL 覆盖。

静态发布清单仍排除 agents、references、证据与凭据。Python 边界检查独立运行；infra/scripts/check-docs-browser.cjs 是可选的跨仓库部署验收，依赖已有 web Playwright，不是 docs 构建前置条件。