Files
MES/yawei-mes/.tasks/2025-10-18_硬件融合接口加密文档.md
2026-04-02 10:39:03 +08:00

24 KiB
Raw Blame History

LabVIEW接口加密使用指南

📋 文档信息

  • 项目名称MES系统 - LabVIEW硬件设备接口
  • 更新日期2025-10-18
  • 文档版本v4.0
  • 当前状态 所有8个LabVIEW接口已全面加密

快速导航

章节 内容 适用人员
📌 接口总览 所有接口列表及加密状态 全部
🔐 已加密接口 加密接口使用方法 LabVIEW开发
🔓 未加密接口 不需加密的接口说明 LabVIEW开发
🎯 AES加密参数 加密技术参数 技术人员
🛠️ 解密方法 Python脚本使用 LabVIEW开发
常见问题 FAQ 全部

📌 接口总览

LabVIEW专用接口外部调用- 全部已加密

接口名称 请求方式 路径 是否加密 用途
通过设备ID查询配置 GET /device/{iotDeviceId} 已加密 获取数据库配置
通过租户+设备查询 POST /tenant/device 已加密 获取数据库配置
查询配置列表 GET /list 已加密 获取所有配置
获取配置详情 GET /{id} 已加密 获取单个配置
获取目标表配置 GET /targetTable/{id} 已加密 获取目标表配置
测试数据库连接 POST /testConnection 已加密 测试连接并返回配置
查询所有设备ID GET /deviceIds 已加密 获取设备列表和配置
按租户查询设备ID GET /deviceIds/tenant 已加密 按租户获取设备列表和配置

管理后台接口(内部使用)

接口名称 请求方式 路径 是否加密 说明
新增配置 POST / 未加密 Spring Security保护
修改配置 PUT / 未加密 Spring Security保护
删除配置 DELETE /{ids} 未加密 Spring Security保护
导出配置 POST /export 未加密 Spring Security保护

🔐 已加密接口详情

接口1通过设备ID查询配置

适用场景LabVIEW只知道设备ID需要获取数据库配置

📝 接口信息

方法GET
路径:/iot/labview/device/{iotDeviceId}
完整地址http://服务器IP:8080/iot/labview/device/{iotDeviceId}

📥 请求示例

GET http://192.168.1.100:8080/iot/labview/device/1001

路径参数

  • iotDeviceId设备ID数字

📤 响应示例

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "id": 1,
    "iotDeviceId": 1001,
    "tenantId": 1,
    "tenantName": "默认租户",
    "iotTargetTable": "{\"data\":\"ymes_iiot_data\"}",
    "encrypted": "pzH8mWXKJqP9vE5tYnZxJg8fL2kR7sW..."
  }
}

接口2:通过租户+设备查询配置

适用场景LabVIEW知道租户ID和设备ID需要获取数据库配置

📝 接口信息

方法POST
路径:/iot/labview/tenant/device
完整地址http://服务器IP:8080/iot/labview/tenant/device
请求头Content-Type: application/json

📥 请求示例

POST http://192.168.1.100:8080/iot/labview/tenant/device
Content-Type: application/json

{
  "tenantId": 1,
  "iotDeviceId": 1001
}

接口3:查询配置列表

适用场景LabVIEW需要获取所有配置信息

📝 接口信息

方法GET
路径:/iot/labview/list
完整地址http://服务器IP:8080/iot/labview/list

📥 请求示例

GET http://192.168.1.100:8080/iot/labview/list

📤 响应示例

{
  "msg": "操作成功",
  "code": 200,
  "data": [
    {
      "id": 1,
      "iotDeviceId": 1001,
      "tenantId": 1,
      "tenantName": "默认租户",
      "iotTargetTable": "{\"data\":\"ymes_iiot_data\"}",
      "encrypted": "pzH8mWXKJqP9vE5tYnZxJg8fL2kR7sW..."
    },
    {
      "id": 2,
      "iotDeviceId": 1002,
      "tenantId": 1,
      "tenantName": "默认租户",
      "iotTargetTable": "{\"data\":\"ymes_iiot_data\"}",
      "encrypted": "7wgJZsxp4cOk1T/WwnXO7IlP7hPBpFc..."
    }
  ]
}

