环境要求
本文是 1.x 的归档文档（冻结于 1.x）。该分支只接收勘误修正， 内容基本不再变动；文中的源码路径、配置项与版本号均以 1.x 为准，不建议用于新项目。
新项目请查看 5.x 最新文档。已在 1.x 上运行的项目，本文仍是可靠依据。
这一页回答一个问题：在动手之前，机器上该有什么、路径该是什么。
它只列可以核对的既有事实，每条都给出源码或配置文件的位置；凡是我没有实际跑过验证的， 都会写明「未验证」。把它过一遍，15 分钟跑起来 里的命令才有可能一次跑通。
一、先认清三个目录
后面所有路径都建立在这三行上：
| 目录 | 是什么 | 构建方式 |
|---|---|---|
wujies-platform/ | 后端宿主、平台初始化 SQL、部署物料 | Maven（Java 17） |
plus-ui/ | 宿主前端 | npm |
wujies/wujies-plugins/ | 插件本体 + 插件前端工程 | Maven + pnpm workspace |
三者没有共同的 git 根，各自分支、各自提交。改一个功能经常要两边都动。
这个名字在三处含义不同，历史上已经误导过两次排查。判据很简单：看有没有 pom.xml。
| 写法 | 实际指 | 判据 |
|---|---|---|
wujies-platform/wujies-admin/ | 后端启动模块 | 有 pom.xml、src/main；产物是 wujies-admin.jar |
工作区顶层的 wujies-admin/ | 前端产物的落位目录 | 里面只有 app-market-dist/，没有 package.json、没有 src/ |
plus-ui/ | 宿主前端仓库 | 有 vite.config.ts、src/；它的 package.json 里 name 恰好就是 wujies-admin |
所以：凡是指向 src/views/**、src/plugins/**、app-market-dist/** 的，都是前端 = plus-ui/；
凡是指向 src/main/resources/**、wujies-admin.jar、-pl wujies-admin 的，都是后端。
二、工具链
| 项 | 要求 | 依据 |
|---|---|---|
| JDK | 17 或更高 | 根 wujies-platform/pom.xml 的 <java.version>17</java.version> 被 maven-compiler-plugin 用作 <release>；插件仓 wujies-plugins/pom.xml 同为 17；部署镜像也是 JDK 17 |
| Maven | 本机安装（版本下限仓库未约束，未验证） | 仓库里没有 Maven Wrapper（.mvn/、mvnw、mvnw.cmd 都不存在，已核对）。wujies-platform/AGENTS.md §0 给的是"本机没加 PATH 时"的两行写法 |
| Node.js | 20 或更高 | wujies/wujies-plugins/package.json 的 engines.node = >=20；plus-ui/package.json 是 >=18.18.0 —— 取更严的那个 |
| pnpm | 与 wujies-plugins/package.json 的 packageManager 一致（当前 pnpm@10.32.1） | 插件仓是 pnpm workspace（pnpm-workspace.yaml 只收 frontend/*-app） |
| npm | 用于 plus-ui/（该仓库走 package-lock.json，不是 pnpm） | plus-ui/package.json 的 engines.npm = >=8.9.0 |
插件对平台构件（cn.wujies:*:${platform.version}）的依赖全是 provided —— 运行期由宿主提供，
但编译期仍要能解析到。所以第一次上手必须先在平台仓装一遍：
mvn -B install -DskipTests # 工作目录：wujies-platform/wujies-plugins/pom.xml 的 <platform.version> 当前是 5.6.2，与平台根 pom 的 <revision> 一致；
平台升版时改的就是这一行。
关键依赖版本（来自 wujies-platform/pom.xml）
| 依赖 | 版本 |
|---|---|
| Spring Boot | 3.5.15 |
| MyBatis-Plus | 3.5.16 |
| Sa-Token | 1.45.0 |
| Redisson | 3.52.0 |
| dynamic-datasource | 4.3.1 |
| SnailJob | 1.10.0 |
| warm-flow（工作流） | 1.8.5 |
| springdoc | 2.8.17 |
| FastExcel | 1.3.0 |
| Hutool | 5.8.43 |
Web 容器是 Undertow：wujies-common-web/pom.xml 排除了 spring-boot-starter-tomcat，
改引 spring-boot-starter-undertow。
宿主前端（plus-ui/）关键版本
| 依赖 | 版本 |
|---|---|
| Vue | 3.5.13 |
| Vite | 6.3.2 |
| Vue Router | 4.5.0 |
| Pinia | 3.0.2 |
| Element Plus | ^2.11.8 |
| TypeScript | ~5.8.3 |
| UnoCSS | 66.5.2 |
| Vitest | 3.1.2 |
目标浏览器见 plus-ui/package.json 的 browserslist：Chrome ≥ 87 / Edge ≥ 88 / Safari ≥ 14 / Firefox ≥ 78。
三、中间件
| 中间件 | 要求 | 依据 |
|---|---|---|
| MySQL | 8.0 以上；不支持 MariaDB | 平台初始化 SQL 通篇 utf8mb4_0900_ai_ci，MariaDB 没有这个排序规则（见 wujies-platform/docs/1panel/1Panel部署与上架.md）。驱动是 com.mysql.cj.jdbc.Driver；只装了 mysql-connector-j，其它数据库的驱动在 wujies-admin/pom.xml 里是注释掉的 |
| Redis | 客户端是 Redisson 3.52.0；最低版本仓库未约束（未验证） | application-dev.yml 的 spring.data.redis 段 |
| RabbitMQ | 平台消息 / 延时队列用到 | application-dev.yml 的 spring.rabbitmq 段。哪些功能强依赖它，我没有逐个验证（未验证） |
| SnailJob 调度中心 | 可选。它是一个独立服务 + 自己的库 | 表与账号在 wujies-platform/script/sql/ry_job.sql；宿主侧开关是 snail-job.enabled |
插件仓里有一个 sandbox 模块（wujies-plugins/pom.xml 的 <module>sandbox</module>，
注释写明"开发工具，不进任何应用包"）：它用 H2 内存库替代 MySQL，不装配 Redis / RabbitMQ，
端口 18080（sandbox/src/main/resources/application.yml）。
用法见 本地联调；沙箱的具体行为我没有实测（未验证）。
四、端口
| 端口 | 用途 | 出处 |
|---|---|---|
| 8086 | 后端宿主（server.port，context-path 为 /） | wujies-admin/src/main/resources/application.yml |
| 80 | 宿主前端 dev server（VITE_APP_PORT） | plus-ui/.env.development，由 plus-ui/vite.config.ts 读取 |
| 9090 | 监控中心（spring.boot.admin.client.url）；dev profile 里 enabled: false | application-dev.yml |
| 17888 | SnailJob 调度中心服务端端口 | application-dev.yml 的 snail-job.server.port |
2${server.port} → 28086 | SnailJob 客户端端口，随主端口漂移 | application-dev.yml 的 snail-job.port |
| 3306 / 6379 / 5672 | MySQL / Redis / RabbitMQ 默认端口 | application-dev.yml 各段 |
前端 dev 代理把 /dev-api（VITE_APP_BASE_API）转到 http://127.0.0.1:8086 并去掉前缀，
见 plus-ui/vite.config.ts 的 server.proxy。
wujies-platform/wujies-admin/Dockerfile 与 deploy/dist/1panel/docker/backend/Dockerfile 都写
ENV SERVER_PORT=8080，1Panel 的 compose 也用 8080。本地的 8086 只来自 application.yml。
五、工作目录
app-market.deploy 下两个路径都是相对路径
（wujies-platform/wujies-admin/src/main/resources/application.yml）：
plugin-dir: plugins-dist
frontend-dir: ../wujies-admin/app-market-dist/remote-apps在别的目录启动，插件 jar 与远程应用前端产物就会落到错误的位置 —— 表现是"安装成功了、功能却打不开"。两条硬约束：
plugin-dir必须与启动参数-Dloader.path一致，而且loader.path只加载该目录根下的 jar，不递归子目录（迁移脚本放在migrations/子目录里正是靠这一点）；frontend-dir指向的物理目录必须就是宿主提供/remote-apps/<appCode>/的那个目录。
- 后端落位到
frontend-dir，按上面的工作目录解析出来是工作区顶层的wujies-admin/app-market-dist/remote-apps/<appCode>/； - 宿主前端 dev server 从
plus-ui/app-market-dist/remote-apps/<appCode>/提供/remote-apps/**（plus-ui/vite/plugins/appMarketStatic.ts，sourceDir=<plus-ui 根>/app-market-dist）。
两者必须是同一份产物。对不上时的现象是菜单点开「远程视图不可用」，控制台报
Failed to fetch dynamically imported module: /remote-apps/<code>/index.js
（plus-ui/src/plugins/appmarket/loader.ts 里有同样的提示）。拼装方式是：
插件前端构建时用 WUJIES_FRONTEND_DIST 指到宿主的 app-market-dist/remote-apps
（wujies-plugins/frontend/build/vite.ts），插件仓的 package.ps1 用 -FrontendDist 读同一位置。
⚠️ 当前这两个路径是否已经用软链或环境变量对齐，我没有验证（未验证）。 遇到"菜单打不开"时，先按上面两处路径各看一眼。
该脚本第 60 行用 $root = Split-Path $PSScriptRoot -Parent 推工程根，而脚本本身在 script/prune/ 下 ——
按源码推断得到的是 wujies-platform/script，不是仓库根。这个问题已记在
工作区根的 docs/开发问题与解决方案.md §9「遗留清单」（该 docs/ 不在任何仓库里），状态是未改。
所以：不要无脑直接跑它，先自己在 wujies-platform/ 下开终端，或按
15 分钟跑起来 手工启动（注意 -Dloader.path=... 的引号不能省）。
六、数据库初始化
全新部署实际导入的是三份 SQL，顺序固定为 平台 → 应用市场 → 应用目录。
deploy/tools/build-1panel.ps1（$appMarketScripts 在 L129–137，组装在 L187 / L199 / L208）
把它们装成安装包 sql/files/ 下的三个文件，由后端容器首次启动时按文件名顺序导入：
| 顺序 | 包内文件 | 来源（都在 wujies-platform/script/sql/） | 作用 | 谁需要 |
|---|---|---|---|---|
| ① | 01-platform.sql | platform_init.sql | 平台自身的 25 张表 + 平台数据（地区、字典、参数、菜单、角色授权、租户、默认账号） | 所有部署 |
| ② | 02-app-market.sql | update/ 下的 7 个脚本按固定顺序拼接 | 应用市场自己的表与列（app_info / app_version / app_install / app_schema_history …） | 所有部署 |
| ③ | 03-app-catalog.sql | app_catalog_seed.sql | 应用目录种子（app_info / app_version / app_category） | 所有部署 |
第 ② 步那 7 个脚本的清单与顺序是固定的（不是"按文件名排序"）：
app_market.sql 应用市场核心表（app_info / app_version / app_install / app_schema_history …）
app_market_app_model.sql install_mode / audience 列
fix_app_version_unique_index.sql UNIQUE(app_id, version_active)
app_market_home_path.sql home_path 列
app_market_sync_icon.sql app_info.icon 跟随菜单表
app_market_schema_history_fix.sql 迁移账本唯一键 (app_code, script)
app_market_register_modules.sql 把平台自带模块登记成应用手工导库时按上表顺序执行；漏掉 ② 或 ③ 的现象是"后端起来了，市场是空的 / 装不上应用"。
script/sql/ry_job.sql 不在这三份里，只有装了 SnailJob 调度中心才需要 —— 它建的是调度中心自己的库
（sj_* 表 + 命名空间 / 组配置 / 控制台账号）。
字符集统一 utf8mb4_0900_ai_ci；开发配置里的库名是 wujies（见 application-dev.yml 的数据源 URL）。
backup/*.sql—— 线上库的全库快照，是deploy/tools/下几个生成器的输入物，不是种子数据；archive-upstream/update_*.sql—— 上游的版本升级脚本，仅存档；执行它们只会把结构改回上游的样子。
判断方法很简单：全新部署不需要它们，存量部署按需执行。
完整说明见 wujies-platform/script/sql/README.md。
该文件已从仓库删除。它是上游产品的种子数据，不是本仓库的库结构： 缺 82 行参数、31 个字典类型、几百行菜单与整份地区数据。 上游来源与本项目的差异见 这个项目是什么。
它们随应用包走：wujies/wujies-plugins/wujies-<app>/migrations/*.sql，安装 / 升级时自动执行。
不要手工导入 —— 平台是靠迁移脚本里的 CREATE TABLE 语句才知道"彻底删除"时该删哪些表的，
手工建的表平台不认，卸载时会留下孤儿。
⚠️ sys_config.platform.init.version 这一行不是 platform_init.sql 自带的：它由 1Panel 后端容器
首次导入后写入（wujies-platform/deploy/docker/backend/entrypoint.sh）。
手工导入 SQL 时它不存在，别拿它当"初始化是否完整"的判据。
七、默认账号与凭据
| 项 | 值 |
|---|---|
| 租户 | 000000 |
| 账号 | admin |
| 密码 | admin123 |
| 登录页 | /login |
仓库里的配置文件带真实可通过的凭据与密钥，公开发布前全部替换：
application-dev.yml/application-prod.yml里的数据库、Redis、RabbitMQ 连接信息与密码 （RabbitMQ 的账号密码是写死在该文件里的）；application.yml的sa-token.jwt-secret-key，以及api-decrypt的公私钥对；application.yml的app-market.security.public-key—— 源码注释写明它是开发验证阶段生成的， 对外发布前重新生成一对并替换（见 密钥与签名）；plus-ui/.env.development/.env.production的接口地址（VITE_APP_BASE_API）， 以及VITE_APP_RSA_PUBLIC_KEY/VITE_APP_RSA_PRIVATE_KEY。
application.yml 里当前是 mode: enforce；但首次安装还没有配公钥，而没配公钥时 enforce 会拒绝所有包
（包括你自己签的）。所以 1Panel 应用清单把 SECURITY_MODE 的默认值设成 warn，配好公钥后再改
（见 deploy/dist/1panel/apps/wujies-platform-server/5.6.3/）。
三种模式的差别见 安全校验模式。