LabelChange-server/.trae/documents/jsp_proxy_deployment.md

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

<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

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 测试

# 测试 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 测试

// 测试获取标签率
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 头：

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 设置：

response.setHeader("Access-Control-Allow-Origin", "https://yourdomain.com");

📝 日志配置

启用 JSP 调试日志

在 web.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. 输入验证（已包含基础验证）

建议增强：

// 验证 handoverNumber 格式
if (!handoverNumber.matches("^[A-Z0-9-]+$")) {
    resultJson.put("error", "Invalid handoverNumber format");
}

2. 限制访问

在 JSP 开头添加 IP 白名单：

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. 请求限流

// 添加简单的速率限制（需要使用 Redis 或其他缓存）
String key = clientIP + "_" + action;
if (hasExceededRateLimit(key)) {
    resultJson.put("error", "Rate limit exceeded");
}

4. 请求签名验证

String signature = request.getParameter("signature");
if (!verifySignature(params, signature)) {
    resultJson.put("error", "Invalid signature");
}

📊 性能优化

1. 连接超时优化

connection.setConnectTimeout(5000);   // 5 秒
connection.setReadTimeout(10000);     // 10 秒

2. 连接复用

// 使用连接池（需要添加依赖）
HttpClientBuilder.create()
    .setConnectionManager(connManager)
    .build();

3. 缓存响应

// 缓存 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. 安全审计 - 定期进行安全审计

🎓 扩展功能

添加认证

String token = request.getParameter("token");
if (!validateToken(token)) {
    resultJson.put("error", "Unauthorized");
}

添加审计日志

auditLog.info("Action: " + action + ", User: " + userId + ", Timestamp: " + System.currentTimeMillis());

支持更多 API

else if ("getOrderLog".equals(action)) {
    apiUrl = baseUrl + "/api/order-log/query";
}

---

文档版本: 1.0 最后更新: 2026-05-17 作者: 系统团队