galbd / AstrBot 插件

把栞接入 galbd QQ 机器人（AstrBot 的 GalBirthday 插件）：先看前提条件、支持的版本、安装配置、权限、连接验证和故障排查，再看文件从哪里获取。

桌面版0.2.8 已提供
网页版已可用

本页内容

前提条件
支持的版本
安装配套接口
权限与安全
远程成员
关联你的 QQ（群成员）
验证连接
故障排查
回退或移除
下载

galbd 是 AstrBot QQ 机器人上的 GalBirthday 插件，在 QQ 群里提供生日、每日推荐和共享记录等功能。栞的配套接口为这个插件增加一个小型本地接口，让桌面客户端可以与 galbd 同步你的记录，也让群成员可以关联自己的 QQ。

群成员不需要在机器人上安装任何东西。在桌面客户端中填写群号和自己的 QQ 号，按照关联你的 QQ操作即可。
机器人运营者需要在运行 AstrBot 的电脑上安装一次配套接口。本页其余内容是写给运营者的，下载任何文件之前请完整阅读。

前提条件#

一个正在运行的 AstrBot 实例，已安装并能正常使用 GalBirthday 插件（astrbot_plugin_galbirthday）。
QQ 通过 aiocqhttp（OneBot v11）适配器接入 AstrBot，例如使用 NapCat。配套接口只接受来自 aiocqhttp 平台的 QQ 事件，不支持其他适配器。
机器人所在电脑上可以运行 Python，用于执行安装器。
栞桌面客户端与配套接口文件来自同一次发布。不要混用不同发布包中的接口文件。
仅当其他电脑上的成员也要接入时：一个由你管理、证书有效的 HTTPS 域名，以及反向代理（见远程成员）。

支持的版本#

组件	支持范围
GalBirthday 插件	4.x：不低于 4.0.0 且低于 5.0.0，已用 4.0.0 测试。
接口协议	主版本 1
栞桌面客户端	与配套接口同一次发布的版本（本文更新时为 0.2.7）
AstrBot	没有单独记录最低版本，兼容性按插件版本和插件报告的能力来检查。

安装器会拒绝 4.x 以外的插件，并且不做任何改动。桌面客户端每次连接都会检查协议和能力（library.read、sessions.read、private.owner），因此不兼容的更新会表现为“未连接”，而不会写入错误的数据。

安装配套接口#

以下命令在包含栞 integration 文件夹的目录中运行。

先检查。这一步会核对插件版本、配套接口所需的插件接口以及文件摘要，不做任何修改：
```
python integration/install_bridge.py --check
```
安装。安装器会把它要改动的插件文件备份到 integration/backup/<时间>/，加入带标记的挂钩和 core/client_bridge.py 文件，不会替换整个插件。重复运行不会重复添加挂钩，失败时会还原本次写入的内容。
```
python integration/install_bridge.py
```
如果运行着多个 AstrBot 实例，或者插件不在 ~/.astrbot_launcher/instances/ 下，请指定准确的插件目录：--plugin "<astrbot_plugin_galbirthday 的完整路径>"。
在 AstrBot 管理界面中只重载 GalBirthday。安装器本身从不重启或重载任何东西，也不需要重启 AstrBot 或 NapCat。
在同一台电脑上连接桌面客户端：在设置中打开 galbd / QQ 连接并连接。插件加载时会创建本机配对文件，客户端会自动读取，无需手动抄写任何密钥。

权限与安全#

配套接口只监听 127.0.0.1:18766。除非按下文配置反向代理，其他电脑无法访问。
配对密钥保存在插件数据目录的 galshelf-bridge.json 中。在 Windows 上只有当前用户和 SYSTEM 可以读取，其他系统上权限为 0600。不要把这个文件或其中的密钥发给任何人。
本机管理员密钥不能通过代理使用。远程成员只有在群内证明 QQ 身份后，才会获得属于自己的凭据。
来自网页的请求会被拒绝，任何网站都不能冒充你的客户端。
群内验证要求机器人是该群成员，能查询群成员并在群里 @ 他人。
不要通过代理暴露 AstrBot 管理面板、NapCat 端口或配对文件。

