chore: 项目环境升级为 JDK25，Spring 4.1，项目重构为多模块

2026-09-08 15:02:18 +08:00
parent d392436620
commit 81a0d81f11
168 changed files with 2785 additions and 1375 deletions
--- a/README.md
+++ b/README.md
@@ -4,21 +4,53 @@

 ## 技术栈

- Spring Boot 3.5.16、JDK 21、AgentScope Java 2.0.1、AG-UI
+- Spring Boot 4.1.1、JDK 25、AgentScope Java 2.0.1、AG-UI
+- MyBatis-Flex 1.11.8（Boot 4 starter）、业务与 HTTP 使用 Jackson 3；AgentScope 内部保留 Jackson 2
 - Vue 3.5、Vite、Element Plus、Vue Element Plus X
 - PostgreSQL 17、Flyway

 ## 本地启动

+需要 JDK 25、Maven、Node.js 22 和 Docker。先设置 `JAVA_HOME` 指向 JDK 25；IDEA 从
+`server/pom.xml` 导入 Maven reactor，项目 SDK 与 Maven runner 均选 JDK 25，运行
+`manuagent-web` 的 `ManuAgentApplication`，工作目录设为仓库根目录。
+IDEA 运行配置同时设置 `APP_DATA_ROOT` 为既有数据目录的绝对路径，以及
+`APP_DASHSCOPE_KEY_FILE` 为知识库密钥文件的绝对路径，与下面的命令行启动配置保持一致。
+
+后端通过 `SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_USERNAME`、`SPRING_DATASOURCE_PASSWORD`
+连接可用的 PostgreSQL 17。根 Compose 的数据库端口只供容器内部使用；宿主机开发需使用已发布
+端口的本地数据库，或在本地 Compose override 中增加 PostgreSQL 端口映射。
+
 ```bash
-docker build -t smart-factory-agent-runtime:0.1.0 -f sandbox/Dockerfile sandbox
-docker compose up -d postgres
-mvn -q -f server/pom.xml spring-boot:run
-npm --prefix web-ui install
+docker build -t agent-sandbox:0.1 -f sandbox/Dockerfile sandbox
+mvn -f server/pom.xml clean package
+export APP_DATA_ROOT="$PWD/data"
+export APP_DASHSCOPE_KEY_FILE="$PWD/dashscope_key.txt"
+java -jar server/manuagent-web/target/manuagent-web.jar
+# 在另一个终端启动前端；依赖只从 workspace 根目录安装。
+npm --prefix web-ui ci
 npm --prefix web-ui run dev
 ```

-本地开发服务器默认使用 Vite 配置的端口。容器化部署固定从 <http://127.0.0.1:5173> 访问。
+本地开发入口为 <http://127.0.0.1:15173>，代理后端 8080。唯一可执行产物是
+`server/manuagent-web/target/manuagent-web.jar`。上述命令从仓库根目录执行，将 `APP_DATA_ROOT` 设为
+根目录下 `data` 的绝对路径；已有数据时改为对应绝对路径，避免移动启动目录后找不到历史文件。
+容器化部署固定从 <http://127.0.0.1:5173> 访问。
+
+Agent 会话状态保存在 `APP_DATA_ROOT/agent-state`，与项目文件和沙箱快照一起持久化。
+启动时，会为数据目录内的已有项目从当前运行用户的 `~/.agentscope/state`（或 JVM `agentscope.state.home`
+指定目录）分别复制会话与沙箱状态，补齐此前只迁移会话的项目；保留旧目录，不覆盖已有新状态。
+跨机器或从旧容器升级时，须先将旧状态目录复制到新环境的对应位置，并保留快照原有绝对路径；
+仅保留项目文件不能恢复完整会话。旧进程停止后再迁移，避免继续写入旧位置。
+
+沙箱镜像统一为 `agent-sandbox:0.1`。升级前停止旧后端并确认旧沙箱容器已退出；历史会话恢复时
+会将旧 `smart-factory-agent-runtime` 镜像引用迁移到当前 `APP_SANDBOX_IMAGE` 配置，保留会话和快照。
+
+`APP_RUN_TIMEOUT` 限制整个 Run（含重连与结果修复）的总时长，默认 60 分钟；结构化结果最多修复
+3 次。`APP_MAX_CONCURRENT_RUNS` 限制单个后端同时运行的任务数，默认 2，新增任务满额时返回 429。
+同项目的模型切换、停止后继续及阶段接续共用原运行名额，等待旧任务释放资源、保存快照后再启动。
+修改沙箱文件后须重建 `sandbox/Dockerfile` 镜像；其中 `docx-example.cjs` 提供与已安装依赖
+一致的表格、原生批注示例及可执行验证。

 模型连接只能在“模型配置”页面新增并持久化到 PostgreSQL；API Key 会使用 `APP_MASTER_KEY`
 环境变量提供的主密钥加密后保存。`dashscope_key.txt` 仅供百炼知识库使用，不参与模型配置。
