Discord 机器人 & Server-chan

Saba-chan Discord 机器人的配置,以及无需端口转发即可控制服务器的 Server-chan 配对流程。

Discord 机器人 & Server-chan

Server-chan(中继服务器)是 Saba-chan 的姐姐,在 Discord 和你的电脑之间传递命令。Saba-chan 的 Discord 机器人是运行在 Server-chan 上的官方机器人。你不需要自己运行机器人进程,也不需要管理 Discord 令牌。请把官方机器人邀请到你的 Discord 服务器,然后用 Saba-chan 应用中的代码配对一次。


1. 工作原理

云端
Discord用聊天下命令
Discord 中继Saba-chan 机器人 · 云端
你的电脑
Saba-chan 守护进程你的电脑
游戏服务器你的电脑
  1. 1
    Saba-chan 守护进程Discord 中继

    等待新命令(长轮询)

  2. 2
    DiscordDiscord 中继

    输入命令 /saba … 或聊天

  3. 3
    Discord 中继Saba-chan 守护进程

    转交命令

  4. 4
    Saba-chan 守护进程

    检查权限

  5. 5
    Saba-chan 守护进程游戏服务器

    启动 · 控制台命令

  6. 6
    Saba-chan 守护进程Discord 中继

    发送结果

  7. 7
    Discord 中继Discord

    回复结果

由你的电脑主动连出并取回命令,所以不需要在路由器上开放端口。请求使用配对时发放的令牌签名。守护进程每 60 秒向中继报告服务器列表和状态。
  • 机器人本身运行在 Server-chan 内部。你的电脑上不会安装任何与机器人相关的东西。
  • 游戏服务器运行在你的电脑上。电脑上的 Saba-chan 守护进程通过长轮询主动连接到 Server-chan,获取命令并回传结果。
  • 守护进程按 stdin(服务器控制台)→ REST → RCON 的顺序发送游戏命令。Palworld 使用其 REST API。只有仅支持 RCON 的游戏才使用 RCON,并且只通过回环地址(127.0.0.1)连接。
  • 守护进程 ↔ Server-chan 之间的通信只有从你的电脑发出的 HTTPS 出站连接。无需在路由器上做端口转发。
  • 音乐不经过你的电脑,由 Server-chan 一侧直接处理,所以即使电脑关机也能使用。

2. 配对

配对是在 Server-chan 上注册**主机(Saba-chan 守护进程)和节点(Discord 服务器)**的过程。只需输入一次代码即可完成。

2.1 流程图

你的电脑
GUI 应用你的电脑
Saba-chan 守护进程你的电脑
云端
Discord 中继Saba-chan 机器人 · 云端
Discord斜杠命令
  1. 1
    GUI 应用Saba-chan 守护进程

    请求配对码

  2. 2
    Saba-chan 守护进程Discord 中继

    申请发放配对码

  3. 3
    Discord 中继Saba-chan 守护进程

    配对码 + 轮询密钥(5 分钟有效)

  4. 4
    Saba-chan 守护进程GUI 应用

    显示配对码

  5. 5
    DiscordDiscord 中继

    /saba connect code:…

  6. 6
    Discord 中继

    登记电脑 · 发放节点令牌

  7. 7
    GUI 应用Saba-chan 守护进程

    每 3 秒检查状态

  8. 8
    Saba-chan 守护进程Discord 中继

    检查状态(附轮询密钥)

  9. 9
    Discord 中继Saba-chan 守护进程

    已连接 + 节点令牌(仅一次)

  10. 10
    Saba-chan 守护进程

    保存令牌 · 开始连接中继

  11. 11
    Saba-chan 守护进程GUI 应用

    显示“已连接”

即使别人看到配对码,没有轮询密钥也拿不到令牌。令牌只发放一次,由守护进程而不是 GUI 保存。在 Discord 服务器中连接需要“管理服务器”权限。
  • 配对代码为 32 个字符,pollSecret 为 48 个字符。代码的有效期为 5 分钟。
  • 令牌只返回一次(原子交换)。由守护进程(而不是 GUI)在收到后立即保存到 .node_token,并开始 Server-chan 连接。应用只把 poll secret 交给你电脑上的守护进程,守护进程再通过请求头(而不是 URL)把它发送给 Server-chan。
  • 即使有人看到了你的配对代码,没有 pollSecret 也无法截获令牌。
  • 一个 Discord 账号可以连接多台电脑。用已经有电脑的账号连接时,会出现 作为新电脑连接 和选择以前电脑的 重新连接 按钮。重新连接后,那台电脑以前的令牌将失效。一个 Discord 服务器也可以接入多人的电脑(Discord 联动)。

