启动、停止与首次演示

两个入口，两个生命周期

交付物	工作目录	启动命令	入口
文档网站	压缩包根目录	npm ci && npm run dev	终端显示的VitePress地址
教材系统	system/	docker compose up --build -d	http://localhost:8000

文档网站可单独构建发布；教材系统的模型密钥只能放在system/.env，不能写入文档环境或前端脚本。

环境要求

Docker Engine/Desktop与Compose v2；建议4核CPU、8GB内存、10GB可用磁盘。CPU即可运行流程和FFmpeg；默认真实模式调用外部API，不在本地下载LLM。目标平台为Linux amd64/arm64以及macOS Docker Desktop。当前交付环境的Docker不可用，因此未执行容器构建和双架构启动，见验收记录。

第一次需要联网拉取镜像、安装依赖；准备完成后demo模式不需要API密钥和外部模型服务。它不是离线依赖包，不包含Docker镜像和node_modules。

首次运行

cd system
cp .env.example .env
docker compose up --build -d
docker compose ps
docker compose logs init
docker compose logs -f api worker

init等数据库健康后执行版本化SQL和LangGraph表初始化，再导入示例资料与地区规则。资料seed可重复执行，不会重复导入相同有效资料。API绑定宿主机127.0.0.1；数据库不映射宿主端口。

打开 http://localhost:8000。默认主题为“校园生活”，等级A1、语言英文、地区SA，选择“答案错误→自动修订”。观察：第一次评审指出c1-practice答案错误，第二版只修改答案，然后进入human。点击人工通过，等待媒体任务完成，下载ZIP。

演示图片有DEMO标识，音频为3秒静音；视频含图片、静音和可选择字幕轨。字幕是均匀分配时段，并非真实语音对齐。播放器需要手动打开字幕。

API与自动冒烟

curl http://localhost:8000/health
curl -X POST http://localhost:8000/api/jobs \
  -H 'Content-Type: application/json' \
  --data-binary @samples/task.json
docker compose exec api python scripts/smoke.py

冒烟脚本通过HTTP创建任务、观察状态、在无阻断问题时通过审核、下载交付物到/data/smoke-delivery.zip。真实模式会产生真实模型与素材调用费用；有未解决问题时脚本停止，不自动强制通过。

docker compose cp api:/data/smoke-delivery.zip ./smoke-delivery.zip

测试与评测

为避免worker和测试进程争抢测试任务，运行测试时先停止worker。测试夹具会创建独立随机数据库，结束时删除该测试数据库；不清空业务数据库。

docker compose stop worker
docker compose --profile test run --rm tests
docker compose exec api python scripts/evaluate.py --output /data/evaluation.json
docker compose cp api:/data/evaluation.json ./evaluation.json
docker compose start worker

测试依赖本地数据库、FFmpeg；不需要真实API密钥。真实适配器契约测试使用MockTransport，不代表供应商线上可用。评测默认使用演示模式；真实环境下会实际调用服务，且需要重新解读指标。

停止、更新、备份

docker compose stop
# 更新源码后：
docker compose up --build -d
# 仅移除容器，保留持久化卷：
docker compose down

postgres卷保存业务与checkpoint；media卷保存文件与回执。日常不要使用down -v，它会删除数据。备份应同时包含数据库和媒体卷，并实际演练恢复，单独备份ZIP不等于完整业务备份。

开发时可用锁文件安装Python依赖直接运行，但Docker是交付的主要运行方式。需要离线部署时，在可联网机器预先构建和导出镜像，并记录平台与镜像摘要。