故障排除：XPayLabs 网关错误解决方案

​

API 问题

​

为什么我收到 401 签名验证失败？

1. JSON 序列化——确保 data 对象被序列化为紧凑 JSON（无空格、无换行）。JavaScript 中的 JSON.stringify(obj) 默认生成正确格式。
2. 数据内容——签名仅基于 data 字段计算，而非完整的请求信封。sign、timestamp 和 nonce 字段被排除在外。
3. 令牌不匹配——确认用于计算签名的 MERCHANT_TOKEN 与网关中配置的令牌匹配。
4. 字符编码——确保令牌和 JSON 字符串使用 UTF-8 编码。
5. 测试您的签名——为已知负载计算签名并进行比较：

const crypto = require("crypto");
const token = "your-merchant-token";
const data = { amount: "100.00", symbol: "USDT", chain: "TRON" };
const sign = crypto
  .createHmac("sha256", token)
  .update(JSON.stringify(data), "utf8")
  .digest("hex");
console.log(sign); // 应当与网关期望的值匹配

​

为什么我收到 400 验证错误？

​

区块链扫描器问题

​

为什么区块链支付未被检测到？

1. 检查扫描器日志： docker logs <scanner-container-name>
2. 验证 RPC 端点： 确保配置的 RPC URL 可从网关服务器访问。
3. 检查区块高度： 扫描器从最后处理的区块开始同步。如果网关刚部署，可能需要时间来追赶。
4. 确认代币配置： 验证该链的代币合约地址是否正确配置。
5. 检查区块链浏览器： 确认交易确实存在于链上并且发往正确的地址。

​

为什么扫描器速度慢？

• RPC 速率限制： 公共 RPC 端点可能会限制高频请求。考虑使用专用 RPC 端点。
• 出块时间： 不同链的出块时间不同。TRON 每 3 秒出块，Ethereum 每 12 秒出块。
• 确认要求： 在网关设置中配置每条链所需的区块确认数。

​

Webhook 问题

​

为什么我没有收到 Webhook？

1. 验证回调 URL： 检查网关配置中的 callback-url。
2. 网络可达性： 网关必须能够到达您的回调 URL。如果在本地测试，请使用 ngrok 等隧道工具。
3. 检查网关日志： docker compose logs xpay-user 查看 Webhook 投递尝试。
4. 检查您的端点日志： 确保您的服务器正在监听正确的路径并返回 HTTP 200。

​

为什么 Webhook 签名验证失败？

1. 仅验证数据： 仅对 data 字段验证签名，而非完整的 NotifyPayload。
2. Webhook 密钥不匹配： 确认用于验证的 webhook-secret 与网关中配置的匹配。
3. JSON 格式： data 字段必须序列化为紧凑 JSON 才能进行验证。

​

部署问题

​

为什么 Docker 容器没有启动？

# 检查容器状态
docker compose ps

# 查看特定服务的日志
docker compose logs xpay-user
docker compose logs xpay-tron

• 端口 180 已被占用
• 磁盘空间不足
• 配置中缺少环境变量

​

为什么网关没有响应？

1. 确认容器正在运行： docker compose ps 应显示 Up 状态。
2. 检查端口绑定： docker compose port gateway 180
3. 本地测试： curl http://localhost:180/v1/symbol/supportSymbols
4. 检查防火墙： 确保服务器防火墙中已开放 180 端口。

​

速率限制

async function fetchWithRetry(url, options, retries = 5) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;
    const delay = Math.pow(2, i) * 1000 + Math.random() * 1000;
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error("Max retries exceeded");
}

​

获取帮助

1. 检查容器日志中的错误消息。
2. 查看常见问题了解常见问题。
3. 在 github.com/xpaylabs/gateway 提交 GitHub Issue。
4. 如需商业支持，请联系 support@xpaylabs.com。

• 网关版本和部署方式
• 相关配置（脱敏处理密钥）
• 完整的错误消息和日志
• 复现步骤