Files
adminandClaude 646cfeab57 chore: 清理废弃目录 + boot/ 并入本仓库
清理三个目录 (理由见 AGENTS.md §3):
- 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                摘掉后 boot/ 变普通子目录并入。154 个 commit 已备份
                            到 ~/.cache/testspace-cleanup-20261015/boot-git-backup

根 docker-compose.yml 保留 (5 个镜像的来源记录)。根 Dockerfile 未动 —— 它是
compose 时代的 java+Claude Code 镜像, 与 JNPF 部署无关, 待定。

boot/ 并入 (原 origin gitea:3000 已不可达, 且工作区有大量未提交改动):
把 §6.12 的三处 pom 修复和 §6.13 的两个 SSO 新文件 (SsoBindController /
SsoTokenGranter) 一起纳入版本管理 —— 它们此前只活在工作区, 推不出去。

关掉 §6.12 那个坑: boot/.gitignore 里有一条 resources/, 把
ssw-admin/src/main/resources/ 整个排掉了。于是 application.yml (含 SSO 的
gateway.white-url 白名单) 从来不在版本控制里 —— 重新 clone 一遍白名单就没了,
SSO 入口退回 HTTP 200 + code 600, 而 git status 看不到任何异常, 因为它本来
就该入库却一直被忽略着。现已删除该规则, resources/ 全部 22 个文件入库
(含 ip2region xdb v4 11M + v6 35M, 保证 clone 出来就能 mvn package)。

AGENTS.md: §3 补 boot/ 与清理说明, §6.12 末尾改为「已闭合」并写明别再往
boot/.gitignore 加宽规则, §7.1/§1/§10 去掉 docker-optional 与 other/ 的
失效引用, §9 加一条「clone 后白名单消失」的排查项。

Co-Authored-By: Claude <[email protected]>
2026-10-15 14:39:05 +08:00
..

ssw-common 模块开发指南

本文档记录如何在 ssw-common 中添加新功能,包括代码编写、编译、打包、重启和测试验证。


一、模块结构

boot/ssw-common/
├── ssw-common-entity/           # 实体层
│   └── pom.xml
├── ssw-common-biz/              # 业务层
│   ├── pom.xml
│   └── src/main/java/ssw/common/
│       ├── entity/              # 实体类
│       ├── service/            # 服务接口
│       └── service/impl/       # 服务实现
└── ssw-common-controller/      # 控制层
    ├── pom.xml
    └── src/main/java/ssw/common/controller/

二、Maven 安装(如果系统没有 mvn)

# 方案1:下载解压
cd /tmp
curl -L "https://archive.apache.org/dist/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz" -o maven.tar.gz
tar -xzf maven.tar.gz
mv apache-maven-3.9.6 ~/maven
export PATH="$HOME/maven/bin:$PATH"

# 方案2:Homebrew
brew install maven

三、编译

cd /Users/xs/Desktop/6.2/boot
export PATH="$HOME/maven/bin:$PATH"

# 仅编译 ssw-common(快速检查语法)
mvn clean compile -pl ssw-common -am -DskipTests

# 编译整个项目(推荐)
mvn clean compile -DskipTests

四、打包

cd /Users/xs/Desktop/6.2/boot
export PATH="$HOME/maven/bin:$PATH"

# 跳过测试打包
mvn clean package -DskipTests

五、重启服务

cd /Users/xs/Desktop/6.2/boot/jnpf-admin

# 1. 找到进程 PID
ps aux | grep "jnpf-admin.*dev" | grep -v grep

# 2. 停止旧进程(替换 PID)
kill <PID>

# 3. 启动新 jar
java -jar target/jnpf-admin-6.2.0-RELEASE.jar --spring.profiles.active=dev

# 或者后台运行
nohup java -jar target/jnpf-admin-6.2.0-RELEASE.jar --spring.profiles.active=dev > app.log 2>&1 &

六、测试验证

6.1 获取 Token(使用 Python)

import sys
sys.path.insert(0, '/Users/xs/Desktop/6.2')
from aibridge import JNPFClient, JNPFConfig

client = JNPFClient.from_config(JNPFConfig())
client.login()
print(client.token)

6.2 使用 curl 测试

# 获取 token(从上面 Python 输出复制)
TOKEN="bearer <your-token>"

# 测试 API
curl -s "http://127.0.0.1:30000/api/common/tableCount/ais/count" \
  -H "Authorization: $TOKEN" | jq .

curl -s "http://127.0.0.1:30000/api/common/tableCount/ais/list" \
  -H "Authorization: $TOKEN" | jq '.data | .[0:5]'

七、pom.xml 依赖规范

ssw-common-entity/pom.xml

<dependencies>
    <dependency>
        <groupId>com.jnpf</groupId>
        <artifactId>jnpf-common-all</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>

ssw-common-biz/pom.xml

<dependencies>
    <dependency>
        <groupId>com.jnpf</groupId>
        <artifactId>ssw-common-entity</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>com.jnpf</groupId>
        <artifactId>jnpf-common-all</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>3.12.0</version>
    </dependency>
</dependencies>

ssw-common-controller/pom.xml

<dependencies>
    <dependency>
        <groupId>com.jnpf</groupId>
        <artifactId>ssw-common-biz</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>com.jnpf</groupId>
        <artifactId>jnpf-common-all</artifactId>
        <version>${project.version}</version>
    </dependency>
</dependencies>

jnpf-admin/pom.xml(添加模块依赖)

<dependency>
    <groupId>com.jnpf</groupId>
    <artifactId>ssw-common-controller</artifactId>
    <version>${project.version}</version>
</dependency>

八、常见问题

8.1 mvn: command not found

Maven 未安装或不在 PATH 中,参考第二节安装。

8.2 编译错误:找不到符号

  • 检查 pom.xml 依赖是否正确添加
  • 检查 import 语句是否正确
  • 确保在 boot 根目录执行 mvn 命令

8.3 404 错误:接口未找到

服务未重启,需要重新打包并启动 jar。

8.4 401 错误:未授权

Token 过期或未传递,重新获取 Token。


九、一键脚本

#!/bin/bash
cd /Users/xs/Desktop/6.2/boot
export PATH="$HOME/maven/bin:$PATH"

echo "=== 1. 编译打包 ==="
mvn clean package -DskipTests

echo "=== 2. 停止旧进程 ==="
PID=$(ps aux | grep "jnpf-admin.*dev" | grep -v grep | awk '{print $2}')
if [ -n "$PID" ]; then
    kill $PID
    echo "已停止进程: $PID"
    sleep 3
fi

echo "=== 3. 启动新服务 ==="
cd jnpf-admin
nohup java -jar target/jnpf-admin-6.2.0-RELEASE.jar --spring.profiles.active=dev > /tmp/jnpf.log 2>&1 &
echo "启动中,等待 15 秒..."
sleep 15

echo "=== 4. 测试验证 ==="
curl -s "http://127.0.0.1:30000/api/common/tableCount/ais/count" | jq .

十、相关配置

配置项 值
Maven 路径 ~/maven/bin/mvn
项目路径 /Users/xs/Desktop/6.2/boot
JAR 路径 jnpf-admin/target/jnpf-admin-6.2.0-RELEASE.jar
服务端口 30000
日志文件 /tmp/jnpf.log
ais db_link_id 808687067075709509