Files
adminandClaude Code 5fd76c5c50 chore: 删根 Dockerfile, 订正 docker-compose.yml 头部
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]>
2026-10-15 14:50:23 +08:00

986 lines
76 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 个环境变量):
```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/ <testspace>/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>.<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 |
判别(一步到位,别先怀疑后端):
```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_<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` 的 `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` 的 `<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):
```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.<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`)
```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 <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`。