跳转到指南

文档 9.6.24

Discord 集成

使用已安装面板提供的集成功能。

Webhook#

在正确频道创建 webhook 并保存设置。URL 与机器人令牌均应保密。启用通知前发送受控测试消息。

权限#

仅授予必要权限。失败时检查频道、令牌与提供方响应。轮换泄露令牌，勿在日志或截图中公开。

区分三种集成信息#

设置 → 集成中的 Webhook 地址、机器人令牌和 OAuth 客户端信息是不同字段，分别用于通知、机器人身份和登录。Webhook 能发送消息并不证明机器人命令或 OAuth 已就绪。

Webhook、令牌和客户端秘密应保密。社区公开邀请链接不同，不要把秘密 Webhook 填入网站的 Discord 邀请字段。

受控验证通知#

先选择仅适当工作人员可访问的频道，再发送玩家或处罚信息。

  1. 按照 Discord 官方指南为自己的频道创建 Webhook，将完整地址保存到对应字段。
  2. 检查地址截断、空格和其他频道的旧值。
  3. 有现成测试功能时使用；否则观察安全的正常事件。不要为测试封禁玩家或发起真实付款。
  4. 核对频道、时间和内容。没有消息时先定位失败流程，不要连续重复产生事件。

机器人、OAuth 与泄露处理#

仅给予机器人所用功能需要的权限。保存令牌不会自动完成运行环境或所有命令配置。OAuth 的客户端编号与秘密应分开填写，回调地址要匹配已安装的登录集成，不要猜测路径。

保留当前管理员会话，在另一个会话测试登录。报告问题时说明是通知、机器人还是登录，并提供时间与已去除秘密的错误。

已公开的令牌或 Webhook 应在提供方更换，再更新面板和其他使用旧值的安装。重新核对正常流程，截图中隐藏秘密字段。

从事件到频道追踪缺失通知#

Discord 没有消息时，先确认预期事件确实发生，而且该事件使用的集成已配置。保存了 webhook 地址，不能证明每一种事件都会发出通知。更换凭据前，记录有关服务器或网站和事件时间，将同一时段的面板记录与频道历史比较。

若普通事件在面板可见却未到达 Discord，检查目标频道和保存的 webhook。已删除的 webhook、变化的频道或缺少字符的地址，需要在相应环节修正。保留旧配置的非秘密上下文，使改动可供检查；另一个服务器的频道有消息，不代表本次通知成功。

若消息进入错误频道，进一步测试前先限制该频道访问并修正目标。不要反复产生处罚事件来诊断投递。向支持提供事件类别、时间和脱敏错误，不要提供完整 webhook 或玩家私密数据。修正后再通过安全的普通通知确认结果。

了解集成保存时保留哪些值#

机器人 token 和 OAuth client secret 是保密密码字段。当前设置实现中，保存时把任一字段留空，会保留原来存储的值。因此，界面上字段为空并不单独表示没有配置秘密；更换之前先阅读字段说明。只编辑其他集成字段时也应理解这一行为。

轮换凭据时，把替换值放入对应字段，由授权账号保存。Webhook URL 和 client ID 使用独立字段，行为也不同。不要假定空白保存会撤销机器人 token 或 OAuth secret；已经泄露的凭据需要通过 Discord 撤销。记录改变了哪个字段，避免新旧值混淆。

注明凭据类别及更改时间，不记录秘密值。随后验证对应流程：webhook 的频道投递、机器人的现有功能，或 OAuth 的实际登录结果。一个流程成功，不会验证其他两个。准备支持截图时，也要检查浏览器地址和玩家信息是否暴露。

安全诊断 Discord 登录返回#

从正确的网站重新开始登录，并在同一浏览器会话中完成流程。OAuth 使用 state 将发出请求与返回关联。打开旧 callback 地址或混合多次登录尝试，可能使返回与当前会话无关。记录错误出现在返回哪个页面时，不要仅凭 webhook 投递情况解释登录问题。

若提示 state 无效或类似错误，记下消息，从正常登录入口重新开始，而不是反复刷新 callback。检查浏览器设置或扩展是否阻止所需 cookies 或导航。调查时保留现有管理员会话；如果尝试之间切换了账号或网站，也应注明。

区分平台的 Discord 账号登录，与租用网站保存的自定义集成凭据。更改 client ID 或跳转设置前，确认究竟哪个流程失败。不要向公开支持频道发送含授权码、state、会话资料或秘密的 callback URL。先提供错误、时间和流程描述更合适。

按团队需要检查通知内容#

消息到达证明投递，而向正确人员提供清晰上下文是另一项检查。查看集成产生的普通消息：能否识别服务器或网站、事件时间及操作类型？阅读现有格式，不要假定面板提供尚不存在的模板编辑器或过滤选项。