@@ -31,23 +63,23 @@ $env:APP_MASTER_KEY = '<使用独立生成的高强度密钥>'

 ## Docker Compose 部署

-部署包含 Nginx 前端、Spring Boot 后端、Agent Runtime 镜像和 PostgreSQL。Agent Runtime
-不是常驻 API 服务：镜像在开发机预先构建并导入服务器，服务器上的 `agent-runtime` 服务只校验
+部署包含 Nginx 前端、Spring Boot 后端、沙箱镜像和 PostgreSQL。沙箱
+不是常驻 API 服务：镜像在开发机预先构建并导入服务器，服务器上的 `sandbox` 服务只校验
 镜像存在，随后以状态码 0 退出；后端再通过 Docker Socket 为每个 Agent Session 动态创建隔离容器。

-1. 在开发机构建并导出 Agent Runtime 镜像：
+1. 在开发机构建并导出沙箱镜像：

   ```bash
-   docker build -t smart-factory-agent-runtime:0.1.0 -f sandbox/Dockerfile sandbox
-   docker save -o smart-factory-agent-runtime-0.1.0.tar smart-factory-agent-runtime:0.1.0
+   docker build -t agent-sandbox:0.1 -f sandbox/Dockerfile sandbox
+   docker save -o agent-sandbox-0.1.tar agent-sandbox:0.1
   ```

   将 Tar 文件传到服务器后导入。Compose 设置了 `pull_policy: never`，若镜像不存在会直接报错，
   不会在服务器自动拉取或构建：

   ```bash
-   docker load -i smart-factory-agent-runtime-0.1.0.tar
-   docker image inspect smart-factory-agent-runtime:0.1.0
+   docker load -i agent-sandbox-0.1.tar
+   docker image inspect agent-sandbox:0.1
   ```

 2. 复制环境变量模板并替换其中的三个必填密码/密钥；生产环境建议使用密码管理系统生成随机值。
@@ -56,9 +88,9 @@ $env:APP_MASTER_KEY = '<使用独立生成的高强度密钥>'
   cp .env.example .env
   ```

-3. 确认 `MANUAGENT_DATA_ROOT` 是 Docker 宿主机上的绝对路径。这个路径会以完全相同的路径挂载到
-   后端容器，供动态 Agent Runtime 继续挂载项目材料、工作目录和产物。Linux 默认值为
-   `/srv/manuagent/data`。
+3. Compose 中的镜像、数据库名称、端口和数据目录均使用静态值；调整时直接修改根目录的 `docker-compose.yml`。
+   数据目录固定为 `/srv/manuagent/data`；修改时须同步更新后端的 `APP_DATA_ROOT` 和对应挂载的
+   `source`、`target`，保持容器内外使用同一个宿主机绝对路径，供动态沙箱挂载项目材料和产物。

 4. 构建前后端并启动完整服务：

@@ -67,7 +99,11 @@ $env:APP_MASTER_KEY = '<使用独立生成的高强度密钥>'
   docker compose -f docker-compose.yml ps
   ```

