galbd / AstrBot plugin

galbd is the GalBirthday plugin for the AstrBot QQ bot, used in QQ groups for birthdays, daily recommendations and shared records. GalShelf's companion bridge adds a small local interface to that plugin so the desktop app can sync your records with galbd, and so group members can link their own QQ.

• Group members don't install anything on the bot. In the desktop app, enter the group number and your QQ number and follow Link your QQ.
• Bot operators install the bridge once on the computer that runs AstrBot. The rest of this page is for them. Read it all before downloading anything.

Prerequisites#

• A running AstrBot instance with the GalBirthday plugin (astrbot_plugin_galbirthday) installed and working.
• QQ connected to AstrBot through the aiocqhttp (OneBot v11) adapter, for example with NapCat. The bridge only accepts QQ events from the aiocqhttp platform; other adapters are not supported.
• Python on the bot computer, to run the installer.
• The GalShelf desktop app and bridge files from the same release. Never mix bridge files from different release packages.
• Only for members joining from other computers: a domain you control with a valid HTTPS certificate and a reverse proxy (see Remote members).

Supported versions#

The installer refuses a plugin outside 4.x and changes nothing. The desktop app checks the protocol and capabilities (library.read, sessions.read, private.owner) on every connection, so an incompatible update shows up as "not connected" instead of writing bad data.

Set up the bridge#

Run these commands from the folder that contains GalShelf's integration folder.

1. Check first. This verifies the plugin version, the plugin interfaces the bridge needs and the file digests, without changing anything:

   python integration/install_bridge.py --check

2. Install. The installer backs up the plugin files it touches to integration/backup/<time>/, adds clearly marked hooks and the file core/client_bridge.py, and does not replace the plugin. Running it again doesn't add duplicate hooks, and a failure restores what it wrote.

   python integration/install_bridge.py

   If you run several AstrBot instances, or the plugin is not under ~/.astrbot_launcher/instances/, name the exact plugin folder: --plugin "<full path to astrbot_plugin_galbirthday>".

3. Reload only GalBirthday from the AstrBot management page. The installer never restarts or reloads anything itself, and you don't need to restart AstrBot or NapCat.
4. Connect the desktop app on the same computer: open the galbd / QQ connection in settings and connect. The plugin creates a local pairing file when it loads, and the app reads it automatically, so you don't copy any keys by hand.

Permissions and security#

• The bridge listens only on 127.0.0.1:18766. It is not reachable from other computers unless you set up the reverse proxy below.
• The pairing key is stored in galshelf-bridge.json in the plugin's data folder. On Windows it is readable only by the current user and SYSTEM; elsewhere it is set to 0600. Never send this file or its key to anyone.
• The local administrator key can't be used through the proxy. Remote members get their own credential only after proving their QQ in the group.
• Requests from web pages are refused, so a website can't act as your client.
• For group verification the bot must be a member of the group, able to look up group members and to @mention people there.
• Don't expose the AstrBot management panel, NapCat ports or the pairing file through the proxy.

Remote members#

Members on other computers can link their QQ only after you open the service. In the plugin's data folder (next to galshelf-bridge.json), create galshelf-remote.json:

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

Use your own HTTPS domain; the example won't work. The bot must be in every listed group. Without this file remote verification is off and no codes are sent. Reload the plugin after changing it.

Then configure an HTTPS reverse proxy on the bot computer that forwards only /v1/ to http://127.0.0.1:18766, replaces (rather than appends to) X-Forwarded-For and X-Forwarded-Proto, sets X-Forwarded-Host to your domain and limits request bodies to 1 MB. A full Nginx example is in docs/QQ_BINDING.md of the release.

Link your QQ (members)#

1. In the desktop app, enter the service address, the group number and your QQ number, and ask for a code.
2. The bot @mentions you in that group with a 6-digit code (valid for 5 minutes, 5 attempts).
3. From the same QQ, reply in the group: /gal关联 <code>.
4. Enter the same code in the desktop app.

One QQ can be linked to one desktop app, and the credential lasts 90 days. Unlink in the app, or send /gal解除关联 in the group if you lost the device. To use the website with your galbd records, choose Authorise browser under the QQ link in the desktop app and enter the 8-character code on the website.

Verify the connection#

• python integration/install_bridge.py --check reports the plugin version and whether the hooks are in place.
• python integration/check_release.py compares the installed plugin hooks, bridge files and release manifest; --skip-installed checks only the package. It reads no credentials and changes nothing.
• The AstrBot log shows [GalBirthday] Companion bridge … started on loopback port 18766 after the reload.
• In the desktop app the galbd connection shows as connected and compatible.
• If you also run the GalShelf website against this bot, its /healthz?deep=1 reports whether the bridge is ready.

Troubleshooting#

Roll back or remove#

Restore the backup made by the installer, then reload only GalBirthday:

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

If the plugin was changed after the install, the automatic restore stops rather than overwriting the newer files. Rolling back never deletes personal libraries or play logs; the bridge's receipts stay in the plugin's own database.

Download#

• GalShelf releases are published only at the verified release page https://github.com/Harihi-Works/GalShelf-Dev/releases (external link), the same place the desktop app checks for updates. That public page carries the Windows desktop package.
• The bridge installer (integration/, with install_bridge.py, check_release.py and the release manifest) is part of the GalShelf suite's source package, which is not published on that public page. Ask the GalShelf maintainer for the bridge package that matches your desktop version.
• The GalBirthday plugin itself is not distributed by GalShelf, and no verified download location for it is recorded, so this page doesn't link to one. Use the plugin your bot already runs.

GalShelf never installs or reloads the plugin for you.