JNPF 后端服务

基于 Spring Cloud Alibaba 的低代码微服务平台（v6.1.0-RELEASE），业务侧包含 LIMS（实验室信息管理）、DMS（文档管理）等模块。

配套仓库：

bostal/
├── jnpf-java-cloud-v6x                    # 后端（本仓库）
└── jnpf-web-monorepo-framework-v6.1       # 前端（pnpm monorepo）

一、macOS 本机启动（start-all.sh）

start-all.sh 是宿主机 java -jar 形态的批量启动脚本：Java 服务直接跑在 macOS 上，基础设施（PostgreSQL / Redis / 流程引擎 / OnlyOffice）跑在 Docker 里。相比全栈容器，改一行代码重启单个服务只要几十秒。

0. 前置条件

依赖	要求	说明
JDK	21（推荐）或 17	镜像基底是 `bellsoft/liberica-openjre-rocky:21`；流程引擎工程要求 21
Maven	3.6.3+	无 mvnw wrapper，需系统安装
Docker Desktop	任意近期版本	起基础设施容器
PostgreSQL	已建好的实例	库结构与初始数据不在本仓库内，由甲方提供。需要两个库：业务库 `jnpf_init`（角色 `jnpf_app`）、流程引擎库 `jnpf_flow`（角色 `jnpf_flow_app`）

macOS 自带 bash 是 3.2，脚本已按 3.2 语法编写（无关联数组、空数组用 ${arr[@]+...} 展开），直接 ./start-all.sh 即可，不需要装 bash 5。

1. 配置 hosts

宿主进程要用容器名解析到本机，一次性写入 /etc/hosts：

127.0.0.1 cx-infra cx-redis cx-flow-engine

2. 准备 .env

cp .env.example .env

至少确认这几项（.env.example 内每一节都有详细注释）：

键	说明
`CUSTOMER_DB_HOST` / `CUSTOMER_DB_PORT`	数据库坐标。业务库和流程引擎库都由这一组推导，必然同源
`JNPF_APP_DB_USER` / `JNPF_APP_DB_PASSWORD`	业务库凭据
`JNPF_FLOW_DB_USER` / `JNPF_FLOW_DB_PASSWORD`	流程引擎库凭据
`JNPF_REDIS_PASSWORD`	Redis `requirepass`，业务侧同值透传
`ONLYOFFICE_JWT_SECRET`	必填，缺了 compose 起不来；只在需要文档在线编辑时才关心
`COMPOSE_PROFILES`	用外部数据库时注释掉这一行（它控制是否启动栈内 PG 容器）

两个坑：

不要设 JNPF_FLOW_DB_URL。它是整串覆盖的逃生口，会把流程引擎库和业务库拆成两个来源，症状是流程模板大面积「找不到流程模板」。
数据库坐标写 cx-postgres 时，start-all.sh 会**自动翻译成 127.0.0.1:5433**（compose 只把栈内 PG 发布到 5433，避免和系统 PG 撞车）。指向外部实例（IP 坐标）时这个翻译不生效。启动时脚本会打印实际使用的坐标，可以据此确认连的是哪个库。

3. 启动服务

./start-all.sh

前台运行，实时打印每个服务的就绪状态，Ctrl+C 统一停止。首次运行若缺 JAR 会自动编译对应模块。

命令速查

./start-all.sh                              # 前台启动全部（缺 JAR 自动补编）
./start-all.sh --build                      # 先全量编译再启动
./start-all.sh restart                      # 停止 → 编译 → 启动
./start-all.sh stop                         # 停止全部（可在另一个终端执行）
./start-all.sh status                       # 查看运行状态
./start-all.sh help                         # 完整帮助

./start-all.sh jnpf-lims                    # 只启动 lims
./start-all.sh restart jnpf-lims            # 只重启 lims（仅编译该模块，快很多）
./start-all.sh stop jnpf-lims               # 只停 lims，不影响其他服务
./start-all.sh status jnpf-lims             # 只看 lims
./start-all.sh restart jnpf-lims jnpf-platform   # 多服务一起

日常开发最常用的是 ./start-all.sh restart jnpf-lims —— 它用 mvn -pl <模块> -am 只编译目标模块及其依赖，比全量 mvn package 快一个数量级。

启动编排

脚本不是一股脑全拉起来的：

阶段 1：先起网关（30000），等端口就绪
阶段 2：业务服务分四波，波与波之间过负载闸门

| 波次 | 服务 |
|---|---|
| 1 | jnpf-platform |
| 2 | jnpf-biz-common |
| 3 | jnpf-lims、jnpf-dms |
| 4 | 其余（当前是 jnpf-eln） |

闸门逻辑：读 vm.loadavg，负载 ≥ LOAD_GATE（默认 9）就等 20s 再放下一波。4 个业务 JVM 同时启动会瞬间打满 CPU，导致 Druid 建连超时。

指定服务子集且不超过 4 个时**直启不分波**，重启单个服务不会被波次拖慢。

可调环境变量：

