From 2dde407a678d88d28cb88d6695c90e90cc369fc0 Mon Sep 17 00:00:00 2001 From: Tian jianyong <11429339@qq.com> Date: Thu, 20 Nov 2025 12:27:14 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=A0=E9=99=A4adxp-adapter=E7=9A=84QUICKSTA?= =?UTF-8?q?RT.md=EF=BC=8C=E4=BF=AE=E6=94=B9README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- adxp-adapter/QUICKSTART.md | 438 ------------------------------------- adxp-adapter/README.md | 140 ++++-------- 2 files changed, 41 insertions(+), 537 deletions(-) delete mode 100644 adxp-adapter/QUICKSTART.md diff --git a/adxp-adapter/QUICKSTART.md b/adxp-adapter/QUICKSTART.md deleted file mode 100644 index a0b84a53..00000000 --- a/adxp-adapter/QUICKSTART.md +++ /dev/null @@ -1,438 +0,0 @@ -# ADXP SDK Adapter 快速开始 - -## 方案概述 - -ADXP SDK (adxp-client-2.6.9.jar) 基于 JDK 8 开发，无法在 Java 11+ 环境运行。本方案通过独立的适配器服务解决兼容性问题。 - -### 架构 - -``` -主应用 (Java 17) → HTTP → ADXP Adapter (Java 8, Docker) → SOAP → 数据中台 - └─ port 8080 └─ port 8086 └─ port 7001 -``` - -### Apple Silicon (M1/M2/M3) 用户 - -✅ **推荐使用 Docker**，无需安装 Java 8（Homebrew 的 openjdk@8 只有 x86_64 版本） - ---- - -## 🚀 快速开始（Docker 方式，推荐） - -### 步骤 1: 启动 Mock 服务器（模拟数据中台） - -```bash -# 在项目根目录 -cd tools -python3 mock_adxp.py --host 0.0.0.0 --port 7001 --auto --interval 10 -``` - -**说明**: Mock 服务器监听 `0.0.0.0:7001`，每 10 秒自动生成航班消息 - -### 步骤 2: 编译适配器服务 - -```bash -cd ../adxp-adapter -mvn clean package -DskipTests -``` - -**预期输出**: `BUILD SUCCESS`，生成 `target/adxp-adapter.jar` - -### 步骤 3: 构建 Docker 镜像 - -```bash -docker build -t adxp-adapter:1.0.0 . -``` - -**说明**: 使用 OpenJDK 8（非 Alpine），包含 `net-tools`（SDK 需要 `ifconfig` 命令） - -### 步骤 4: 启动 Docker 容器 - -```bash -docker run -d \ - -p 8086:8086 \ - -e ADXP_HOST=host.docker.internal \ - -e ADXP_PORT=7001 \ - --name adxp-adapter \ - adxp-adapter:1.0.0 -``` - -**说明**: -- `host.docker.internal` 指向宿主机（访问本地 mock 服务器） -- 环境变量可覆盖配置文件 - -### 步骤 5: 验证适配器服务 - -```bash -# 健康检查 -curl http://localhost:8086/api/adxp/health - -# 预期输出: {"activeSessions":0,"status":"UP"} -``` - -### 步骤 6: 测试完整流程 - -```bash -# 1. 登录 -LOGIN_RESPONSE=$(curl -s -X POST http://localhost:8086/api/adxp/login \ - -H "Content-Type: application/json" \ - -d '{"username":"dianxin","password":"dianxin@123"}') - -echo "登录响应: $LOGIN_RESPONSE" -# 预期: {"success":true,"sessionId":"xxx-xxx-xxx","message":"登录成功"} - -# 2. 提取 SessionId -SESSION_ID=$(echo "$LOGIN_RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['sessionId'])") -echo "SessionId: $SESSION_ID" - -# 3. 接收消息 -curl -s "http://localhost:8086/api/adxp/messages?sessionId=$SESSION_ID" | python3 -m json.tool - -# 4. 退出登录 -curl -s -X POST http://localhost:8086/api/adxp/logout \ - -H "Content-Type: application/json" \ - -d "{\"sessionId\":\"$SESSION_ID\"}" | python3 -m json.tool - -# 预期: {"success":true,"message":"登出成功"} -``` - -### 步骤 7: 启动主应用 - -```bash -cd ../qaup-admin -mvn spring-boot:run -Dspring-boot.run.profiles=dev,druid -``` - -**主应用会自动通过 HTTP 调用适配器服务！** - ---- - -## 📋 Docker 常用命令 - -```bash -# 查看日志 -docker logs -f adxp-adapter - -# 重启容器 -docker restart adxp-adapter - -# 停止并删除容器 -docker stop adxp-adapter && docker rm adxp-adapter - -# 重新构建镜像（代码修改后） -cd adxp-adapter -mvn clean package -DskipTests -docker stop adxp-adapter && docker rm adxp-adapter -docker build -t adxp-adapter:1.0.0 . -docker run -d -p 8086:8086 -e ADXP_HOST=host.docker.internal -e ADXP_PORT=7001 --name adxp-adapter adxp-adapter:1.0.0 -``` - ---- - -## 🛠️ 本地运行（需要 Java 8） - -**仅适用于 x86_64 机器或已安装 Java 8 的环境** - -### 步骤 1: 启动 Mock 服务器 - -```bash -cd tools -python3 mock_adxp.py --host 0.0.0.0 --port 7001 --auto --interval 10 -``` - -### 步骤 2: 编译 - -```bash -cd ../adxp-adapter -mvn clean package -DskipTests -``` - -### 步骤 3: 启动适配器 - -```bash -# 如果系统默认是 Java 8 -java -jar target/adxp-adapter.jar - -# 或指定 Java 8 路径 -/path/to/jdk8/bin/java -jar target/adxp-adapter.jar - -# 或使用启动脚本（自动查找 Java 8） -./start.sh -``` - -### 步骤 4: 测试 - -同 Docker 方式的步骤 6 - -## 配置说明 - -### 主应用配置 (application-dev.yml) - -```yaml -data: - collector: - adxp-adapter: - host: localhost # 适配器服务地址 - port: 8086 # 适配器服务端口 - username: dianxin - password: dianxin@123 - reconnect-delay-millis: 3000 -``` - -### 适配器服务配置 (application.yml) - -```yaml -adxp: - host: localhost # 真实数据中台地址（或 mock 服务器） - port: 7001 # 数据中台端口 -``` - ---- - -## 🐳 Docker Compose 部署（生产环境） - -### 1. 准备环境变量 - -```bash -# 创建 .env 文件 -cat > .env << EOF -ADXP_HOST=10.10.10.100 # 真实数据中台 IP -ADXP_PORT=7001 # 真实数据中台端口 -EOF -``` - -### 2. 编译和构建 - -```bash -cd adxp-adapter -mvn clean package -DskipTests -docker build -t adxp-adapter:1.0.0 . -``` - -### 3. 启动服务 - -```bash -# 使用 Docker Compose -docker-compose up -d - -# 查看日志 -docker-compose logs -f adxp-adapter - -# 查看状态 -docker-compose ps -``` - -### 4. 验证部署 - -```bash -# 健康检查 -curl http://localhost:8086/api/adxp/health - -# 测试登录 -curl -X POST http://localhost:8086/api/adxp/login \ - -H "Content-Type: application/json" \ - -d '{"username":"dianxin","password":"dianxin@123"}' -``` - -### 5. 停止服务 - -```bash -docker-compose down -``` - ---- - -## 🔧 环境切换 - -### 开发环境（使用 Mock） - -**主应用配置** (`qaup-admin/src/main/resources/application-dev.yml`): -```yaml -data: - collector: - adxp-adapter: - host: localhost - port: 8086 - username: dianxin - password: dianxin@123 - reconnect-delay-millis: 3000 -``` - -**适配器配置** (`.env` 或环境变量): -```bash -ADXP_HOST=host.docker.internal # 指向宿主机 mock 服务器 -ADXP_PORT=7001 -``` - -**Mock 服务器**: -```bash -python3 tools/mock_adxp.py --host 0.0.0.0 --port 7001 --auto --interval 10 -``` - -### 生产环境（连接真实数据中台） - -**主应用配置** (`qaup-admin/src/main/resources/application-prod.yml`): -```yaml -data: - collector: - adxp-adapter: - host: 192.168.1.100 # 适配器服务的真实 IP - port: 8086 - username: ${ADXP_USERNAME} # 从环境变量读取 - password: ${ADXP_PASSWORD} - reconnect-delay-millis: 3000 -``` - -**适配器配置** (`.env` 文件): -```bash -ADXP_HOST=10.10.10.100 # 真实数据中台 IP -ADXP_PORT=7001 -``` - ---- - -## 🐛 故障排查 - -### 问题 1: Docker 容器启动失败 - -**检查日志**: -```bash -docker logs adxp-adapter -``` - -**常见错误**: -- `Cannot find ifconfig` → Dockerfile 使用了 Alpine 镜像，应使用 `openjdk:8-jdk` -- `Connection refused` → Mock 服务器未启动或端口错误 - -### 问题 2: 登录失败 (code=802/803) - -**原因**: SDK 无法连接到数据中台 - -**排查步骤**: -```bash -# 1. 检查 mock 服务器是否运行 -lsof -ti:7001 - -# 2. 测试网络连接 -curl http://localhost:7001/LoginService?wsdl - -# 3. 检查适配器环境变量 -docker exec adxp-adapter env | grep ADXP - -# 4. 查看适配器日志 -docker logs adxp-adapter 2>&1 | grep -E "ERROR|Exception" -``` - -### 问题 3: HTTP 406 Not Acceptable - -**原因**: DTO 类缺少 getter/setter 方法 - -**解决方案**: -- 确保 `LoginResponse`、`MessageResponse` 有显式的 getter/setter（不要只依赖 Lombok） -- 确保 `jackson-databind` 依赖存在 - -**验证**: -```bash -# 查看 pom.xml 中的 Jackson 依赖 -grep -A 5 "jackson-databind" adxp-adapter/pom.xml -``` - -### 问题 4: Apple Silicon 兼容性 - -**错误**: `openjdk@8: The x86_64 architecture is required` - -**解决方案**: 使用 Docker（推荐），或使用 Rosetta 2 运行 x86_64 版本 - -### 问题 5: Mock 响应格式错误 - -**症状**: SDK 返回 code=803 "发送请求错误" - -**排查**: -```bash -# 查看 mock 服务器日志 -tail -f /tmp/mock_adxp.log - -# 检查 SOAP 响应格式 -curl -X POST http://localhost:7001/LoginService \ - -H "Content-Type: text/xml" \ - -d ' - - - dianxindianxin@123 - -' -``` - ---- - -## 📊 监控和日志 - -### 健康检查端点 - -```bash -# 适配器健康状态 -curl http://localhost:8086/api/adxp/health -# 返回: {"activeSessions":0,"status":"UP"} - -# Spring Boot Actuator -curl http://localhost:8086/actuator/health -``` - -### 日志查看 - -```bash -# Docker 容器日志 -docker logs -f adxp-adapter - -# 实时过滤错误 -docker logs -f adxp-adapter 2>&1 | grep -E "ERROR|WARN" - -# Mock 服务器日志 -tail -f /tmp/mock_adxp.log - -# 主应用日志 -tail -f qaup-admin/app.log | grep -E "adxp|flight" -``` - -### 性能监控 - -```bash -# 容器资源使用 -docker stats adxp-adapter - -# 网络延迟测试 -time curl -s http://localhost:8086/api/adxp/health -``` - ---- - -## 📈 性能指标 - -- **HTTP 延迟**: < 5ms（局域网） -- **适配器内存**: ~256MB（基础）+ SDK 使用 -- **并发支持**: 多个主应用实例可共享一个适配器 -- **会话管理**: 自动重连，无需手动维护 - ---- - -## ✅ 验收检查清单 - -部署前请确认： - -- [ ] Mock 服务器正常运行（开发环境） -- [ ] 适配器 Docker 镜像构建成功 -- [ ] 适配器容器启动成功 -- [ ] 健康检查返回 `{"status":"UP"}` -- [ ] 登录测试成功，返回 sessionId -- [ ] 主应用能通过 HTTP 调用适配器 -- [ ] 日志中无 ERROR 级别错误 - ---- - -## 🚀 下一步 - -1. ✅ **开发环境测试完成** - Mock 服务器 + 适配器正常工作 -2. 🔧 **生产部署** - 修改 ADXP_HOST 连接真实数据中台 -3. 📊 **监控集成** - 添加 Prometheus metrics（可选） -4. 🔒 **安全加固** - 添加 API 认证/授权（可选） -5. 📦 **K8s 部署** - 创建 Deployment 和 Service 配置（可选） diff --git a/adxp-adapter/README.md b/adxp-adapter/README.md index 2a144de1..53580afa 100644 --- a/adxp-adapter/README.md +++ b/adxp-adapter/README.md @@ -15,7 +15,20 @@ ADXP 数据中台 SDK 适配器服务 - 基于 JDK 8 运行的独立微服务 ## 快速开始 -### 方式1：本地运行（需要 JDK 8） +### 方式1：Docker Compose（推荐） + +```bash +# 1. 构建并启动服务 +docker-compose up -d + +# 2. 查看日志 +docker-compose logs -f + +# 3. 停止服务 +docker-compose down +``` + +### 方式2：本地运行（需要 JDK 8） ```bash # 1. 编译 @@ -23,42 +36,10 @@ mvn clean package # 2. 运行 java -jar target/adxp-adapter.jar \ - --adxp.host=10.10.10.100 \ + --adxp.host=localhost \ --adxp.port=7001 ``` -### 方式2：Docker 运行（推荐） - -```bash -# 1. 构建镜像 -docker build -t adxp-adapter:1.0.0 . - -# 2. 运行容器 -docker run -d \ - -p 8086:8086 \ - -e ADXP_HOST=10.10.10.100 \ - -e ADXP_PORT=7001 \ - --name adxp-adapter \ - adxp-adapter:1.0.0 -``` - -### 方式3：Docker Compose（最简单） - -```bash -# 1. 设置环境变量 -export ADXP_HOST=10.10.10.100 -export ADXP_PORT=7001 - -# 2. 启动服务 -docker-compose up -d - -# 3. 查看日志 -docker-compose logs -f - -# 4. 停止服务 -docker-compose down -``` - ## API 文档 ### 1. 登录 @@ -128,19 +109,20 @@ GET /api/adxp/health } ``` -## 测试 +## 快速测试 ```bash -# 1. 登录 +# 健康检查 +curl http://localhost:8086/api/adxp/health +# 预期输出: {"status":"UP","activeSessions":0} + +# 登录 curl -X POST http://localhost:8086/api/adxp/login \ -H "Content-Type: application/json" \ -d '{"username":"dianxin","password":"dianxin@123"}' -# 2. 接收消息（替换为实际的 sessionId） +# 接收消息（替换为实际的 sessionId） curl "http://localhost:8086/api/adxp/messages?sessionId=YOUR_SESSION_ID" - -# 3. 健康检查 -curl http://localhost:8086/api/adxp/health ``` ## 配置说明 @@ -165,56 +147,26 @@ adxp: ### 开发环境 -使用 mock 服务器进行开发测试： - ```bash -# 启动 mock ADXP 服务器 +# 1. 启动 mock ADXP 服务器 cd /path/to/QAUP-Management/tools python3 mock_adxp.py --auto --interval 10 -# 启动适配器（指向 localhost） +# 2. 启动适配器（默认指向 localhost） docker-compose up -d ``` ### 生产环境 -连接真实的 ADXP 数据中台： - ```bash -# 设置真实环境变量 -export ADXP_HOST=10.10.10.100 # 真实数据中台 IP -export ADXP_PORT=7001 +# 1. 创建环境变量文件 +cat > .env << EOF +ADXP_HOST=10.10.10.100 # 真实数据中台 IP +ADXP_PORT=7001 # 真实数据中台端口 +EOF -# 启动服务 -docker-compose -f docker-compose.yml up -d -``` - -## 监控 - -- **健康检查**: `http://localhost:8086/api/adxp/health` -- **Actuator**: `http://localhost:8086/actuator/health` -- **日志文件**: `logs/adxp-adapter.log` - -## 故障排查 - -### 登录失败 - -1. 检查 ADXP 服务器是否可达 -2. 验证用户名密码是否正确 -3. 查看日志: `docker-compose logs adxp-adapter` - -### Session 过期 - -客户端需要实现重新登录逻辑，定期刷新 session。 - -### 网络问题 - -确保容器能够访问 ADXP 服务器： - -```bash -# 进入容器测试网络 -docker exec -it adxp-adapter sh -ping ${ADXP_HOST} +# 2. 启动服务 +docker-compose up -d ``` ## 开发说明 @@ -223,31 +175,21 @@ ping ${ADXP_HOST} ``` adxp-adapter/ -├── pom.xml # Maven 配置 -├── Dockerfile # Docker 镜像定义 -├── docker-compose.yml # Docker Compose 配置 -├── libs/ # SDK JAR 文件 +├── pom.xml # Maven 配置 +├── Dockerfile # Docker 镜像定义 +├── docker-compose.yml # Docker Compose 配置 +├── libs/ # 数据中台 SDK │ ├── adxp-client-2.6.9.jar │ └── mq.allclient-9.0.jar -└── src/main/java/com/qaup/adxp/adapter/ - ├── AdxpAdapterApplication.java # 主应用类 - ├── controller/ - │ └── AdxpController.java # REST API 控制器 - ├── service/ - │ └── AdxpSdkService.java # SDK 封装服务 - └── dto/ - ├── LoginRequest.java - ├── LoginResponse.java - ├── FlightMessage.java - └── MessageResponse.java +└── src/ # 源代码 ``` -### 依赖说明 +### 核心依赖 -- `adxp-client-2.6.9.jar`: 数据中台 SDK -- `mq.allclient-9.0.jar`: IBM MQ 客户端 -- Apache CXF 3.2.4: SOAP 支持 -- Jackson 1.9.13: JSON 序列化 +- **adxp-client-2.6.9.jar**: 数据中台 SDK +- **Apache CXF 3.2.4**: SOAP 协议支持 +- **Jackson 1.9.13**: JSON 序列化 +- **Spring Boot 2.7.18**: 应用框架 ## 许可证