Wujies 无界平台
开始使用

环境要求

这一页回答一个问题：在动手之前，机器上该有什么、路径该是什么。

它只列可以核对的既有事实，每条都给出源码或配置文件的位置；凡是我没有实际跑过验证的， 都会写明「未验证」。把它过一遍，15 分钟跑起来 里的命令才有可能一次跑通。

这一页不解释"应用是什么"

名词定义见 核心概念；这套结构为什么长这样见 这个项目是什么。

一、先认清三个目录

后面所有路径都建立在这三行上：

目录是什么构建方式
wujies-platform/后端宿主、平台初始化 SQL、部署物料Maven（Java 17）
plus-ui/宿主前端npm
wujies/wujies-plugins/插件本体 + 插件前端工程Maven + pnpm workspace

三者没有共同的 git 根，各自分支、各自提交。改一个功能经常要两边都动。

三个 wujies-admin 不是一个东西

这个名字在三处含义不同，历史上已经误导过两次排查。判据很简单：看有没有 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 的，都是后端。

二、工具链

项要求依据
JDK17 或更高根 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.js20 或更高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
先 mvn install 平台，插件才编译得动

插件对平台构件（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 Boot3.5.15
MyBatis-Plus3.5.16
Sa-Token1.45.0
Redisson3.52.0
dynamic-datasource4.3.1
SnailJob1.10.0
warm-flow（工作流）1.8.5
springdoc2.8.17
FastExcel1.3.0
Hutool5.8.43

Web 容器是 Undertow：wujies-common-web/pom.xml 排除了 spring-boot-starter-tomcat， 改引 spring-boot-starter-undertow。

宿主前端（plus-ui/）关键版本

依赖版本
Vue3.5.13
Vite6.3.2
Vue Router4.5.0
Pinia3.0.2
Element Plus^2.11.8
TypeScript~5.8.3
UnoCSS66.5.2
Vitest3.1.2

目标浏览器见 plus-ui/package.json 的 browserslist：Chrome ≥ 87 / Edge ≥ 88 / Safari ≥ 14 / Firefox ≥ 78。

三、中间件

中间件要求依据
MySQL8.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
只想开发一个插件时，不必装 MySQL / Redis

插件仓里有一个 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: falseapplication-dev.yml
17888SnailJob 调度中心服务端端口application-dev.yml 的 snail-job.server.port
2${server.port} → 28086SnailJob 客户端端口，随主端口漂移application-dev.yml 的 snail-job.port
3306 / 6379 / 5672MySQL / 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。

容器里的后端端口是 8080，不是 8086

wujies-platform/wujies-admin/Dockerfile 与 deploy/dist/1panel/docker/backend/Dockerfile 都写 ENV SERVER_PORT=8080，1Panel 的 compose 也用 8080。本地的 8086 只来自 application.yml。

五、工作目录

后端进程的工作目录必须是 wujies-platform/

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 与前端 dev server 认的目录是两个位置
  • 后端落位到 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 读同一位置。

⚠️ 当前这两个路径是否已经用软链或环境变量对齐，我没有验证（未验证）。 遇到"菜单打不开"时，先按上面两处路径各看一眼。

script/prune/start-host.ps1 的工程根推断已知错位

该脚本第 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.sqlplatform_init.sql平台自身的 25 张表 + 平台数据（地区、字典、参数、菜单、角色授权、租户、默认账号）所有部署
②02-app-market.sqlupdate/ 下的 7 个脚本按固定顺序拼接应用市场自己的表与列（app_info / app_version / app_install / app_schema_history …）所有部署
③03-app-catalog.sqlapp_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）。

script/sql/ 里另外两个目录不要执行
  • backup/*.sql —— 线上库的全库快照，是 deploy/tools/ 下几个生成器的输入物，不是种子数据；
  • archive-upstream/update_*.sql —— 上游的版本升级脚本，仅存档；执行它们只会把结构改回上游的样子。

判断方法很简单：全新部署不需要它们，存量部署按需执行。 完整说明见 wujies-platform/script/sql/README.md。

不要用上游的 ry_vue_5.X.sql 初始化

该文件已从仓库删除。它是上游产品的种子数据，不是本仓库的库结构： 缺 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。
1Panel 安装包里签名校验的默认值是 warn

application.yml 里当前是 mode: enforce；但首次安装还没有配公钥，而没配公钥时 enforce 会拒绝所有包 （包括你自己签的）。所以 1Panel 应用清单把 SECURITY_MODE 的默认值设成 warn，配好公钥后再改 （见 deploy/dist/1panel/apps/wujies-platform-server/5.6.3/）。 三种模式的差别见 安全校验模式。

相关阅读

核心概念

上一页

项目结构

下一页

目录

一、先认清三个目录二、工具链关键依赖版本（来自 wujies-platform/pom.xml）宿主前端（plus-ui/）关键版本三、中间件四、端口五、工作目录六、数据库初始化七、默认账号与凭据相关阅读