接口4:获取配置详情

适用场景LabVIEW知道配置ID需要获取具体配置

📝 接口信息

方法GET
路径:/iot/labview/{id}
完整地址http://服务器IP:8080/iot/labview/{id}

📥 请求示例

GET http://192.168.1.100:8080/iot/labview/1

接口5:获取目标表配置

适用场景LabVIEW需要获取目标表配置信息

📝 接口信息

方法GET
路径:/iot/labview/targetTable/{id}
完整地址http://服务器IP:8080/iot/labview/targetTable/{id}

📥 请求示例

GET http://192.168.1.100:8080/iot/labview/targetTable/1

📤 响应示例

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "id": 1,
    "iotDeviceId": 1001,
    "tenantId": 1,
    "tenantName": "默认租户",
    "iotTargetTable": {
      "data": "ymes_iiot_data"
    },
    "encrypted": "pzH8mWXKJqP9vE5tYnZxJg8fL2kR7sW..."
  }
}

接口6:测试数据库连接

适用场景LabVIEW需要测试数据库连接并获取配置

📝 接口信息

方法POST
路径:/iot/labview/testConnection
完整地址http://服务器IP:8080/iot/labview/testConnection
请求头Content-Type: application/json

📥 请求示例

POST http://192.168.1.100:8080/iot/labview/testConnection
Content-Type: application/json

{
  "iotDeviceId": 1001,
  "iotDbIp": "192.168.1.200",
  "iotDbPort": 3306,
  "iotDbName": "mes_database",
  "iotDbUser": "root",
  "iotDbPass": "password123"
}

📤 响应示例

{
  "msg": "操作成功",
  "code": 200,
  "data": {
    "success": true,
    "message": "数据库连接成功",
    "id": 1,
    "iotDeviceId": 1001,
    "tenantId": 1,
    "tenantName": "默认租户",
    "iotTargetTable": "{\"data\":\"ymes_iiot_data\"}",
    "encrypted": "pzH8mWXKJqP9vE5tYnZxJg8fL2kR7sW..."
  }
}

接口7查询所有设备ID

适用场景LabVIEW需要获取所有设备ID和配置

📝 接口信息

方法GET
路径:/iot/labview/deviceIds
完整地址http://服务器IP:8080/iot/labview/deviceIds

📥 请求示例

GET http://192.168.1.100:8080/iot/labview/deviceIds

📤 响应示例

{
  "msg": "操作成功",
  "code": 200,
  "data": [
    {
      "id": 1,
      "iotDeviceId": 1001,
      "tenantId": 1,
      "tenantName": "默认租户",
      "iotTargetTable": "{\"data\":\"ymes_iiot_data\"}",
      "encrypted": "pzH8mWXKJqP9vE5tYnZxJg8fL2kR7sW..."
    },
    {
      "id": 2,
      "iotDeviceId": 1002,
      "tenantId": 1,
      "tenantName": "默认租户",
      "iotTargetTable": "{\"data\":\"ymes_iiot_data\"}",
      "encrypted": "7wgJZsxp4cOk1T/WwnXO7IlP7hPBpFc..."
    }
  ]
}

接口8按租户查询设备ID

适用场景LabVIEW需要按租户获取设备ID和配置

📝 接口信息

方法GET
路径:/iot/labview/deviceIds/tenant
完整地址http://服务器IP:8080/iot/labview/deviceIds/tenant?tenantId=1

📥 请求示例

方式1通过租户ID查询

GET http://192.168.1.100:8080/iot/labview/deviceIds/tenant?tenantId=1

方式2通过租户名称查询模糊匹配