2.2 应用端步骤

  1. 在 Saba-chan 应用中打开 Discord → 连接,点击 连接 Discord 服务器。
  2. 如果官方 Saba-chan 机器人还不在你的 Discord 服务器中,先用 邀请机器人 邀请它。
  3. 界面会显示连接代码和要输入的命令。点击 复制,然后在 Discord 频道中以 /saba connect code:<代码> 的形式输入(应用可能会显示韩语名称 /사바쨩 연결 코드:<code>,它们是同一条命令)。
  4. 只有在该 Discord 服务器中拥有 管理服务器 权限的成员才能运行此命令。在与机器人的私信中发送,则不涉及 Discord 服务器,只把电脑连接到我的账号。
  5. 如果是第一次使用的 Discord 账号,机器人会先引导你注册。点 注册,在网站上确认条款并注册后,那条回复会变成连接确认。同意之前不会连接电脑。
  6. 机器人显示询问是否连接的按钮时,点 连接。如果填入的是别人给你的代码,那个人的电脑就会连接到我的账号,所以只有代码是你在 Saba-chan 应用里亲自获取的才可以点。
  7. 应用每 3 秒通过守护进程检查一次状态,守护进程保存 .node_token 后切换为“已连接”。

配对完成后,守护进程会自动与 Server-chan 保持长轮询连接。如果在应用中关闭 命令转发 开关,你的电脑将不再接收 Discord 命令,机器人也不会响应。

2.3 无需代码连接另一个 Discord 服务器

如果你的 Discord 账号已经配对,只需在另一个 Discord 服务器中运行 /saba connect(不带代码)。

  • 机器人会把与你的账号关联的所有电脑立即连接到那个 Discord 服务器。不需要在电脑上另外接受,也不需要选择电脑。
  • 如果是第一次使用的账号,要先注册。注册后,那个 Discord 服务器也会登记到 Saba-chan,没有连接电脑时它会保持为没有电脑的服务器(§2.5)。已注册的账号如果没有电脑,会提示你用配对代码连接。
  • 这样连接的 Discord 服务器起初一台游戏服务器都看不到。请在电脑上的 Saba-chan 应用中,为那个 Discord 服务器选择要用的服务器。
  • 用配对代码连接的 Discord 服务器,遵循应用 Discord 连接界面中的 对新 Discord 服务器直接开放我的服务器 设置。打开时所有服务器都会直接可见,关闭时需要自己选择。
  • 与使用代码时一样,需要 管理服务器 权限。如果那个 Discord 服务器已经连接了其他电脑,不会抢走,而是把我的电脑一并连接上去。

2.4 解除配对

  • 在应用中点击 断开连接 → 守护进程停止命令转发并删除 .node_token。这台电脑会与所有 Discord 服务器断开。
  • 若只想断开某一个 Discord 服务器,请在该服务器中运行 /saba disconnect。只有连接者本人或 Discord 服务器所有者可以使用,该服务器的频道分配也会一并移除。

2.5 没有电脑的 Discord 服务器

没有安装 Saba-chan 应用的人,也可以邀请机器人来使用音乐、会说话的 Saba-chan、会朗读的 Saba-chan、服务器管理命令和游戏战绩。

  • 设置保存在 Server-chan 上。Discord 服务器所有者或拥有 管理服务器 权限的人可以修改语言、会说话的 Saba-chan・音乐频道分配、表情符号放大、会说话的 Saba-chan 设置、会朗读的 Saba-chan 设置。通过 Discord 的 /saba 命令或 Saba-chan 网页进行,第一次修改时会注册。
  • 没有 Saba-chan 等级(权限台阶)和游戏服务器命令。通知・游戏聊天・状态板频道是由电脑发送的,所以无法分配。
  • 之后连接电脑时会原样继承这些设置,从那时起设置的原本就是那台电脑。
  • 听音乐、对话这类普通成员的使用不需要注册。

3. 机器人斜杠命令

