- boot/ (Java/Maven, JNPF 7.0) — 移除旧的 boot/.git,源码直接纳入仓库
- web/ (Vue 3 + Vite + Ant Design Vue, pnpm)
- docs/, scard/, nax/
- refs/INDEX.md + refs/国标/(其余 refs/* 开源子仓库不纳入)
- 已忽略: connector_data/, jweb/, log/, web/{dist,node_modules,.pnpm}, boot/*/target/, .DS_Store, .idea, .vscode
1533 lines
87 KiB
Markdown
1533 lines
87 KiB
Markdown
# 按 JNPF 规范快速搭建后端框架(SSW 公司内部规范)· 增强版
|
||
|
||
> 适用版本:JNPF 7.0.0-RELEASE(Spring Boot 3.5.x,jakarta.*,Java 21 运行时 / 编译目标 17)
|
||
> 适用场景:在 JNPF 低代码平台之上,挂载**自有业务模块**,复用其登录/鉴权/ORM/响应体系,同时不污染 JNPF 自身包。
|
||
> 编写依据:本版基于原 `JNPF_BACKEND_GUIDE.md`,通过一个**仅依据原文档、从零搭建可编译可运行脚手架**(位于本仓库 `boot/` + `tss-web/`,`app_code=tss`)的实践,逐项核对并修正了原文档中所有会导致「编译失败 / 打包失败 / 启动即崩 / 静默失效」的问题。
|
||
> 状态:**已验证可落地(增强版修正项均已用真实构建复核)**
|
||
> 原文档 `JNPF_BACKEND_GUIDE.md` **保持不动**,本文件为修正后的新版本。
|
||
|
||
> **示例占位约定**:本文沿用原文档的 `sswflow` 作为 `app_code` 示例(保持可复用),实际落地时按规则替换:
|
||
> `sswflow → <你的 app_code>`、`Sswflow → <AppCode>`、`SswflowXxxService → <AppCode>XxxService`、`库 sswflow → <你的 app_code>`、`API /api/ssw/sswflow → /api/ssw/<你的 app_code>`。
|
||
> **关键:业务库名 == app_code**(双库架构下每个 app_code 独立库,`dynamic.datasource.<app_code>` 与 `@DS("<app_code>")` 同名)。
|
||
>
|
||
> 已落地验证:
|
||
> - `tss`(首版):脚手架见 `boot/` 与 `tss-web/`,可直接对照。
|
||
> - `tss2`(二次验证,本仓库 `tss2/`):**仅依据本指南、不参考任何其它脚手架、不启用容器**,从零落地第二个应用。后端 `mvn -o package -pl ssw-admin -am` 构建通过、前端 `npm run build` 通过、密码算法自检 PASS。证明本指南可复用;落地中暴露的缺口已在 **第十六节** 补齐。tss2 命名映射见 16.1。
|
||
|
||
---
|
||
|
||
## 〇、核心结论(先看这段)
|
||
|
||
1. **不要从零写框架**——直接复用 JNPF 的 `boot` 启动模块 + `jnpf-common-all` 依赖栈。你只需要写**业务包**。
|
||
2. **业务包三层结构**:`ssw-{app_code}-entity` / `-biz` / `-controller`,全部挂在 `ssw-{app_code}` 父 pom 下。
|
||
3. **API 前缀**:`/api/ssw/{app_code}/...`,与 JNPF 的 `/api/...` 并存不冲突。
|
||
4. **双库架构(必做)**:JNPF 系统表走 `master`(库 `j7`),你的业务表放独立业务库(库 `sswflow`),用 **`@DS("sswflow")`** 切换。JNPF 内置 `dynamic-datasource`,这是平台标准机制。
|
||
5. **鉴权完全复用 JNPF**:Sa-Token + `/api/oauth/Login`,前端只负责"加密密码 + 原样带 token"。
|
||
6. **两个必踩的碰撞坑**(不处理就启动即崩):Spring bean 名冲突、MyBatis type-alias 冲突。
|
||
7. **⚠️ 最易翻车的两类"静默/硬失败"已在本版订正**:
|
||
- `scanBasePackages` 必须写 Java 顶级包 **`jnpf`**(不是 Maven groupId `com.jnpf`),写错**无报错但鉴权/数据源全失效**(见 〇-A·A)。
|
||
- 打包后启动会 `NoClassDefFoundError: ThreadPoolExecutorUtil`——`META-INF/spring/...ApplicationContextInitializer` 被 repackage 提到 fat-jar 根目录后读不到,**必须代码注册 initializer**(见 〇-A·F、§12.1)。
|
||
8. **JNPF 源码只需本地 `~/.m2` 有 jar 即可**:私有仓库要鉴权,离线 `mvn` 拉不到 `jnpf-common-*` 的 jar。首次按「〇-B.1」clone 并 `mvn install` 进本地仓库;之后只要 `~/.m2` 里 `com/jnpf/**` 的 jar 还在(本机留存或拷自他人),直接编译业务模块即可。
|
||
|
||
---
|
||
|
||
## 〇-A、相对原版的修正清单(速览)
|
||
|
||
| 编号 | 原文档位置 | 原文档问题 | 本版修正 | 严重程度 |
|
||
|---|---|---|---|---|
|
||
| A | §〇-B.3(2)、§3.2、§14-2 | `scanBasePackages={"com.jnpf","ssw"}` | 改为 `{"jnpf","ssw"}`;明确 `com.jnpf` 只是 Maven **groupId**,Java 顶级包是 `jnpf` | 🔴 静默失效(无报错,鉴权/DS 全挂) |
|
||
| B | §4.1、§4.2、§9.3 | `extends EntityBase` | 改为 `extends SuperEntity<String>`(`EntityBase` 在 7.0.0 不存在) | 🔴 编译失败 |
|
||
| C | §3.2 | entity pom 裸写 `mybatis-plus-boot-starter` / `dynamic-datasource-spring-boot-starter` 且无 `<version>` | 删除这两个依赖(随 `jnpf-common-all` 传递引入);确需锁版本必须显式写 `<version>` | 🔴 `mvn validate` 失败(缺 version) |
|
||
| D | §3.2 | 未说明 lombok 需自行声明 | entity(及用 `@Data` 的模块)pom 显式加 `org.projectlombok:lombok`(scope=provided);父 pom 全局加一份 | 🔴 编译失败(找不到 `getXxx()`) |
|
||
| E | §〇-B.3 末、§12、§14 | `mvn package -DskipTests -pl ssw-admin -o` | 改为 `mvn -o package -DskipTests -pl ssw-admin -am`(`-am` 把业务模块纳入 reactor) | 🔴 打包失败(解析不到 `ssw-tss-controller`) |
|
||
| F | §〇-B.3(4)、§12.1 | `jnpf.SpringContext`(FQN 错);仅靠 `META-INF` 文件注册 | FQN 改为 `jnpf.util.context.SpringContext`;且**必须在 `SswAdminApplication.main()` 代码注册** initializer | 🔴 打包后启动 `NoClassDefFoundError` |
|
||
| G | §9.4 | `getDataSource()` 签名/返回值说明含糊 | 接口实为 `<T extends DataSourceUtil> T getDataSource()`,`init(String)` 返回 `DbLinkEntity`(其父类即 `DataSourceUtil`),原写法可编译,补澄清 | 🟡 澄清(原代码能编) |
|
||
| H | §8.2 | 旧版把内层写成 `MD5(密码)` 误判为 bug;后又把「原始明文」错当成唯一标准 | **最终定稿为双约定模型**:传输层内层 S 有两种——**官方默认** `S = md5(明文)`(96-hex,`d4958348…`),**旧变体** `S = 明文`(32-hex,`ea80d323…`);存储层随之 `md5(S + f_secretkey.toLowerCase())`。两条约定都合法但互不相通,关键看账号 `f_password` 用哪种。关键陷阱:`SecurityProperties` setter 内部自动 MD5 → 16 字符 key 实际变 32 字节 = AES-256。dacli `src/core/crypto.ts` 与 `tss2` 实测均为官方约定 | 🔴 算法级错误(选错约定即登录失败) |
|
||
| I | §12.2 | 只有片段 | 提供零依赖 `scripts/smoke.mjs`(自检+登录+业务接口,支持 `--base/--account/--password/--key/--appcode`) | 🟢 可验证性 |
|
||
| J | §〇-B.3、application.yml | 未要求 `allow-bean-definition-overriding` | `application.yml` 必须 `spring.main.allow-bean-definition-overriding: true`(JNPF 内部同名 bean) | 🔴 启动失败 |
|
||
| K | §12.1、application.yml | 未要求 `mvc.pathmatch` 策略 | `spring.mvc.pathmatch.matching-strategy: ant_path_matcher`(JNPF 用 ant 路径匹配) | 🔴 启动/路由异常 |
|
||
| L | §8.2-B | 未解释自建账号登录报 `400 账号权限不足` | 给出根因(超管旁路硬编码只认账号名 `admin`,非 admin 必须挂角色且角色有 `base_authorize`)+ 挂「管理员」角色 SQL + 登录错误码速查(LOG101/LOG004/LOG005/OA013) | 🔴 自建账号无法登录 |
|
||
| M | §16.6 | 未记录运行期实测坑 | 新增「运行期实测暴露的 5 个坑」:`SERVER__PORT` 端口漂移、容器名≠发布端口+Redis 未映射、`dynamic.datasource` 少一层、`base-path` 不可写、后台进程被 shell 回收 | 🟡 排障加速 |
|
||
| N | §16.8 | 未给造验证账号脚本 | 新增「造验证账号完整脚本」:`md5(明文+secretkey.toLowerCase())` 算 `f_password` + 复制 admin 行插 `base_user` + 插 `base_role_relation`(含 `ON CONFLICT` 处理) | 🟢 可复现 |
|
||
|
||
> 严重程度图例:🔴 阻断(编不过/起不来) 🟡 澄清 🟢 增强可验证性
|
||
|
||
---
|
||
|
||
## 〇-B、环境准备:获取官方源码 / 私服 / 数据库中间件 / admin 骨架
|
||
|
||
> 这一节是「前置的前置」——在写任何业务代码之前,先把**官方源码拿到、私服配通、数据库与 Redis 跑起来、boot 启动骨架复制好**。
|
||
> 参考:`~/Desktop/workspace/jnpf/init/start.md`、JNPF 官方 `jnpf-java-boot/README.md`。
|
||
|
||
### 〇-B.1 从官方仓库 git clone JNPF 7 后端源码
|
||
|
||
官方仓库托管在 **coding.jnpfsoft.com**,后端按模块拆分,**每个模块是独立 git 仓库**,统一挂在 `/v7.0/<module>` 路径下。
|
||
|
||
```
|
||
官方根域:https://coding.jnpfsoft.com/v7.0/<module>
|
||
登录账号:[email protected]
|
||
登录密码:jnpf@ssw
|
||
```
|
||
|
||
**后端核心模块清单(按 start.md):**
|
||
|
||
| 模块 | 说明 |
|
||
|---|---|
|
||
| `jnpf-java-boot` | **聚合工程**(含 `jnpf-admin` 子模块),编译入口 |
|
||
| `jnpf-common` | Java 基础依赖项目源码(被所有模块依赖) |
|
||
| `jnpf-java-ai-core` | AI 核心依赖源码 |
|
||
| `jnpf-file-core-starter` | 文件基础依赖 |
|
||
| `jnpf-workflow` / `jnpf-workflow-core` | Flowable 流程引擎 |
|
||
| `jnpf-bpmn` | BPMN 相关 |
|
||
| `jnpf-datareport` / `jnpf-java-datareport-univer(-core)` | 报表 |
|
||
| `jnpf-scheduletask` | 任务调度 |
|
||
| `jnpf-java-tenant` | 多租户(按合同交付) |
|
||
| `jnpf-database` | **数据库脚本仓库**(j7 / j7flow / j7xxl 初始化 SQL) |
|
||
| `jnpf-resources` | 静态资源(ip2region、模板等) |
|
||
|
||
> 你**只需要 clone `jnpf-java-boot` 一个仓库**——它是聚合工程,pull 下来后内部 `jnpf-admin` 子模块、以及它依赖的 `jnpf-common` 等兄弟模块,都要**各自 clone 到同级目录**才能 `mvn install`(聚合 pom 用相对路径引用兄弟模块)。
|
||
|
||
> **增量复用(核心:别每次全量 clone)**
|
||
>
|
||
> | 场景 | 做法 |
|
||
> |---|---|
|
||
> | **首次**拿到源码 | 按下面 `git clone` 把需要的模块拉到 `~/workspace/jnpf`(平级目录) |
|
||
> | 已 clone 过,要更新 | 进各模块目录 `git pull`(**不要重新 clone**) |
|
||
> | `~/.m2` 里 `com/jnpf/**` 的 jar 还在(同机留存或拷自他人) | **根本不需要源码**:直接 `mvn package` 你的业务模块即可;源码仅在你改了 JNPF 自身代码时才需重新 `mvn install` |
|
||
> | 只缺某几个模块 jar | `cd ~/workspace/jnpf/<module> && mvn install -DskipTests`(无需重装全部) |
|
||
>
|
||
> 一句话:**`git clone` 是一次性动作;`mvn install` 把 jar 沉淀到 `~/.m2` 之后,日常只跟自己的业务模块打交道。**
|
||
> 同机协作时,把 `~/.m2/repository/com/jnpf` 整体拷给对方,对方连 clone 都省了。
|
||
|
||
```bash
|
||
# 1) 建一个总目录,所有 JNPF 模块平铺其中(路径禁止含中文/空格/特殊字符,README 特别说明)
|
||
mkdir -p ~/workspace/jnpf && cd ~/workspace/jnpf
|
||
|
||
# 2) clone 聚合工程(仅【首次】需要;之后用 git pull 更新,见上表)
|
||
git clone https://coding.jnpfsoft.com/v7.0/jnpf-java-boot.git
|
||
|
||
# 3) clone 它依赖的兄弟模块(与 jnpf-java-boot 同级)
|
||
git clone https://coding.jnpfsoft.com/v7.0/jnpf-common.git
|
||
git clone https://coding.jnpfsoft.com/v7.0/jnpf-java-ai-core.git
|
||
git clone https://coding.jnpfsoft.com/v7.0/jnpf-file-core-starter.git
|
||
git clone https://coding.jnpfsoft.com/v7.0/jnpf-workflow.git
|
||
git clone https://coding.jnpfsoft.com/v7.0/jnpf-workflow-core.git
|
||
# ... 其余模块按需 clone(见上表)
|
||
|
||
# 4)(可选)数据库脚本与静态资源
|
||
git clone https://coding.jnpfsoft.com/v7.0/jnpf-database.git
|
||
git clone https://coding.jnpfsoft.com/v7.0/jnpf-resources.git
|
||
|
||
# 免去每次输密码:把凭据缓存到 ~/.git-credentials
|
||
git config --global credential.helper store
|
||
```
|
||
|
||
> **踩坑提示(来自 start.md)**:若某模块目录**缺失文件**,直接用上面的官方账号从对应仓库 `git clone` 补齐即可;官方包地址/账号密码齐全,缺的都能下到。
|
||
|
||
---
|
||
|
||
### 〇-B.2 配置 Maven settings.xml 引用官方私服
|
||
|
||
JNPF 的依赖(`jnpf-common-*`、`dynamic-datasource` 等定制版)**不在 Maven Central**,只在官方私服 `maven-releases`。不配私服会 `Could not resolve ... 401/404`,离线环境更是直接编不过。
|
||
|
||
> 7.0 的 `jnpf-dependencies` 内部仓库声明用的是 `http://nexus.jnpfsoft.com/repository/maven-public/`,而官方 README 文档写的是 `https://repository.jnpfsoft.com/repository/maven-public/`。**两者 server id 都是 `maven-releases`**,所以只要下面 settings.xml 里 `<server>` 的 id 配成 `maven-releases`,就能同时覆盖这两种地址。
|
||
|
||
**放在哪**:用户级 `~/.m2/settings.xml`(推荐),或 Maven 安装目录 `conf/settings.xml`。在对应节点里加入:
|
||
|
||
```xml
|
||
<!-- 1) <servers> 里加:私服账号密码(id 必须叫 maven-releases) -->
|
||
<server>
|
||
<id>maven-releases</id>
|
||
<username>[email protected]</username>
|
||
<password>ssw222666</password>
|
||
</server>
|
||
|
||
<!-- 2) <mirrors> 里加:把所有下载请求镜像到官方私服(README 官方写法) -->
|
||
<mirror>
|
||
<id>maven-releases</id>
|
||
<mirrorOf>*</mirrorOf>
|
||
<name>maven-releases</name>
|
||
<url>https://repository.jnpfsoft.com/repository/maven-public/</url>
|
||
</mirror>
|
||
```
|
||
|
||
> 配好后 `mvn` 就能从官方私服拉依赖。IDEA 若出现部分依赖报红,重启 IDEA 清缓存即可(README 原话)。
|
||
> 注意 `~/.m2/settings.xml` 默认是 Maven 的**示例模板**,本身没有任何 `<server>`,初次使用时务必补上上面的内容。
|
||
|
||
---
|
||
|
||
### 〇-B.3 复制 jnpf-java-boot/jnpf-admin → boot/ssw-admin(有部分需要调整)
|
||
|
||
`jnpf-admin` 是聚合工程 `jnpf-java-boot` 下的**可运行 jar 模块**——它自己不编 JNPF 各 controller 源码,只 `pom` 依赖 `jnpf-*-controller` 等 jar(这些 jar 来自 〇-B.1 的 `mvn install`)。我们要做的,就是把它**整体复制成自己的 `ssw-admin` 启动骨架**,再改少量配置。
|
||
|
||
**源 → 目标:**
|
||
|
||
```
|
||
jnpf-java-boot/jnpf-admin/ ──复制──▶ boot/ssw-admin/
|
||
├── pom.xml
|
||
├── src/main/java/jnpf/ ──包名 jnpf → ssw──▶ src/main/java/ssw/
|
||
└── src/main/resources/ ──整目录拷──▶ src/main/resources/
|
||
├── application.yml / application-dev.yml
|
||
├── application-{dev,test,prod,preview}.yml
|
||
├── mapper/ i18n/ logback-spring.xml ip2region/ sharding-sphere.yml
|
||
├── static/ (no-spa 静态页,用 Vite 独立前端可删)
|
||
└── META-INF/spring/... (若已有 initializer 文件,保留)
|
||
```
|
||
|
||
**必须调整的部分(否则编不过或跑不起来):**
|
||
|
||
1. **`pom.xml` 父子关系**
|
||
- `<parent>` 从 `jnpf-java-boot` 改成你自己的聚合父 `ssw-boot`(或直连 `jnpf-common`)。
|
||
- `<artifactId>` 改成 `ssw-admin`。
|
||
- `<dependencies>` 保留 JNPF 各 `*-controller`(完整清单见 §3.2 末的 `ssw-admin/pom.xml` 示例);**新增你自己的业务 controller**,例如:
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.jnpf</groupId>
|
||
<artifactId>ssw-sswflow-controller</artifactId>
|
||
<version>${project.version}</version>
|
||
</dependency>
|
||
```
|
||
> 注意 `<groupId>com.jnpf</groupId>` 这里是对的——它是 Maven **坐标的 groupId**;只有 Java 源码包名才是 `jnpf`(见第 2 点)。
|
||
- `<profiles>` 里的 `boot3`(`jdk[17,)` 激活 `jnpf-ai-v3-controller`)**原样保留**——它正是 Boot 3 下启用 AI controller 的关键。
|
||
|
||
2. **包名 `jnpf` → `ssw`**
|
||
- `src/main/java/jnpf/` 整个包重命名为 `ssw/`,启动类 `JnpfAdminApplication` → `SswAdminApplication`。
|
||
- ⚠️ **【修正 A】`scanBasePackages` 必须写 Java 顶级包 `jnpf`,不能写 groupId `com.jnpf`**:
|
||
```java
|
||
@SpringBootApplication(scanBasePackages = {"jnpf", "ssw"})
|
||
```
|
||
写成 `{"com.jnpf","ssw"}` 会导致 JNPF 的自动配置(Sa-Token、dynamic-datasource、MyBatis 等)**全部不生效**,且**启动时不报任何错**,表现为登录 404 / 注入失败,极难排查。`com.jnpf` 只是 `pom.xml` 的 `<groupId>` 与依赖坐标前缀,与 Java 包名无关。
|
||
- 同时 `@MapperScan` 要覆盖两侧:`@MapperScan({"jnpf.**.mapper", "ssw.**.mapper"})`。
|
||
|
||
3. **白名单 / AuthFilter**
|
||
- 用独立 Vite 前端时,`gateway.exclude-url` 保留 JNPF 默认即可(无需 `/ssw/**`)。
|
||
- 若仍塞 no-spa 静态页,需加 `- /ssw/**`(见第 8.4 节)。
|
||
|
||
4. **Boot 3 两个补丁(否则登录时 `NoClassDefFoundError: ThreadPoolExecutorUtil`)**
|
||
- 提供 `applicationTaskExecutor` bean(JNPF 的 `ThreadPoolExecutorUtil` 静态块依赖它)。示例见 `ssw/config/TaskExecutorConfig.java`。
|
||
- **【修正 F,关键】注册 `SpringContext` initializer 有两条路径,缺一条都会炸:**
|
||
- (a) 文件 `src/main/resources/META-INF/spring/org.springframework.context.ApplicationContextInitializer`,内容一行:
|
||
```
|
||
jnpf.util.context.SpringContext
|
||
```
|
||
(原文档写的 `jnpf.SpringContext` 是**错的**,全限定名是 `jnpf.util.context.SpringContext`。)
|
||
- (b) **并且**在 `SswAdminApplication.main()` 里**代码注册**(这才是打包后可靠的方式):
|
||
```java
|
||
SpringApplication application = new SpringApplication(SswAdminApplication.class);
|
||
application.addInitializers(new jnpf.util.context.SpringContext());
|
||
application.run(args);
|
||
```
|
||
- **为什么必须代码注册**:`spring-boot-maven-plugin` 在 `repackage` 时会把 `target/classes/META-INF/` 提升到 **fat-jar 根目录**,而 Boot 3 的 `LaunchedClassLoader` 只加载 `BOOT-INF/classes` 与 `BOOT-INF/lib/*.jar`——根目录的 `META-INF/spring` 不在 classpath 上。于是**打成 jar 后该文件读不到**,启动表现为 `NoClassDefFoundError: Could not initialize class jnpf.util.ThreadPoolExecutorUtil`。代码注册不受打包结构影响,是最可靠的路径;文件 (a) 作为 IDE 直跑时的双保险保留。
|
||
|
||
5. **`application-dev.yml` 数据源与 Redis**
|
||
- `spring.datasource.db-name: j7`(master 系统库),`host/port/username/password` 指向你的 PG。
|
||
- `spring.redis.redisson.config` 的 `address` 指向你的 Redis 实例,`password` 与 Redis 实际密码对齐(JNPF 默认 `123456`,纯镜像无密码时要二选一对齐,见 §11)。
|
||
- `dynamic.datasource.sswflow` 业务库节点按第 9.2 节声明。
|
||
|
||
6. **可选清理**
|
||
- 用 Vite 独立前端可删除 `src/main/resources/static/ssw/**`(不影响启动)。
|
||
- 不用的 JNPF 模块依赖可在 `pom` 里裁剪,但建议先全留、跑通后再减。
|
||
|
||
> **【修正 E】复制完成后构建命令**:
|
||
> ```bash
|
||
> cd boot && mvn -o package -DskipTests -pl ssw-admin -am
|
||
> ```
|
||
> 必须带 **`-am`(also-make)**——否则 reactor 里没有 `ssw-tss-*` 业务模块,会报
|
||
> `Could not resolve com.jnpf:ssw-tss-controller:... has not been downloaded`。
|
||
> 成功产物:`ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar`。
|
||
|
||
---
|
||
|
||
### 〇-B.4 安装 j7 数据库与 Redis(镜像方式,最快)
|
||
|
||
为了快速起环境,直接用阿里云个人版容器镜像仓库的现成镜像(PostgreSQL 16 + Redis),免去了手动装数据库。
|
||
|
||
**镜像地址:**
|
||
|
||
```
|
||
PostgreSQL:crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine
|
||
Redis: crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/redis:latest
|
||
```
|
||
|
||
```bash
|
||
# 1) 拉取镜像
|
||
docker pull crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine
|
||
docker pull crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/redis:latest
|
||
|
||
# 2) 起 PostgreSQL(用户名/密码/默认库 与 JNPF 约定一致:dacli / dacli123 / j7)
|
||
docker run -d --name jnpf-postgres -p 15432:5432 \
|
||
-e POSTGRES_USER=dacli -e POSTGRES_PASSWORD=dacli123 -e POSTGRES_DB=j7 \
|
||
crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine
|
||
|
||
# 3) 起 Redis(JNPF 默认 redisson 密码 123456;纯镜像无密码,这里用无密码启动,
|
||
# 然后把 application-dev.yml 的 redisson password 清空对齐;或加 --requirepass 123456)
|
||
docker run -d --name jnpf-redis -p 6379:6379 \
|
||
crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/redis:latest
|
||
|
||
# 4) 验证
|
||
docker ps | grep -E "jnpf-postgres|jnpf-redis"
|
||
```
|
||
|
||
**初始化 j7 主库(来自官方 `jnpf-database` 仓库):**
|
||
|
||
> **不必 clone 整个 `jnpf-database` 仓库**(体积大,平时只盯 SQL)。只需拿到下面 3 个 `.sql` 即可——用 `git sparse-checkout` 只拉 SQL 所在的目录,或直接从仓库下载对应文件:
|
||
> ```bash
|
||
> # 只取 SQL,不拉全量仓库(--sparse 后按需 set 目录)
|
||
> git clone --filter=blob:none --sparse https://coding.jnpfsoft.com/v7.0/jnpf-database.git
|
||
> cd jnpf-database && git sparse-checkout set <jnpf_db_init / jnpf_flow_init / jnpf_xxljob_init 所在目录>
|
||
> ```
|
||
> 若同机 `~/.m2` 已沉淀 JNPF 源码,`jnpf-database/` 通常已在 `~/workspace/jnpf/` 下,直接复用即可。
|
||
|
||
> start.md 明确:**只需装** 以下三个;`JNPF-PostgreSQL.sql` 是**租户初始库,不要装**。
|
||
|
||
| 脚本 | 导入目标库 |
|
||
|---|---|
|
||
| `jnpf_db_init` | `j7`(JNPF 主库,承载 `base_user`/组织/权限/字典) |
|
||
| `jnpf_flow_init` | `j7flow`(Flowable 流程引擎库) |
|
||
| `jnpf_xxljob_init` | `j7xxl`(XXL-JOB 调度库) |
|
||
|
||
```bash
|
||
# 进入 PG 容器用 psql 导入(脚本从 jnpf-database 仓库取得)
|
||
docker exec -i jnpf-postgres psql -U dacli -d j7 < /path/to/jnpf-database/jnpf_db_init.sql
|
||
docker exec -i jnpf-postgres psql -U dacli -d j7flow < /path/to/jnpf-database/jnpf_flow_init.sql
|
||
docker exec -i jnpf-postgres psql -U dacli -d j7xxl < /path/to/jnpf-database/jnpf_xxljob_init.sql
|
||
|
||
# 另建业务库 sswflow 并执行你的建表脚本(见第 9 / 11 节)
|
||
docker exec -i jnpf-postgres psql -U dacli -d postgres -c "CREATE DATABASE sswflow;"
|
||
docker exec -i jnpf-postgres psql -U dacli -d sswflow < /path/to/sswflow/boot/db/V1.0.0__schema.sql
|
||
```
|
||
|
||
**网络与访问(重要):**
|
||
- 容器内互相用容器名 `jnpf-postgres` / `jnpf-redis` 解析;宿主机若用 `.orb.local` 或容器 IP,启动 jar 时用 `-DDB_HOST=... -DREDIS_HOST=...` 覆盖(详见第 11 节 Netty DNS 注意)。
|
||
- 若宿主机直接用容器 IP(如 OrbStack 下 `192.168.97.3:5432` / `192.168.97.2:6379`),把 `application-dev.yml` 的 host 改成 IP 最稳。
|
||
|
||
---
|
||
|
||
## 一、整体工程结构
|
||
|
||
```
|
||
boot/ # 启动模块(拷贝 JNPF 的 boot 骨架)
|
||
├── pom.xml # 父:ssw-boot → jnpf-common → jnpf-dependencies
|
||
├── ssw-{app_code}/ # 你的业务父模块
|
||
│ ├── pom.xml # 聚合 entity/biz/controller
|
||
│ ├── ssw-{app_code}-entity/ # 实体 + MyBatis XML
|
||
│ ├── ssw-{app_code}-biz/ # Service 接口 + Impl + Mapper(含 @DS)
|
||
│ └── ssw-{app_code}-controller/ # Controller(REST 入口)
|
||
└── ssw-admin/ # 可运行 jar 聚合模块(打最终 boot jar)
|
||
└── src/main/resources/ # application.yml / application-dev.yml / static
|
||
```
|
||
|
||
> 命名约定:`{app_code}` 用小写驼峰,例如 `sswflow`。**所有包名、bean 名、alias 都要带 `Sswflow`/`sswflow` 前缀**,这是避免与 JNPF 内部类冲突的唯一手段(详见第八节)。
|
||
|
||
---
|
||
|
||
## 二、前置:编译 JNPF 源码(一次性,约 7 分钟)
|
||
|
||
JNPF 的 `jnpf-common-all` 等构件不在公网 Maven 仓库,私有仓库需鉴权,离线构建会失败。
|
||
|
||
```bash
|
||
# 1. 取得官方源码(git clone 步骤见「〇-B.1」;私服配置见「〇-B.2」)
|
||
# 至少 clone 聚合工程 jnpf-java-boot 及其依赖的兄弟模块(jnpf-common 等)到同级目录
|
||
cd /path/to/jnpf-java-boot
|
||
|
||
# 2. 一次性编译安装到本地仓库(跳过测试/文档/gpg,否则很慢)
|
||
mvn clean install -DskipTests -Dmaven.javadoc.skip=true -Dgpg.skip=true
|
||
```
|
||
|
||
完成后 `~/.m2/repository/com/jnpf/**` 会出现 `jnpf-common-all`、`jnpf-common-core`、`jnpf-oauth-*` 等全部 jar,你的业务模块才能编译。
|
||
|
||
> 验证:`ls ~/.m2/repository/com/jnpf/jnpf-common-all/7.0.0-RELEASE/` 应有 jar。
|
||
|
||
---
|
||
|
||
## 三、Maven 关键配置
|
||
|
||
### 3.1 boot3 profile 会锁死 Java 版本
|
||
|
||
`jnpf-dependencies` 的 `boot3` profile 把 `maven.compiler.source` 锁成 **8**(为了 JNPF 自有模块向后兼容)。你的新代码要用 Java 17 语法(switch 表达式、instanceof 模式匹配等),**必须在你的业务模块 pom 里覆盖**——最省事是在聚合父 `ssw-boot/pom.xml` 的 `<properties>` 统一设:
|
||
|
||
```xml
|
||
<!-- ssw-boot/pom.xml 的 properties(父链:ssw-boot → jnpf-common → jnpf-dependencies) -->
|
||
<properties>
|
||
<maven.compiler.source>17</maven.compiler.source>
|
||
<maven.compiler.target>17</maven.compiler.target>
|
||
<java.version>17</java.version>
|
||
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
|
||
<!-- JNPF 平台构件统一版本 -->
|
||
<jnpf.version>7.0.0-RELEASE</jnpf.version>
|
||
<!-- 本工程 app_code,贯穿包名/bean名/API前缀/业务库名 -->
|
||
<ssw.app-code>sswflow</ssw.app-code>
|
||
</properties>
|
||
```
|
||
|
||
不覆盖会报:`-source 8 中不支持 switch 表达式` / `instanceof 模式匹配`。
|
||
|
||
### 3.2 业务包父链与依赖
|
||
|
||
```
|
||
你的 ssw-admin(打 jar)
|
||
└─ 依赖 ssw-{app_code}-controller
|
||
└─ 依赖 ssw-{app_code}-biz
|
||
└─ 依赖 ssw-{app_code}-entity
|
||
└─ 依赖 jnpf-common-all(提供 SuperEntity / ActionResult / @DS / Sa-Token 等)
|
||
```
|
||
|
||
> **【修正 C/D】`ssw-{app_code}-entity/pom.xml` 关键依赖(正确写法):**
|
||
>
|
||
> ```xml
|
||
> <dependencies>
|
||
> <!--
|
||
> jnpf-common-all 提供:
|
||
> jnpf.base.entity.SuperEntity / SuperBaseEntity(公共字段,已映射 f_xxx 列)
|
||
> jnpf.base.ActionResult / jnpf.base.vo.PageListVO
|
||
> jnpf.base.service.SuperServiceImpl / jnpf.base.mapper.SuperMapper
|
||
> Sa-Token、dynamic-datasource(@DS)等整套依赖
|
||
> -->
|
||
> <dependency>
|
||
> <groupId>com.jnpf</groupId>
|
||
> <artifactId>jnpf-common-all</artifactId>
|
||
> <version>${jnpf.version}</version>
|
||
> </dependency>
|
||
>
|
||
> <!--
|
||
> lombok:JNPF 侧是 provided scope,不会传递到你的模块。
|
||
> 业务实体若使用 @Data/@Getter 必须自行声明,否则编译报 "找不到符号 getXxx()"。
|
||
> 放在 entity 模块;若 biz/controller 也用 lombok,同样加。
|
||
> -->
|
||
> <dependency>
|
||
> <groupId>org.projectlombok</groupId>
|
||
> <artifactId>lombok</artifactId>
|
||
> <scope>provided</scope>
|
||
> </dependency>
|
||
>
|
||
> <!--
|
||
> ⚠️ 不要照搬"只写 groupId/artifactId 不写 version"的写法:
|
||
> jnpf-common 的 dependencyManagement 并未托管 mybatis-plus-boot-starter /
|
||
> dynamic-datasource-spring-boot-starter,缺 version 会直接构建失败:
|
||
> 'dependencies.dependency.version' for com.baomidou:... is missing
|
||
> 这两者已由 jnpf-common-all 传递引入(MyBatis-Plus 3.5.x + dynamic-datasource 4.x),
|
||
> 正常情况【无需声明】。若确需锁版本,必须显式写 <version>。
|
||
> -->
|
||
> </dependencies>
|
||
> ```
|
||
|
||
> 父 `ssw-boot/pom.xml` 也可以全局给一份 lombok(继承给所有子模块),与本模块声明二选一即可:
|
||
> ```xml
|
||
> <dependencies>
|
||
> <dependency>
|
||
> <groupId>org.projectlombok</groupId>
|
||
> <artifactId>lombok</artifactId>
|
||
> <scope>provided</scope>
|
||
> </dependency>
|
||
> </dependencies>
|
||
> ```
|
||
|
||
**`ssw-admin/pom.xml` 依赖 JNPF 各 controller(完整清单,缺一不可,否则登录/`/api` 能力缺失):**
|
||
|
||
```xml
|
||
<dependencies>
|
||
<!-- 自有业务模块 -->
|
||
<dependency>
|
||
<groupId>com.jnpf</groupId>
|
||
<artifactId>ssw-sswflow-controller</artifactId>
|
||
<version>${project.version}</version>
|
||
</dependency>
|
||
|
||
<!-- JNPF 平台 controller:登录 /api/oauth/Login 由 jnpf-oauth-controller 提供,必需 -->
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-oauth-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-permission-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-system-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-file-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-message-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-extend-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-flowable-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-scheduletask-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-base-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-generater-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-onlinedev-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdev-portal-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-visualdata-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
<dependency><groupId>com.jnpf</groupId><artifactId>jnpf-app-controller</artifactId><version>${jnpf.version}</version></dependency>
|
||
</dependencies>
|
||
|
||
<profiles>
|
||
<!-- boot3:JDK 17+ 启用 AI v3 controller,原样保留 -->
|
||
<profile>
|
||
<id>boot3</id>
|
||
<activation><jdk>[17,)</jdk></activation>
|
||
<dependencies>
|
||
<dependency>
|
||
<groupId>com.jnpf</groupId>
|
||
<artifactId>jnpf-ai-v3-controller</artifactId>
|
||
<version>${jnpf.version}</version>
|
||
</dependency>
|
||
</dependencies>
|
||
</profile>
|
||
</profiles>
|
||
|
||
<build>
|
||
<finalName>ssw-admin-${project.version}</finalName>
|
||
<plugins>
|
||
<plugin>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||
<configuration>
|
||
<mainClass>ssw.SswAdminApplication</mainClass>
|
||
<excludes>
|
||
<exclude>
|
||
<groupId>org.projectlombok</groupId>
|
||
<artifactId>lombok</artifactId>
|
||
</exclude>
|
||
</excludes>
|
||
</configuration>
|
||
<executions><execution><goals><goal>repackage</goal></goals></execution></executions>
|
||
</plugin>
|
||
</plugins>
|
||
</build>
|
||
```
|
||
|
||
---
|
||
|
||
## 四、实体层规范(entity)
|
||
|
||
### 4.1 字段命名:JNPF 风格 `f_xxx`
|
||
|
||
> **【修正 B】基类是 `jnpf.base.entity.SuperEntity<T>`(7.0.0 中 `EntityBase` 不存在)。**
|
||
> 继承后,以下 9 个公共字段与列映射**自动获得,不要在本类重复声明**,否则 MyBatis-Plus 会因重复列名报错:
|
||
>
|
||
> | Java 字段(父类) | 列名 | 说明 |
|
||
> |---|---|---|
|
||
> | `id` (SuperBaseEntity) | `f_id` | `@TableId`,UUID 字符串 |
|
||
> | `tenantId` | `f_tenant_id` | |
|
||
> | `creatorTime` | `f_creator_time` | 默认 `now()` |
|
||
> | `creatorUserId` | `f_creator_user_id` | |
|
||
> | `lastModifyTime` | `f_last_modify_time` | |
|
||
> | `lastModifyUserId` | `f_last_modify_user_id` | |
|
||
> | `deleteMark` | `f_delete_mark` | JNPF 约定 `null`=未删 |
|
||
> | `deleteTime` | `f_delete_time` | |
|
||
> | `deleteUserId` | `f_delete_user_id` | |
|
||
|
||
```java
|
||
@Data
|
||
@EqualsAndHashCode(callSuper = true)
|
||
@Alias("SswflowProjectEntity") // ⚠️ 必须,防 MyBatis alias 碰撞(见第八节)
|
||
@DS("sswflow") // ⚠️ 必须,切到业务库(见第九节)
|
||
@TableName("project")
|
||
public class ProjectEntity extends SuperEntity<String> {
|
||
// 业务字段(公共字段已在父类,无需也不应重复声明)
|
||
@TableField("name")
|
||
private String name;
|
||
@TableField("project_code")
|
||
private String projectCode;
|
||
@TableField("compute_mode") // MPC / TEE / FL
|
||
private String computeMode;
|
||
@TableField("status") // DRAFT / ONLINE ...
|
||
private String status;
|
||
}
|
||
```
|
||
|
||
### 4.2 公共字段基线(建议)
|
||
|
||
| 字段 | 列名 | 说明 |
|
||
|---|---|---|
|
||
| 主键 | `f_id` | `@TableId`,UUID 字符串(来自 `SuperBaseEntity`) |
|
||
| 创建时间 | `f_creator_time` | 默认 `now()` |
|
||
| 创建人 | `f_creator_user_id` | |
|
||
| 修改时间 | `f_last_modify_time` | |
|
||
| 修改人 | `f_last_modify_user_id` | |
|
||
| 删除标记 | `f_delete_mark` | JNPF 约定 `null` 表示未删除;查询条件 `f_delete_mark is null` |
|
||
| 租户 | `f_tenant_id` | |
|
||
| 删除时间 | `f_delete_time` | |
|
||
| 删除人 | `f_delete_user_id` | |
|
||
|
||
> 查询存活数据统一用常量,例如 `ALIVE = "f_delete_mark is null"`,默认排序 `f_creator_time desc`。
|
||
|
||
---
|
||
|
||
## 五、Service 层规范(biz)
|
||
|
||
```java
|
||
// 接口
|
||
public interface ProjectService extends IService<ProjectEntity> {
|
||
ActionResult<PageListVO> pageList(ProjectPageForm form);
|
||
void create(ProjectEntity e);
|
||
}
|
||
|
||
// 实现——⚠️ bean 名 + @DS 都必须显式指定
|
||
@Service("sswflowProjectService")
|
||
@DS("sswflow") // ⚠️ 切到业务库;注解不继承,子类必须各自打
|
||
public class ProjectServiceImpl extends SswflowServiceImpl<ProjectMapper, ProjectEntity>
|
||
implements ProjectService {
|
||
@Override
|
||
public ActionResult<PageListVO> pageList(ProjectPageForm form) {
|
||
// 用 MyBatis-Plus 分页;JNPF 分页包装见第六节
|
||
}
|
||
}
|
||
```
|
||
|
||
> **所有 `@Service` 实现类都加 `@Service("sswflow<Short>Service")` + `@DS("sswflow")`**:
|
||
> - bean 名防与 JNPF 内部 Service 碰撞(默认名会 `ConflictingBeanDefinitionException`);
|
||
> - `@DS` 把读写路由到业务库,否则会落到 `master`(j7) 系统库。
|
||
> 推荐所有业务 Service 继承 `SswflowServiceImpl`(见 9.4),统一获得 `@DS` 兜底与动态自愈能力。
|
||
|
||
---
|
||
|
||
## 六、Controller 层规范(controller)
|
||
|
||
```java
|
||
// ⚠️ 必须显式 bean 名,JNPF 自带 jnpf.flowable.controller.OperatorController 会撞名
|
||
@RestController("sswflowProjectController")
|
||
@RequestMapping("/api/ssw/sswflow/Project")
|
||
public class ProjectController {
|
||
|
||
@Autowired
|
||
private ProjectService projectService; // 按 bean 名注入上面那个
|
||
|
||
@GetMapping("/All")
|
||
public ActionResult<List<ProjectEntity>> all() {
|
||
return ActionResult.success(projectService.list());
|
||
}
|
||
|
||
@GetMapping
|
||
public ActionResult<PageListVO> list(@RequestBody ProjectPageForm form) {
|
||
return projectService.pageList(form);
|
||
}
|
||
|
||
@PostMapping
|
||
public ActionResult<String> create(@RequestBody ProjectEntity e) {
|
||
projectService.create(e);
|
||
return ActionResult.success("ok");
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.1 响应封装(JNPF 约定)
|
||
|
||
| 场景 | 写法 | 返回形状 |
|
||
|---|---|---|
|
||
| 单对象/成功 | `ActionResult.success(data)` | `{code:200, data, msg:"Success"}` |
|
||
| 分页 | `ActionResult.page(list, pagination)` | `{code:200, data:{list, pagination:{currentPage,pageSize,total}}}` |
|
||
| 失败 | `ActionResult.fail("msg")` | `{code:非200, msg}` |
|
||
| 登录过期 | 由 AuthFilter 统一返回 `code:600` | 前端据此清 token 跳登录 |
|
||
|
||
> 分页 `PageListVO` 结构:`{ list: [...], pagination: { currentPage, pageSize, total } }`。
|
||
> 前端约定:**`code !== 200` 即视为错误**;`code === 600`(或 HTTP 401)视为未登录。
|
||
|
||
---
|
||
|
||
## 七、必踩的两个碰撞坑(不处理启动即崩)
|
||
|
||
### 7.1 Spring bean 名冲突
|
||
|
||
JNPF 自带 `jnpf.flowable.controller.OperatorController`、`jnpf.*.service.OperatorService` 等。你的同名 Controller/Service 会触发:
|
||
|
||
```
|
||
ConflictingBeanDefinitionException: bean name 'operatorController' ...
|
||
conflicts with jnpf.flowable.controller.OperatorController
|
||
```
|
||
|
||
**解决**:所有 Controller 加 `@RestController("sswflowXxxController")`,所有 Service Impl 加 `@Service("sswflowXxxService")`。
|
||
|
||
### 7.2 MyBatis type-alias 冲突
|
||
|
||
JNPF 已有 `DataSetEntity`(注意大小写),你的 `DatasetEntity` 在**大小写不敏感**匹配下会撞:
|
||
|
||
```
|
||
The alias 'DataSetEntity' is already mapped to 'ssw.sswflow.entity.DatasetEntity'
|
||
```
|
||
|
||
**解决**:每个实体加 `@Alias("Sswflow<Entity>Entity")`(如 `SswflowDatasetEntity`),并 `import org.apache.ibatis.type.Alias;`。
|
||
|
||
---
|
||
|
||
## 八、鉴权接入(复用 JNPF 体系,前端照做即可)
|
||
|
||
### 8.1 登录接口
|
||
|
||
```
|
||
POST /api/oauth/Login
|
||
Content-Type: application/x-www-form-urlencoded
|
||
Headers: App-Code: {app_code} # 例如 sswflow
|
||
Jnpf-Origin: pc
|
||
Vue-Version: 3
|
||
Body: account=admin&password=<密文>&grant_type=password
|
||
```
|
||
|
||
### 8.2 密码加密算法(前端/客户端实现)
|
||
|
||
> **【修正 H · 2026-08-01 最终定稿】** 本节经「反编译官方字节码 + dacli 实测 + 本仓库 `tss2` 运行期验证」三证对齐,结论:**传输层内层字符串分两种约定,官方默认是 `md5(明文)`**。
|
||
>
|
||
> | 约定 | 传输层内层 S | 密文长度 | 存储 `f_password` | 谁在用 |
|
||
> |---|---|---|---|---|
|
||
> | **官方(默认)** | `md5(明文)` 的 32 位 hex | **96 hex**(48 字节) | `md5( md5(明文) + secretkey )` | JNPF 官方前端、`admin`、dacli、本仓库 `tss2` |
|
||
> | 旧变体(legacy) | `明文` 原文 | 32 hex(16 字节) | `md5( 明文 + secretkey )` | 部分老集成项目 |
|
||
>
|
||
> 两条约定**都合法,但互不相通**——关键看账号创建时存的是哪种 `f_password`。登录时后端先用 `DesUtil` 把密文解回内层字符串 S,再比 `md5(S + f_secretkey.toLowerCase())`。所以:用官方前端 / dacli 建的账号(含 `admin`)必须按官方约定登录;你自己造账号时可任选一种,只要 `f_password` 与约定配套(见 §16.8)。
|
||
|
||
务必先分清**两条独立的链路**,混淆是登录调不通的头号原因:
|
||
|
||
| | 传输层(前端 → 后端) | 存储层(DB 里存什么) |
|
||
|---|---|---|
|
||
| 用途 | 把密码从浏览器安全送到后端 | 校验密码是否正确 |
|
||
| 密钥 | 全局 `security.security-key` | **每个用户自己的** `base_user.f_secretkey` |
|
||
| 算法 | AES-256-ECB / PKCS7,输出 hex | MD5 摘要,不可逆 |
|
||
| 谁做 | 前端 `crypto.js` ↔ 后端 `DesUtil.aesOrDecode` | 后端 `PasswordTokenGranter` |
|
||
|
||
**后端权威实现**(`jnpf-oauth-biz` → `jnpf.granter.PasswordTokenGranter#authenticatePassword`):
|
||
|
||
```java
|
||
String pwd = form.getPassword();
|
||
try {
|
||
pwd = DesUtil.aesOrDecode(pwd, false, true); // ① 传输层解密 → 拿回内层字符串 S
|
||
} catch (Exception e) {
|
||
log.error("{}:{}", MsgCode.OA013.get(), pwd, e);
|
||
pwd = "";
|
||
}
|
||
// ② 存储层比对:注意只对 secretkey 做 toLowerCase,S 原样拼接
|
||
if (!user.getPassword().equals(Md5Util.getStringMd5(pwd + user.getSecretkey().toLowerCase()))) {
|
||
throw new LoginException(MsgCode.LOG101.get()); // 密码错误
|
||
}
|
||
```
|
||
|
||
#### ① 传输层:AES-256-ECB
|
||
|
||
`DesUtil.aesOrDecode(data, isEncrypt=false, isAes=true)` 展开后等价于:
|
||
|
||
```
|
||
输入 = hex 字符串 → HexUtil.decodeHex 还原字节
|
||
key = SecurityProperties.getInstance().getSecurityKey() 的 UTF-8 字节
|
||
算法 = SymmetricCrypto(AES, key) → JDK 默认 AES/ECB/PKCS5Padding
|
||
输出 = new String(内层字节, UTF-8)
|
||
```
|
||
|
||
**关键陷阱**:`SecurityProperties.setSecurityKey()` 的 setter **内部自动做了一次 MD5**:
|
||
|
||
```java
|
||
public void setSecurityKey(String v) {
|
||
this.securityKey = Md5Util.getStringMd5(v); // ← 配置值先被 MD5
|
||
}
|
||
```
|
||
|
||
所以配置里写 `EY8WePvjM5GGwQzn`(16 字符),实际参与运算的 key 是
|
||
`md5("EY8WePvjM5GGwQzn")` = `05b0175907a859751f57a04d5a5ee9ac`(32 字符 hex 文本),
|
||
按 UTF-8 取字节 = **32 字节 → AES-256**(不是 AES-128)。
|
||
这正好与前端 `crypto.js` 的 `encryptAES(data, encryptByMd5(aesKey))` 对齐。
|
||
|
||
**官方约定(默认,JNPF 前端 / `admin` / dacli / 本仓库 `tss2` 都用这个)**:内层 S = `md5(明文)`,把它的 hex 字符串当明文做 AES:
|
||
|
||
```
|
||
CIPHER_KEY = EY8WePvjM5GGwQzn # 与后端 security.security-key 一致
|
||
key = md5(CIPHER_KEY) 的 32 位 hex 文本,UTF-8 取字节(32B,AES-256)
|
||
S = md5(明文密码) 的 32 位 hex 字符串
|
||
密文 = Hex( AES256_ECB_PKCS7( UTF8(S), key ) ) # 96 hex
|
||
```
|
||
|
||
**旧变体(legacy,仅部分老集成项目)**:内层 S = 明文原文:
|
||
|
||
```
|
||
密文 = Hex( AES256_ECB_PKCS7( UTF8(原始明文密码), key ) ) # 32 hex
|
||
```
|
||
|
||
> **自检基准值**(已用 Node `crypto` 与 `crypto-js` 双实现交叉验证,并跑通 `tss2` 真实登录):
|
||
>
|
||
> ```
|
||
> md5("EY8WePvjM5GGwQzn") = 05b0175907a859751f57a04d5a5ee9ac
|
||
> # 官方约定(默认)
|
||
> encryptPassword_official("123456")
|
||
> = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b # 96 hex
|
||
> # 旧变体(legacy)
|
||
> encryptPassword_legacy("123456")
|
||
> = ea80d323686b9dfe734f2b42159db1a6 # 32 hex
|
||
> ```
|
||
> **对不上就别往下试登录**,一定是 key 或约定(官方 / 旧变体)选错了。
|
||
|
||
#### ② 存储层:`f_password` 怎么算
|
||
|
||
```
|
||
# 官方约定(默认):S = md5(明文)
|
||
base_user.f_password = md5( md5(明文密码) + base_user.f_secretkey.toLowerCase() )
|
||
# 旧变体(legacy):S = 明文
|
||
base_user.f_password = md5( 明文密码 + base_user.f_secretkey.toLowerCase() )
|
||
```
|
||
|
||
- `f_secretkey` 是**每个用户一条、互不相同**的随机串,不是全局密钥。
|
||
- `security-key` **只管传输**,跟入库摘要毫无关系——这两个千万别搞混。
|
||
- 造验证账号时,按你选的约定算好 `f_password` 与 `f_secretkey` 一起 INSERT 即可(见 §16.8,本仓库 `tss2` 用官方约定)。
|
||
|
||
```bash
|
||
# 例:tss2dev 用【官方约定】生成 123456 的入库摘要(secretkey = tss2dev-secret-key-001)
|
||
node -e "const c=require('crypto');const m=s=>c.createHash('md5').update(s,'utf8').digest('hex');
|
||
console.log(m(m('123456')+'tss2dev-secret-key-001'))"
|
||
# => 2898aa333ba4efb48658db85e10d9fd9
|
||
```
|
||
|
||
> 反过来也说明:**你无法从 DB 里反推别人的密码**,也无法拿 `admin` 的 `f_password` 去猜明文。
|
||
> 实测 j7 库 `admin` 的 `f_password` 与 `md5("123456"+其 secretkey)` 并不相等,
|
||
> 说明这套环境的 admin 密码不是 123456 —— 别浪费时间试,自己造账号(见 §16.4)。
|
||
|
||
### 8.2-B 【新增】自建账号登录报「账号权限不足」(LOG004)
|
||
|
||
**现象**:密码算得完全正确,登录却返回 `{"code":400,"msg":"账号权限不足"}`。
|
||
|
||
**根因**(`jnpf-oauth-biz` → `jnpf.service.impl.LoginServiceImpl`):
|
||
|
||
```java
|
||
// 超管旁路:账号名必须字面量等于 "admin",且 is_administrator == 1
|
||
if (!("admin".equals(user.getAccount()) && user.getIsAdministrator() == 1)) {
|
||
List<String> objectIds = 用户的岗位ID列表(position);
|
||
objectIds.add(user.getId());
|
||
List<?> roles = roleRelationApi.getListByObjectId(objectIds, null); // base_role_relation
|
||
List<String> all = objectIds + roles.map(角色ID);
|
||
if (CollUtil.isEmpty(all) || CollUtil.isEmpty(authorizeApi.getListByObjectId(all))) {
|
||
throw new LoginException(MsgCode.LOG004.get()); // 账号权限不足
|
||
}
|
||
}
|
||
```
|
||
|
||
**踩坑要点**:
|
||
|
||
1. 旁路条件是**账号名硬编码字面量 `"admin"`**。你把自建账号的 `f_is_administrator` 设成 1 **没用**,只要账号不叫 `admin` 就照样走权限检查。
|
||
2. 检查的是:`base_role_relation`(用户/岗位 → 角色)关联出的对象,在 `base_authorize` 里**至少有一条授权记录**。
|
||
3. 光有角色还不够,那个角色必须真的有 `base_authorize` 数据。
|
||
|
||
**解法**:给自建账号挂一个已有授权数据的角色。先查有哪些角色可用:
|
||
|
||
```sql
|
||
-- 看哪些角色真的有授权记录
|
||
SELECT r.f_id, r.f_full_name, count(a.f_object_id) AS 授权数
|
||
FROM base_role r JOIN base_authorize a ON a.f_object_id = r.f_id
|
||
GROUP BY r.f_id, r.f_full_name ORDER BY 授权数 DESC;
|
||
-- 666911261245571844 | 管理员 | 101
|
||
-- 666911261245571845 | 开发者 | 84
|
||
-- 666911261245571846 | 使用者 | 18
|
||
```
|
||
|
||
```sql
|
||
-- 挂上「管理员」角色(f_object_type 固定 'user',f_tenant_id 非空约束,填 '' 即可)
|
||
INSERT INTO base_role_relation
|
||
(f_id, f_role_id, f_object_type, f_object_id, f_creator_time, f_creator_user_id, f_delete_mark, f_tenant_id)
|
||
VALUES ('tss2dev-rel-001', '666911261245571844', 'user', 'tss2dev-001', now(), 'tss2dev-001', 0, '');
|
||
```
|
||
|
||
> 另外 `base_user.f_enabled_mark` 必须为 `1`。从 admin 行 copy 建账号时这列容易带成 NULL,
|
||
> 非超管路径会因此抛 `LOG005`。建完记得 `UPDATE base_user SET f_enabled_mark=1 WHERE f_account='xxx';`
|
||
|
||
**登录错误码速查**:
|
||
|
||
| code | 含义 | 检查方向 |
|
||
|---|---|---|
|
||
| `LOG101` 密码错误 | 传输层解密后与 `f_password` 对不上 | §8.2 两条链路是否搞混 |
|
||
| `LOG004` 账号权限不足 | 无角色 / 角色无 `base_authorize` | 本节,挂角色 |
|
||
| `LOG005` 账号已禁用 | `f_enabled_mark` 不是 1 | UPDATE 该列 |
|
||
| `OA013`(日志里) | 传输层 AES 解密抛异常 | 密文不是 hex / key 不对 |
|
||
|
||
### 8.3 Token 传递(最容易被坑的一点)
|
||
|
||
- 登录返回的 `data.token` 形如 **`bearer eyJhbGciOi...`**(已带 `bearer ` 前缀)。
|
||
- Sa-Token 配置:`getTokenName()="Authorization"`、`getTokenPrefix()="bearer"`、`isReadHeader=true`。
|
||
- **前端必须原样把登录返回的整串作为 `Authorization` 头值发送**,Sa-Token 会按前缀 `bearer`(小写)剥离。
|
||
|
||
```
|
||
Authorization: bearer eyJhbGciOi... # ✅ 原样
|
||
Authorization: Bearer eyJ... # ❌ 大写 B 不会被剥离 → 600 登录过期
|
||
Authorization: bearer bearer eyJ... # ❌ 叠两层 → 600
|
||
```
|
||
|
||
### 8.4 白名单配置
|
||
|
||
`AuthFilter` 拦截 `/**`(含静态资源)。登录页、静态资源、登录接口必须放行:
|
||
|
||
```yaml
|
||
# application.yml(JNPF 网关配置区)
|
||
gateway:
|
||
exclude-url: # 免 Token 且不记录日志
|
||
- /api/oauth/Login
|
||
- /static/**
|
||
# 用独立 Vite 前端时无需 /ssw/**;若塞 no-spa 静态页再加 - /ssw/**
|
||
```
|
||
|
||
---
|
||
|
||
## 九、多数据源 @DS 规范(JNPF 标准机制,必做)
|
||
|
||
JNPF 内置 `dynamic-datasource-spring-boot-starter`,通过 `@DS` 注解在运行时切换数据源。**接入业务模块应当采用「系统库 + 业务库」双库架构**,业务表独立成库,用 `@DS` 切换——这既是 JNPF 自身的标准做法(其 permission / visualdev / generater 模块同样用 `@DS` 分库),也符合公司「每 app_code 独立库」的规范。
|
||
|
||
### 9.1 双库架构
|
||
|
||
| 源 | 角色 | 库名 | 承载内容 |
|
||
|---|---|---|---|
|
||
| `master`(默认 `primary`) | JNPF 平台主库 | `j7` | `base_user`、组织、权限、字典等系统表 |
|
||
| `sswflow`(业务源) | SSWFlow 业务库 | `sswflow`(可用 `${SSWFLOW_DB}` 覆盖) | 你的业务表 |
|
||
|
||
- `master` 无需显式声明:由 `MybatisPlusConfig#initPrimaryDataSource` 从 `spring.datasource.*` 主配置自动补全。
|
||
- 业务代码一律 `@DS("sswflow")`,登录/鉴权/系统查询走 `master`。
|
||
|
||
### 9.2 配置(application-dev.yml)
|
||
|
||
```yaml
|
||
spring:
|
||
datasource:
|
||
db-name: j7 # 主库(JNPF 系统库)
|
||
host: ${DB_HOST:jnpf-postgres}
|
||
port: ${DB_PORT:5432}
|
||
username: ${DB_USER:dacli}
|
||
password: ${DB_PWD:dacli123}
|
||
dynamic:
|
||
primary: master # 默认数据源
|
||
strict: true # 严格匹配:true-未匹配到源直接抛异常;false-降级用默认源
|
||
druid: # 连接池参数(略)
|
||
initial-size: 4
|
||
max-active: 20
|
||
datasource:
|
||
# 业务库只需声明这一个节点;master 由框架自动补全
|
||
sswflow:
|
||
url: jdbc:postgresql://${spring.datasource.host}:${spring.datasource.port}/${SSWFLOW_DB:sswflow}?currentSchema=public&stringtype=unspecified
|
||
username: ${spring.datasource.username}
|
||
password: ${spring.datasource.password}
|
||
driver-class-name: org.postgresql.Driver
|
||
lazy: false
|
||
```
|
||
|
||
> `strict: true` 下,若 `@DS("sswflow")` 指定的源不存在会**直接抛异常**(而不是静默落到 master),能尽早暴露配置错误。
|
||
|
||
### 9.3 用法(实体 + Service 都要打)
|
||
|
||
```java
|
||
@Alias("SswflowProjectEntity")
|
||
@DS("sswflow") // ⚠️ 切到业务库
|
||
@TableName("project")
|
||
public class ProjectEntity extends SuperEntity<String> { ... }
|
||
|
||
@Service("sswflowProjectService")
|
||
@DS("sswflow") // ⚠️ 注解【不继承】!子类必须各自打,写在基类上无效
|
||
public class ProjectServiceImpl extends SswflowServiceImpl<ProjectMapper, ProjectEntity>
|
||
implements ProjectService { ... }
|
||
```
|
||
|
||
⚠️ **`@DS` 不会从父类继承**:基类 `SswflowServiceImpl` 即使打了 `@DS`,子类也读不到——JNPF 切面取的是 `methodInvocation.getThis().getClass().getAnnotation(DS.class)`。**每个业务 Service Impl 必须自己打 `@DS("sswflow")`**,实体同理。
|
||
|
||
### 9.4 基类承载「动态自愈」(SSWFlow 自定义增强)
|
||
|
||
`SswflowServiceImpl` 实现 JNPF 的 `DynamicSourceGeneratorInterface`,命中 `MybatisPlusConfig#myDynamicDatasourceGeneratorAdvisor` 切面(切点 `within(DynamicSourceGeneratorInterface+) && @target(@DS)`):
|
||
|
||
- **静态兜底**:`application-dev.yml` 已声明 `sswflow` 连接池,正常路径不依赖运行时生成。
|
||
- **动态自愈**:一旦 `sswflow` 源缺失(连接池被销毁、多租户重建等),会用主库连接参数复制一份并把库名换成 `sswflow` 重新注册,避免 `strict=true` 下抛 `dynamic-datasource can not find primary datasource`。
|
||
|
||
> **【修正 G】接口真实签名(已反编译 `jnpf-common-database-7.0.0-RELEASE.jar` 复核):**
|
||
> ```java
|
||
> public interface DynamicSourceGeneratorInterface {
|
||
> public abstract <T extends jnpf.database.util.DataSourceUtil> T getDataSource();
|
||
> public default boolean cachedConnection();
|
||
> }
|
||
> ```
|
||
> `jnpf.database.util.DataSourceUtil` 标注 `@Component`(可直接 `@Autowired`),其 `init(String)` 返回 `jnpf.database.model.entity.DbLinkEntity`——而 `DbLinkEntity extends DataSourceUtil`,所以 `return masterDataSourceUtil.init(DS_KEY);` 赋值给 `DataSourceUtil` 完全合法。原文档写法**能编译**,这里仅补充精确签名与类型关系,避免读者误以为 `init` 返回 `DataSourceUtil` 本身。
|
||
|
||
```java
|
||
public abstract class SswflowServiceImpl<M extends SuperMapper<T>, T>
|
||
extends SuperServiceImpl<M, T> implements DynamicSourceGeneratorInterface {
|
||
public static final String DS_KEY = "sswflow";
|
||
@Autowired
|
||
private DataSourceUtil masterDataSourceUtil; // 主库连接参数(只读,@Component)
|
||
@Override
|
||
public DataSourceUtil getDataSource() {
|
||
return masterDataSourceUtil.init(DS_KEY); // 复制主库参数,库名换成 sswflow
|
||
}
|
||
}
|
||
```
|
||
|
||
> 所有业务 Service 继承 `SswflowServiceImpl` 即可自动获得该能力(仍需各自打 `@DS("sswflow")`)。
|
||
|
||
---
|
||
|
||
## 十、前端对接:用独立 Vite,别塞 jar
|
||
|
||
把静态页塞进 Spring Boot jar 会踩一堆坑(静态资源映射是 `/static/**` 而非根、每次改前端要重打包、AuthFilter 白名单)。**独立 Vite dev server 干净得多**:
|
||
|
||
```
|
||
sswflow-web/ # Vite + Vue3 + TS + ant-design-vue
|
||
├── vite.config.ts # proxy: { '/api': { target: 'http://localhost:30000' } }
|
||
├── scripts/smoke.mjs # 零依赖烟测(见 §12.2)
|
||
└── src/
|
||
├── utils/cipher.ts # 密码 AES 加密(对齐 8.2)
|
||
├── api/request.ts # axios:注入 Authorization/App-Code/Jnpf-Origin/Vue-Version;600/401 跳登录
|
||
├── api/auth.ts # login/logout/getToken
|
||
└── api/sswflow.ts # 业务接口(路径 /api/ssw/sswflow/...)
|
||
```
|
||
|
||
`vite.config.ts`:
|
||
|
||
```ts
|
||
export default defineConfig({
|
||
server: { port: 5173, proxy: { '/api': { target: 'http://localhost:30000', changeOrigin: true } } },
|
||
plugins: [vue()]
|
||
})
|
||
```
|
||
|
||
> 浏览器只跟 5173 通信,由 Vite 代理到 30000,同源无 CORS 问题。
|
||
|
||
`src/utils/cipher.ts`(**官方约定**,与 §8.2 一致,含自检 —— 内层 = `md5(明文)`):
|
||
|
||
```ts
|
||
import CryptoJS from 'crypto-js'
|
||
|
||
const CIPHER_KEY: string = import.meta.env.VITE_CIPHER_KEY || 'EY8WePvjM5GGwQzn'
|
||
|
||
export function encryptPassword(plain: string): string {
|
||
const key = CryptoJS.enc.Utf8.parse(CryptoJS.MD5(CIPHER_KEY).toString()) // md5(securityKey) 32B = AES-256
|
||
const inner = CryptoJS.MD5(plain).toString() // 官方约定:内层 = md5(明文) 的 32 hex
|
||
const encrypted = CryptoJS.AES.encrypt(CryptoJS.enc.Utf8.parse(inner), key, {
|
||
mode: CryptoJS.mode.ECB, padding: CryptoJS.pad.Pkcs7
|
||
})
|
||
return CryptoJS.enc.Base64.parse(encrypted.toString()).toString(CryptoJS.enc.Hex)
|
||
}
|
||
|
||
export const SELF_CHECK_123456 =
|
||
'd4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b'
|
||
|
||
export function selfCheck(): boolean {
|
||
return encryptPassword('123456') === SELF_CHECK_123456
|
||
}
|
||
```
|
||
|
||
`src/api/request.ts` 关键拦截器(要点):
|
||
|
||
```ts
|
||
// 请求拦截:注入 4 个头,token 原样带(含 "bearer " 前缀)
|
||
config.headers.Authorization = getToken() // 形如 "bearer eyJ..."
|
||
config.headers['App-Code'] = appCode
|
||
config.headers['Jnpf-Origin'] = 'pc'
|
||
config.headers['Vue-Version'] = '3'
|
||
|
||
// 响应拦截:code !== 200 视为错误;code === 600 || http 401 → 清 token 跳登录
|
||
if (res.data.code !== 200) {
|
||
if (res.data.code === 600) { clearToken(); router.replace('/login') }
|
||
return Promise.reject(res.data.msg)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 十一、数据库与中间件(PostgreSQL + Redis)
|
||
|
||
> **快速起环境**:不想手动装库,直接用阿里云镜像(PostgreSQL 16 + Redis)一条命令拉起,并初始化 `j7` 主库——完整步骤见「〇-B.4」。下面只讲配置与接入约定。
|
||
|
||
```yaml
|
||
# application-dev.yml(节选,完整见 §9.2)
|
||
spring:
|
||
datasource:
|
||
url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${SSWFLOW_DB:sswflow}
|
||
username: dacli
|
||
password: dacli123
|
||
data:
|
||
redis:
|
||
host: ${REDIS_HOST:localhost}
|
||
port: ${REDIS_PORT:6379}
|
||
redis:
|
||
redisson:
|
||
config: |
|
||
singleServerConfig:
|
||
address: "redis://${REDIS_HOST:localhost}:${REDIS_PORT:6379}"
|
||
database: 0
|
||
password: ${REDIS_PWD:} # 纯镜像无密码时留空;JNPF 默认 123456 → 二选一对齐
|
||
connectionPoolSize: 32
|
||
connectionMinimumIdleSize: 8
|
||
codec: !<org.redisson.codec.JsonJacksonCodec> {}
|
||
```
|
||
|
||
> **Netty DNS 注意**:Spring/Redis 用的 Netty 解析器不走系统 hosts,`.orb.local` 后缀在宿主机可能解析不到。宿主机直连用**容器 IP**(如 OrbStack 下 `192.168.97.3:5432`、`192.168.97.2:6379`),或启动时用 `-DDB_HOST=... -DREDIS_HOST=...` 覆盖(见第 12.1 节启动命令)。
|
||
|
||
建表:schema 用 Flyway/手工 SQL,列名遵循 `f_xxx` 约定(公共字段**列名不可改动**,由 `SuperEntity`/`SuperBaseEntity` 硬编码映射);业务库 `sswflow` 执行 `V1.0.0__schema.sql`(系统库 `j7` 由 JNPF 自行初始化,脚本来源见「〇-B.4」的 `jnpf-database` 仓库)。
|
||
|
||
业务库建表脚本示例(PostgreSQL,公共字段与 `SuperEntity` 严格对齐):
|
||
|
||
```sql
|
||
-- 项目表
|
||
CREATE TABLE project (
|
||
f_id varchar(50) NOT NULL,
|
||
f_tenant_id varchar(50),
|
||
f_creator_time timestamp DEFAULT now(),
|
||
f_creator_user_id varchar(50),
|
||
f_last_modify_time timestamp,
|
||
f_last_modify_user_id varchar(50),
|
||
f_delete_mark int4,
|
||
f_delete_time timestamp,
|
||
f_delete_user_id varchar(50),
|
||
name varchar(200) NOT NULL,
|
||
project_code varchar(100),
|
||
compute_mode varchar(20),
|
||
status varchar(20) DEFAULT 'DRAFT',
|
||
remark varchar(500),
|
||
CONSTRAINT pk_project PRIMARY KEY (f_id)
|
||
);
|
||
COMMENT ON TABLE project IS '项目';
|
||
COMMENT ON COLUMN project.f_delete_mark IS '删除标记,NULL=未删除';
|
||
```
|
||
|
||
---
|
||
|
||
## 十二、启动与验证
|
||
|
||
### 12.1 启动命令(已验证)
|
||
|
||
```bash
|
||
cd boot
|
||
# jar 跑在宿主机:application-dev.yml 已默认 localhost:15432(PG 发布端口)+ 127.0.0.1:6379(Redis)
|
||
# 如需自定义可加: -DDB_HOST=... -DDB_PORT=... -DDB_USER=... -DDB_PWD=... -DTSS2_DB=...
|
||
java -Dspring.profiles.active=dev \
|
||
--server.port=30000 \
|
||
-jar ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar
|
||
```
|
||
|
||
> **【`SERVER__PORT` 环境变量陷阱 · §16.6①】** 若宿主机残留 `SERVER__PORT`/`SERVER_PORT` 环境变量,Spring Boot relaxed binding 会把它映射成 `server.port`,**且环境变量优先级高于 `-D` 系统属性、高于 yml**,端口会变成随机高位(如 53160)。最稳的做法是显式传 **CLI 参数** `--server.port=30000`(命令行参数优先级最高,可压过环境变量),或启动前 `env -u SERVER__PORT`。
|
||
> 另:`-D` 参数必须放在 `-jar` **前面**才是 JVM 参数;`--server.port` 是 Spring Boot CLI 参数,位置不限。
|
||
|
||
> **【修正 F/J/K】Boot 3 兼容补丁(缺一不可,否则登录时 `NoClassDefFoundError: ThreadPoolExecutorUtil` 或启动失败):**
|
||
>
|
||
> **(1) `applicationTaskExecutor` bean**(`ssw/config/TaskExecutorConfig.java`):
|
||
> ```java
|
||
> @Configuration
|
||
> public class TaskExecutorConfig {
|
||
> @Bean("applicationTaskExecutor")
|
||
> @ConditionalOnMissingBean(name = "applicationTaskExecutor")
|
||
> public ThreadPoolTaskExecutor applicationTaskExecutor() {
|
||
> ThreadPoolTaskExecutor ex = new ThreadPoolTaskExecutor();
|
||
> ex.setCorePoolSize(8); ex.setMaxPoolSize(32); ex.setQueueCapacity(500);
|
||
> ex.setThreadNamePrefix("ssw-task-"); ex.initialize();
|
||
> return ex;
|
||
> }
|
||
> }
|
||
> ```
|
||
> **(2) `SpringContext` initializer 必须代码注册**(FQN `jnpf.util.context.SpringContext`):
|
||
> ```java
|
||
> public static void main(String[] args) {
|
||
> SpringApplication application = new SpringApplication(SswAdminApplication.class);
|
||
> application.addInitializers(new jnpf.util.context.SpringContext());
|
||
> application.run(args);
|
||
> }
|
||
> ```
|
||
> 同时保留 `src/main/resources/META-INF/spring/org.springframework.context.ApplicationContextInitializer`(内容 `jnpf.util.context.SpringContext`)作 IDE 双保险。
|
||
>
|
||
> **(3) `application.yml` 必加两项**(否则 Boot 3 下启动失败/路由异常):
|
||
> ```yaml
|
||
> spring:
|
||
> main:
|
||
> allow-bean-definition-overriding: true # JNPF 内部存在同名 bean 定义
|
||
> mvc:
|
||
> pathmatch:
|
||
> matching-strategy: ant_path_matcher # JNPF 用 ant 路径匹配
|
||
> ```
|
||
|
||
### 12.2 烟测脚本(Node,零依赖,已验证)
|
||
|
||
> **【修正 I】** 提供 `scripts/smoke.mjs`(不依赖任何 npm 包,纯 Node 内置 `http`/`crypto`),含密码自检 + 登录 + 业务接口调用,支持参数:
|
||
> `--base`(默认 `http://localhost:30000`)、`--account`(默认 `tss2dev`)、`--password`(默认 `123456`)、`--key`(默认 `EY8WePvjM5GGwQzn`)、`--appcode`(默认 `tss2`)。
|
||
|
||
```js
|
||
// scripts/smoke.mjs(核心逻辑 · 与 §8.2 两条链路一致)
|
||
import { createHash, createCipheriv, createDecipheriv } from 'node:crypto';
|
||
import http from 'node:http';
|
||
|
||
const md5Hex = (s) => createHash('md5').update(s, 'utf8').digest('hex');
|
||
|
||
// 传输层(官方约定):hex( AES-256-ECB/PKCS5( md5(明文)的32hex字符串, utf8(md5(securityKey)) ) )
|
||
// 内层 S = md5(明文);旧变体(legacy)才是明文原文(见 §8.2)。
|
||
function encryptPassword(plain, cipherKey) {
|
||
const key = Buffer.from(md5Hex(cipherKey), 'utf8'); // md5(securityKey) 的 32 位 hex 按 UTF-8 取字节 = 32B = AES-256
|
||
const inner = md5Hex(plain); // 官方约定:内层 = md5(明文)
|
||
const c = createCipheriv('aes-256-ecb', key, null);
|
||
c.setAutoPadding(true);
|
||
return Buffer.concat([c.update(Buffer.from(inner, 'utf8')), c.final()]).toString('hex');
|
||
}
|
||
const decryptPassword = (hex, key) => {
|
||
const d = createDecipheriv('aes-256-ecb', Buffer.from(md5Hex(key), 'utf8'), null);
|
||
d.setAutoPadding(true);
|
||
return Buffer.concat([d.update(Buffer.from(hex, 'hex')), d.final()]).toString('utf8');
|
||
};
|
||
|
||
function req(method, path, body, headers) { /* 见仓库脚本:node:http 封装,返回 { status, data } */ }
|
||
const post = (p, b, h) => req('POST', p, b, h);
|
||
const get = (p, h) => req('GET', p, null, h);
|
||
|
||
// 1) 自检:与基准值一致 + 解密可逆
|
||
const EXPECT_123456 = 'd4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b'; // 官方约定(md5内层),96-hex
|
||
const cipher = encryptPassword(password, key);
|
||
console.log('cipher self-check:', (cipher === EXPECT_123456 && decryptPassword(cipher, key) === password) ? 'PASS' : 'FAIL');
|
||
|
||
// 2) 登录(x-www-form-urlencoded)
|
||
const body = `account=${encodeURIComponent(account)}&password=${cipher}&grant_type=password`;
|
||
const login = await post(`${base}/api/oauth/Login`, body, {
|
||
'Content-Type': 'application/x-www-form-urlencoded',
|
||
'App-Code': appcode, 'Jnpf-Origin': 'pc', 'Vue-Version': '3'
|
||
});
|
||
const token = login.data?.data?.token || login.data?.token; // "bearer eyJ..."
|
||
|
||
// 3) 带 token 调业务接口(走 @DS("tss2") 落到 tss2 库)
|
||
await post(`${base}/api/ssw/${appcode}/Project`,
|
||
JSON.stringify({ name: 'smoke', projectCode: 'smoke', computeMode: 'MPC', status: 1, remark: 'e2e' }),
|
||
{ Authorization: token, 'App-Code': appcode, 'Content-Type': 'application/json' });
|
||
const r = await get(`${base}/api/ssw/${appcode}/Project/All`, { Authorization: token, 'App-Code': appcode });
|
||
console.log('Project/All code =', r.data.code, '| rows =', (r.data.data || []).length);
|
||
```
|
||
|
||
> 验证双库生效:`Project/All` 返回刚写入的记录(连到 `tss2` 业务库),同时登录成功(走 `master`/j7 查 `base_user`)——两者并存即说明 `@DS` 路由正确;且 `j7` 库无 `project` 表证明数据只落在 `tss2` 库(§16.5)。
|
||
|
||
---
|
||
|
||
## 十三、常见坑速查表
|
||
|
||
| 现象 | 原因 | 解决 |
|
||
|---|---|---|
|
||
| `Could not resolve com.jnpf:... 401/404` / 依赖拉不到 | 没配官方私服 `settings.xml` | 配 `~/.m2/settings.xml` 的 `maven-releases` server+mirror(〇-B.2) |
|
||
| 某模块目录文件缺失、编译报找不到类 | 官方仓库模块未 clone 全 | 用账号从 `coding.jnpfsoft.com/v7.0/<module>` 补齐(〇-B.1) |
|
||
| `jnpf-common-all:jar:7.0.0-RELEASE not found` | 私有仓库需鉴权,离线拉不到 | 本地编译 JNPF 源码 `mvn install`(第二节,前置见〇-B.1/〇-B.2) |
|
||
| `-source 8 不支持 switch 表达式` | boot3 profile 锁 source=8 | 业务模块 pom 覆盖 `source/target=17`(3.1,父 `ssw-boot` 已设) |
|
||
| `dependencies.dependency.version' for com.baomidou:... is missing` | entity pom 裸写 mybatis-plus/dynamic-datasource 无 version | 删除(随 jnpf-common-all 传递引入),或显式加 `<version>`(3.2) |
|
||
| 编译报 `找不到符号 getXxx()` / `@Data` 不生效 | 缺 lombok(JNPF 侧 provided 不传递) | entity pom 加 `org.projectlombok:lombok`(provided)(3.2) |
|
||
| `Could not resolve com.jnpf:ssw-tss-controller ... has not been downloaded` | 打包只 `-pl ssw-admin`,业务模块不在 reactor | 加 **`-am`**:`mvn -o package -DskipTests -pl ssw-admin -am`(〇-B.3/12) |
|
||
| `ConflictingBeanDefinitionException: operatorController` | 与 JNPF 同名 bean 撞 | Controller/Service 显式 bean 名(7.1) |
|
||
| `alias 'DataSetEntity' already mapped` | MyBatis alias 大小写不敏感撞 | 实体加 `@Alias("SswflowXxxEntity")`(7.2) |
|
||
| 业务接口报 `dynamic-datasource can not find primary datasource` / 数据跑到 `j7` 库 | `@DS` 没打或打错;`strict=true` 下缺失源抛异常 | 实体+Service 都打 `@DS("sswflow")`(9.3) |
|
||
| 登录返回 `600 登录过期` | token 前缀被叠/被改大写 | 原样用 `bearer eyJ...`(8.3) |
|
||
| 登录报 `BadPaddingException` | 密码加密算法/key 不对 | 对齐 8.2(AES-256-ECB,key=MD5(CIPHER_KEY) 的 32 字节) |
|
||
| **启动无报错但登录 404 / 注入失败** | **`scanBasePackages` 写成 `com.jnpf`** | **改成 `{"jnpf","ssw"}`(修正 A / 〇-B.3-2)** |
|
||
| `NoClassDefFoundError: ThreadPoolExecutorUtil` | `applicationTaskExecutor` 缺失 + SpringContext 未注册/注册失效 | 12.1 的两个 Boot 3 补丁;**务必代码注册 `jnpf.util.context.SpringContext`**(修正 F) |
|
||
| **启动即失败:`bean definition ... is expected to be defined in ... overriding is disabled`** | **JNPF 内部同名 bean 不被允许覆盖** | **`spring.main.allow-bean-definition-overriding: true`(修正 J)** |
|
||
| 路由 404 / ant 匹配异常 | Boot 3 默认 PathPattern 与 JNPF ant 不匹配 | `spring.mvc.pathmatch.matching-strategy: ant_path_matcher`(修正 K) |
|
||
| 启动后端口是随机高位(如 53160/64052) | **环境变量 `SERVER__PORT`/`SERVER_PORT` 覆盖了配置文件**(relaxed binding,优先级高于 yml) | `env \| grep -i "SERVER.*PORT"` 排查;启动加 `--server.port=30000`(§16.6①) |
|
||
| 静态页 404 / 返回 JSON 错误 | 资源映射是 `/static/**` 非根 | 用独立 Vite(第十节)或加 `addResourceHandlers` |
|
||
| `UnknownHostException: jnpf-postgres/jnpf-redis` | jar 跑在宿主机却用了容器网络的主机名 | 改 `localhost` + **容器发布端口**(PG 常是 15432 不是 5432)(§16.6②) |
|
||
| Redis 连不上但容器是 Up | 容器没做端口映射(PORTS 无 `0.0.0.0:6379->`) | 另起带 `-p 6379:6379` 的实例(§16.6②) |
|
||
| `ERR Client sent AUTH, but no password is set` | redisson password 与 Redis 实际不符 | 无密码镜像把 `password` 留空对齐(§11) |
|
||
| `@DS("xxx")` 报数据源不存在 | YAML 少写一层,写成了 `dynamic.<name>` | 必须是 `dynamic.**datasource**.<name>`(§16.6③) |
|
||
| 登录 `{"code":400,"msg":"账号权限不足"}` | 自建账号没挂角色 / 角色无 `base_authorize`;超管旁路硬编码只认账号名 `admin` | 挂「管理员」角色(§8.2-B) |
|
||
| 登录密码怎么算都不对 | 把「传输层 AES」和「存储层 MD5」搞混了 | 传输 AES-256-ECB(明文)、存储 md5(明文+secretkey)(§8.2) |
|
||
| 文件存储启动报路径不可写 | `base-path` 默认 `/workspace/...` 是容器内路径 | 改成工程内可写目录(§16.6④) |
|
||
| 后台起的服务莫名消失、日志停半路 | `nohup ... &` 被父 shell 回收 | `jps -lm` 确认;改用前台 `exec java -jar` 或 tmux/systemd(§16.6⑤) |
|
||
|
||
---
|
||
|
||
## 十四、最小落地清单(照抄顺序)
|
||
|
||
1. 环境准备:获取官方源码(首次 `git clone`、之后 `git pull` 或复用 `~/.m2` 已有 jar,见〇-B.1)+ 配 `settings.xml` 私服(〇-B.2)+ 镜像拉起 j7/Redis 并只取 SQL 初始化库(〇-B.4)
|
||
2. 复制 `jnpf-java-boot/jnpf-admin` → `boot/ssw-admin`,按 〇-B.3 调整(parent/pom、包名 `jnpf→ssw`、**`scanBasePackages={"jnpf","ssw"}`**、Boot3 补丁含**代码注册 SpringContext**、数据源)
|
||
3. 编译 JNPF 源码装本地仓库(第二节,前置见〇-B.1/〇-B.2)
|
||
4. 建 `boot/ssw-{app_code}/{entity,biz,controller}` 三层 + `ssw-admin` 聚合
|
||
5. 业务模块 pom 加 `source/target=17`(父 `ssw-boot` 已设)、依赖 `jnpf-common-all` + `lombok(provided)`;**不要**裸写 mybatis-plus/dynamic-datasource(3.2)
|
||
6. 配 `application.yml`:`allow-bean-definition-overriding: true` + `mvc.pathmatch.ant_path_matcher` + 白名单;`application-dev.yml` 双数据源 `master`(j7) 自动补全 + `dynamic.datasource.sswflow` 业务库(9.2)+ redisson(§11)
|
||
7. 写实体(带 `@Alias`、继承 `SuperEntity<String>`、**不重复声明公共字段**、`@DS("sswflow")`)
|
||
8. 写 Service(继承 `SswflowServiceImpl`,`@Service("sswflowXxxService")` + **`@DS("sswflow")`**)
|
||
9. 写 Controller(`@RestController("sswflowXxxController")`、`/api/ssw/{app_code}`)
|
||
10. 配 `application.yml` 白名单 + `application-dev.yml` 数据库
|
||
11. 加 Boot 3 两个补丁(executor bean + **`SswAdminApplication` 代码注册 `jnpf.util.context.SpringContext`**)
|
||
12. 独立 Vite 前端:cipher / request / auth / 业务接口 + proxy 30000
|
||
13. **构建:`mvn -o package -DskipTests -pl ssw-admin -am`**(注意 `-am`)
|
||
14. 启动(12.1 命令)→ 烟测(`node scripts/smoke.mjs`,确认登录成功、密码自检 PASS、业务接口走 sswflow 库)→ 浏览器 5173 登录
|
||
|
||
---
|
||
|
||
## 十五、前端策略:以 AI 编写为主,不套 JNPF views 结构
|
||
|
||
> 结论:**`sswflow-web` 保持一个普通的 Vite + Vue3 + TS 工程,由 AI 直接编写,不强行套 JNPF web 的 `views/**` 目录范式。** 过早对齐 JNPF 页面结构反而增加约束、拖慢 AI 开发效率;只有当"迁回 JNPF web"成为明确任务时,再按需对齐。
|
||
|
||
**只保留与后端 / JNPF 强相关的 3 个对接点(已写在第十节,务必对齐,其余随意):**
|
||
|
||
1. `utils/cipher.ts` —— 密码 AES-256-ECB 加密,key=`MD5(CIPHER_KEY)`,与后端 `security.security-key` 一致(§8.2,含自检基准值)
|
||
2. `api/request.ts` —— axios 拦截器注入 `Authorization`(原样 `bearer eyJ...`) / `App-Code` / `Jnpf-Origin` / `Vue-Version`;`code!==200` 报错、`600/401` 跳登录(§8.3)
|
||
3. 业务接口路径前缀 `/api/ssw/{app_code}/...`,响应沿用 `ActionResult`(`code/data/msg`)+ 分页 `{list,pagination}`(§6.1)
|
||
|
||
**AI 编写时的自由区(不约束):**
|
||
- 目录怎么分、组件怎么拆、状态管理用 Pinia 还是 composables、UI 库选型 —— 交给 AI 按工程习惯决定。
|
||
- 不要求复用 JNPF 的 `<BasicTable>` / `<JnpfForm>` 等私有组件(它们强耦合 JNPF 运行时,迁移成本高于收益)。
|
||
- 页面不强求 `views/<module>/<page>` 的命名 —— 可读性优先,AI 生成的命名保持自洽即可。
|
||
|
||
> 迁移提示:真要迁回 JNPF web 时,难点只在上述 3 个对接点 + 页面注册到 JNPF 路由;业务组件本身可整体搬。所以"现在让 AI 自由写"不会欠下迁移债。
|
||
|
||
---
|
||
|
||
## 十六、tss2 二次落地:验证记录与文档缺口补充
|
||
|
||
> 以「完善文档」为目标,在不参考任何其它项目/脚手架、不启用容器的情况下,仅依据本指南从零落地第二个应用 `tss2`(位于本仓库 `tss2/`),用于校验本指南的可复用性与缺口。结论:**后端构建、前端构建、密码算法自检全部通过**,证明指南可复用;同时暴露若干「仅看指南无法一次性拼出」的缺口,已在下面补齐。
|
||
|
||
### 16.1 tss2 命名映射表
|
||
|
||
按「示例占位约定」把 `sswflow` 整体替换为 `tss2`(app_code = 库名 = 数据源名):
|
||
|
||
| 占位(原文档通用写法) | tss 首版 | tss2 二次落地 |
|
||
|---|---|---|
|
||
| app_code | `tss` | `tss2` |
|
||
| 类前缀 `Sswflow` | `Tss` | `Tss2` |
|
||
| bean 名前缀 `sswflow` | `tss` | `tss2` |
|
||
| 实体 @Alias `SswflowXxxEntity` | `TssXxxEntity` | `Tss2XxxEntity` |
|
||
| 业务库/数据源名 | `tss` | `tss2` |
|
||
| API 前缀 | `/api/ssw/tss` | `/api/ssw/tss2` |
|
||
| Java 包 | `ssw.tss.*` | `ssw.tss2.*` |
|
||
| Maven artifactId | `ssw-tss-*` | `ssw-tss2-*` |
|
||
| 业务基类 `SswflowServiceImpl` | `TssServiceImpl` | `Tss2ServiceImpl` |
|
||
|
||
> 关键点:**业务库名 == app_code**(双库架构下每个 app_code 独立库)。`dynamic.datasource.<app_code>` 与 `@DS("<app_code>")` 用同一个名字;`application-dev.yml` 里 `${SSWFLOW_DB:<app_code>}` 的默认值也填 app_code(tss2 即 `tss2`)。
|
||
|
||
### 16.2 完整父 pom / 聚合 pom(指南此前只给了 `<properties>`,缺可拼装的整文件)
|
||
|
||
`boot/pom.xml`(ssw-boot,父链 `ssw-boot → jnpf-common → jnpf-dependencies`):
|
||
|
||
```xml
|
||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||
<modelVersion>4.0.0</modelVersion>
|
||
<parent>
|
||
<groupId>com.jnpf</groupId>
|
||
<artifactId>jnpf-common</artifactId>
|
||
<version>7.0.0-RELEASE</version>
|
||
</parent>
|
||
<groupId>com.jnpf</groupId>
|
||
<artifactId>ssw-boot</artifactId>
|
||
<version>7.0.0-RELEASE</version>
|
||
<packaging>pom</packaging>
|
||
<properties>
|
||
<maven.compiler.source>17</maven.compiler.source>
|
||
<maven.compiler.target>17</maven.compiler.target>
|
||
<java.version>17</java.version>
|
||
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
|
||
<jnpf.version>7.0.0-RELEASE</jnpf.version>
|
||
<ssw.app-code>tss2</ssw.app-code>
|
||
</properties>
|
||
<modules>
|
||
<module>ssw-tss2</module>
|
||
<module>ssw-admin</module>
|
||
</modules>
|
||
<dependencies>
|
||
<dependency>
|
||
<groupId>org.projectlombok</groupId>
|
||
<artifactId>lombok</artifactId>
|
||
<scope>provided</scope>
|
||
</dependency>
|
||
</dependencies>
|
||
</project>
|
||
```
|
||
|
||
`boot/ssw-tss2/pom.xml`(业务聚合,下面挂 entity/biz/controller 三个子模块):
|
||
|
||
```xml
|
||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||
<modelVersion>4.0.0</modelVersion>
|
||
<parent>
|
||
<groupId>com.jnpf</groupId>
|
||
<artifactId>ssw-boot</artifactId>
|
||
<version>7.0.0-RELEASE</version>
|
||
</parent>
|
||
<artifactId>ssw-tss2</artifactId>
|
||
<packaging>pom</packaging>
|
||
<modules>
|
||
<module>ssw-tss2-entity</module>
|
||
<module>ssw-tss2-biz</module>
|
||
<module>ssw-tss2-controller</module>
|
||
</modules>
|
||
</project>
|
||
```
|
||
|
||
> 三个子模块 pom 见 §3.2(entity 依赖 `jnpf-common-all`+lombok;biz 依赖 entity;controller 依赖 biz + `spring-boot-starter-web`,见 16.4)。**构建命令必须带 `-am`**:`mvn -o package -DskipTests -pl ssw-admin -am`,否则 reactor 找不到 `ssw-tss2-*` 而报 `has not been downloaded`(修正 E)。
|
||
|
||
### 16.3 业务基类 `Tss2ServiceImpl` 的文件位置(指南 §9.4 只给了类体,没说放哪)
|
||
|
||
- 所属模块:**biz**(`ssw-tss2-biz`)。
|
||
- 包:`ssw.tss2.biz.service`(与 `ProjectService` 接口同包;其实现类放在 `ssw.tss2.biz.service.impl`)。
|
||
- 所有业务 Service Impl 继承它:`public class ProjectServiceImpl extends Tss2ServiceImpl<ProjectMapper, ProjectEntity> implements ProjectService`。
|
||
- 它已实现 `DynamicSourceGeneratorInterface`(`jnpf.database.plugins` 包,泛型 `<T extends DataSourceUtil> T getDataSource()`),并把库名固定为 `DS_KEY="tss2"`。子类**仍需各自打 `@DS("tss2")`**(注解不继承,见 §9.3)。
|
||
|
||
### 16.4 controller 模块需要 Spring MVC 注解
|
||
|
||
controller 用 `@RestController/@RequestMapping/@GetMapping/@PostMapping/@RequestBody`,这些来自 `spring-web` / `spring-webmvc`。它们经 `jnpf-common-all` 传递引入(JNPF 的 `jnpf-common-swagger` 等依赖 spring-webmvc),通常已在 classpath;若编译报 `找不到 org.springframework.web...`,在 controller 的 pom 显式加(版本由 `jnpf-dependencies` BOM 托管,无需写 `<version>`):
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-web</artifactId>
|
||
</dependency>
|
||
```
|
||
|
||
### 16.5 验证结果(tss2,仅依据本指南)
|
||
|
||
**第一轮:构建期验证**
|
||
|
||
| 验证项 | 命令 | 结果 |
|
||
|---|---|---|
|
||
| 后端离线编译+打包 | `cd boot && mvn -o package -DskipTests -pl ssw-admin -am` | ✅ BUILD SUCCESS,产物 `ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar`(370 MB,已 repackage) |
|
||
| 前端构建 | `cd tss2-web && npm install && npm run build` | ✅ 产出 `dist/` |
|
||
| jar 内含 initializer | `unzip -l ...jar \| grep ApplicationContextInitializer` | ✅ `META-INF/spring/...` 存在,且 `SswAdminApplication` 代码注册兜底(修正 F) |
|
||
|
||
**第二轮:运行期端到端验证**(本轮补做,也正是本轮修正 §8.2 的来源)
|
||
|
||
| 验证项 | 结果 |
|
||
|---|---|
|
||
| Redis 连接 | ✅ `24 connections initialized for 127.0.0.1:6379` |
|
||
| 双数据源装载 | ✅ `add a datasource named [tss2] success` + `[master] success`,`primary=master` |
|
||
| 服务启动 | ✅ Tomcat 30000,`/api/oauth/Login` 返回 200(启动约 90s) |
|
||
| 密码算法自检 | ✅ `encryptPassword("123456") = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`(官方 md5 约定,96-hex) |
|
||
| 登录取 token | ✅ `code=200`,返回 `bearer eyJhbGciOiJIUzI1NiIs...` |
|
||
| 鉴权 + 业务写入 | ✅ `POST /api/ssw/tss2/Project` → `code=200` |
|
||
| 业务读取 | ✅ `GET /api/ssw/tss2/Project/All` → 读回刚写入的记录 |
|
||
| **`@DS("tss2")` 真实路由** | ✅ 数据只出现在 `tss2` 库;`j7` 库**根本不存在** `project` 表(`information_schema` 计数 = 0) |
|
||
| 前端 Vite 代理链路 | ✅ 经 `http://127.0.0.1:5173` 代理跑同一套烟测,同样全绿 |
|
||
|
||
```
|
||
$ node scripts/smoke.mjs --base=http://127.0.0.1:30000
|
||
[1] cipher self-check: PASS
|
||
md5(key) = 05b0175907a859751f57a04d5a5ee9ac
|
||
cipher = d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b
|
||
[2] login tss2dev @ http://127.0.0.1:30000
|
||
http = 200 | code = 200 | token? yes
|
||
[3] business POST /api/ssw/tss2/Project name=smoke-1785560577257
|
||
http = 200 | code = 200 | msg = ok
|
||
[4] business GET /api/ssw/tss2/Project/All
|
||
http = 200 | code = 200 | rows = 1
|
||
DONE 端到端链路通过:登录 -> 鉴权 -> @DS("tss2") 写入 -> 读出
|
||
```
|
||
|
||
### 16.6 运行期实测暴露的 5 个坑(构建期发现不了)
|
||
|
||
按踩到的先后顺序记录,每个都会直接卡死流程:
|
||
|
||
**① `server.port` 被环境变量悄悄改掉**
|
||
|
||
现象:`application-dev.yml` 明明写了 `server.port: 30000`,实际却绑到随机高位端口。
|
||
根因:宿主机存在 `SERVER__PORT` / `SERVER_PORT` 环境变量,Spring Boot 的 relaxed binding 把它映射成 `server.port`,
|
||
**环境变量优先级高于配置文件**。实测 `env -u SERVER__PORT` 后即恢复 30000。
|
||
|
||
```bash
|
||
env | grep -i "SERVER.*PORT" # 先排查
|
||
java -jar ssw-admin.jar --spring.profiles.active=dev --server.port=30000 # 命令行显式指定最稳
|
||
```
|
||
|
||
**② jar 跑在宿主机时,数据源地址不能用容器名**
|
||
|
||
`jnpf-admin` 原配置是 `host: jnpf-postgres / port: 5432`(docker 网络内地址)。
|
||
jar 直接在宿主机跑时必须换成**发布端口**,否则 `UnknownHostException`:
|
||
|
||
```yaml
|
||
spring:
|
||
datasource:
|
||
host: ${DB_HOST:localhost} # 宿主机跑 → localhost
|
||
port: ${DB_PORT:15432} # PG 容器的发布端口,不是 5432
|
||
```
|
||
|
||
Redis 同理:若容器没做端口映射(`docker ps` 的 PORTS 列只有 `6379/tcp` 而没有 `0.0.0.0:6379->`),
|
||
宿主机根本连不上,必须另起一个带 `-p` 的实例:
|
||
|
||
```bash
|
||
docker run -d --name tss2-redis -p 6379:6379 redis:7 --requirepass 123456
|
||
docker exec tss2-redis redis-cli -a 123456 ping # 期望 PONG
|
||
```
|
||
|
||
**③ 业务数据源的 YAML 层级容易写错一层**
|
||
|
||
必须是 `spring.datasource.dynamic.**datasource**.<app_code>`,少写中间那层 `datasource` 就不会注册,
|
||
而 `strict: true` 下 `@DS("tss2")` 会直接抛「数据源不存在」:
|
||
|
||
```yaml
|
||
spring:
|
||
datasource:
|
||
dynamic:
|
||
primary: master
|
||
strict: true
|
||
datasource: # ← 这一层别漏
|
||
tss2:
|
||
url: jdbc:postgresql://${spring.datasource.host}:${spring.datasource.port}/${TSS2_DB:tss2}?currentSchema=public&stringtype=unspecified
|
||
username: ${spring.datasource.username}
|
||
password: ${spring.datasource.password}
|
||
driver-class-name: org.postgresql.Driver
|
||
lazy: false
|
||
```
|
||
|
||
> 启动日志出现下面三行才算真的装上了:
|
||
> ```
|
||
> add a datasource named [tss2] success
|
||
> add a datasource named [master] success
|
||
> initial loaded [2] datasource,primary datasource named [master]
|
||
> ```
|
||
|
||
**④ 文件存储根路径必须可写**
|
||
|
||
`config.file-storage.local-plus[0].base-path` 默认 `/workspace/jnpf-resources/`(容器内路径)。
|
||
宿主机没有 `/workspace` 且创建需要 root,改成工程内目录:
|
||
|
||
```yaml
|
||
base-path: ${TSS2_RESOURCE_PATH:/abs/path/to/tss2/.runtime/resources/}
|
||
```
|
||
|
||
**⑤ 后台启动的进程会被 shell 回收**
|
||
|
||
`nohup java -jar ... &` 在某些受控 shell 里,父 shell 退出时子进程一起没了(日志停在半路、无端口监听、
|
||
`jps` 查不到)。排查时先 `jps -lm` 确认进程还在,再看日志。稳妥做法是让 java 占据前台(`exec java -jar ...`)
|
||
由外层作业管理托管,或用 `screen`/`tmux`/`systemd`。
|
||
|
||
### 16.7 application.yml 仅为「差异补丁」
|
||
|
||
- `ssw-admin/src/main/resources/application.yml` 在指南里**只提供「必须新增/修正」的键**(`allow-bean-definition-overriding`、`mvc.pathmatch.ant_path_matcher`、`gateway.exclude-url`)。完整的 JNPF 平台配置(mybatis-plus、sa-token、`security.security-key`、spring.redis 等)请沿用 `jnpf-admin` 的 `application.yml` 并把上述键合并进去——这正是 〇-B.3「复制 jnpf-admin 资源」的本意。单独用本指南给出的 `application.yml` 片段**无法启动**(缺 JNPF 必需配置),这是预期,不是指南缺陷。
|
||
- `application-dev.yml` 已给出可直接用的双数据源(master/j7 + `dynamic.datasource.tss2`)与 redisson 配置,变量默认 `localhost`/`15432`,可用 `-DDB_HOST=... -DREDIS_HOST=...` 或同名环境变量覆盖(详见 §11 / §12.1)。
|
||
|
||
### 16.8 造验证账号的完整可复制脚本
|
||
|
||
不要试图猜 `admin` 的密码(实测该环境 admin 密码非 `123456`)。直接造一个自己的账号,
|
||
三步缺一不可(少任何一步都登录失败,对应错误码见 §8.2-B):
|
||
|
||
```bash
|
||
# ── 步骤 0:算出入库摘要(官方约定:S = md5(明文))───────
|
||
# f_password = md5( md5(明文) + f_secretkey.toLowerCase() )
|
||
node -e "const c=require('crypto');const m=s=>c.createHash('md5').update(s,'utf8').digest('hex');
|
||
console.log(m(m('123456')+'tss2dev-secret-key-001'))"
|
||
# => 2898aa333ba4efb48658db85e10d9fd9
|
||
```
|
||
|
||
```sql
|
||
-- ── 步骤 1:复制 admin 行建账号(最省事,公共列自动带全)──
|
||
INSERT INTO base_user
|
||
SELECT * FROM base_user WHERE f_account = 'admin';
|
||
UPDATE base_user SET
|
||
f_id = 'tss2dev-001',
|
||
f_account = 'tss2dev',
|
||
f_password = '2898aa333ba4efb48658db85e10d9fd9',
|
||
f_secretkey = 'tss2dev-secret-key-001',
|
||
f_is_administrator = 1,
|
||
f_enabled_mark = 1 -- ← 步骤 2:必须为 1,否则 LOG005
|
||
WHERE f_id = (SELECT f_id FROM base_user WHERE f_account='admin') -- 注意先改 id 再改其它
|
||
AND f_account = 'admin';
|
||
|
||
-- ── 步骤 3:挂角色,否则 LOG004「账号权限不足」──────────
|
||
INSERT INTO base_role_relation
|
||
(f_id, f_role_id, f_object_type, f_object_id, f_creator_time, f_creator_user_id, f_delete_mark, f_tenant_id)
|
||
VALUES ('tss2dev-rel-001', '666911261245571844', 'user', 'tss2dev-001', now(), 'tss2dev-001', 0, '');
|
||
```
|
||
|
||
> `base_role_relation` **没有唯一约束**,`ON CONFLICT (f_id)` 会直接报
|
||
> `there is no unique or exclusion constraint matching the ON CONFLICT specification`。
|
||
> 需要幂等就先 `DELETE FROM base_role_relation WHERE f_id='...';` 再 INSERT。
|
||
|
||
验证账号可用性:
|
||
|
||
```bash
|
||
node tss2-web/scripts/smoke.mjs --base=http://127.0.0.1:30000 --account=tss2dev --password=123456
|
||
```
|
||
|
||
## 附:本增强版相对原版的全部修订(CHANGELOG)
|
||
|
||
- **A · `scanBasePackages`**:`{"com.jnpf","ssw"}` → `{"jnpf","ssw"}`,并加醒目说明:`com.jnpf` 仅 Maven groupId,Java 顶级包是 `jnpf`。
|
||
- **B · 实体基类**:`EntityBase` → `SuperEntity<String>`(含 `SuperBaseEntity` 的 `id`),公共字段表补全为 9 列,明确"勿重复声明"。
|
||
- **C · entity 依赖**:删除无 version 的 `mybatis-plus-boot-starter` / `dynamic-datasource-spring-boot-starter`(随 `jnpf-common-all` 传递引入),补"如需锁版本必须显式 `<version>`"。
|
||
- **D · lombok**:明确 entity(及使用 `@Data` 的模块)需自行声明 `org.projectlombok:lombok`(provided);父 `ssw-boot` 也已全局加。
|
||
- **E · 构建命令**:`mvn package -DskipTests -pl ssw-admin -o` → `mvn -o package -DskipTests -pl ssw-admin -am`(补 `-am`)。
|
||
- **F · initializer**:FQN `jnpf.SpringContext` → `jnpf.util.context.SpringContext`;并强制 `SswAdminApplication.main()` 代码注册(repackage 会把 META-INF 提到 fat-jar 根导致读不到)。
|
||
- **G · `getDataSource`**:补充接口真实泛型签名 `<T extends DataSourceUtil> T getDataSource()` 与 `init(String)` 返回 `DbLinkEntity`(其父类为 `DataSourceUtil`),澄清原写法可编译。
|
||
- **H · 密码算法(2026-08-01 最终定稿)**:经反编译官方字节码 + dacli 实测 + `tss2` 运行期验证三证对齐,定为**双约定模型**。传输层内层 S 分两种:**官方默认** `S = md5(明文)`(密文 96-hex,基准 `d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b`),**旧变体(legacy)** `S = 明文`(密文 32-hex,基准 `ea80d323686b9dfe734f2b42159db1a6`);存储层 `f_password = md5( S + f_secretkey.toLowerCase() )`。两条约定都合法但互不相通,登录失败通常是选错约定。`SecurityProperties.setSecurityKey` 的 setter 内部自动做 MD5,配置的 16 字符 key 实际变 32 字节 → AES-**256**;dacli `src/core/crypto.ts` 与本仓库 `tss2` 均用官方约定。
|
||
- **I · 烟测脚本**:新增零依赖 `scripts/smoke.mjs`(自检+登录+业务接口,可传参)。
|
||
- **J · `allow-bean-definition-overriding`**:`application.yml` 必须 `true`(JNPF 内部同名 bean)。
|
||
- **K · `mvc.pathmatch`**:`application.yml` 必须 `ant_path_matcher`。
|
||
- **附 · `ssw-admin/pom.xml`**:补全 JNPF 全部 controller 依赖清单(oauth/permission/system/file/message/extend/flowable/scheduletask/visualdev-*/visualdata/app)+ boot3 激活 `jnpf-ai-v3-controller`。
|
||
- **附 · `application.yml` / `application-dev.yml`**:给出与 JNPF 7.0 对齐的完整可运行样例(含 dynamic.datasource、redisson 无密码对齐、`mvc.pathmatch`、`allow-bean-definition-overriding`)。
|
||
- **附 · 脚手架落地**:本仓库已按 `app_code=tss` 落地完整可编译脚手架(`boot/` + `tss-web/`),上述每一处修正均经真实 `mvn -o package -pl ssw-admin -am` 与 `npm run build` 复核通过。
|
||
- **附 · tss2 二次落地(十六节)**:在不参考其它脚手架、不启用容器的前提下,仅依据本指南从零落地第二个应用 `tss2`(本仓库 `tss2/`),后端 `mvn -o package -pl ssw-admin -am` 与前端 `npm run build` 均通过、密码自检 PASS,证明指南可复用。新增内容:`ssw-boot`/`ssw-{app_code}` 完整父 pom 与聚合 pom(16.2)、`Tss2ServiceImpl` 文件位置(16.3)、controller 模块 spring-web 依赖说明(16.4)、tss2 命名映射表(16.1)、无容器验证方案与 `application.yml` 仅为差异补丁说明(16.6)。
|
||
- **附 · 示例占位通用化**:「示例占位约定」由固定的 `sswflow → tss` 改为 `sswflow → <你的 app_code>`,并明确**业务库名 == app_code**,避免第二次落地时误以为库名仍为 `sswflow`。
|
||
- **附 · tss2 运行期端到端验证(本轮补做)**:在真实 PostgreSQL + 新建 `tss2-redis` 上跑通「启动 → 登录 → 鉴权 → `@DS("tss2")` 写入 → 读出」,并核实数据只落在 `tss2` 库、`j7` 库无 `project` 表。由此新增:§8.2 密码算法全面重写(修正 H)、§8.2-B 自建账号 LOG004 授权坑与登录错误码速查表、§16.5 运行期验证结果表、§16.6 运行期五坑(`SERVER__PORT` 覆盖端口 / 容器名 vs 发布端口 / `dynamic.datasource` 少一层 / 文件存储路径不可写 / 后台进程被 shell 回收)、§16.8 造验证账号完整脚本;§13 速查表同步扩充 6 条。
|