GET http://192.168.1.100:8080/iot/labview/deviceIds/tenant?tenantName=默认

方式3组合查询

GET http://192.168.1.100:8080/iot/labview/deviceIds/tenant?tenantId=1&tenantName=默认

📤 响应示例

{
  "msg": "操作成功",
  "code": 200,
  "data": [
    {
      "id": 1,
      "iotDeviceId": 1001,
      "tenantId": 1,
      "tenantName": "默认租户",
      "iotTargetTable": "{\"data\":\"ymes_iiot_data\"}",
      "encrypted": "pzH8mWXKJqP9vE5tYnZxJg8fL2kR7sW..."
    }
  ]
}

📋 所有接口统一响应格式

响应字段说明

字段名 类型 说明 是否加密
id 数字 配置ID 明文
iotDeviceId 数字 设备ID 明文
tenantId 数字 租户ID 明文
tenantName 文本 租户名称 明文
iotTargetTable 文本/对象 目标表配置JSON字符串或对象 明文
encrypted 文本 数据库配置Base64密文 AES加密

🔓 解密后的数据

使用Python脚本解密 encrypted 字段后,得到:

{
  "iotDbIp": "192.168.1.200",
  "iotDbPort": 3306,
  "iotDbName": "mes_database",
  "Object": "root",
  "Class": "password123"
}

🎯 AES加密参数

核心参数表

参数名称 参数值 说明
加密算法 AES 高级加密标准
加密模式 ECB 电子密码本模式
密钥 YaviiMESpassword ⚠️ 严格区分大小写
密钥长度 128 bits (16字节) 标准长度
填充方式 PKCS5Padding 自动填充
字符编码 UTF-8 统一编码
输出格式 Base64 可见字符编码
偏移量IV 不需要 ECB模式无需IV

⚠️ 重要提醒

1. 密钥输入规范

✅ 正确YaviiMESpassword
❌ 错误yaviimespassword    (大小写错误)
❌ 错误Yavii MES password  (有空格)
❌ 错误YaviiMESpassword123 (长度错误)

2. 不需要偏移量

ECB模式不使用偏移量IV

  • 只需要密钥
  • 不需要IV
  • 不需要偏移量

如果工具强制要求,可以:

  • 留空
  • 000000000000000016个0
  • 填任意值(不会被使用)

🛠️ 解密方法

方法1Python脚本推荐

前提条件

  1. 安装Python 3.6+
  2. 安装加密库
    pip install pycryptodome
    

使用步骤

步骤1调用接口获取数据

{
  "encrypted": "pzH8mWXKJqP9vE5tYnZxJg8fL2kR7sW..."
}

步骤2运行解密脚本

python 2025-10-18_硬件融合接口解密脚本.py "pzH8mWXKJqP9vE5tYnZxJg8fL2kR7sW..."

步骤3获取明文配置

{
  "iotDbIp": "192.168.1.200",
  "iotDbPort": 3306,
  "iotDbName": "mes_database",
  "Object": "root",
  "Class": "password123"
}

脚本位置

项目根目录/.tasks/labview_aes_decrypt.py

方法2在线工具

推荐工具

  1. 站长工具:https://tool.oschina.net/encrypt
  2. 菜鸟工具:https://c.runoob.com/front-end/893/
  3. 在线工具:https://www.sojson.com/encrypt_aes.html

参数设置

设置项 填写值 备注
操作 解密Decrypt 必选
密文 粘贴 encrypted 的值 Base64格式
算法 AES 必选
模式 ECB ⚠️ 必须选ECB
密钥 YaviiMESpassword 区分大小写
密钥长度 128 bits 或填128
填充 PKCS5 或 PKCS7 任选一个
字符集 UTF-8 必选
输出格式 Base64 必选
偏移量/IV 留空 或 填0 ECB不需要

📊 LabVIEW集成流程

完整调用流程

