删除adxp-adapter的QUICKSTART.md，修改README.md
This commit is contained in:
parent
6e1f1c7369
commit
2dde407a67
@ -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 '<?xml version="1.0"?>
|
||||
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
|
||||
<soapenv:Body><log:login xmlns:log="http://LoginService">
|
||||
<username>dianxin</username><password>dianxin@123</password>
|
||||
</log:login></soapenv:Body>
|
||||
</soapenv:Envelope>'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 监控和日志
|
||||
|
||||
### 健康检查端点
|
||||
|
||||
```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 配置（可选）
|
||||
@ -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**: 应用框架
|
||||
|
||||
## 许可证
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user