以下是官方机器人根命令下的命令。在设置为韩语以外语言的 Discord 客户端中,根命令显示为 /saba,子命令为英文名称;韩语中为 /사바쨩。没有连接电脑的 Discord 服务器只显示 connect・assign・language・settings・reading・web・big-emoji・help,并且由 Discord 服务器所有者或拥有管理服务器权限的人使用,而不是“节点所有者”。其他斜杠命令(/tts、/stats、/clear 等)见 命令。

命令对象作用
/saba status任何人显示连接到此服务器的电脑以及各游戏服务器的状态(CPU、RAM)
/saba connect [code]管理服务器权限用配对代码连接。代码留空则把我账号下的所有电脑连接到这个服务器(§2.3)。第一次使用需先注册
/saba disconnect连接者或服务器所有者断开此服务器与电脑的连接
/saba permission <level> [user]节点所有者选择用户则给该成员授予命令等级(级别列表中的 Remove 会清除个人等级并恢复为默认等级),留空则设置没有单独获得等级的成员的默认等级(初始为 User)。级别列表是这个服务器的权限台阶
右键成员 → 应用 → Change Saba-chan level节点所有者在列表中选择该成员的命令等级(也有 Remove)。与 /saba permission 作用相同。只有拥有管理服务器权限的人能看到该菜单
/saba sleep节点所有者让机器人在此服务器上休眠(忽略所有消息)
/saba wake节点所有者唤醒机器人
/saba assign kind:<会说话的 Saba-chan|音乐|通知|游戏聊天|状态板>节点所有者・服务器所有者将此频道指定为会说话的 Saba-chan 频道(可多个,最多 20 个;会说话的 Saba-chan 只在这些频道中对话)、音乐频道(一个;普通消息会被删除,因此会要求确认)、通知频道(一个;服务器崩溃、更新、备份和计划重启的通知,以及崩溃通知上的 重启 按钮)、游戏聊天频道(一个;转发游戏服务器内的聊天)或状态板频道(一个;每个已开启的服务器一张状态卡片)。详情见 命令 的频道功能。一个频道只能有一种类型;再次运行同一类型会将其移除。也可以在应用的 Discord 服务器 → 服务器管理 标签页的 Saba-chan 分配 中修改
/saba language <language>节点所有者机器人在此服务器上回复所用的语言(Auto = 跟随所关联应用的语言)
/saba reading节点所有者此服务器上会朗读的 Saba-chan 的音量・语速・音调和称呼名字设置。仅你自己可见
/saba big-emoji state:<On|Off>节点所有者・服务器所有者把只发送了一个自定义表情的消息改成大图重新发布(默认关闭)
/saba web任何人(自己的账号)Saba-chan 网页的一次性链接(5 分钟)。有电脑则可管理那台电脑,没有则只能修改我所管理的 Discord 服务器设置。仅你自己可见
/saba settings节点所有者修改此服务器上会说话的 Saba-chan 的设置(开/关、插话、记忆、AI 审核、执行前确认步骤、按类别的工具、触发词)。在应用中被全部允许的工具屏蔽的工具无法开启。仅你自己可见
/saba help任何人显示 Saba-chan 的使用方法和命令列表(仅你自己可见)
/mysaba web任何人(自己的账号)与 /saba web 相同。在任何服务器或私信中都可以使用
/mysaba my-pcs任何人(自己的电脑)列出连接到你 Discord 账号的电脑,改名或删除(只有自己能看到)
/mysaba agent任何人(自己的账号)查看并断开连接到你 Discord 账号的 AI 代理(远程 MCP)。没有时会显示要填入代理的地址。私信中也可用,仅你自己可见(连接 AI 代理)
/saba update连接电脑的人检查连接到此服务器的电脑上的 Saba-chan 更新,点确认按钮后应用

/mysaba 是与我的账号相关的命令,所以不会出现在服务器成员列表中。连接电脑后,用机器人显示的 安装到我的账号 按钮把 Saba-chan 安装到你的 Discord 账号,就可以在任何服务器或私信中使用,且只有你自己能看到。在与机器人的私信中,即使没有安装,也可以用 /saba web・/saba my-pcs・/saba agent。