┌──────────────────────────────────────────┐
│ LabVIEW主程序                             │
└──────────────────────────────────────────┘
            ↓
   [1] 调用HTTP接口
            ↓
   选择接口类型:
   ├─ 方式AGET /device/{iotDeviceId}
   └─ 方式BPOST /tenant/device
            ↓
   [2] 获取JSON响应
            ↓
   解析JSON提取 "encrypted" 字段
            ↓
   [3] 调用Python脚本解密
   命令python labview_aes_decrypt.py "<encrypted>"
            ↓
   [4] 解析解密后的JSON
   提取:
   - iotDbIp数据库IP
   - iotDbPort数据库端口
   - iotDbName数据库名
   - Object数据库账号
   - Class数据库密码
            ↓
   [5] 连接数据库
   使用上面提取的信息连接MySQL数据库
            ↓
   [6] 上传数据
   写入数据到指定表

关键步骤说明

步骤1HTTP请求

使用LabVIEW自带的HTTP Client VI

  • URLhttp://服务器IP:8080/iot/labview/device/1001
  • 方法GET 或 POST
  • 请求头:Content-Type: application/json仅POST需要

步骤2JSON解析

使用LabVIEW的JSON解析工具

  • 解析响应的 data.encrypted 字段
  • 得到Base64密文字符串

步骤3Python解密

使用System Exec VI调用Python脚本

  • 命令:python
  • 参数:.tasks\labview_aes_decrypt.py "<encrypted>"
  • 读取标准输出

步骤4解析配置

再次使用JSON解析工具

  • 解析Python输出的JSON
  • 提取各个数据库配置字段

步骤5连接数据库

使用LabVIEW Database Connectivity Toolkit

  • HostiotDbIp
  • PortiotDbPort
  • DatabaseiotDbName
  • UserObject
  • PasswordClass

🔒 安全说明

已加密的信息

字段名 说明 为什么要加密
iotDbIp 数据库IP地址 防止暴露数据库位置
iotDbPort 数据库端口 防止暴露服务端口
iotDbName 数据库名称 防止暴露数据库结构
Object 数据库账号 防止账号泄露
Class 数据库密码 防止密码泄露

🔓 未加密的信息

字段名 说明 为什么不加密
id 配置ID 业务标识,无敏感性
iotDeviceId 设备ID 已知信息,用于查询
tenantId 租户ID 已知信息,用于查询
tenantName 租户名称 业务标识,无敏感性
iotTargetTable 目标表配置 表名信息,无敏感性

🛡️ 安全等级

场景 安全等级 说明
内网环境(局域网) 高度安全
VPN专线 高度安全
云端VPC私网 高度安全
公网HTTP临时 中等安全建议升级HTTPS

📋 测试验证清单

接口测试

测试1接口1正常调用

# 请求
GET http://localhost:8080/iot/labview/device/1001

# 预期结果
- code = 200
- data.encrypted 存在且不为空
- encrypted 是Base64字符串

测试2接口2正常调用

# 请求
POST http://localhost:8080/iot/labview/tenant/device
Body: {"tenantId":1, "iotDeviceId":1001}

# 预期结果
- code = 200
- data.encrypted 存在且不为空
- encrypted 是Base64字符串

测试3Python解密成功

# 命令
python 2025-10-18_硬件融合接口解密脚本.py "<encrypted>"

# 预期结果
- 输出JSON格式
- 包含 iotDbIp, iotDbPort, iotDbName, Object, Class
- 所有字段值正确

测试4数据库连接成功

使用解密后的配置连接数据库

# 预期结果
- 连接成功
- 可以执行SQL

常见问题

Q1接口返回 "未找到该设备的数据库配置"

原因:数据库中没有该设备的配置记录。

解决方法

  1. 确认设备ID是否正确
  2. 在MES管理后台检查该设备配置是否已创建
  3. 确认租户ID是否正确接口2

Q2Python脚本报错 "No module named 'Crypto'"

原因未安装pycryptodome库。

解决方法