变量	默认	说明
`SERVICE_READY_TIMEOUT`	360	等待就绪的最长秒数
`JNPF_SERVICE_MAX_HEAP`	384m	单服务堆上限
`JNPF_PLATFORM_MAX_HEAP`	1536m	`jnpf-platform` 例外档（九个模块同一个 JVM）
`LOAD_GATE`	9	分波负载闸门

用法：JNPF_SERVICE_MAX_HEAP=512m ./start-all.sh jnpf-lims

日志与排障

位置	内容
`log/<服务名>/startup.log`	宿主栈的启动与运行日志（脚本重定向的 stdout/stderr）
`.pids/<服务名>.pid`	进程 PID，`stop` / `status` 靠它跨终端管理

常见状态含义：

[跳过] ... 已在运行 — PID 文件里的进程还活着
[失败] ... 端口 X 已被未登记进程占用 — 端口上有进程但不是本脚本启动的，脚本不会去动它，需要自己 lsof -i :X 处理
[未登记]（status 输出）— 同上，端口在监听但没有对应 PID 文件
[超时] — 进程活着但超时未监听端口，去 log/<服务名>/startup.log 看栈

关于 OnlyOffice

宿主栈下，Document Server 在容器里而后端在宿主上，容器内的 127.0.0.1 指向容器自己。脚本已自动导出三个地址变量走 host.docker.internal，正常情况下不用在 .env 里配；显式配了则以 .env 为准。

二、模块划分

服务拓扑

服务	端口	职责
`jnpf-gateway`	30000	API 网关，路由转发。基于 WebFlux，与 servlet 栈不能同进程，必须独立部署
`jnpf-platform`	30002	平台聚合服务：下列九个平台模块合并在一个 JVM 内
`jnpf-scheduletask`	30009	定时任务（xxl-job admin），未并入 platform
`jnpf-eln`	30013	ELN 电子实验记录（当前为骨架）
`jnpf-biz-common`	30015	公共业务能力聚合：OnlyOffice、审计等
`jnpf-dms`	30016	文档管理
`jnpf-lims`	30019	LIMS 实验室信息管理，主要业务模块
`jnpf-flow-engine`	31000	Flowable 7.0.1 流程引擎。独立工程，不在根 pom，用独立数据库 `jnpf_flow`

jnpf-platform 内含的九个模块：

模块	原端口	职责
`jnpf-oauth`	30001	认证授权（Sa-Token + JWT）
`jnpf-system`	30002	平台核心：字典、权限、数据接口；同时是 Dubbo `LogProvider` 的唯一 provider（20880）
`jnpf-visualdev`	30003	在线开发引擎（表单/列表设计器）
`jnpf-flowable`	30004	工作流业务层，注册名是 `jnpf-workflow`（真引擎是上面的 flow-engine）
`jnpf-file`	30005	文件管理
`jnpf-message`	30008	消息中心
`jnpf-permission`	30010	权限管理
`jnpf-visualdata`	30011	数据可视化
`jnpf-app`	30012	移动端服务

九个模块合并进一个 JVM 后内存占用从约 6.7GB 降到 1.07GB。**九个服务名全部保留为服务发现表里的别名**，指向 30002 —— 所以 60 多个 @FeignClient、网关的 lb:// 路由、各类脚本都不需要改动，写代码时照旧按原服务名调用即可。九个 *-server 模块的源码也保留着，由各自父 pom 的 microservice profile 门控，回滚不需要改代码。

同理，审计能力已并入 jnpf-biz-common，但服务名 jnpf-audit 和路由前缀 /api/audit/ 都刻意保留为别名，调用方零改动。

API 路由前缀

前端请求 → 网关（30000）→ 按前缀转发：

前缀	目标
`/api/lims/`、`/api/extend/`（旧前缀，同指）	jnpf-lims
`/api/dms/`	jnpf-dms
`/api/eln/`	jnpf-eln
`/api/biz/`	jnpf-biz-common（如 `/api/biz/onlyoffice/xxx`）
`/api/audit/`	jnpf-biz-common（别名保留）
`/api/oauth/` `/api/system/` `/api/visualdev/` `/api/workflow/` `/api/file/` `/api/message/` …	jnpf-platform（经服务名别名解析）

完整路由表在 config/shared/router.yaml。

业务模块分层

以 jnpf-lims 为例，其他业务模块（dms/eln）结构相同：

jnpf-lims/
├── jnpf-lims-entity        # 实体类、DTO、枚举
├── jnpf-lims-biz           # Service + Mapper
├── jnpf-lims-controller    # REST 控制器
├── jnpf-lims-api           # Feign 远程调用接口
└── jnpf-lims-server        # Spring Boot 启动入口 + 配置

包名统一用 lims 前缀：

层	路径
Entity	`jnpf-lims-entity/src/main/java/jnpf/limsEntity/`
Mapper	`jnpf-lims-biz/src/main/java/jnpf/limsMapper/`
Service	`jnpf-lims-biz/src/main/java/jnpf/limsService/`
Controller	`jnpf-lims-controller/src/main/java/jnpf/limsController/`

