接口安全配置 (接口验签) #

为了保证接口调用的安全性，防止恶意请求，TDUCK 采用了接口签名（Signature）校验机制。

[!NOTE] 版本说明：社区开源版后端项目默认未注册签名校验过滤器，所有请求可直接通行。但前端项目默认仍会通过 Axios 拦截器计算签名并附加参数，以便于未来升级至 Pro/Enterprise 版本。

如果您希望在社区版中自行实现后端验签逻辑，可以参考本篇说明。

🎨 前端签名算法实现 #

前端实现文件：tduck-front/src/api/index.js 和 tduck-front/src/utils/sign.js

在每次请求发送前，Axios 拦截器会执行以下操作：

1. 添加时间戳：自动在请求的 params 中附加当前时间戳 timestamp。
2. 参数排序：将请求的 params (GET参数) 与 data (POST参数) 进行合并，并按 Key 字母做升序排序。
3. 加盐哈希：将排序后的参数序列化为 JSON 字符串，在头部拼接上签名秘钥（secret），然后进行 MD5 加密并转换为小写。

示例数据 #

• 签名秘钥 (secret)：916lWh2WMcbSWiHv (在前端 constants.js 或配置文件中指定)
• 待加密字符串：916lWh2WMcbSWiHv{"current":"1","name":"","size":"10","timestamp":"1616904031441"}
• MD5计算结果：81deff67b73d2669f04e48f45faa20ac (该值即为 sign 参数的值)

☕ 后端自定义验签思路 #

如果您在二开时需要开启接口签名校验：

1. 配置秘钥：在 application.yml 中定义签名相关的配置项：
   yaml

   platform:
     sign:
       enable: true
       secret: 916lWh2WMcbSWiHv
       ignore-urls:
         - /tduck-api/webjars/**
         - /tduck-api/swagger/**
   

2. 编写 Filter/Interceptor：在后端 tduck-api 模块编写过滤器，拦截请求。
3. 校验步骤：
   • 从 Request 获取 timestamp，如果请求时间与当前服务器时间相差过大（例如超过 5 分钟），拦截请求，防止重放攻击。
   • 读取请求中的所有查询参数 and Body 中的 JSON 参数。
   • 使用相同的排序和拼接规则，结合后端的 secret 计算出 MD5。
   • 对比计算出的 MD5 与请求中携带的 sign 参数。如果一致则放行，否则返回 403 或“非法请求”错误。

[!WARNING] 如果您启用了自定义接口验签，当遇到“非法访问，请检查请求信息”的报错时，通常是因为前端所在客户端（如手机/电脑）的时间与后端服务器的系统时间不一致，导致时间戳过期。请先校准服务器和客户端的时间。