频道仅开放给需要这些信息的团队。导出或截图时隐藏玩家标识及不必要的个人细节。检测消息可能没有全部上下文，应按时间与面板记录对应。多个服务器共用频道时，特别检查标签能否清楚区分。

消息不清晰就记录类型、时间和脱敏文本，向支持澄清实际输出，不要假定新功能或通过处罚玩家进行测试。验收目标是成员理解同一资源与事件，同时避免不必要地泄露秘密。

检查 Discord 账号选择与取消登录#

评估 OAuth 不仅看成功，也考虑错误账号和取消权限。浏览器可能已登录另一 Discord。阅读授权页面身份，确认目标账号。这是身份流程，不是改变 webhook 频道就能解决的通知问题。

用户取消或拒绝时记录结果，从正常入口重新开始。不要分发旧 callback URL，它可能带有登录专用值。成功后检查所示账号及网站上下文；管理意外账号前停止。新建账号或购买方案不能验证身份对应正确。

验收记录注明流程、预期账号、结果和时间，排除 token、client secret、state 与授权码。平台登录和租用网站自定义集成不同。明确所测流程有助于支持调查，而不修改无关凭据。

将机器人作为独立服务验证#

网站、webhook 和机器人是独立组件。Client ID、Guild ID 和私密凭据必须对应同一站点和 Discord 服务器。

请使用受支持的 Node.js LTS 版本；机器人至少需要 Node 22 LTS。已安装的独立服务使用 Node 24.21.0 LTS：/opt/tosun-discord-node/v24.21.0/bin/node。服务示例中的 ExecStartPre doctor 检查和 ExecStart 使用同一可执行文件。运行 npm ci 和 doctor 时，也应将该运行环境加入 PATH。如果 doctor 失败，服务不会登录；请在补齐必需凭据后再启用。

  1. 核对角色和频道的数字 ID；不要向整个团队授予 Administrator。
  2. 操作员安装站点专用密钥并迁移操作账本。npm ci 使用锁定依赖；npm run doctor 不登录 Discord 即可检查。
  3. 秘密字段留空会保留原值；保存新秘密需要站点加密密钥。更改 token/API 后重启服务。

重试前核实不确定结果#

超时不能证明操作失败。同一已完成交互不会再次执行，但新命令会产生新的交互 ID。

  1. Processing 和 unknown 不会因时间经过而允许重试。再次执行金钱、物品、封禁或服务器命令前核实结果和操作 ID。
  2. Screenshot、live-watch、sync 和 diag 需要面板的授权会话。不要向支持发送 token、密钥或数据库密码。

分开管理Discord与AC机密#

机器人令牌、webhook地址、OAuth客户端密钥和Tosun许可证是不同凭据。机器人机密应放在私有服务配置或授权的Discord面板字段，不应放入共享Lua、NUI或AC服务器配置文件。

AC密钥属于server.cfg或configs/anticheat_server.lua。短期截图/视频令牌仅授权指定证据上传。请在各自提供方轮换泄露凭据，并受控重启服务。使用状态命令与测试频道验收；结果不明时先核对记录，不要盲目重复经济或封禁操作。

单独安装包内的 Discord 机器人#

discord-bot 运行在 Node.js 上，不能用 ensure 启动。在 Discord Developer Portal 创建自己的应用，使用自己的 Application ID、Guild ID、频道和角色 ID。Token 仅保存在私有环境文件中。

租用网站的数据库账户默认仅能从服务商 localhost 连接。将机器人放在另一台 FiveM 机器不会自动开放连接。应在网站主机上运行托管服务，或使用服务商批准且仅属于自己网站账户的私有连接。不要使用服务商 root 账户，也不要公开 MySQL。需要直接查询游戏表的旧命令必须单独验证。

以站点所有者身份，在站点管理 → Discord 机器人中保存 token、Client ID 和 Guild ID。通过 Download private bot setup 下载私有文件，将其保存为自己机器人目录中的 .env。它仅包含所选站点的密钥，与 ZIP 中的空白示例不同。不要分享或提交到版本库。

  1. 安装受支持的 Node.js LTS 22 或更高版本，通过安装脚本准备示例配置。
  2. 使用 bot 和 applications.commands 范围邀请机器人，仅授予所需权限。
  3. 配置网站数据库和 HTTPS API。命令签名密钥仅属于该机器人与网站，不是 Tosun 许可证，也不能分发主 SaaS 密钥。
  4. 启动前运行 npm run doctor，全部必需检查通过后再运行。doctor 不登录 Discord；实际在线状态和角色权限需另行测试。
cd discord-bot
sh setup.sh
# Configure the private .env and site bot settings first.
npm run doctor
npm start