pip install pycryptodome

如果安装失败,尝试使用国内镜像:

pip install pycryptodome -i https://pypi.tuna.tsinghua.edu.cn/simple

Q3解密失败提示 "Padding is incorrect"

原因:密钥不正确。

解决方法

  1. 检查密钥是否为:YaviiMESpassword
  2. 检查大小写是否正确(必须完全一致)
  3. 检查是否有多余的空格
  4. 确认密钥长度为16字节

Q4解密出来是乱码

原因:字符编码不对。

解决方法

  1. 确认使用UTF-8编码
  2. 不要使用GBK、GB2312等其他编码

Q5每次调用接口encrypted的值都不一样

:这是正常现象!

原因

  • 数据库配置可能有更新
  • 或者配置中包含时间戳等动态字段

验证方法 只要能正确解密并连接数据库,就说明没问题。


Q6接口1和接口2应该用哪个

:根据业务场景选择。

场景 推荐接口 原因
单租户系统 接口1 参数简单只需设备ID
多租户系统 接口2 需要区分不同租户
参数来自URL 接口1 GET请求参数在URL
参数来自表单 接口2 POST请求参数在Body

Q7密钥可以修改吗

:可以,但需要同步修改多处。

修改步骤

  1. 修改后端Java代码中的密钥AESUtil.java
  2. 修改Python脚本中的密钥labview_aes_decrypt.py
  3. 重新编译部署后端
  4. 更新所有LabVIEW设备的Python脚本
  5. 通知所有使用者

⚠️ 建议:非必要不修改,除非有安全需求。


Q8需要定期更换密钥吗

:建议定期更换。

推荐周期每3-6个月更换一次

更换流程

  1. 生成新的16字节密钥英文字母+数字)
  2. 按Q7的步骤同步修改
  3. 选择低峰期进行更换
  4. 提前通知所有使用者

Q9可以用在线工具解密吗

:可以,但不推荐用于生产环境。

原因

  • 在线工具会将密文上传到第三方服务器
  • 存在密钥泄露风险

建议

  • 开发测试阶段 → 可以使用在线工具
  • 生产环境 → 必须使用本地Python脚本

Q10接口响应很慢怎么办

可能原因

  1. 网络延迟
  2. 数据库查询慢
  3. 加密运算耗时

排查方法

  1. 检查网络连接ping服务器
  2. 检查数据库性能(查询时间)
  3. 查看后端日志(是否有异常)

优化建议

  • AES加密速度很快< 5ms不是性能瓶颈
  • 重点优化数据库查询
  • 考虑添加缓存机制

🚀 升级路径

当前状态v3.0

已完成

  • 接口1GET /device/{iotDeviceId} → AES加密
  • 接口2POST /tenant/device → AES加密
  • Python解密脚本 → 完整可用
  • 完整文档 → 使用指南

安全等级(高)

短期优化可选1-2周

可选添加API Key验证

  • 在现有AES加密基础上增加API Key
  • 双重防护AES加密 + API Key验证
  • 实施时间2小时
  • 效果:进一步提升安全性

中期升级推荐3-6个月

推荐升级为HTTPS

  • 申请SSL证书免费或付费
  • 配置HTTPS
  • 保留AES加密双重防护
  • 实施时间6小时
  • 效果:达到业界最佳实践

长期优化(持续)

  1. 数据库密码加密存储

    • 数据库中的密码也进行AES加密
    • 查询时解密后返回
  2. 密钥轮换机制

    • 自动定期更换密钥
    • 平滑过渡,无需停机
  3. 访问审计日志

    • 记录所有接口调用
    • 分析异常访问模式
  4. 定期安全评估

    • 每季度进行安全扫描
    • 及时发现并修复漏洞

📞 技术支持

遇到问题?

优先级顺序

  1. 查看本文档FAQ部分
  2. 检查参数设置是否正确
  3. 测试Python脚本是否正常
  4. 查看后端日志(如有权限)
  5. ⚠️ 联系技术支持