在已连接电脑的 Discord 服务器中,权限、休眠、语言、音乐、会朗读的 Saba-chan 设置的原本是电脑上的 Saba-chan 设置,所以这些命令在电脑开机时才会生效(没有电脑的服务器见 §2.5)。同样的设置也可以在应用的 Discord 服务器界面中修改。权限在 实例 标签页点击服务器打开的 各级别命令・各成员级别 界面,音乐・会朗读的 Saba-chan 在各自的标签页,语言・前缀・斜杠命令样式在 机器人设置 标签页。一次让所有 Discord 服务器休眠,请在 Discord → 连接 界面操作。

3.1 每个服务器的斜杠命令和操作菜单

配对后,机器人会在每个 Discord 服务器中注册额外的命令。

  • /<服务器名称> 命令:<命令> 参数1:… 参数2:…:每个游戏服务器实例一条命令。Discord 的命令列表中,每个服务器只显示一行。点击 命令 栏,会列出该服务器上可用的命令(启动・停止・状态、操作、模块命令),输入文字可按名称筛选。参数栏会根据所选命令显示选项列表、是/否、数值范围或输入提示。
  • 命令列表中,你的等级不能用的命令和不符合服务器当前状态的命令(已开启服务器的启动、已关闭服务器的停止)会被排除,你在该服务器最近用过的命令排在前面。是否真能使用,由 Saba-chan 应用重新判断。
  • 操作:Saba-chan 应用向 Discord 开放的操作(重启、备份等)也会放进同一个命令列表。需要确认的操作(见确认设置,§5)会显示将要更改的内容,并且必须由请求者按下执行按钮。Saba-chan 应用的更新不在操作菜单中,请用 /saba update。
  • 玩家:游戏支持查看在线玩家时,服务器的命令列表中会出现 玩家 命令,显示当前在线人数和名字。
  • 恢复备份:从列表中选择要恢复的备份(输入文字可筛选)。服务器正在运行时会先询问,按 停止并继续 会先停止服务器再恢复。恢复是危险操作,执行前会再确认一次。只有发起请求的人能按按钮。
  • 启动完成通知:通过 /<服务器名> 斜杠命令、通知上的 重启 按钮或会说话的 Saba-chan 启动或重启服务器后,服务器可以接受连接时会在同一频道通知。最终没能启动时,会用一行说明原因。
  • 只会显示该服务器允许的实例(应用的 Discord 服务器 → 实例 标签页)。

4. 聊天命令(前缀)

配对后,你可以在 Discord 文字频道中使用基于前缀的命令操作服务器。

Saba-chan <服务器> <命令> [参数…]

默认前缀是 Saba-chan。可以在应用的 Discord 服务器 → 机器人设置 标签页的 命令前缀 中按 Discord 服务器分别修改或添加。

<服务器> 可以是实例名称、服务器别名,或模块名称及其别名。所有模块共用的命令:

命令说明
start启动服务器。示例:Saba-chan minecraft start
stop停止服务器
status查询状态

称呼服务器和命令的词在应用的服务器界面 → Discord 标签页中设置。完整命令列表请参阅 命令 文档。


5. 权限等级

等级依次为 所有者 (3) > 管理员 (2) > 用户 (1) > 访客 (0) > 禁止 (-1)。等级是累加的,上面的级别可以使用下面级别能用的所有命令。

  • 所有者 是连接该服务器的人(节点所有者)。可以使用所有命令,且不能被降级。
  • 每条命令都有风险等级(安全、注意、危险)。默认预设下所需的等级为 安全 = 访客、注意 = 用户、危险 = 管理员。在应用的 Discord 服务器 → 实例 标签页点击服务器,在 各级别命令 台阶上选择预设(宽松、默认、严格),或把命令标签移到其他等级。成员等级和默认等级在同一处的 各成员级别 中设置,并同时应用到这个 Discord 服务器的所有服务器。
  • 帮助和列表只要不是禁止,任何人都可以使用。禁止 的成员无法使用机器人的任何功能,包括音乐和会说话的 Saba-chan。
  • 通过会说话的 Saba-chan 发出的请求不能超过 会说话的 Saba-chan 上限(起初为访客)。

