基于@top-gg/sdk的Discord机器人Top.gg投票Webhook无法接收触发请求的排查

已完成排除的前置校验项 #

• 端口占用状态：机器人运行时25569端口被正常绑定，停止服务后端口无残留占用，不存在端口冲突类问题
• 系统防火墙规则：已通过ufw放行22、80、443、25569端口，规则生效，系统层面无入站拦截
• 平台侧提交状态：Top.gg后台点击测试按钮后返回正常提示，不存在请求提交失败的问题

核心排查与修复步骤 #

1. 校验服务监听的绑定地址 #

Express服务如果默认绑定127.0.0.1回环地址，即便端口在防火墙放通，外部网络流量也无法触达服务进程：

• 验证操作：机器人运行状态下执行ss -tulpn | grep 25569，若输出的本地监听地址为127.0.0.1:25569，即属于配置错误
• 修复方式：修改服务启动代码，明确指定监听所有网卡地址，示例代码：

// 替换原有app.listen(25569, 回调函数)写法
app.listen(25569, '0.0.0.0', () => {
  console.log('Webhook服务已在25569端口启动')
})

2. 校验服务商前置网络防火墙 #

Vultr控制面板自带的云防火墙属于网络层前置拦截，规则优先级高于服务器内部的ufw配置，多数容易被遗漏：

• 验证操作：在本地终端执行telnet <你的VPS公网IPv4地址> 25569，若连接超时无响应，说明请求在到达服务器前就被拦截
• 修复方式：登录Vultr控制台，找到对应VPS实例绑定的防火墙策略组，添加入站规则放通TCP协议的25569端口，来源设置为任意地址

3. 校验Webhook路由与响应逻辑匹配 #

• 路径匹配校验：逐一核对Top.gg后台填写的Webhook完整URL与代码中挂载webhook中间件的路由，确保路径拼写、大小写、斜杠完全一致。例如后台填写的URL为http://<VPS_IP>:25569/dblwebhook，代码中挂载路由必须严格对应/dblwebhook，不能出现拼写偏差
• 响应时效校验：Top.gg平台要求Webhook接口需在3秒内返回200状态码，若路由处理链中加入了无超时的外部请求、同步数据库查询等耗时操作，平台会因等待超时判定请求失败，不会将事件推送到服务端

4. 加全链路日志定位链路断点 #

在webhook路由的最外层增加前置拦截日志，不经过SDK中间件直接打印所有入站请求信息，快速定位断点：

// 替换原有直接挂载SDK中间件的写法
app.use('/dblwebhook', (req, res, next) => {
  console.log(`收到入站请求 | 来源IP: ${req.ip} | 请求方法: ${req.method} | 请求路径: ${req.originalUrl}`)
  next()
}, webhook.middleware())

若测试请求后控制台能打印上述日志，说明网络链路完全正常，问题出在SDK中间件的鉴权或事件处理逻辑；若无任何日志输出，说明请求未到达服务端，需回溯网络层配置。

内容的提问来源于stack exchange，提问作者hex