远程成员#

只有在你开放服务之后，其他电脑上的成员才能关联 QQ。在插件数据目录（与 galshelf-bridge.json 同一目录）中创建 galshelf-remote.json：

{
  "public_url": "https://galbd.example.org",
  "allowed_groups": ["<群号>"]
}

请使用你自己的 HTTPS 域名，示例地址无法使用。机器人必须已加入列表中的每个群。没有这个文件时，远程验证处于关闭状态，不会发送任何验证码。修改后需要重载插件。

然后在机器人所在电脑上配置 HTTPS 反向代理：只把 /v1/ 转发到 http://127.0.0.1:18766；覆盖而不是追加 X-Forwarded-For 和 X-Forwarded-Proto；把 X-Forwarded-Host 设为你的域名；请求体限制为 1 MB。完整的 Nginx 示例见发布包中的 docs/QQ_BINDING.md。

关联你的 QQ（群成员）#

在桌面客户端中填写服务地址、群号和自己的 QQ 号，申请验证码。
机器人会在该群中 @ 你并发送 6 位验证码（5 分钟内有效，可尝试 5 次）。
用同一个 QQ 在群里回复：/gal关联 <验证码>。
在桌面客户端中填写同一个验证码。

一个 QQ 只能关联一个桌面客户端，凭据有效期 90 天。可以在客户端中取消关联；设备丢失时，可以在群里发送 /gal解除关联。想在网页上使用 galbd 记录，请在桌面客户端 QQ 关联下选择授权浏览器，并在网站上填写 8 位授权码。

验证连接#

python integration/install_bridge.py --check 会报告插件版本和挂钩是否就位。
python integration/check_release.py 会对照已安装的插件挂钩、接口文件和发布清单；加上 --skip-installed 则只检查发布包。它不读取任何凭据，也不做任何修改。
重载后，AstrBot 日志中会出现 [GalBirthday] Companion bridge … started on loopback port 18766。
桌面客户端中的 galbd 连接显示为已连接且兼容。
如果你还为这个机器人运行了栞网站，它的 /healthz?deep=1 会报告接口是否就绪。

故障排查#

问题	处理方法
客户端提示尚未连接 galbd	确认已安装配套接口，并在安装后只重载了 GalBirthday。在 AstrBot 日志中查看接口启动的那一行。
在 AstrBot 中更新插件后连接中断	插件更新可能覆盖了挂钩。重新运行安装器，它会检查并补回。
提示 “This bridge supports GalBirthday 4.x”	插件版本不在 4.x 范围内，没有做任何改动。请使用 4.x 插件，或等待支持该版本的接口发布。
提示 “Pass --plugin with the exact GalBirthday plugin directory”	找到了多个插件目录或一个也没有。用 `--plugin` 指定准确的目录。
群里收不到验证码	确认该群已列入 `galshelf-remote.json`、机器人在线且在群中、你是群成员。请求有频率限制：同一 QQ 和客户端至少间隔 60 秒、每小时最多 3 次；同一地址每小时 12 次；每个群每小时 30 次。
验证码被拒绝	验证码 5 分钟内有效、可尝试 5 次，请重新申请。

回退或移除#

恢复安装器生成的备份，然后只重载 GalBirthday：

python integration/install_bridge.py --restore "integration/backup/<时间>"

如果安装后插件又被修改过，自动回退会停止，以免覆盖更新的文件。回退不会删除个人书架或游玩日志，接口的回执保留在插件自己的数据库中。

下载#

栞的发布只在已核实的发布页 https://github.com/Harihi-Works/GalShelf-Dev/releases (外部链接) 公开，桌面客户端也从这里检查更新。这个公开页面提供的是 Windows 桌面客户端安装包。
配套接口安装器（integration/，包含 install_bridge.py、check_release.py 和发布清单）属于栞套件的源码包，不在上述公开页面发布。请向栞的维护者索取与你的桌面客户端版本匹配的接口包。
GalBirthday 插件本身不由栞分发，也没有记录经过核实的下载地址，因此本页不提供它的下载链接。请使用你的机器人正在运行的插件。

栞从不替你安装或重载插件。