317 lines
7.3 KiB
Markdown
317 lines
7.3 KiB
Markdown
# JSP 代理层部署指南
|
||
|
||
## 📌 概述
|
||
|
||
`metrics-proxy.jsp` 是一个 JSP 代理文件，用于处理前端到后端 C# API 的跨域请求。通过在后端调用 API，绕过浏览器的跨域限制。
|
||
|
||
## 🗂️ 文件位置
|
||
|
||
**推荐位置**: 项目 Web 根目录
|
||
```
|
||
/metrics-proxy.jsp
|
||
```
|
||
|
||
**或者 Tomcat 对应位置**:
|
||
```
|
||
$CATALINA_HOME/webapps/ROOT/metrics-proxy.jsp
|
||
```
|
||
|
||
## ⚙️ 部署步骤
|
||
|
||
### 步骤1：复制文件
|
||
将 `metrics-proxy.jsp` 复制到 Web 服务器根目录
|
||
|
||
### 步骤2：验证 Java 环境
|
||
确保安装了以下依赖：
|
||
- Java 8 或更高版本
|
||
- Tomcat 8.5 或更高版本
|
||
- org.json 库
|
||
|
||
### 步骤3：检查 JSP 引擎
|
||
验证服务器支持 JSP：
|
||
```
|
||
访问任何 .jsp 文件，检查是否能正确处理
|
||
```
|
||
|
||
### 步骤4：测试连接
|
||
在浏览器中测试：
|
||
```
|
||
http://localhost:8080/metrics-proxy.jsp?action=getLabelRate&handoverNumber=TEST&env=test
|
||
```
|
||
|
||
## 📦 依赖配置
|
||
|
||
### Maven pom.xml
|
||
```xml
|
||
<dependency>
|
||
<groupId>org.json</groupId>
|
||
<artifactId>json</artifactId>
|
||
<version>20230227</version>
|
||
</dependency>
|
||
|
||
<!-- JSP API -->
|
||
<dependency>
|
||
<groupId>javax.servlet</groupId>
|
||
<artifactId>javax.servlet-api</artifactId>
|
||
<version>3.1.0</version>
|
||
<scope>provided</scope>
|
||
</dependency>
|
||
```
|
||
|
||
### Gradle build.gradle
|
||
```gradle
|
||
dependencies {
|
||
implementation 'org.json:json:20230227'
|
||
providedCompile 'javax.servlet:javax.servlet-api:3.1.0'
|
||
}
|
||
```
|
||
|
||
## 🔧 配置说明
|
||
|
||
### 环境配置
|
||
JSP 自动检测环境参数：
|
||
|
||
| 环境参数 | 值 | 后端地址 |
|
||
|--------|-----|---------|
|
||
| env | local | http://localhost:5002 |
|
||
| env | test | http://172.232.21.79:5002 |
|
||
| env | production | https://lr.tooexp.com |
|
||
|
||
### 支持的操作
|
||
|
||
| Action | 方法 | 参数 | 说明 |
|
||
|--------|------|------|------|
|
||
| getLabelRate | GET | handoverNumber | 获取标签率 |
|
||
| getOrderAssessment | GET | neutralWaybillNumber | 获取订单评估 |
|
||
| getDailySummary | GET | date | 获取每日汇总 |
|
||
| getDailySummaries | GET | startDate, endDate | 获取日期范围 |
|
||
| get24HCompletionRate | GET | date | 获取24小时率 |
|
||
| getDailyCompletionRate | GET | date | 获取每日率 |
|
||
| getBatchOrderMetrics | POST | waybills | 批量查询 |
|
||
| recalculateLabelRate | POST | handoverNumber | 重新计算 |
|
||
|
||
## 🧪 测试方法
|
||
|
||
### 使用 cURL 测试
|
||
```bash
|
||
# 测试 GET 请求
|
||
curl "http://localhost:8080/metrics-proxy.jsp?action=getLabelRate&handoverNumber=HN001&env=test"
|
||
|
||
# 测试 POST 请求
|
||
curl -X POST "http://localhost:8080/metrics-proxy.jsp" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"action":"getBatchOrderMetrics","waybills":["LR001","LR002"],"env":"test"}'
|
||
```
|
||
|
||
### 使用 Postman 测试
|
||
|
||
1. 新建 GET 请求
|
||
2. URL: `http://localhost:8080/metrics-proxy.jsp`
|
||
3. 参数:
|
||
- action: `getLabelRate`
|
||
- handoverNumber: `HN001`
|
||
- env: `test`
|
||
4. 发送请求
|
||
|
||
### 使用 JavaScript 测试
|
||
```javascript
|
||
// 测试获取标签率
|
||
fetch('metrics-proxy.jsp?action=getLabelRate&handoverNumber=HN001&env=test')
|
||
.then(r => r.json())
|
||
.then(data => console.log(data))
|
||
.catch(e => console.error(e));
|
||
```
|
||
|
||
## 🛡️ CORS 配置
|
||
|
||
JSP 已配置 CORS 头：
|
||
```jsp
|
||
response.setHeader("Access-Control-Allow-Origin", "*");
|
||
response.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
|
||
response.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
|
||
```
|
||
|
||
### 限制跨域来源（生产环境建议）
|
||
修改第一行的 CORS 设置：
|
||
```jsp
|
||
response.setHeader("Access-Control-Allow-Origin", "https://yourdomain.com");
|
||
```
|
||
|
||
## 📝 日志配置
|
||
|
||
### 启用 JSP 调试日志
|
||
在 `web.xml` 中添加：
|
||
```xml
|
||
<init-param>
|
||
<param-name>development</param-name>
|
||
<param-value>true</param-value>
|
||
</init-param>
|
||
<init-param>
|
||
<param-name>supressLog</param-name>
|
||
<param-value>false</param-value>
|
||
</init-param>
|
||
```
|
||
|
||
### 查看日志
|
||
- Tomcat: `$CATALINA_HOME/logs/catalina.out`
|
||
- 应用: 取决于配置的日志框架
|
||
|
||
## 🔍 问题排查
|
||
|
||
### 问题1: 404 Not Found
|
||
```
|
||
原因: JSP 文件不存在或路径错误
|
||
解决:
|
||
1. 检查文件是否在正确位置
|
||
2. 确保服务器根目录配置正确
|
||
3. 清除浏览器缓存
|
||
```
|
||
|
||
### 问题2: 500 Internal Server Error
|
||
```
|
||
原因: JSP 执行错误
|
||
解决:
|
||
1. 查看服务器日志
|
||
2. 检查 org.json 库是否正确安装
|
||
3. 检查 Java 环本版本
|
||
```
|
||
|
||
### 问题3: org.json 导入失败
|
||
```
|
||
原因: 缺少依赖
|
||
解决:
|
||
1. 添加 org.json Maven 依赖
|
||
2. 重新构建项目
|
||
3. 清除 Tomcat 工作目录: rm -rf $CATALINA_HOME/work/*
|
||
```
|
||
|
||
### 问题4: 连接到后端 API 超时
|
||
```
|
||
原因: 后端未启动或网络不通
|
||
解决:
|
||
1. 确保后端 API 正在运行
|
||
2. 检查防火墙设置
|
||
3. 验证 URL 是否正确
|
||
4. 增加超时时间: connection.setConnectTimeout(15000)
|
||
```
|
||
|
||
### 问题5: 返回空数据
|
||
```
|
||
原因: 数据不存在或参数错误
|
||
解决:
|
||
1. 检查参数是否正确
|
||
2. 在数据库中验证数据
|
||
3. 查看后端日志
|
||
4. 使用 cURL 直接测试 API
|
||
```
|
||
|
||
## 🔐 安全加固
|
||
|
||
### 1. 输入验证（已包含基础验证）
|
||
建议增强：
|
||
```jsp
|
||
// 验证 handoverNumber 格式
|
||
if (!handoverNumber.matches("^[A-Z0-9-]+$")) {
|
||
resultJson.put("error", "Invalid handoverNumber format");
|
||
}
|
||
```
|
||
|
||
### 2. 限制访问
|
||
在 JSP 开头添加 IP 白名单：
|
||
```jsp
|
||
String clientIP = request.getRemoteAddr();
|
||
String[] whiteList = {"127.0.0.1", "192.168.1.0"};
|
||
if (!Arrays.asList(whiteList).contains(clientIP)) {
|
||
response.sendError(403, "Access Denied");
|
||
return;
|
||
}
|
||
```
|
||
|
||
### 3. 请求限流
|
||
```jsp
|
||
// 添加简单的速率限制（需要使用 Redis 或其他缓存）
|
||
String key = clientIP + "_" + action;
|
||
if (hasExceededRateLimit(key)) {
|
||
resultJson.put("error", "Rate limit exceeded");
|
||
}
|
||
```
|
||
|
||
### 4. 请求签名验证
|
||
```jsp
|
||
String signature = request.getParameter("signature");
|
||
if (!verifySignature(params, signature)) {
|
||
resultJson.put("error", "Invalid signature");
|
||
}
|
||
```
|
||
|
||
## 📊 性能优化
|
||
|
||
### 1. 连接超时优化
|
||
```jsp
|
||
connection.setConnectTimeout(5000); // 5 秒
|
||
connection.setReadTimeout(10000); // 10 秒
|
||
```
|
||
|
||
### 2. 连接复用
|
||
```jsp
|
||
// 使用连接池（需要添加依赖）
|
||
HttpClientBuilder.create()
|
||
.setConnectionManager(connManager)
|
||
.build();
|
||
```
|
||
|
||
### 3. 缓存响应
|
||
```jsp
|
||
// 缓存 5 分钟
|
||
response.setHeader("Cache-Control", "max-age=300");
|
||
```
|
||
|
||
## 🚀 生产环境清单
|
||
|
||
- [ ] org.json 库已正确安装
|
||
- [ ] JSP 文件已部署到正确位置
|
||
- [ ] 后端 API 已配置 HTTPS
|
||
- [ ] CORS 头已限制为生产域名
|
||
- [ ] 日志记录已启用
|
||
- [ ] 输入验证已加强
|
||
- [ ] IP 白名单已配置
|
||
- [ ] 请求限流已实现
|
||
- [ ] 错误处理已完善
|
||
- [ ] 性能监控已启用
|
||
|
||
## 📞 维护建议
|
||
|
||
1. **定期检查日志** - 每天检查一次错误日志
|
||
2. **监控性能** - 记录 API 响应时间
|
||
3. **备份配置** - 保存 web.xml 和其他配置文件
|
||
4. **更新依赖** - 定期更新 org.json 库
|
||
5. **安全审计** - 定期进行安全审计
|
||
|
||
## 🎓 扩展功能
|
||
|
||
### 添加认证
|
||
```jsp
|
||
String token = request.getParameter("token");
|
||
if (!validateToken(token)) {
|
||
resultJson.put("error", "Unauthorized");
|
||
}
|
||
```
|
||
|
||
### 添加审计日志
|
||
```jsp
|
||
auditLog.info("Action: " + action + ", User: " + userId + ", Timestamp: " + System.currentTimeMillis());
|
||
```
|
||
|
||
### 支持更多 API
|
||
```jsp
|
||
else if ("getOrderLog".equals(action)) {
|
||
apiUrl = baseUrl + "/api/order-log/query";
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**文档版本**: 1.0
|
||
**最后更新**: 2026-05-17
|
||
**作者**: 系统团队
|