联系方式


📚 附录

A. 快速参数速查表

┌─────────────────────────────────────┐
│         AES加密参数速查             │
├─────────────────────────────────────┤
│ 算法AES                            │
│ 模式ECB                            │
│ 密钥YaviiMESpassword               │
│ 密钥长度128 bits (16字节)          │
│ 填充PKCS5Padding / PKCS7Padding    │
│ 编码UTF-8                          │
│ 格式Base64                         │
│ IV偏移量不需要ECB模式           │
└─────────────────────────────────────┘

B. 接口快速对照表

需求 使用接口 请求方式
只知道设备ID /device/{id} GET
知道租户+设备 /tenant/device POST
查所有设备ID /deviceIds GET
按租户查设备 /deviceIds/tenant GET

C. 错误代码对照表

code msg 原因 解决方法
200 操作成功 正常 -
500 未找到该设备的数据库配置 设备不存在 检查设备ID
500 租户ID和设备ID不能为空 参数缺失 检查请求参数
500 数据加密失败 后端异常 联系技术支持

D. 测试清单

□ 能否正常调用接口?
□ 接口返回code是否为200
□ encrypted字段是否存在
□ encrypted是否为Base64格式
□ Python脚本能否解密
□ 解密结果是否为JSON格式
□ 数据库配置信息是否完整?
□ 能否用配置连接数据库?
□ 能否成功写入数据?

E. 文件清单

📁 项目根目录
├── 📁 .tasks/
│   ├── 📄 2025-10-18_硬件融合接口加密文档.md  ← 本文档
│   └── 🐍 labview_aes_decrypt.py              ← Python解密脚本
│
├── 📁 yjh-mes/src/main/java/cn/sourceplan/
│   ├── 📁 common/utils/
│   │   └── ☕ AESUtil.java                    ← Java加密工具类
│   └── 📁 iot/controller/
│       └── ☕ IotLabviewConfigController.java ← 接口Controller

文档更新记录

版本 日期 更新内容 更新人
v1.0 2025-10-14 初始版本 开发团队
v2.0 2025-10-18 实施AES加密增加接口2 开发团队
v3.0 2025-10-18 接口1也加密重构文档 开发团队
v4.0 2025-10-18 所有8个接口全面加密统一响应格式 开发团队

文档版本v4.0
更新日期2025-10-18
下次审阅2025-11-18
文档负责人MES开发团队
当前实施状态 所有8个LabVIEW接口已全面加密


🎯 总结

核心要点

  1. 8个加密接口 → 全面保护数据库配置安全
  2. 5个加密字段 → IP、端口、库名、账号、密码
  3. 1个密钥 → YaviiMESpassword16字节
  4. 0个偏移量 → ECB模式不需要IV
  5. Python解密 → 简单易用,一行命令

已加密接口列表

全部8个LabVIEW接口已加密

  1. /device/{iotDeviceId} - 通过设备ID查询配置
  2. /tenant/device - 通过租户+设备查询配置
  3. /list - 查询配置列表
  4. /{id} - 获取配置详情
  5. /targetTable/{id} - 获取目标表配置
  6. /testConnection - 测试数据库连接
  7. /deviceIds - 查询所有设备ID
  8. /deviceIds/tenant - 按租户查询设备ID

使用流程

调用接口 → 获取encrypted → Python解密 → 连接数据库

安全建议

  • 内网、VPN环境 → 当前方案足够安全
  • ⚠️ 公网HTTP环境 → 临时方案建议升级HTTPS
  • 🔐 长期方案 → HTTPS + AES双重防护

记住这些

  • 密钥:YaviiMESpassword(严格区分大小写)
  • 模式ECB不需要偏移量
  • 脚本:python labview_aes_decrypt.py "<encrypted>"
  • 支持遇到问题先查FAQ再联系技术支持

所有接口已全面加密,安全等级达到最高! 🎉