开发环境启动

1. 启动本地 MySQL、Redis 和 Nacos，或使用后端仓库的 docker-compose-dev.yml。
2. 在根工程设置 Maven profile、Nacos 地址和数据库凭据。
3. 执行 mvn -pl muotai-ai/muotai-ai-biz -am package -DskipTests 验证 API/Biz 依赖顺序。
4. 按依赖顺序启动 Register、UPMS、Auth、领域服务和 Gateway。
5. 通过 /actuator/health、登录接口和一次最小 AI 请求验证链路。

开发 Compose 中部分 build context、镜像名和端口仍是历史值，不能直接推断源码启动参数；以模块 application.yml 和当前 Dockerfile 为准。

推荐启动顺序

先启动 MySQL、Redis、Nacos 和对象/向量存储，再启动 Auth、UPMS、DocSpace、AI 和其他业务服务，最后启动 Gateway。每个服务启动后先看 Nacos 注册和 /actuator/health，再执行登录、文件上传和最小聊天；不要在 Gateway 尚未更新路由时把 404 当作业务错误。

AI 本地验收

创建一个测试 Agent，绑定默认 CHAT 模型、一个 Dataset 和只读工具；创建 session 后测试普通 SSE、断线重连、RAG 引用、工具失败、暂停/恢复和 JSONL 重启恢复。需要 Sandbox 时同时检查 FileRoom ACL、相对路径和宿主/容器挂载。

源码默认 AI 端口是 6062，而镜像暴露 6060，这个差异在本地也会造成服务正常但网关 503；启动参数、Compose 映射和 Gateway route 必须显式统一。