公共依赖链

jnpf-common（parent POM）
  └── jnpf-public/jnpf-cloud-base          # 静态服务发现 + 核心工具
       └── jnpf-public/jnpf-common-springaop  # AOP + Sa-Token + Sentinel + Swagger
            └── 各业务服务

开发约定

Controller 只做请求/响应转换，业务逻辑在 Service 层
新建 Mapper 后确认启动类的 @MapperScan 能扫描到
实体字段命名跟随数据库列名（拼音风格，如 jianyan_liushuihao、chanpin_mingcheng）
🔴 业务字段禁止以 f_ 开头：这是平台技术列的保留前缀（f_id / f_tenant_id / f_version / f_delete_mark / f_creator_time / f_flow_state 等），审计层正是靠这个前缀剔除技术列
ORM 用 MyBatis-Plus（@TableName + BaseMapper<T>）
标准响应格式：{code: 200, msg: "...", data: ...}

构建

mvn clean package -DskipTests                                    # 全量（约 10 分钟）
mvn clean package -DskipTests -pl jnpf-lims/jnpf-lims-server -am  # 只构建 lims
make jars                                                        # 打包全部业务 jar

构建 profile：default-package（fat JAR，默认）、external-package（依赖外置）。

三、配置机制

没有配置中心。配置是仓库内的 YAML 文件 + 环境变量占位符，三层组合。

三层结构

层	位置	作用	是否进镜像
共享配置	`config/shared/*.yaml`	单一事实源。所有环境共用同一份结构	✅ `/config/shared`
宿主覆盖	`config/host-override/*.yaml`	宿主 `java -jar` 栈的差异覆盖	❌ 只存在于工作区
环境值	仓库根 `.env`	真实的密码、坐标、域名	❌ 不入库

规则很简单：**config/shared/ 里只写结构和占位符，真实值一律走 .env**。

# config/shared/datasource.yaml 里长这样
  datasource:
    db-type: PostgreSQL
    db-name: jnpf_init
    host: ${CUSTOMER_DB_HOST:cx-postgres}
    port: ${CUSTOMER_DB_PORT:5432}
    username: ${JNPF_APP_DB_USER:jnpf_app}
    password: ${JNPF_APP_DB_PASSWORD:jnpf_app_2026}

占位符的默认值 = 本机 compose 开发形态，所以 cp .env.example .env 之后基本可以直接跑。

config/shared/ 下按关注点分文件：datasource.yaml（数据源/Redis）、discovery.yaml（服务发现）、router.yaml（网关路由）、logger.yaml（日志）、resources.yaml（文件存储）、system-config.yaml（域名等）、jnpf-biz-common.yaml、jnpf-dms.yaml（模块专属）等。

两种运行形态共用一份配置

.env 同时被两边读取：

容器栈：docker compose 自动读仓库根 .env，注入容器环境
宿主栈：start-all.sh 启动时逐行解析 .env 并 export

差异只在 config/host-override/。目前只有一份 discovery.yaml —— 服务发现表里，容器栈解析到容器名（cx-platform:30002），宿主栈整表覆盖为 127.0.0.1:30002。这个文件在容器内不存在，Spring 的 optional: 导入落空即跳过，所以同一份 application.yml 能双栈通用。

.env 里同名键**后出现的覆盖先出现的**；启动前已在环境里的变量不会被 .env 覆盖，所以可以 FOO=bar ./start-all.sh 临时改值。

静态服务发现

没有 Nacos。config/shared/discovery.yaml 是一张 SimpleDiscoveryClient 实例表，直接把服务名映射到 URI：

spring.cloud.discovery.client.simple.instances:
  jnpf-lims:
    - uri: http://cx-lims:30019

消费方是所有 @FeignClient 的 lb 解析、网关的 lb:// 路由、knife4j 的文档聚合。

⚠️ 新增服务要同步三处：config/shared/discovery.yaml、config/host-override/discovery.yaml、docker-compose.yml。漏掉任何一处，对应形态下的调用会 502。

改配置后怎么生效

场景	操作
改 `config/**` 或 `.env`，宿主栈	`./start-all.sh stop && ./start-all.sh`（Druid 连接池在启动时定死，不热更新）
改 `config/**`，容器栈	rebuild 镜像，或用 volume 挂载覆盖 `/config/shared`（开发用的 override 已经挂好）
交付现场改结构级配置	挂载覆盖 `/config/shared` 即可，不必重建镜像

数据库

主库 PostgreSQL；代码层同时兼容 MySQL、Oracle、SQLServer、DM8、KingbaseES
业务库 jnpf_init 和流程引擎库 jnpf_flow 由同一组坐标推导，**必须同源**
连接池配额通过 JNPF_APP_CONN_LIMIT / JNPF_FLOW_CONN_LIMIT 分配，两者之和要小于实例 max_connections − 3，避免单个角色占满连接槽饿死另一个