-5. 打开 <http://127.0.0.1:5173>，使用 `.env` 中的 `APP_ADMIN_USERNAME` 和
+   根目录的 `docker-compose.yml` 是唯一部署入口。后端镜像使用 Maven 3.9.13 / Temurin 25.0.2
+   构建和 Temurin 25.0.2 JRE 运行；前端镜像从
+   `web-ui/apps/web/dist` 复制静态文件。
+
+5. 打开 <http://127.0.0.1:5173>，使用 Compose 中的管理员账号 `admin` 和 `.env` 中的
   `APP_ADMIN_PASSWORD` 登录。查看日志或停止服务：

   ```bash
@@ -75,22 +111,42 @@ $env:APP_MASTER_KEY = '<使用独立生成的高强度密钥>'
   docker compose -f docker-compose.yml down
   ```

-默认端口映射为 `0.0.0.0:5173:80`。若 Windows 的动态端口排除范围占用了 5173，可仅在本机
-验证时临时执行 `$env:FRONTEND_PORT = '15173'`；Linux 服务器部署应保留默认的 5173。
+端口映射为 `0.0.0.0:5173:80`。若 Windows 的动态端口排除范围占用了 5173，可在本机验证时
+将 Compose 的端口映射临时改为 `0.0.0.0:15173:80`；Linux 服务器部署应保留 5173。

 PostgreSQL 数据保存在 `postgres-data` 命名卷中；项目材料、Agent 工作区、快照和生成文件保存在
-`MANUAGENT_DATA_ROOT`。`docker compose down` 不会删除它们，只有显式增加 `--volumes` 才会删除
+Compose 配置的数据目录。`docker compose down` 不会删除它们，只有显式增加 `--volumes` 才会删除
 PostgreSQL 卷。后端挂载 Docker Socket 等价于授予其管理宿主机容器的高权限，应只在受信任的
 Docker 主机上运行，并限制 5173 端口的网络访问范围。通过 HTTPS 反向代理部署时，请将
-`SESSION_COOKIE_SECURE` 设为 `true`。
+Compose 中的 `SERVER_SERVLET_SESSION_COOKIE_SECURE` 设为字符串 `"true"`。

 ## 验证

 ```bash
-mvn -q -f server/pom.xml test
-npm --prefix web-ui run test
+mvn -f server/pom.xml verify
+npm --prefix web-ui test
 npm --prefix web-ui run build
 docker compose -f docker-compose.yml config --quiet
 ```

-产品、数据库与验收设计见 [docs](docs/)。内置 Skill 与资源由 Flyway 种子迁移写入数据库，无需额外导入文件。
+以上命令分别验证后端测试/打包、前端测试、四个 workspace 的类型检查及单应用构建、Compose 配置。
+模块依赖边界仍需在代码审查中核对，当前没有自动边界检查命令。
+
+## 模块边界
+
+| 后端模块 | 前端 workspace | 职责 |
+| --- | --- | --- |
+| `manuagent-common` | `packages/common` | 错误、TypeHandler；前端共享请求、CSRF、基础样式 |
+| `manuagent-admin` | `packages/admin` | 用户服务与用户持久化；登录页面 |
+| `manuagent-agent` | `packages/agent` | 项目、文件、模型、Skill、Agent 执行、规划与产物；业务页面和侧栏 |
+| `manuagent-web` | `apps/web` | HTTP、认证上下文、基础设施装配与启动；单应用壳和路由 |
+
+Agent 和 Admin 只依赖 Common，Web 装配三者。仍是一个后端进程、一个数据源和一个事务体系。
+Controller 从登录身份解析用户 UUID，业务服务负责事务及审计字段。`AdminProperties` 和
+`AgentProperties` 继续绑定原有 `app.*` 键，数据库配置和环境变量名保持兼容。
+
+历史 Flyway 文件保留在 `server/src/main/resources/db/migration`，由 Web 原样打包一份；
+请勿迁移、重命名或改写这些已共享脚本。Agent 的 Mapper XML 和提示词随普通库 JAR 加载。
+前端只有根目录一份 `package-lock.json`，业务包通过 `@manuagent/*` 的公开 exports 引用。
+
+本次改造的证据与验收边界见 [MANU-1 实现与验收](docs/MANU-1-implementation.md)。内置 Skill 与资源由 Flyway 种子迁移写入数据库，无需额外导入文件。