Dockerfile 构建的是 jnpf-claude 开发镜像(ubuntu + Claude Code CLI), 对应 compose 服务块早已整段注释, 全仓库无 build: 段引用, 无容器无镜像, 且违反 §7.1「不重打镜像」。移入回收站。 docker-compose.yml 保留 —— 它是本机正在跑的 jnpf-gitea/jnpf-postgres/ jnpf-redis 三个容器唯一的完整定义, 也是 §1 那几个复用镜像 (liberica-openjre-rocky:21 / nginx:latest) 的唯一出处, 删了 Gitea 无法重建。 - 头部换成实际内容: 只跑 3 个服务, JNPF 服务块已随 K8s 迁移注释掉 - 标注路径陷阱: 挂载全是相对 ./persist/..., 而 persist/ 是 testspace 的 兄弟目录, 在本目录跑会静默起一套空 PG+Gitea 且容器名冲突 - 记录 gitea 容器 compose 标签指向的旧路径已不存在, 本文件是幸存副本 - AGENTS.md §3 补 Dockerfile 行 + compose/Dockerfile 对照表, §10 同步 - 顺手订正 §10: kkfile 在 compose 里不是「注释状态」而是完全没有条目 Co-Authored-By: Claude Code <[email protected]>
76 KiB
AGENTS.md — jnpf-v7 on k8s(wuguirong 租户)
JNPF v7 低代码平台在 wuguirong 租户 K8s 的完整部署。目标:让大家能各自建应用做测试/开发,AI 操作用 ../dacli 辅助。
1. 现状:一句话
8 个 Deployment 全部 Running,Web 端 http://192.168.1.26:30093/,host@admin / 123456 登录已验证通过(含租户切换链路),租户管理中心 http://192.168.1.26:30095/(admin / 123456)也验证通过,dacli 登录同样通过。已开启多租户(config.MultiTenancy: true,架构见 §6.9,租户端前端见 §6.11)。
本次部署不构建、不推送任何自定义镜像 —— 全部复用现成的 5 个镜像(4 个来自 compose 时代,加上用户指定的 kkFileView),产物(jar / 前端静态资源)以 tar 落在 NFS PVC 上。这条是硬要求,见 §7。
| 组件 | 镜像 | Service | 端口 |
|---|---|---|---|
| jnpf-admin(主服务 + AI) | ssw188/liberica-openjre-rocky:21 |
jnpf |
30000 / 39999 |
| jnpf-tenant(租户管理中心) | ssw188/liberica-openjre-rocky:21 |
jnpf-tenant |
30006(ClusterIP,不开 NodePort) |
| jnpf-web(入口 nginx,2 个 server 块) | ssw188/nginx:latest |
nginx / jnpf-tenant-web |
NodePort 30093(主站 8080)+ 30095(租户端 8081) |
| jnpf-workflow(Flowable) | ssw188/liberica-openjre-rocky:21 |
jnpf-workflow |
31000 |
| jnpf-report(Univer 报表/大屏) | ssw188/liberica-openjre-rocky:21 |
jnpf-report |
32000 |
| jnpf-xxl(调度台) | ssw188/liberica-openjre-rocky:21 |
jnpf-xxl |
NodePort 30094 |
| jnpf-postgres | ssw188/postgres:16-alpine |
postgres / jnpf-postgres |
NodePort 30092 |
| jnpf-redis | ssw188/redis:latest |
redis / jnpf-redis |
6379 |
| jnpf-kkfile(预览) | ssw188/kkfile:1.1 |
jnpf-kkfile |
30090 |
所有镜像全名(集群用阿里云 CR 前缀):
crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/<image>:<tag>
2. 入口信息(给使用方)
Web http://192.168.1.26:30093/ host@admin / 123456
SSO http://192.168.1.26:30093/api/ssw/tds/SsoBind/login?tenant=<租户号> 公司 ipass 账号直接登
租户端 http://192.168.1.26:30095/ admin / 123456
调度台 http://192.168.1.26:30094/xxl-job-admin/ admin / 123456
数据库 postgresql://dacli:[email protected]:30092/{j7,j7flow,j7xxl,j7tenant,sswflow,dacli_kb}
SSO 登录(推荐给同事):登录页底部就有「公司统一认证」区 —— 填自己的租户号 → 点「IPASS 登录」,跳 ipass 授权页,登录完直接进 JNPF,不用记账号密码。首次会自动建本地用户并挂「开发者」角色。也仍可直接打开 SsoBind/login?tenant=<自己的租户号> 这个链接;tenant 省略则用默认租户 host。细节见 §6.13,按钮的前端构建流程见 §6.14。
多租户登录:账号必须带租户号(租户号@账号)。02-seed-db.sh 预先登记了宿主租户 host(映射到 j7 的 public schema),所以本部署原来的数据用 host@admin 登录即可;新建租户后用 新租户号@admin 登录。不带 @ 的 admin 会被整个当成租户号去查 → 租户不存在。细节见 §6.9。
租户端(30095)是第三套账号体系,跟上面两套都不同,别混:
| 入口 | 账号 | 密码 | 存在哪 |
|---|---|---|---|
| 主站 30093 | 租户号@账号(如 host@admin) |
123456 | 租户自己的 schema 的 base_user |
| 租户端 30095 | admin(不带租户号) |
123456 | j7tenant.base_tenant_account |
| 调度台 30094 | admin |
123456 | j7xxl.xxl_job_user |
租户端登录的是 POST /api/tenant/login,密码存的是 md5(md5(明文))(两端各 md5 一次,见 §6.11),重置用 RESET_TENANT_ADMIN=1 ./scripts/02-seed-db.sh。
dacli 接入(每个人在自己电脑上设这 3 个环境变量):
export JNPF_BASE_URL=http://192.168.1.26:30093/api
export JNPF_WEB_URL=http://192.168.1.26:30093
export VITE_CIPHER_KEY=EY8WePvjM5GGwQzn # 见 §6.3,缺了 dacli 拒绝登录
VITE_CIPHER_KEY 是 JNPF 前端登录口令的加密密钥,值来自 ../jnpf/jnpf-app-vue3/utils/define.js 的 cipherKey。dacli 用 md5(cipherKey) 做 AES-ECB 加密口令,后端解不开就 400。不要用 xop get -v 之类的手段取密钥,这个值本身就在公开前端源码里,直接给即可。
3. 目录结构
jnpf-k8s/
├── k8s/ # K8s 清单(按应用顺序命名,数字前缀即 apply 顺序)
│ ├── 00-sync-pod.yaml # 产物同步用的临时 Pod(脚本自动建/删)
│ ├── 05-pvc.yaml # 3 个 PVC
│ ├── 10-infra.yaml # postgres + redis
│ ├── 20-admin.yaml # ConfigMap(admin/wait-db) + jnpf-admin + Service
│ ├── 30-web.yaml # nginx + Service nginx(NodePort 30093) + Service jnpf-tenant-web(NodePort 30095)
│ ├── 40-satellites.yaml # workflow / report / xxl
│ ├── 45-kkfile.yaml # kkFileView 文件预览
│ └── 50-tenant.yaml # ConfigMap + jnpf-tenant + Service(ClusterIP)
├── build/ # 产物源(从这里同步进 PVC)
│ ├── admin/app.jar # ssw-admin.jar 367M
│ ├── workflow|report|xxl/app.jar
│ ├── tenant/app.jar # jnpf-tenant-7.0.0-RELEASE.jar 188M(本机 mvn -o package)
│ ├── tenant/config/ # tenant 的部署期覆盖配置(挂 ConfigMap)
│ ├── tenantApi/ # JNPF-PostgreSQL.sql —— 建租户 schema 时现场灌
│ ├── jnpf-resources/ 文件存储的**内置**资源(ProjectLogo/Avatar/…,15M,见 §6.15)
│ ├── web/{dist,datav,public} # 前端静态资源
│ ├── tenant-web/ # 多租户管理中心前端(jnpf-web-tenant-vue3 的 vite 产物,见 §6.11)
│ ├── pg/*.sql # 4 个灌库 SQL(128M,含 jnpf_tenant_init.sql)
│ ├── nginx/{nginx.conf,default.conf}
│ └── java-start.sh # 5 个 java 服务共用的启动器
├── scripts/
│ ├── 01-artifacts.sh # 产物 → NFS PVC(按文件数+字节比对,相同则跳过)
│ ├── 02-seed-db.sh # 建库 + 灌数据(可重入;RESET_TENANT_ADMIN=1 重置租户端 admin 密码)
│ ├── 03-deploy.sh # 全量部署(可重入)
│ └── 04-verify.sh # 验收
├── docker-optional/ # 已弃用:早期"每个服务打一个镜像"的方案(2026-10-15 已删)
└── docs/
boot/ —— ssw-admin 源码(2026-10-15 并入)
ssw-admin.jar 的全部定制代码在这里。2026-10-15 从独立 git 仓库并入本仓库:原 origin 是
gitea:3000/ssw/boot(旧 compose 网络,主机名已解析不了,推不上去),且工作区有大量未提交改动
(§6.12 的三处 pom 修复 + §6.13 的 SsoBindController / SsoTokenGranter 两个新文件)。并入后
它们进了版本库。
⚠️ 并入时删掉了 boot/.gitignore 里的一条 resources/。那条规则把
ssw-admin/src/main/resources/ 整个排掉了,而那目录是运行必需的 —— 详见 §6.12 末尾那个坑。
现在 application*.yml / mapper / i18n / ip2region xdb(v4 11M + v6 35M,一并入库,保证 clone
出来就能 mvn package)都在版本库里。
旧的
ssw/boot远端仓库(public,625MB)仍在,但已不再更新 —— 本仓库是唯一权威副本。
已清理的历史目录(2026-10-15)
| 目录 | 为什么能删 |
|---|---|
jnpf-k8s/docker-optional/ |
早期「每个服务打一个镜像」方案,§7.1 已列为硬约束「不重打镜像」,零代码引用 |
other/ |
compose 时代的产物源。datav/ 与 build/web/datav 完全重复;4 个 jar 已被 build/{workflow,report,xxl,tenant}/app.jar 取代;config/*.yml 的有效部分已进 ConfigMap |
boot/.git |
见上。154 个 commit 已备份到 ~/.cache/testspace-cleanup-20261015/boot-git-backup,原目录在回收站 |
Dockerfile(仓库根) |
构建 jnpf-claude 开发镜像(ubuntu:24.04 + Claude Code CLI + cloudcli)。对应服务块早已在 compose 里整段注释,全仓库无任何 build: 段引用它,无容器无镜像,且 §7.1 明令不重打镜像 |
根 docker-compose.yml 保留,删的是同目录的 Dockerfile —— 两者都在仓库根、都在 compose 时代,但性质相反:
docker-compose.yml |
Dockerfile |
|
|---|---|---|
| 定义的东西 | 正在跑的 jnpf-gitea / jnpf-postgres / jnpf-redis |
早已注释掉的 jnpf-claude |
| 删了会怎样 | 容器一旦被误删无法重建;AGENTS.md §1 那几个复用镜像的出处消失,§7.1「不重打镜像」的约束悬空 | 无影响 |
⚠️ docker-compose.yml 不能在 testspace/ 下直接 docker compose up -d。 里面挂载全是相对路径 ./persist/...,而 persist/ 是 testspace 的兄弟目录(/Users/xs/Desktop/workspace/persist/{gits,postgres})。在本目录跑会新建一套空 postgres + gitea,且容器名与现有实例冲突直接起不来。正确姿势:
cd /Users/xs/Desktop/workspace && docker compose -f /Users/xs/Desktop/workspace/testspace/docker-compose.yml up -d
# 查现存实例的真实 compose 路径(标签记录的是创建时的位置):
docker inspect jnpf-gitea --format '{{index .Config.Labels "com.docker.compose.project.working_dir"}}'
# → /Users/xs/Desktop/workspace ← 该路径下的 compose 文件已不存在,testspace/ 这份是幸存的副本
4. 常用操作
export KUBECONFIG=$HOME/.kube/kubeconfig-wuguirong # 所有 kubectl 前置
# 全量部署(幂等,可反复跑)
./scripts/03-deploy.sh
SKIP_LLM_KEY=1 ./scripts/03-deploy.sh # 不注入 AI 密钥(AI 功能会鉴权失败)
# 只同步产物(jar / 前端改了之后)
./scripts/01-artifacts.sh
FORCE=1 ./scripts/01-artifacts.sh # 忽略比对强制重传
# 验收
./scripts/04-verify.sh
SMOKE_AI=1 ./scripts/04-verify.sh # 额外真跑一次 AI 建表单(会在 j7 留数据)
# 重置租户管理端(30095)的 admin 密码为 123456
RESET_TENANT_ADMIN=1 ./scripts/02-seed-db.sh
# 重建租户管理中心前端(改了 ../jnpf/jnpf-web-tenant-vue3 之后)
cd ../jnpf/jnpf-web-tenant-vue3
pnpm install --registry=https://registry.npmmirror.com
NODE_OPTIONS=--max-old-space-size=8192 npx vite build # 别省掉下面的 postBuild
npx esno ./build/script/postBuild.ts # 生成 _app.config.js,缺了白屏
rsync -a --delete dist/ <testspace>/jnpf-k8s/build/tenant-web/
cd - && ./scripts/01-artifacts.sh
主前端(30093)不一样,必须在 Linux 容器里 build,细节见 §6.14:
# 1) 改源码(git 仓库是独立那个,monorepo 的 apps/ 被 gitignore)
cd ../jnpf/jnpf-web-apps-main && $EDITOR src/views/_core/login/LoginForm.vue
cp src/views/_core/login/LoginForm.vue \
../jnpf/jnpf-web-monorepo-framework/apps/jnpf-web-apps-main/src/views/_core/login/
# 2) 容器内 build(~5 分钟,路径必须是 /workspace/jnpf-web-monorepo-framework,见 §6.14)
cd ../jnpf/jnpf-web-monorepo-framework
docker run --rm --user "$(id -u):$(id -g)" -e HOME=/tmp -e NODE_OPTIONS=--max-old-space-size=8192 \
-v "$PWD:/workspace/jnpf-web-monorepo-framework" \
-w /workspace/jnpf-web-monorepo-framework/apps/jnpf-web-apps-main \
node:22-slim node ../../node_modules/vite/bin/vite.js build --mode production
# 3) 落地 + 同步到 PVC(nginx 直接读盘,不用重启任何 Pod)
grep -rl "公司统一认证" apps/jnpf-web-apps-main/dist # 自检:改动真的进了产物
rsync -a --delete apps/jnpf-web-apps-main/dist/ /Users/xs/Desktop/workspace/testspace/jnpf-k8s/build/web/dist/
cd /Users/xs/Desktop/workspace/testspace/jnpf-k8s && ./scripts/01-artifacts.sh
# 日常查看
kubectl -n wuguirong get deploy,pod,svc -o wide | grep jnpf
kubectl -n wuguirong logs deploy/jnpf-admin --tail=100
kubectl -n wuguirong exec deploy/jnpf-postgres -- psql -U dacli -d j7 -c '\dt'
改任何 ConfigMap 后必须重启 Pod,ConfigMap 变更不会触发 rollout:
kubectl -n wuguirong delete pod -l app=jnpf-admin
5. PVC 上的产物布局
沿用 compose 时代的 /usr/ssw 目录结构,三个 PVC:
| PVC | 挂载点 | 内容 |
|---|---|---|
jnpf-pg-data |
postgres 的 /var/lib/postgresql/data |
PGDATA |
jnpf-redis-data |
redis 的 /data |
appendonly |
jnpf-resources |
所有应用的 /usr/ssw |
5 个 jar + 前端 + 创租户脚本 + log + resources + jnpf-resources |
/usr/ssw/
├── admin/app.jar workingDir=/usr/ssw/admin
├── wf/app.jar workingDir=/usr/ssw/wf
├── report/app.jar workingDir=/usr/ssw/report
├── xxl/app.jar workingDir=/usr/ssw/xxl
├── tenant/app.jar workingDir=/usr/ssw/tenant
├── tenantApi/ JNPF-PostgreSQL.sql(jnpf-tenant 的 spring.file 指向这里)
├── dist|datav|public nginx 静态根
├── tenant-web/ 租户管理中心前端静态根(nginx 第二个 server 块,8081)
├── log/<服务名>/ 日志(ConfigMap 里 log.path 指定)
└── jnpf-resources/ 文件存储根 = 内置资源(build/jnpf-resources 同步,§6.15)+ 用户上传
运行时基址由 ConfigMap 的 file-storage.local-plus[0].base-path 指定
一个 PVC 在一个 Pod 里只能挂一次(见 §6.1)。jnpf-resources 这个目录名与 compose 时代的语义一致:/workspace/jnpf-resources/ 改成了 /usr/ssw/jnpf-resources/,靠外挂 config 改的,不是改 jar。
6. 踩过的坑(都是实测的,改配置前先读)
6.1 同一个 PVC 在一个 Pod 里挂两次 → Pod 永久卡在 ContainerCreating,且没有任何 Event
admin 原本同时挂 /usr/ssw(jar)和 /workspace(文件存储),结果 init 容器永远 PodInitializing,kubectl describe pod 只有一行 Successfully assigned,连 FailedMount 都不报。用最小探针 Pod 复现确认。
修法:只挂 /usr/ssw,文件存储改指同卷子目录 /usr/ssw/jnpf-resources/,在外挂 config 里改 config.file-storage.local-plus[0].base-path。
Spring 的列表是整体替换不是按 key 合并。只写
base-path会把platform/enable-storage/domain/path-patterns全部丢掉,所以该条目必须整个写全(见k8s/20-admin.yaml的 ConfigMap)。
6.2 System abnormality(验证码正常、一登录就炸)→ 缺 applicationTaskExecutor bean
jar 里 sswflow 模块注册了 sswflowExecutor、sswflowSsePoller 两个 Executor bean。Spring Boot 的 TaskExecutorConfigurations.OnExecutorCondition.ExecutorBeanCondition 一旦发现已有 Executor bean,就整体放弃创建 applicationTaskExecutor;而 JNPF 的 ThreadPoolExecutorUtil 静态块硬取 getBean("applicationTaskExecutor"),登录走 IpUtil 时触发 → ExceptionInInitializerError,之后所有请求 NoClassDefFoundError。
本部署的 jar 已不含 sswflow(2026-10-15 断引,见 §6.12),这两个 bean 随之消失,所以
System abnormality现在不会再出现。ConfigMap 里的spring.task.execution.mode: force留着是无害冗余。真要跑 sswflow 才需要看这一节。
外部表现为:/api/oauth/captcha 200,但 /api/oauth/Login 报 System abnormality。
排查手段(下次遇到类似"bean 不存在"直接抄)——外挂 config 临时加:
logging:
level:
org.springframework.boot.autoconfigure: debug
重启后看启动日志里的 condition evaluation report,会直接写明哪个条件没匹配、找到了哪些 bean。
修法(外挂 config,不用重打包):
spring:
task:
execution:
mode: force # Boot 3.2+ 官方开关,无视已有 Executor 照建该 bean
⚠️ 这个改动必须重启 Pod 才生效(ConfigMap 改动不触发 rollout),否则会看到"配置已经写进去了但日志说没找到属性"的假象,白排查一轮。
6.3 nginx 代理后端:proxy_pass 含变量后的两个 DNS 坑
起因:写死 proxy_pass http://jnpf-report:32000 时,nginx 启动那一刻就要解析主机名。apply 顺序是 30-web 在 40-satellites 之前,jnpf-report Service 还不存在,nginx 直接 [emerg] host not found 退出。
修法分两步,两步都做对才算修好:
# nginx.conf(http 块内)
resolver 10.96.0.10 valid=10s ipv6=off; # ① resolver 指 kube-dns ClusterIP
# default.conf(server 块内)
set $jnpf_report http://jnpf-report.wuguirong.svc.cluster.local:32000; # ② FQDN,不是短名
proxy_pass $jnpf_report$request_uri; # ③ 显式拼 $request_uri
⚠️ proxy_pass 一旦含变量,就不自动替换 location 前缀、不自动补 query,必须显式拼 $request_uri(它自带 query string)。
⚠️ resolver 不能写 127.0.0.11。那是 NodeLocal DNSCache 的地址,本集群没开——kubelet 下发的 /etc/resolv.conf 是 nameserver 10.96.0.10,容器里没人监听 127.0.0.11。
⚠️ 后端地址必须写 FQDN(<svc>.<ns>.svc.cluster.local)。nginx 的 resolver 把字面主机名直接丢给 DNS,不走 search 域补全、不认 options ndots:5。写短名查的就是 jnpf. → NXDOMAIN。
这两个坑的外部表现极其隐蔽,因为静态资源不出网、健康探针也只打静态页,所以 Pod 一直 Running、前端首页 200 正常:
| 现象 | 实际含义 |
|---|---|
静态页 200,所有 /api/、/FileServer/ 请求挂到超时(curl 000,不是 502) |
① resolver 指了没人的地址,DNS 查询卡住 |
| 同上但快速返回 502 | ② 短名解析不了(resolver 本身通了) |
access log 里只有 kube-probe 的 /,看不到自己的请求 |
请求还在 nginx 里挂着没结束,超时后才补一条 499 |
判别(一步到位,别先怀疑后端):
kubectl -n wuguirong logs deploy/jnpf-web | grep resolver
# 111 Connection refused → ① resolver 错
# Host not found → ② 后端地址没写 FQDN
反证后端是否真有问题(别一上来就 exec 后端 Pod,慢且经常白跑):
kubectl -n wuguirong run probe --rm -i --restart=Never \
--image=crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/postgres:16-alpine \
--command -- sh -c 'getent hosts jnpf; wget -q -S -O /dev/null -T 8 http://jnpf:30000/oauth/captcha 2>&1 | head -3'
postgres:16-alpine 没有 curl,用 wget -S 或 nc -z -w 3。探针通 → 后端和 Service 都没问题,问题必在 nginx。
kube-dns的 ClusterIP 随集群重建可能变(本集群 24 天,10.96.0.10)。升级/重建后回来核对:kubectl -n kube-system get svc kube-dns -o jsonpath='{.spec.clusterIP}'
6.4 NodePort 预检把自己的端口判成冲突
脚本重入时,上次建的 Service 还在,30093 已占用 直接退出。k8s/10-infra.yaml / 30-web.yaml 的 Service 都有 app.kubernetes.io/part-of: jnpf-v7,预检按这个 label 排除自己。
⚠️ 不能按名字前缀排 —— 前端 Service 必须叫 nginx(jar 里 AI 自环的 api-host 写死了 http://nginx/api/ssw/ai/openai-proxy)。
6.5 bash 里 $var 紧跟中文标点会报 unbound variable
echo " skip $dst(已一致)" # ← bash 把 ( 当成变量名的一部分
写成 ${dst} 即可。全项目已 grep 清干净。改脚本后 bash -n 过一遍再跑。
6.6 NFS 上的 PostgreSQL
PGDATA必须是卷下的子目录(/var/lib/postgresql/data/pgdata),不能指向卷根 —— 卷根由 provisioner 以 root 创建,initdb要 chmod 自己的数据目录,Operation not permitted直接退出。/var/run/postgresql挂emptyDir(镜像里那目录属主是 postgres/999,我们以 10106 跑)。- NFS 上每次 commit 一趟 fsync,实测灌 128MB SQL 慢到 10 张表 / 3 分钟。已用
ALTER SYSTEM SET fsync=off / synchronous_commit=off / full_page_writes=off+pg_reload_conf()关掉(都是 SIGHUP 可重载的,不用重启)。这是测试/开发库,节点断电可能丢最近的数据;要当生产用改回fsync=on。 - Flowable 的 boolean 列在 dump 里是
0/1,PG 默认拒绝。导入期间临时把pg_cast的 int4→bool castcontext 改成'i',导完必须还原'e'。
6.7 灌库脚本可重入
02-seed-db.sh 按「表数是否到位」逐库判断(j7 ≥300 表 / j7flow ≥40 / j7xxl ≥10),并检查 jnpf_seed_meta 标记。灌库被中断时不要 DROP DATABASE,直接重跑脚本,它会接着跳过的部分。
6.8 macOS 同步产物到 NFS
tar --no-xattrs—— 否则 macOS 的 xattr 在对端变成._*垃圾文件 + 一堆LIBARCHIVE告警。- PVC 根是 provisioner 建的,我们不是 owner,
chmod根会 EPERM。只 chmod 自己新建的子目录。
6.9 多租户架构(PG schema 隔离)
两个服务,只靠 HTTP 耦合:
admin ──HTTP GET {config.MultiTenancyUrl}{tenantCode}──▶ jnpf-tenant :30006
←─{"db_names": {...}} (Service jnpf-tenant)
MultiTenancy: true 打开后,admin 每个请求都按租户切数据源。隔离方式由 base_tenant.f_type 逐租户决定:0=schema 隔离、1=列隔离(WHERE f_tenant_id=?)、2=租户自带连接串。
本部署用 f_type=0(schema 隔离)。CreateDataUtil.createData() 在 PG 分支只做两件事:
CREATE SCHEMA jnpf_tenant_<random>; -- 不建 database,PG 分支就是建 schema
-- 然后 conn.setSchema(<上面那个>) + 灌 spring.file 目录下的 JNPF-PostgreSQL.sql
- 租户 schema 都在
j7库里(spring.datasource.dbinit=j7)。 - 租户登记表在
j7tenant库(spring.datasource.dbname=j7tenant,6 张base_tenant*表,←jnpf_tenant_init.sql)。两个库职责不同,别混。 - 宿主租户
f_en_code='host'/f_db_name='public',由02-seed-db.sh插入。它复用j7的publicschema,也就是本部署原来的 300+ 张表和admin/123456。没有它,打开多租户后连原账号都登不进去。 - ⚠️
/usr/ssw/tenantApi/JNPF-PostgreSQL.sql必须在(01-artifacts.sh会校验)。缺了CreateDataUtil抛「脚本文件不存在」,建租户必挂。这个文件不要灌进j7tenant—— 它是建租户时才用的模板。
登录方式:账号按 租户号@账号 拆,或走租户二级域名 Referer。租户号在 j7tenant.base_tenant 里查不到 → TenantInvalidException。
服务间鉴权:sa-token 的 same-token 只认 Redis,别再找配置项
GET /api/tenant/DbName/** 带 JNPF 自己的 @SaCheckSame(不是 sa-token 的同名注解——sa-token 1.45 的默认 handler 表里压根没有它)。链路:
调用方 UserProvider.getInnerAuthToken()
→ SaSameTemplate.getTokenNh() 从 SaTokenDao(= Redisson,也就是那个 Redis)读
→ 空则用 Redisson 分布式锁抢锁 → refreshToken() 生成新串写回 Dao
→ HttpRequest.get(MultiTenancyUrl+code).addHeaders({"SA-SAME-TOKEN": 该值, ...})
被调方 SecurityConfiguration$1.checkMethod(SaCheckSame)
→ 读请求头 SA-SAME-TOKEN → SaSameUtil.checkToken(v) → isValid(v) 与 Dao 里的值比对
所以:
sa-token.same-token这个配置键在 1.45 已经没有对应属性了(SaTokenConfig里只剩sameTokenTimeout和checkSameToken),写进 yml 会被 Spring 静默忽略。历史上那份sa-token.same-token: ssw_mt_same_7Qx2K9pL是死配置,已删。- 唯一的共享机制就是「同一个 Redis 实例 + 同一个 DB 号」。 admin 的
redisson.database是1,tenant 的必须也是1。写错 → 所有跨服务调用 10301 SameTokenInvalid,而且日志里看不出是 DB 号的问题。 - 改动 redisson 的
database时两个服务一起改,改完都 rollout restart。 gateway.white-url: /api/tenant/DbName/**必须留着:admin 是带着 SA-SAME-TOKEN 头调过来的,没有任何登录会话,不加白名单会在进方法前就被全局StpUtil.checkLogin拦掉。
重新打 tenant jar
cd ../jnpf/jnpf-java-tenant
mvn -o package -DskipTests # 依赖在 ~/.m2/repository/com/jnpf/(groupId 是 com.jnpf 不是 jnpf),能纯离线打
cp target/jnpf-tenant-7.0.0-RELEASE.jar ../../testspace/jnpf-k8s/build/tenant/app.jar
cd ../../testspace/jnpf-k8s && FORCE=1 ./scripts/01-artifacts.sh && kubectl -n wuguirong rollout restart deploy/jnpf-tenant
jar 内的 application-dev.yml 带 SSW 的语义配置(PG / dbinit=j7 / dbname=j7tenant / redisson database:1 / white-url),部署期的地址(spring.file / host / port / redisson address / mainDomain)在 build/tenant/config/application-dev.yml(挂成 ConfigMap jnpf-tenant-config),改这些不用重打包。
TDC 已移除
jnpf-java-tenant 原本有一层 SSW-MVP 的「双 schema」扩展(createDualSchemaDb + TdcSchemaInitUtil + 必需的 TDC-PostgreSQL.sql)。TDC 是 SSW-MVP 的业务库概念,本部署不需要,且 TDC-PostgreSQL.sql 根本不存在 → TdcSchemaInitUtil.readTdcFile 抛异常被 log.error 吞掉、建租户静默返回 false。已全部回退到上游单 schema 分支。
保留下来的唯一一处 SSW 适配是 TenantServiceImpl.create() 里的 linkList != null 保护:schema 模式下 TenantController 不传 linkList,上游原版会直接 NPE。
三个实测踩过的坑
① base_tenant 必须填 f_start_time / f_end_time,否则连宿主租户都登不进
TenantController.dbContent 第 109 行直接 entity.getEndTime().getTime(),不判空:
if (nowData.getTime() > entity.getEndTime().getTime()) return fail("当前租户已超过有效时间");
if (nowData.getTime() < entity.getStartTime().getTime()) return fail("当前租户未到设置有效时间");
漏填 → tenant 侧 NullPointerException → admin 侧只看到 系统异常(跟 §6.2 那个 System abnormality 长得一样,但根因完全不同,别被带偏)。02-seed-db.sh 已补上这两个字段,且用 ON CONFLICT DO UPDATE 而不是 DO NOTHING,重跑能修回早期种歪的行。
② MultiTenancy: true 之后账号必须带租户号,admin 会被整个当成租户号
admin 对不含 @ 的账号不做兜底,直接把 admin 当 tenantCode 去查 DbName/admin → 租户不存在。同事必须用 租户号@账号 登录(宿主租户是 host@admin)。JWT 里的 user_name 字段是剥掉租户号后的 admin,这是登录成功的标志。
③ 健康探针不能用业务路由 —— JNPF 业务失败也返回 HTTP 200
/api/tenant/DbName/nonexistent-probe 返回 body {"code":400,"msg":"租户不存在"} 但 HTTP 状态码是 200。拿它当 readinessProbe.httpGet 等于永远 ready,还会在 tenant 日志里每 15 秒刷一条噪音。50-tenant.yaml 的 readiness 已改成 tcpSocket。
租户管理端登录(跟主库 admin 不是一回事)
jnpf-tenant 有独立的登录(POST /api/tenant/login,TenantTokenGranter)和独立的账号表 j7tenant.base_tenant_account,口令只做 md5(password.toLowerCase()) 不加盐。
jnpf_tenant_init.sql 的种子账号是 admin / 管理员,但种子里的密码哈希不是任何常见默认值(扫过 123456/admin/jnpf123/123456789/888888 等都不匹配)。测试环境用:
RESET_TENANT_ADMIN=1 ./scripts/02-seed-db.sh # 把 base_tenant_account.admin 的密码重置成 123456
建租户 POST /api/tenant 需要带这个 token(不是主库 token,也不是 SA-SAME-TOKEN)。必填字段见 TenantCrForm:enCode / fullName / accountNum / startTime / endTime(后两个是 毫秒时间戳,非格式化日期)。
⚠️ kubectl exec ... sh -s <<'HEREDOC' 里的 <<'...' 是带引号的,外层 shell 的变量不会展开。想把本机的开关传进 Pod,必须显式 env VAR=...:
kubectl -n $NS exec -i deploy/jnpf-postgres -- \
env RESET_TENANT_ADMIN="${RESET_TENANT_ADMIN:-0}" sh -s <<'SEED_TENANT'
否则 Pod 内 ${RESET_TENANT_ADMIN:-0} 恒为 0,脚本安静地什么都不做 —— 看起来"跑过了"其实没生效。
端到端验证记录(2026-10-14 实测)
RESET_TENANT_ADMIN=1 ./scripts/02-seed-db.sh → 登录 tenant 管理端 → 建租户 → 用新租户号登录主前端,全绿:
POST /api/tenant {"enCode":"zhangsan", ...}
→ {"code":200,"msg":"新建成功"}
→ j7tenant.base_tenant: zhangsan | 张三测试租户 | jnpf_tenant_l1d9xv905q31 | 0 | 1
→ j7 库新建 schema jnpf_tenant_l1d9xv905q31:331 张表 / 239 个用户 / 5 个应用
→ tenant 服务日志出现 DbName/zhangsan
→ zhangsan@admin / 123456 登录成功,/oauth/CurrentUser 200
zhangsan 是这次冒烟测试留下的租户,留着给同事直接登录试(zhangsan@admin / 123456)。要清就 DELETE /api/tenant/{id},对应的 schema 不会自动删,得手工 DROP SCHEMA。
6.10 dacli 联调(../dacli)
默认 appCode 改成 mainSystem。 dacli 原来硬编码 DEFAULT_APP_CODE = 'testspace',那是公司 JNPF 环境的统一测试场,本地集群的 base_system 里根本没这个应用,于是登录后所有 app 命令都报「appCode 不存在」。现在改成 mainSystem(每个租户 schema 初始化就带的平台应用)。改的地方:
| 文件 | 改法 |
|---|---|
src/core/config.ts:192 |
DEFAULT_APP_CODE 兜底值 → 'mainSystem' |
src/commands/app/_check_system.ts |
加 PLATFORM_APPS 白名单 + keyword 查不到时回退全量列表再判 |
src/commands/app/create.ts |
appCode: 'testspace'(平台占位)和 c.appCode || 'testspace' → DEFAULT_APP_CODE |
src/commands/app/clear.ts |
c.appCode || 'testspace' → DEFAULT_APP_CODE |
src/commands/app/login.ts switch.ts use.ts |
帮助文本里的 testspace 示例 |
为什么检测逻辑要改:/api/system/System(应用中心列表,dacli app status 的存在性检测用的就是它)只返回门户/自建应用。实测本集群 base_system 有 5 行,但这个接口全量只返回 workSystem + developSystem 两个 —— 平台应用 mainSystem/workFlow/teamwork 不在里面,也没有列全表的端点(/system/SystemBase、/system/SystemAll 都 400)。原来的 keyword 精确匹配会把它们一律判成「不存在」。
⚠️ 换到别的 JNPF 环境时,如果报「xxx 不存在」但 base_system 里明明有,就是漏了 PLATFORM_APPS 名单,补进去。
当前状态(2026-10-14 实测):dacli 三项全通,host@admin @ mainSystem:
✓ dbPing 0ms — skip (dbLinkId=0 主库, 不需测试)
✓ llmPing 2040ms — 端到端 OK (model=MiniMax-M3, 7 tokens)
✓ menuIntegrity 704ms
此前 llmPing 报 MiniMax HTTP 401: login fail: Please carry the API secret key in the 'X-Api-Key' field —— 根因是 SswLLMProxyController 把上游硬编码成 MiniMax,而 03-deploy.sh 注入的 vault llm_key 是别家(GLM 网关)的 key。已改成可配(见 §6.12),现在 SSW_LLM_BASE_URL=https://lm.mayishangshu.cn:88/glm + SSW_LLM_MODEL=GLM-5.3-Flash 经 xop 注入,换 provider 不用再重打 jar。
dacli 报的
model=MiniMax-M3只是它请求体里的名字(ymlchat.mode),真正用的是 env 注入的模型名,别被这个显示值误导。
多租户适配(2026-10-15 已落地并实测)
关键认知:租户是「登录态的属性」,不是请求参数。 租户只体现在 POST /oauth/Login 的账号串 租户号@账号 里;后端签发的 token 其 loginId 形如 zhangsan:349057407209541,之后每个请求都由 admin 按 token 自己切数据源。所以 dacli 不需要给任何 API 加租户参数,适配全是本地状态和 CLI 的事。
改动(../dacli,8 个文件):
| 文件 | 改法 |
|---|---|
core/config.ts |
加 DEFAULT_TENANT(JNPF_TENANT env,默认 host)+ 纯函数 loginAccount(tenant, account) / splitAccount(s) |
core/types.ts |
TokenFile 加 tenant?: string;account 保持原样保存,老 token.json 照样能读 |
core/client.ts |
ClientOptions.tenant / JnpfClient.tenant;doLogin() 发 loginAccount() 拼好的串;fromToken() 从缓存恢复;persist() 落 tenant |
app/login.ts |
加 --tenant(默认 host),输出多打一行租户 |
app/switch.ts |
加 --tenant;--appCode 从 requiredOption 降为可选(两者至少给一个,没给的沿用 token 里的) |
app/status.ts |
多打一行租户;--json 加 tenant 字段 |
app/logout.ts |
加 --tenant,仅二次确认 |
app/create.ts |
重新登录时带上 tenant: c.tenant(app create 是在当前租户里建应用,不能换租户) |
di/create.ts |
tenantId: '0' 的值不变,只改注释 |
loginAccount 见到 @ 就不拼租户号,所以老写法 --account 'zhangsan@admin' 继续可用,不需要改任何已有调用点。同理构造函数里 account 自带的租户优先于 opt.tenant —— 反过来会踩这个坑:--account 'zhangsan@admin' 配上 --tenant 的默认值 host 时,登录串是对的(loginAccount 跳过),但 token.json 会把租户错记成 host。这个 bug 是实测发现的,先改了构造函数才绿。
token 仍是单文件 ~/.dacli-token/token.json(与既有 switch --appCode 一致)。所以 app logout --tenant 只做二次确认,不做选择性清除 —— 文件里就一个登录态,清掉就是当前租户被登出。传了且对不上时会 warn,同时把 tenant / tenantMismatch 塞进 JSON 和 ctx.success(⚠️ log.warn 在默认 quiet 模式下会被 _output_filter.ts 丢进 buffer 再丢掉,光打 warn 用户根本看不到)。
用法:
cd ../dacli
export JNPF_BASE_URL=http://192.168.1.26:30093/api
export JNPF_WEB_URL=http://192.168.1.26:30093
export VITE_CIPHER_KEY=EY8WePvjM5GGwQzn
export DACLI_WEB_SRC=~/Desktop/workspace/jnpf/jnpf-web-monorepo-framework/apps/jnpf-web-apps-main
npx tsx src/cli.ts app login --tenant zhangsan --account admin --password 123456
npx tsx src/cli.ts app status # 多一行「租户 : zhangsan」
npx tsx src/cli.ts app switch --tenant host # 只切租户, appCode 沿用
⚠️ DACLI_WEB_SRC 必须是 monorepo 根(.../apps/jnpf-web-apps-main),不带 src —— 少一层就会报 ENOENT ... /src/api/systemData/dataService.ts。env 名是 DACLI_WEB_SRC,不是 JNPF_WEB_SRC。
跨租户落库实测(建一条数据服务,分别在两个租户下建,看它进哪个 schema):
zhangsan 租户下建 daclimtt1 → jnpf_tenant_l1d9xv905q31.base_data_interface ✓
host 租户下建 daclimtt2 → public.base_data_interface ✓
两边 f_tenant_id 都是 '0'
顺带实测确认了 di/create.ts 的 tenantId: '0' 是对的:schema 隔离模式下 f_tenant_id 恒为 '0',JNPF 自己的种子数据在 public 和 jnpf_tenant_l1d9xv905q31 里各 119 行也全是 '0'。只有列隔离(base_tenant.f_type=1,查询拼 WHERE f_tenant_id=?)才拿它当隔离键。别把 di/create.ts 改成填租户号。
6.11 租户管理中心前端(30095)
前端源码 ../jnpf/jnpf-web-tenant-vue3,本机 pnpm install + vite build 出 dist/,rsync 到 build/tenant-web/,由 01-artifacts.sh 传到 PVC 的 /usr/ssw/tenant-web/。
为什么单独开一个 NodePort(30095)而不是挂在主站的 /tenant/ 子路径下:
| 独立 server 块(采用) | 主站子路径 | |
|---|---|---|
| 前端配置 | 一行不改(VITE_PUBLIC_PATH=/、VITE_GLOB_API_URL= 同源) |
要同时改 VITE_PUBLIC_PATH + API 前缀,再加 rewrite 把 /tenant-api/ 拆回 /api/ |
| API 前缀 | 两边各用各的 /api/,天然不冲突 |
共用 /api/,主站的 /api/Report/ 等还得排在租户路由前面 |
| 错位后果 | 无 | 任一个变量错位就是白屏,且 history 回退和静态资源路径一起错 |
| 代价 | 多一个对外端口 | —— |
nginx 第二个 server 块(build/nginx/default.conf)仍守 §6.3 的规矩:变量 + FQDN + $request_uri。租户端的 /api/ 只会打到 jnpf-tenant,所以不需要主站那套 /api/Report/ 让路分支。Service 名叫 jnpf-tenant-web(主站那个必须叫 nginx,见 §6.4)。
坑 1:base_tenant_account.f_delete_mark 是 NULL,登录永远「账号或密码错误」
TenantAccountEntity 继承 SuperExtendEntity,带 @TableLogic 的 deleteMark → MyBatis-Plus 给每条查询自动追加 AND f_delete_mark = 0。而 jnpf_tenant_init.sql 的种子行这一列是 NULL —— SQL 里 NULL = 0 是 unknown 不是 true,于是 TenantTokenGranter.preAuthenticate 的 getInfoByAccount() 一行都取不到,跟密码对不对完全无关,永远抛 MsgCode.LOG101。
02-seed-db.sh 里无条件补:f_delete_mark / f_enabled_mark / f_is_administrator 三个 COALESCE(NULL, 0/1/1)。
坑 2:租户端密码存的是 md5(md5(明文)),不是单层 md5
两端各 md5 一次:前端 LoginForm.vue 先 md5(data.password) 再发,服务端 TenantTokenGranter.preAuthenticate 又做一次 Md5Util.getStringMd5(password.toLowerCase()) 才比对。所以库里落的是 md5(md5('123456')) = 14e1b600b1fd579f47433b88e8d85291。
jnpf_tenant_init.sql 里那条 admin 的种子哈希正好就是这个值(说明 vendor 的初始口令也是这么设的,但明文没人知道),不是单层 md5 的 e10adc39...。RESET_TENANT_ADMIN=1 ./scripts/02-seed-db.sh 现在写 md5(md5('123456'))(SQL 表达式,不硬编码哈希)。
判别:日志
log_error.log里TenantTokenGranter.preAuthenticate抛 NPE(getPassword()为 null)= 请求体压根没解析;抛LOG101= 密码哈希层数或行本身不对。
构建要点
package.json 的 build 脚本是 vite build && esno ./build/script/postBuild.ts,postBuild 不能省 —— 它生成运行时可改的 dist/_app.config.js,少这一步首页直接白屏。产物里的 .gz 与原文件并存,nginx 没开 gzip_static 也不影响(发原文件即可)。
6.12 重打 admin(ssw-admin.jar)
就在 testspace/boot 里打包,不需要 ssw-mvp/boot。 后者是另一个远端(192.168.1.18:13300/ssw/ssw-mvp)的业务仓库,带 ssw-sswflow/ssw-tds/ssw-tdc 等模块 —— 那些是 ssw-mvp 的业务信息,JNPF 是第三方独立开发平台,不依赖它们,本部署也不需要。本文档早前「只能用 ssw-mvp 打」的结论是错的,已作废(2026-10-15 实测推翻)。
boot/ 已于 2026-10-15 从独立 git 仓库并入本仓库(见 §3),现在是 testspace 的一个普通子目录 —— 直接改、直接 commit,没有第二个地方要同步。
cd /Users/xs/Desktop/workspace/testspace/boot
mvn -o clean package -DskipTests -pl ssw-admin -am # 依赖在 ~/.m2,纯离线可打
unzip -p ssw-admin/target/*.jar BOOT-INF/classes/application.yml | grep SsoBind # 改过白名单的话验一下
cp ssw-admin/target/*.jar /Users/xs/Desktop/workspace/testspace/jnpf-k8s/build/admin/app.jar
cd /Users/xs/Desktop/workspace/testspace/jnpf-k8s && ./scripts/01-artifacts.sh # ~4 分钟
kubectl -n wuguirong rollout restart deploy/jnpf-admin
clean 不能省:maven-jar-plugin 发现 class 没变就跳过 thin jar,接着 spring-boot:repackage 把上一次的 fat jar 再包一遍 → 改了代码但运行行为不变。没有 -P full:那个 profile 只存在于 ssw-mvp 的 pom,这里传会直接报 The requested profile "full" could not be activated。
2026-10-15:让 testspace/boot 能独立打包要修的三处
树是裁剪过的,直接 mvn package 会在三个地方卡住,每一处都各自报错、互不相干:
| # | 位置 | 症状 | 修法 |
|---|---|---|---|
| 1 | 根 pom.xml 的 <modules> |
Child module .../boot/ssw-sswflow does not exist —— 目录已在 git 里删除(D 状态),但 <module> 还留着,Maven 连 reactor 都读不进去 |
注释掉 <module>ssw-sswflow</module> |
| 2 | ssw-common/pom.xml 缺 <properties> |
编译报 不兼容的类型: java.nio.charset.Charset 无法转换为 java.lang.String(Base64.getEncoder().encodeToString(byte[],int,int,Charset) 是 Java 10+ API) |
加 maven.compiler.source/target=17(jnpf-dependencies 的 boot3 profile 把它锁在 8,JNPF v7 跑 JDK 17) |
| 3 | ssw-admin/pom.xml 引 ssw-sswflow-controller |
本树没有 sswflow 源码,只能从 ~/.m2 解析 08-14 的旧 jar;那份 jar 的 DatasetController 需要 ssw/common/permission/SswPermissionGuard,本树的 ssw-common-biz 没有 → 启动即 NoClassDefFoundError |
注释掉该 dependency。断引后 jar 里不再有 sswflow,§6.2 那两个 Executor bean(sswflowExecutor/sswflowSsePoller)随之消失,ConfigMap 里的 spring.task.execution.mode: force 变成无害冗余(留着即可) |
修完 fat jar 里 BOOT-INF/lib/ssw-* 从 6 个降到 3 个(ssw-common-{entity,biz,controller}),这才是本部署应有的形态。unzip -l app.jar | grep -c 'BOOT-INF/lib/ssw-' 不再是有效的验收指标。
⚠️ 这棵树与 ssw-mvp 的
application.yml差异不止 SSO 白名单:testspace/boot的spring.profiles.active只有dev(ssw-mvp 是dev,full),且没有config.oauth的ssoEnabled/ticketTimeout/loginPath整块,也没有application-full.yml。但SsoBindController的每个@Value都写了默认值,所以 SSO 靠k8s/20-admin.yaml的 ConfigMap 注入即可,缺块无害。唯一必须补的是gateway.white-url白名单(见下)。
坑:gateway.white-url 漏了 SSO 白名单 → /login 返回 200 + code 600 而不是 302
AuthFilter 只认 gateway.white-url(exclude-url 是另一条链,管静态资源)。缺了这条,未登录用户点 SSO 入口就被 StpUtil.checkLogin() 拦掉:
HTTP 200 {"code": 600, "msg": "Login expired, please log in again", "data": null}
HTTP 状态码是 200,jq/curl -f/浏览器都发现不了,很容易误判成 SSO 配错了。判别:kubectl logs deploy/jnpf-admin | grep SsoBind 能看到 [SSO] init: enabled=true …(bean 起来了)但看不到 [SSO] 入口跳转 —— init 有、请求处理没有,就是白名单拦在外面。
testspace/boot/ssw-admin/src/main/resources/application.yml 的 gateway.white-url 下要有一行(SsoBindController 的 URL 是绝对路径,与包名无关,见 §6.13):
gateway:
white-url:
- /api/ssw/tds/SsoBind/**
改这个要重打包重部署。改 ConfigMap 不解决这个问题 —— ConfigMap 里没有 gateway.white-url 这个键。
✅ 这个坑在 2026-10-15 闭合了。 当时
boot/.gitignore有一条resources/,把ssw-admin/src/main/resources/整个排掉,于是application.yml从来不在版本控制里 (git ls-files查不到),重新 clone 一遍这行就没了、SSO 入口会退回 200/code 600,而git status看不到任何异常 —— 因为它本来就该入库却一直被忽略着。并入本仓库时已删掉那条规则, 现在git ls-files boot/ssw-admin/src/main/resources/application.yml能查到,白名单跟着代码一起走。⚠️ 反过来说,别再往
boot/.gitignore加回resources/这类宽规则。要排构建产物用target/、 要排本地凭据用application-local.yml(那条还在),别整目录排。
坑:每次 rollout restart deploy/jnpf-admin 都会让所有已登录用户掉线
已实测确认(2026-10-15),不是本次换构建源引入的回归:
- sa-token 会话确实持久在 Redis(db 1,重启后
Authorization:login:token:*、Authorization:login:session:*都还在); - 签名密钥不是每 boot 随机的 ——
application-dev.yml里config.oauth.login.jwtSecretKey是写死的字面量(jnpf-common-auth的 metadata 里对应的键是config.oauth.login.jwt-secret-key); - 静置不管(连续 130s 每 20s 打一次
CurrentUser)一直 200,只有重启会死; - 此前部署用的 08-14 那份 jar(
~/.m2/.../ssw-admin-7.0.0-RELEASE.jar)的application.yml里连jwt字样都没有,行为一模一样 → 既有行为。
根因没深挖到底(token 三段但头部不是标准 JWT header,离线验签走不通)。排查时先想到这一条:dacli 报 llmPing … (code=600): Login expired 时,多半只是本地 ~/.dacli-token/token.json 是上一次发版前存的,重新 dacli app login 即可,别去查 AI 代理、白名单、SSO:
cd ../dacli && npx tsx src/cli.ts app login --account 'host@admin' --password 123456
npx tsx src/cli.ts app status
⚠️ dacli app login 的账号参数叫 --account(不是 --host),默认值 admin 在多租户下登不进去,必须写 租户号@账号(§6.9)。
dacli 的深度健康检查里
menuIntegrity在 token 已失效时仍报 ✓,只有llmPing会暴露问题 —— 别因为它绿了就以为 token 有效。
kubectl apply -f k8s/20-admin.yaml 会覆盖已注入的密钥
整份 apply 会重建 Deployment,把 03-deploy.sh 第 7 步注入的真密钥覆盖回 PLACEHOLDER_SET_AT_DEPLOY(§7 / §9)。只想改 ConfigMap 时单独 apply 那一段:
cd jnpf-k8s && awk 'NR>1 && /^---$/{exit} {print}' k8s/20-admin.yaml | kubectl apply -f -
AI 上游改成可配(v0.22,2026-10-14)
以前 SswLLMProxyController 把 MiniMax 焊死了,换 provider 就 401(login fail: Please carry the API secret key in the 'X-Api-Key' field),而且报错完全指不到真因。现在三个 env 成套注入(03-deploy.sh 第 7 步,xop run --secret 一次带 key/url/model):
| env | 落到 | 作用 |
|---|---|---|
SSW_LLM_API_KEY |
spring.cloud.ai.openai.api-key[0] |
上游凭据 |
SSW_LLM_BASE_URL |
ssw.llm.base-url |
真实上游地址 |
SSW_LLM_MODEL |
ssw.llm.model |
上游模型名(留空回落 yml chat.mode) |
为什么不能复用 spring.cloud.ai.openai.api-host:那个值是 http://nginx/api/ssw/ai/openai-proxy —— 本端点自己的自环地址(JNPF 的 SendAiMessage.aiHttp() 拿到 base_ai.baseUrl 后直接 POST)。真实上游没地方放,才导致硬编码。
协议按 URL 自适应(复用 SswLLMClient 的同一套判断,不写第二份):url 含 /anthropic → X-Api-Key + anthropic-version: 2023-06-01,POST {base}/v1/messages;否则 Authorization: Bearer,POST {base}/chat/completions。三个 env 都留空 → 回落 jar 内默认的 MiniMax,老部署不配也能跑。
⚠️ 推理模型(GLM / DeepSeek-R 系)max_tokens 偏小时 choices[0].message.content 是空串、finish_reason: length,文本在 reasoning_content。parseOpenAiText 因此先看 content 再回落 reasoning_content,否则上层报「LLM 返回空」,看起来像网关挂了。
坑:Redisson 地址不能写占位符
application-dev.yml 里原来是 address: "redis://${REDIS_HOST:jnpf-redis}:${REDIS_PORT:6379}",重打包后启动即挂:
Caused by: java.net.MalformedURLException: Invalid authority field: [jnpf-redis:tcp:
at org.redisson.misc.RedisURI.<init>(RedisURI.java:86)
Redisson starter 把整段 config 当不透明字符串丢给自己的 YAML 解析器,Spring 的占位符不在这条链上展开;原样进 RedisURI.parseUrl() 后,它按 indexOf("://")+3 … lastIndexOf(":") 切主机段,主机段里还含 : 就把整段用 [ ] 包起来当 IPv6 → URL 解析失败(新 JDK 文案是 Invalid host: [...],比报错更难认)。
修法:k8s/20-admin.yaml 的 ConfigMap 里整块覆盖 spring.redis.redisson.config(地址写死 redis://jnpf-redis:6379,database: 1),源 yml 也一并改成字面量。换地址只改 ConfigMap。注意 config 是标量键 —— 外部一旦有值,jar 内那份完全不生效,不是合并。
6.13 SSO 接入 ipass-sso(已跑通,2026-10-15)
同事用公司 ipass 账号直接登进 JNPF,不用记 租户号@账号。ipass-sso 那边一行代码没改、没重打镜像 —— 它原生就提供 MaxKey 形状的 OAuth2 端点,JNPF 侧改配置 + 两个 SSW 类就接上了。
入口:http://192.168.1.26:30093/api/ssw/tds/SsoBind/login?tenant=<租户号>
(tenant 省略 = ConfigMap 里的 defaultTenant: host;登录成功后落在 ?redirect=,默认 /work)
curl -sI "http://192.168.1.26:30093/api/ssw/tds/SsoBind/login?tenant=zhangsan" | grep -i location
代码落点
| 文件 | 作用 |
|---|---|
testspace/boot/ssw-common/ssw-common-controller/src/main/java/ssw/common/controller/SsoBindController.java |
两端点:GET /login(302 去 ipass 授权页)、GET /oauth2(code 换 token → 拉 userinfo → 建/绑本地用户 → 签 JNPF token → 302 回前端 /sso?token=…)。原来是段从没跑通过的 MaxKey 桩(返回字面量 "sso-token-…"、查 base_user.f_sso_* 这类不存在的列),已整段重写 |
testspace/boot/ssw-common/ssw-common-biz/src/main/java/ssw/common/sso/SsoTokenGranter.java |
新增,grant_type=sso 的 token granter |
代码放 ssw-common 而不是 ssw-tds,是因为 testspace/boot 里根本没有 ssw-tds 模块(见 §6.12);ssw-common 是它唯一有完整 pom 的模块。ssw-common-biz / ssw-common-controller 只依赖 jnpf-common-all,而它传递带上 jnpf-common-database(TenantDataSourceUtil)和 jnpf-common-auth(AbstractTokenGranter、sa-token),依赖是够的。
⚠️ 包名变了但接口 URL 没变 —— @RequestMapping("/api/ssw/tds/SsoBind") 是写死的绝对路径,与包名无关。所以 jar 内 gateway.white-url: /api/ssw/tds/SsoBind/** 白名单、ipass 管理台登记的 redirect_uri、同事收藏的入口,三样都不用改。
⚠️ testspace/boot 里已经没有 ssw-tds 了,不存在「两份 SsoBindController 打成同一个 jar 导致 bean 冲突」的问题 —— 直接在 testspace/boot 打包即可,不用往 ssw-mvp/boot 同步(§6.12)。
SsoTokenGranter 继承 AbstractTokenGranter 而不是自己拼 token,这样 SSO 签出来的就是一条真正的 sa-token,跟密码登录的 token 在 /api/oauth/CurrentUser 眼里没区别。继承来的三条语义都是必须的:切租户(租户号@账号 → 问 tenant 服务要 dbName)、取 base_system 的 token 配置、checkUser 校验。
它的 URL 兜底路径写成 /Login/sso/**(JNPF 路由下不存在这个路径),所以 TokenGranterBuilder 的 URL 兜底匹配不可能误命中它。
绑定表 ssw_sso_binding(懒创建,逐租户 schema)
f_id | f_sso_source | f_sso_user_id | f_sso_username | f_local_user_id
| f_local_account | f_bind_time | f_last_log_time | f_login_count
| f_tenant_id | f_delete_mark | f_creator_time PK(f_id, f_tenant_id)
UNIQUE(f_sso_source, f_sso_user_id)
绑定键是 ipass 的 id,不是账号名 —— 这是刻意的:按账号名绑定的话,任何人只要能在 ipass 注册一个叫 admin 的账号就能顶掉本地管理员。ipass 那边改密码/改名都不影响绑定。
首次登录建本地 base_user 时会追加 ipass id 前 6 位(admin → admin_admin)避免撞名,并自动挂 defaultRoleName: 开发者 角色 —— LoginServiceImpl.checkUser 对非管理员强制要求有角色 + 非空 base_authorize,不挂就是 LOG004。
配置(k8s/20-admin.yaml 的 ConfigMap,config.oauth.sso.*)
oauth.sso.baseUrl: https://i28868828dm.mayishangshu.cn:188/sign
oauth.sso.auth2.clientId: jnpf
oauth.sso.auth2.clientSecret: ${SSW_SSO_CLIENT_SECRET:} # xop 注入
oauth.sso.scope: openid profile email read # read 是本 controller 显式申请的
oauth.sso.callbackUrl: http://192.168.1.26:30093/api/ssw/tds/SsoBind/oauth2
oauth.sso.defaultTenant / defaultRoleName
- 密钥在 xop vault 的
jnpf_sso_client_secret,由03-deploy.sh第 7 步和三个SSW_LLM_*一起用xop run --secret注入(值不进 argv / 日志 / 模型上下文)。 callbackUrl必须与 ipass 管理台里jnpf客户端登记的redirect_uri逐字符一致。ipass 先校 redirect_uri 再校 scope,不一致直接 400。- 换客户端/密钥:ipass 侧
/api/admin/oauth-clients/{save,rotate,delete}(form 参数,列表逗号分隔),然后xop set jnpf_sso_client_secret <新值>+ 重跑03-deploy.sh第 7 步。
两个实测的坑
① UriComponentsBuilder.build(true) 会让带空格的 query 直接炸
build(true) 的语义是「入参已编码」,于是 scope=openid profile email read 里的空格触发
{"code":400,"msg":"Invalid character ' ' for QUERY_PARAM"}(HTTP 200,无 Location,极易误判成 ipass 报错)。
三处拼 URL 都必须 .build().encode().toUriString()。
② granter 返回的是 Map 不是 String
ActionResult.success(Map) → 控制器里 String token = (String) data 直接
class java.util.HashMap cannot be cast to class java.lang.String。按 instanceof Map 取 token 键。
多租户实测(已验证)
tenant 走 OAuth 的 state 参数({租户号}|{redirect})回传,回调端先 TenantDataSourceUtil.switchTenant(tenantCode) 再碰任何 base_user / ssw_sso_binding。同一个 ipass 账号在两个租户下是两个独立本地用户:
host (public) → f_local_user_id 880332915379012549
zhangsan (jnpf_tenant_l1d9xv905q31) → f_local_user_id 880334981992285189
JWT loginId: "host:880332915379012549" / "zhangsan:880334981992285189"
走不通的两条 vendor 路径(别再试)
config.oauth.ssoEnabled+jnpf-sso-*starter(JNPF 自带的 MaxKey 客户端):三个 starter 在ssw-admin/pom.xml里是注释状态,本机~/.m2/repository/com/jnpf/也没有,离线打不了包。socials/ymsso那套第三方按钮:SocialsTokenGranter没有任何调用方,按钮列表来自一个固定枚举,加了新枚举项也没有地方能变成 URL。
登录页上的「IPASS 登录」按钮(2026-10-15 已加,已部署验证)
src/views/_core/login/LoginForm.vue 的 .socials-box 里加了一块独立于 vendor SSO 的 UI:租户号输入框 + IPASS 登录按钮,直接 302 到 /api/ssw/tds/SsoBind/login?tenant=<租户号>&redirect=<站内路径>。跟 vendor 那条 isSso 分支并存、互不影响(后者永远 false,见上面)。
租户号做成可编辑而不是写死 host:每个同事的租户号不同。取值优先级 ?tenant=(便于把带租户号的登录页直接发出去)→ localStorage 上次填的 → host。
⚠️ vendor 的
handleSsoLogin那条路别拿来复用 —— 它打开的是getLoginConfig()返回的data.url(JNPF 自己的 SSO),还带 iframe + modal 那套逻辑,跟我们的 302 入口完全不是一回事。
改这个文件的正确姿势:源码的 git 仓库是独立仓库 ~/Desktop/workspace/jnpf/jnpf-web-apps-main,monorepo 里 apps/** 被 .gitignore:54 整个忽略(只是构建工作区)。改完同步过去再 build,流程见 §4 的「重建主前端」。
6.14 重建主前端:必须在 Linux 容器里 build
主站(30093)的静态资源来自 jnpf-web-monorepo-framework(pnpm monorepo,apps/jnpf-web-apps-main = 包名 @jnpf/main)。本机构建不了,三个原因叠在一起,每一个的表现都很误导人:
| 坑 | 现象 | 根因 |
|---|---|---|
node_modules 是 linux-x64 装的 |
MODULE_NOT_FOUND,栈顶是 rollup/dist/native.js(esbuild / @parcel+watcher 同理) |
那棵树是在容器里装的。rollup 报的是"找不到模块",完全不像平台不兼容,极易误判成依赖装坏了然后去重装 |
容器里挂载路径必须是 /workspace/jnpf-web-monorepo-framework |
Cannot find module '/workspace/jnpf-web-monorepo-framework/internal/vite-config/src/index.ts' |
internal/vite-config/dist/index.mjs 在打包时把自己在磁盘上的绝对路径烧进去了,换挂载点就对不上 |
cssnano 解析不到 |
[vite:css] Failed to load PostCSS config … Cannot find module 'cssnano' |
cssnano 只被 internal/tailwind-config 声明为依赖(pnpm 严格模式不往 app 目录链),而 postcss 配置在 app 目录、按自己的位置解析插件。同样的坑对任何"只被内部包声明"的 postcss 插件都成立 |
⚠️ pnpm run build:main 会骗你。turbo 命中缓存时 FULL TURBO 全量回放,把上次的构建日志原样打出来,dist/ 里每个文件的 mtime 也都刷新成"刚刚"——看着像新构建的,内容其实是旧的。所以每次改完前端先自检产物再 rsync:
grep -rl "公司统一认证" apps/jnpf-web-apps-main/dist # §6.13 那个按钮的标记
绕开 turbo 直接调 vite 就行(工作区包的 dist/ 已经构建过,不需要重跑 turbo):
docker run --rm --user "$(id -u):$(id -g)" -e HOME=/tmp -e NODE_OPTIONS=--max-old-space-size=8192 \
-v "$HOME/Desktop/workspace/jnpf/jnpf-web-monorepo-framework:/workspace/jnpf-web-monorepo-framework" \
-w /workspace/jnpf-web-monorepo-framework/apps/jnpf-web-apps-main \
node:22-slim node ../../node_modules/vite/bin/vite.js build --mode production
四个参数一个都不能省:挂载路径(见上表)、--user $(id -u):$(id -g)(否则 dist/ 变 root 属主,本机 rsync 会 Permission denied)、NODE_OPTIONS(有 12.6MB 的 chunk,默认堆会 OOM)、-w 指到 app 目录(vite.config.mts 和 .env.production 都在那儿)。耗时 ~5 分钟。
cssnano 那个软链是一次性的,node_modules 一旦被重装就没了:
cd ~/Desktop/workspace/jnpf/jnpf-web-monorepo-framework
ln -sfn ../../../internal/tailwind-config/node_modules/cssnano apps/jnpf-web-apps-main/node_modules/cssnano
node -e "console.log(require.resolve('cssnano',{paths:['apps/jnpf-web-apps-main']}))" # 自检
产物里不用手动补 _app.config.js —— 这个 app 没有 postBuild 步骤,@vben/vite-config 的插件在 vite build 时自己生成(jnpf-web-tenant-vue3 那个仓库才要单独跑 postBuild,见 §6.11)。
nginx 直接读盘,01-artifacts.sh 跑完就生效,不需要重启任何 Pod。
6.15 应用中心图标裂图:文件存储没种子 + JVM 的 sun.jnu.encoding 是 ASCII
2026-10-15 已修复并部署验证(/appCenter 两个应用图标正常出图,04-verify.sh PASS=21/FAIL=0,dacli 三项全绿)。
症状:登录后首页正常,但应用中心(/appCenter)两个应用的 Logo 全是裂图,用户头像同理。请求 /api/file/Image/projectlogo/%E4%BA%92%E8%81%94%E7%BD%91.png 返回 HTTP 200 + {"code":400,"msg":"系统异常"}。
两层原因,各自独立,都要修:
① 01-artifacts.sh 从来没同步过文件存储的内置资源。 它只在第 2 步 mkdir -p jnpf-resources,内容全靠「运行时自生」—— 但 base_system.f_icon、base_user.f_head_icon 这些是种子 SQL 里按路径写死的引用,不存在的文件没人会补。所以 PVC 上 /usr/ssw/jnpf-resources/ 一直是空的。
修法:种子资源放在本机 ~/Desktop/workspace/jnpf/jnpf-resources/(470M),只取种子 SQL 真正引用的内置目录做 build/jnpf-resources/:ProjectLogo / Avatar / AiFile / Language / AiModelIcon / DatabaseIcon / UserAvatar(合计 15M)。BiVisualPath(179M)、TemplateFile、DocumentPreview、WebAnnexFile 都是 vendor 的运行时上传/BI 模板,种子 SQL 不引用,不要带进来。
这个目录在 PVC 上是「内置资源 + 用户上传」混在一起的,所以不能走脚本里那套 sha 比对循环(比对必然不等:远端还多着上传文件),走单独一步「远端文件数为 0 才补」,且 tar 只加不删(没有 --delete),不会误删用户上传。
⚠️ 种子 SQL 里目录名有大小写混用:
file/Image/projectlogo/…、databaseicon/…、aimodelicon/…是小写,而config.*FilePath配的是驼峰(ProjectLogo)。Linux/NFS 大小写敏感,两个都得有。本机 APFS 不敏感没法并存(小写目录会被合并进驼峰目录),只能在对端补:脚本第 4 步末尾cp -R一份小写副本。
② 更致命:容器镜像没有 locale,JVM 的 sun.jnu.encoding 退化成 ANSI_X3.4-1968(ASCII)。
kubectl -n wuguirong exec deploy/jnpf-admin -- java -XshowSettings:properties -version 2>&1 | grep jnu
# sun.jnu.encoding = ANSI_X3.4-1968
java.io.File 用 sun.jnu.encoding 把文件名编码成字节,ASCII 编码器遇到中文一律变成 ?,于是盘上字节完全正确的 UTF-8 文件名也寻址不到。镜像里有 C.utf8 locale,加上就正常:
kubectl -n wuguirong exec deploy/jnpf-admin -- \
env LANG=C.UTF-8 LC_ALL=C.UTF-8 java -XshowSettings:properties -version 2>&1 | grep jnu
# sun.jnu.encoding = UTF-8
修法:k8s/20-admin.yaml、k8s/40-satellites.yaml、k8s/50-tenant.yaml 里每个 java 容器(admin / workflow / report / xxl / tenant)的 env 都加 LANG 和 LC_ALL = C.UTF-8。
⚠️ 加
-Dsun.jnu.encoding=UTF-8到JAVA_OPTS没用 —— 这个属性在 JVM 初始化时从 locale 推导,命令行覆盖会被忽略。只能靠 env。
判别小技巧(一眼分清是 ① 还是 ②):放一个纯 ASCII 文件名的测试图,再请求 projectlogo/asciitest.png。
| 结果 | 结论 |
|---|---|
同样是 {"code":400,"msg":"系统异常"} |
文件根本不在盘上 → 查 ① |
| ASCII 名的能出图、中文名的不能 | 文件在、是 JVM 寻址不了 → 查 ② |
别被 curl 的报错带偏:直接 curl 那个 URL(不带登录态)返回的是 {"code":400,"msg":"链接已失效"} —— 那是签名校验失败(?s= 是每用户的 securityKey,见 jnpf-web-apps-main/src/utils/jnpf.ts 的 getAuthMediaUrl),跟文件在不在毫无关系。要判断文件问题必须在已登录的页面里用 fetch(url, {cache:'no-store'}) 复现。
改了 env 之后的连带影响
kubectl apply -f k8s/20-admin.yaml 会把 §7 注入的真密钥打回 PLACEHOLDER_SET_AT_DEPLOY,改完这 3 个 yaml 一定要接着重跑 03-deploy.sh 第 7 步那段 xop run --secret 注入,否则 LLM 和 SSO 全挂。
5 个 java Pod 会滚动重启 → 所有人被踢下线(§6.12 的既有行为),dacli 那边报 llmPing fail → code=600 Login expired,重新 dacli app login 即可,别去查 AI 代理。浏览器端直接重新登录。
PVC 上还有一批
._*的 AppleDouble 垃圾文件(._dist/._互联网.png等,macOS 早期同步时留下的)。没有任何代码引用它们,不影响功能;要彻底清掉可以在同步 Pod 里find /persist -name '._*' -delete(只删._开头的,别手滑)。
7. 硬约束(用户明确要求 / 租户策略)
- 不重新打镜像。 现成镜像直接用;自建产物只以 tar 形式落 PVC。早期「每个服务打一个镜像」的
jnpf-k8s/docker-optional/方案已于 2026-10-15 删除。kkFileView 用用户指定的现成镜像ssw188/kkfile:1.1,同样不重打。 - 容器级
runAsUser必须 = 10106。 准入策略tenant-storage-guard只认容器级,写在 pod 级无效。 - 不能用 hostPath / nfs 卷,存储必须走 PVC。
- 本集群 SA 不能 create secret、不能 delete PVC、不能 get 其他 ns 资源。 密钥只能明文写 Deployment env(与 compose 时代同安全水平);真正的凭据由
03-deploy.sh第 7 步经 xop 注入,yaml 里只留PLACEHOLDER_SET_AT_DEPLOY。 - 容器内存 limit ≤ 4Gi、cpu ≤ 2(LimitRange
tenant-limit)。 - nginx 不能监听 80/443(非 root),统一
listen 8080(租户端 8081),Serviceport: 80 → targetPort: 8080/8081。 - 集群无 IngressClass,对外只能用 NodePort。
AI 出站密钥的注入方式
本租户 SA 无 secret 权限,真实 key 用 xop 经环境变量管道注入,值不进 argv、不进日志、不进模型上下文:
xop run --secret SSW_LLM_API_KEY=llm_key -- bash -c '
kubectl -n wuguirong get deploy jnpf-admin -o json \
| jq "(.spec.template.spec.containers[] | select(.name==\"admin\") | .env[] | select(.name==\"SSW_LLM_API_KEY\")).value = \$ENV.SSW_LLM_API_KEY" \
| kubectl -n wuguirong apply -f -'
⚠️ 改 Deployment 后要 kubectl rollout status deploy/jnpf-admin。
8. 数据库分配
| 库 | 内容 | 表数 |
|---|---|---|
j7 |
主库(低代码/系统/权限/AI),← jnpf_db_init.sql |
332 |
j7flow |
流程引擎 Flowable,← jnpf_flow_init.sql |
70 |
j7xxl |
调度中心 XXL-Job,← jnpf_xxljob_init.sql |
11 |
j7tenant |
租户登记表(base_tenant*),← jnpf_tenant_init.sql,jnpf-tenant 服务的数据源 |
6 |
sswflow |
空库,ssw-admin 的 @DS("sswflow") 数据源(必须存在) |
0 |
dacli_kb |
空库,dacli 知识库(dacli 自己建 ssw_kb schema) |
0 |
JNPF-PostgreSQL.sql 是新建租户时用来灌进 j7 里那个新 schema 的模板(/usr/ssw/tenantApi/,由 jnpf-tenant 运行时读),不属于任何种子库。细节见 §6.9。
9. 排查速查
| 现象 | 先查 |
|---|---|
Pod 一直 ContainerCreating/PodInitializing 且无 Event |
是不是同一 PVC 挂了两次(§6.1) |
Captcha 200 但登录报 System abnormality |
condition report 找缺哪个 bean(§6.2) |
| nginx CrashLoop | kubectl logs <pod> --previous,看是不是 [emerg] host not found(§6.3) |
首页 200 但 /api/* 全挂到超时(curl 000) |
kubectl logs deploy/jnpf-web | grep resolver(§6.3) |
| java 服务起不来 | kubectl exec deploy/jnpf-admin -- tail -50 /usr/ssw/log/jnpf-admin/log_error.log |
| 改了 ConfigMap 没生效 | ConfigMap 不触发 rollout,手动删 Pod(§4) |
应用中心图标 / 用户头像裂图,/api/file/Image/** 返回 {"code":400,"msg":"系统异常"} |
两层原因:① PVC 上 jnpf-resources 是空的(01-artifacts.sh 从没同步过内置资源);② 容器没 locale,JVM sun.jnu.encoding=ANSI_X3.4-1968 寻址不了中文文件名。两处都得修,见 §6.15 |
curl 图片 URL 返回 {"code":400,"msg":"链接已失效"} |
那只是没带登录态,?s= 签名过不了,与文件在不在无关。判文件问题要在已登录页面里 fetch(§6.15) |
脚本报 unbound variable |
$var 紧跟中文标点,改 ${var}(§6.5) |
kubectl apply -f k8s/20-admin.yaml 之后 AI 功能坏了 |
apply 会把 Deployment 重置,把 03-deploy.sh 第 7 步注入的真密钥覆盖回 yaml 里的 PLACEHOLDER_SET_AT_DEPLOY(25 字符)。改完 20-admin.yaml 必须重跑那段 xop 注入(§7) |
dacli 报 appCode=xxx 不存在 (base_system 查不到) |
/api/system/System 是「应用中心」列表,只返回门户/自建应用,平台内置的 mainSystem/workFlow/teamwork 不在里面。dacli 已加平台应用白名单放行(§6.10) |
打开多租户后 admin/123456 登不进去,报 租户不存在 |
账号必须带租户号:host@admin。不含 @ 时 admin 把 admin 整个当租户号去查(§6.9) |
登录报 系统异常,tenant 日志是 getEndTime() NPE |
base_tenant 缺 f_start_time/f_end_time,跑 02-seed-db.sh 补(§6.9) |
admin 日志刷 TenantInvalidException |
请求里的租户号在 j7tenant.base_tenant 查不到,或该租户 f_enabled_mark=0 |
admin 调 DbName/{code} 报 10301 / SameTokenInvalid |
admin 和 tenant 的 redisson.database 不一致(都得是 1),不是少了 sa-token.same-token(§6.9) |
| 新建租户报「脚本文件不存在」 | /usr/ssw/tenantApi/JNPF-PostgreSQL.sql 不在,跑 01-artifacts.sh 补 |
新建租户接口返回成功但 j7 里没 schema |
多半是 TdcSchemaInitUtil 那条旧路径在吞异常(已删除,重打包即解决);现在看 tenant 日志 /usr/ssw/log/jnpf-tenant/(§6.9) |
| 租户端 30095 报「账号或密码错误」 | 多半不是密码错:base_tenant_account.f_delete_mark 是 NULL 被 @TableLogic 过滤掉了,或存成了单层 md5 而不是 md5(md5())。跑 02-seed-db.sh,重置密码用 RESET_TENANT_ADMIN=1(§6.11) |
| 租户端 30095 白屏,静态资源 200 | dist/_app.config.js 没生成 —— postBuild 被省了。构建必须走 vite build && esno ./build/script/postBuild.ts(§6.11) |
租户端首页 200 但 /api/tenant/** 全挂 |
跟主站同一个坑:kubectl logs deploy/jnpf-web | grep resolver,要么 resolver 指错、要么后端地址没写 FQDN(§6.3) |
| 验收脚本报「@SaCheckSame 没生效」但其实生效了 | java 基础镜像里没有 wget,请求根本没发出去;现在改成在 tenant Pod 里用 bash /dev/tcp 手搓请求。另外 JNPF 把 same-token 失败翻译成 code=600 无效内部认证,不是 sa-token 原版的 SameTokenInvalid(§6.9) |
重打 admin 后 Pod 一直起不来,报 Invalid authority field: [jnpf-redis:tcp: |
Redisson 地址里写了 ${REDIS_HOST:...} 占位符,starter 不展开它,RedisURI.parseUrl 把主机段当 IPv6 加方括号 → 写死字面量,或在 ConfigMap 里整块覆盖 spring.redis.redisson.config(§6.12) |
SSO 入口返回 200 {"code":600,"msg":"Login expired"} 而不是 302 |
gateway.white-url 少了 /api/ssw/tds/SsoBind/**。HTTP 状态码仍是 200,curl -f 发现不了。日志里有 [SSO] init 但没有 [SSO] 入口跳转 就是被拦在外面(§6.12) |
mvn -o clean package 报 Child module .../ssw-sswflow does not exist |
根 pom 的 <modules> 还留着已删除的模块目录,注释掉(§6.12) |
mvn -o clean package 报 Charset 无法转换为 java.lang.String |
ssw-common/pom.xml 缺 maven.compiler.source/target=17 的 <properties>(§6.12) |
The requested profile "full" could not be activated |
full profile 只在 ssw-mvp 的 pom 里,本部署不需要,去掉 -P full(§6.12) |
重打 admin 后 NoClassDefFoundError: ssw/common/permission/SswPermissionGuard |
ssw-admin/pom.xml 还引着 ssw-sswflow-controller,从 ~/.m2 解析到旧 jar。本部署不需要 sswflow,注释掉该 dependency(§6.12) |
mvn package 报 BUILD SUCCESS 但代码改动没生效 |
少了 clean(repackage 把上一次的 fat jar 又包了一遍)(§6.12) |
发完版所有人被踢下线、dacli 报 llmPing … (code=600): Login expired |
rollout restart deploy/jnpf-admin 就会作废所有已签发 token,既有行为不是回归。重新 dacli app login --account '租户号@账号' 即可(§6.12) |
SSO 登录跳回一个 JSON:Invalid character ' ' for QUERY_PARAM |
URL 是用 UriComponentsBuilder.build(true) 拼的,它声明「入参已编码」,scope=openid profile email read 的空格就炸了。三处拼 URL 都要 .build().encode()(§6.13) |
SSO 回调报 HashMap cannot be cast to String |
granter() 返回的是 ActionResult.success(Map),按 instanceof Map 取 token 键,别直接强转(§6.13) |
SSO 回调报 invalid_grant(授权码无效或已使用) |
ipass 的 code 一次性,被前面的 curl 手工调试消费掉了。整条流程重跑一次,别复用旧 code(§6.13) |
ipass 侧授权页直接 400,invalid_request |
callbackUrl 与 ipass 管理台里 jnpf 客户端登记的 redirect_uri 不逐字符一致。ipass 先校 redirect_uri 再校 scope,别先怀疑 scope(§6.13) |
| 前端构建「成功」了但页面上改动没生效 | turbo FULL TURBO 回放的旧产物,mtime 全是新的、内容是旧的。自检 grep -rl "<改动标记>" apps/jnpf-web-apps-main/dist,绕开 turbo 直接调 vite(§6.14) |
dacli app create / di create 报 ENOENT ... /jweb/apps/jnpf-web-apps-main/src/api/... |
DACLI_WEB_SRC 没设或设错。必须指向 monorepo 根(~/Desktop/workspace/jnpf/jnpf-web-monorepo-framework/apps/jnpf-web-apps-main),不带 src;env 名是 DACLI_WEB_SRC 不是 JNPF_WEB_SRC(§6.10) |
dacli app logout --tenant X 什么都没提示 |
log.warn 在默认 quiet 模式下被 _output_filter.ts 丢进 buffer 再丢掉。看 ctx.success 里的 tenant / tenantMismatch 字段(§6.10) |
dacli 记的租户和实际登录的不一致 |
--account '租户号@账号' 全串必须优先于 --tenant 的默认值。构造函数里租户取值顺序是 account → opt.tenant,反过来 token.json 会错记成默认值(§6.10) |
| 重新 clone 后 SSO 入口退回 200 + code 600,且 git status 干净 | 检查 git ls-files boot/ssw-admin/src/main/resources/application.yml 有没有输出。历史原因是 boot/.gitignore 有一条 resources/ 把整个目录排掉了(2026-10-15 已删)。别再往那个文件加宽规则,要排产物用 target/、要排凭据用 application-local.yml(§6.12) |
排查时优先用本地零成本手段(ripgrep / tail / ps / curl),别急着让 LLM 读日志。
10. 没做的 / 已知限制
- kkFileView 已部署(
k8s/45-kkfile.yaml,镜像ssw188/kkfile:1.1),nginx 把/FileServer/按前缀透传给jnpf-kkfile:30090。裸访问/FileServer/返回 404 是正常的 —— kkFileView 的 context-path 就是/FileServer,根路径没有文件可预览。镜像由用户直接指定,docker-compose.yml里从头到尾没有 kkfile 的条目(既不是注释状态,是完全没有)。 docker-optional/、other/、根Dockerfile已于 2026-10-15 删除(理由见 §3「已清理的历史目录」),均在回收站可恢复。根docker-compose.yml保留 —— 它是本机 Gitea/PG/Redis 三个在跑容器的唯一定义,删了无法重建(详见 §3 那张对照表)。- 单副本部署,未配 HPA / PDB。测试环境够用。
- 多租户前后端都已开启并端到端验证通过:后端
MultiTenancy: true+ PG schema 隔离(§6.9),前端独立入口http://192.168.1.26:30095/(§6.11)。租户管理 UI 是独立仓库../jnpf/jnpf-web-tenant-vue3(v7.0.0),不在 monorepo 里 ——jnpf-web-monorepo-framework/apps/下只有jnpf-web-apps-main,所以不能走 monorepo 的pnpm build:tenant。改前端要回那个仓库 build,再rsync到build/tenant-web/跑01-artifacts.sh。 - 同事日常用不到租户管理 UI:他们在主前端用
租户号@账号或 SSO 登录即可,只有建租户的人需要管理中心。 - SSO 登录页的「IPASS 登录」按钮已上线(2026-10-15,§6.13 / §6.14):登录页上有租户号输入框 + IPASS 登录按钮,直接跳公司 ipass。原来的收藏链接
http://192.168.1.26:30093/api/ssw/tds/SsoBind/login?tenant=<租户号>仍然可用,两条路并存。 - dacli 多租户已适配(2026-10-15,见 §6.10):
--tenant加在app login/switch/status/logout上,其余命令(form/user/di…)的租户由登录态决定、不需要也不该加 flag。已知限制:token 是单文件~/.dacli-token/token.json,两个租户不能同时在线,切了就回不去上一个(app logout --tenant只做二次确认,不做选择性清除)。 - 租户 schema 间的数据搬移(导出/导入、备份恢复)没做;备份目前等于备份整个
j7。