# 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/:` --- ## 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:dacli123@192.168.1.26: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 个环境变量): ```bash 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,且容器名与现有实例冲突直接起不来。正确姿势: ```bash 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. 常用操作 ```bash 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/ /jnpf-k8s/build/tenant-web/ cd - && ./scripts/01-artifacts.sh ``` **主前端(30093)不一样,必须在 Linux 容器里 build**,细节见 §6.14: ```bash # 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 ``` ```bash # 日常查看 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: ```bash 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 临时加: ```yaml logging: level: org.springframework.boot.autoconfigure: debug ``` 重启后看启动日志里的 condition evaluation report,会直接写明哪个条件没匹配、找到了哪些 bean。 修法(外挂 config,不用重打包): ```yaml 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 # 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.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 | 判别(一步到位,别先怀疑后端): ```bash kubectl -n wuguirong logs deploy/jnpf-web | grep resolver # 111 Connection refused → ① resolver 错 # Host not found → ② 后端地址没写 FQDN ``` **反证后端是否真有问题**(别一上来就 exec 后端 Pod,慢且经常白跑): ```bash 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` ```bash 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 分支只做两件事: ```sql CREATE SCHEMA jnpf_tenant_; -- 不建 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` 的 `public` schema,也就是本部署原来的 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 ```bash 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()`,**不判空**: ```java 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 等都不匹配)。测试环境用: ```bash 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=...`: ```bash 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` 只是它请求体里的名字(yml `chat.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 用户根本看不到)。 用法: ```bash 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,没有第二个地方要同步。 ```bash 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` 的 `` | `Child module .../boot/ssw-sswflow does not exist` —— 目录已在 git 里删除(`D` 状态),但 `` 还留着,Maven 连 reactor 都读不进去 | 注释掉 `ssw-sswflow` | | 2 | `ssw-common/pom.xml` 缺 `` | 编译报 `不兼容的类型: 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): ```yaml 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: ```bash 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 那一段**: ```bash 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.(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`) ```bash 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.*`) ```yaml 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: ```bash grep -rl "公司统一认证" apps/jnpf-web-apps-main/dist # §6.13 那个按钮的标记 ``` 绕开 turbo 直接调 vite 就行(工作区包的 `dist/` 已经构建过,不需要重跑 turbo): ```bash 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` 一旦被重装就没了: ```bash 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)。** ```bash 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,加上就正常: ```bash 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. 硬约束(用户明确要求 / 租户策略) 1. **不重新打镜像。** 现成镜像直接用;自建产物只以 tar 形式落 PVC。早期「每个服务打一个镜像」的 `jnpf-k8s/docker-optional/` 方案**已于 2026-10-15 删除**。kkFileView 用用户指定的现成镜像 `ssw188/kkfile:1.1`,同样不重打。 2. **容器级 `runAsUser` 必须 = 10106。** 准入策略 `tenant-storage-guard` 只认容器级,写在 pod 级无效。 3. **不能用 hostPath / nfs 卷**,存储必须走 PVC。 4. **本集群 SA 不能 create secret、不能 delete PVC、不能 get 其他 ns 资源。** 密钥只能明文写 Deployment env(与 compose 时代同安全水平);真正的凭据由 `03-deploy.sh` 第 7 步经 xop 注入,yaml 里只留 `PLACEHOLDER_SET_AT_DEPLOY`。 5. 容器内存 limit ≤ 4Gi、cpu ≤ 2(LimitRange `tenant-limit`)。 6. **nginx 不能监听 80/443**(非 root),统一 `listen 8080`(租户端 8081),Service `port: 80 → targetPort: 8080/8081`。 7. 集群**无 IngressClass**,对外只能用 NodePort。 ### AI 出站密钥的注入方式 本租户 SA 无 secret 权限,真实 key 用 xop 经环境变量管道注入,**值不进 argv、不进日志、不进模型上下文**: ```bash 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 --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 的 `` 还留着已删除的模块目录,注释掉(§6.12) | | `mvn -o clean package` 报 `Charset 无法转换为 java.lang.String` | `ssw-common/pom.xml` 缺 `maven.compiler.source/target=17` 的 ``(§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`。