确认:执行前是否用按钮向请求者再次确认,在应用的 Discord 服务器 → 机器人设置 标签页的 确认 卡片(或 saba-chan-cli bot confirm)中设置。直接向机器人提出的请求(前缀・斜杠)起初只对危险命令确认,会说话的 Saba-chan 起初对所有命令都确认,两者都可以在 所有命令・注意及以上・仅危险命令・不询问 中选择。每个命令用于确认的风险步骤,可以在权限界面的标签编辑窗口中修改(不会改变所需的等级)。会说话的 Saba-chan 选定的管理类操作不论设置如何都会询问。只有发出请求的人才能按确认按钮。


6. 音乐功能

音乐播放由与 Server-chan 一同运行的**官方音乐服务器(music-server)**负责。

  • 运行 Saba-chan play … 之类的命令时,机器人会将其交给音乐服务器,由音乐服务器把音频流式传输到 Discord 语音频道。
  • 无需在你的电脑上安装 ffmpeg/yt-dlp。
  • 音乐命令在任何频道都可以使用。如果用 /saba assign kind:音乐 设置了音乐频道,在那里可以不加前缀直接输入命令(或只输入搜索词),并会显示播放器界面。
  • 音乐默认开启,可以在应用的 Discord 服务器 → 音乐 标签页中关闭。在已开启的服务器中会出现 /music 斜杠命令(命令)。

7. 会说话的 Saba-chan(AI 对话)

  • 会说话的 Saba-chan 需要在应用中登记 API 密钥,并为每个 Discord 服务器开启才会工作(在 Discord 服务器界面的 会说话的 Saba-chan 标签页或 /saba settings 中;新服务器是关闭的)。密钥只有你的电脑和 Server-chan 知道,绝不会显示在 Discord 中。
  • 要使用的工具(游戏服务器操作、网页搜索、英雄联盟・云顶之弈・绝地求生战绩、冒险岛角色、多款游戏搜索、生活信息、图像生成)也要为每个 Discord 服务器开启。在应用的公共菜单中被全部允许的工具屏蔽的工具,在任何服务器都不会使用。不开启游戏服务器工具就不会操作服务器。
  • 会说话的 Saba-chan 只在用 /saba assign kind:会说话的 Saba-chan 指定的频道中对话。在其他频道中,即使被呼叫也不会回应。
  • 会说话的 Saba-chan 只能使用模块或扩展向它开放的操作。其他请求一律拒绝。
  • 查询会立即执行。会改变内容的操作会先生成计划,并按确认步骤(§5,起初为所有命令)经过确认按钮;管理类操作总要经过确认按钮。确认按钮只有发出请求的人能按。
  • 执行权限不会超过会说话的 Saba-chan 上限(§5)。
  • 开启会说话的 Saba-chan 后,守护进程无法识别的聊天命令会由会说话的 Saba-chan 转换为准确的命令并再尝试一次。
  • 向会说话的 Saba-chan 询问日志,它会读取服务器日志,包括以前的运行记录。要求以文件提供时,会不经过 AI 直接附上 .log 文件(最多 4 MiB,超出时保留最新部分;IP、密钥和路径会被遮盖)。

8. 安全模型

  • 守护进程通过 HTTPS 在 Authorization: Bearer 请求头中发送配对得到的节点令牌(sbn_{hostId}.{secret})。Server-chan 会将该令牌与其保存的 Argon2 哈希进行比对。
  • Server-chan 从不保存令牌本身,而是与 Argon2 哈希进行比对。
  • 守护进程不接受任何传入连接。游戏服务器密码不会发送到 Server-chan。

9. 故障排查

症状原因 / 解决方法
机器人没有响应检查前缀(默认 Saba-chan)以及其后是否有空格。机器人必须在服务器中、配对必须已完成,并且应用中的 命令转发 必须开启。还要确认机器人没有被 /saba sleep 设为休眠
Saba-chan … start → 找不到服务器第一个词是服务器(实例名称/别名或模块名称/别名),第二个词是命令。如果同一款游戏运行了多个服务器,请使用实例名称或服务器别名
配对代码已过期代码的有效期为 5 分钟,现已过期。请在应用中获取新代码
应用一直在等待确认确实运行了 /saba connect 斜杠命令,并且你拥有管理服务器权限
Discord 命令无法到达电脑在其他地方配对时用 重新连接 选择这台电脑,这台电脑原来的连接会断开。请重新配对这台电脑

更详细的故障排查流程请参阅 故障排查 文档。