This document was written by AI and has been partially reviewed by humans. If you find a mistake, please report it.
Migrating to v0.4
Coming from an older version?
This page covers v0.3 → v0.4 only. If you are still on v0.3 or earlier, work through the v0.3 migration page first — migration steps are meant to be applied one release at a time.
中文版见 迁移到 v0.4。
NextBridge does not keep backwards compatibility before 1.0, so a minor version bump can change config keys and behaviour. This page lists everything that needs attention when moving from v0.3 to v0.4.
Before you upgrade
- Back up
data/. It holdsconfig.*,rules.*,data.dband the optionalcqface-map.yaml. - Check your config keys. v0.4 validates the config file strictly, so a leftover key from an older version now fails at startup instead of being ignored. The Configuration reference is the source of truth.
Config changes
Driver keys
No driver was renamed between v0.3 and v0.4, so a v0.3 config keeps its key names.
For reference: the QQ driver became qq in v0.3 (it was napcat in v0.2 and earlier). If you are upgrading a config that predates v0.3, rename that block too — NextBridge looks up the driver module by its config key and skips the instance with a warning when the module is missing.
New global sections
v0.4 adds several global.* blocks. They are all optional with sane defaults, but the ones below are worth reviewing:
| Key | Why you may want it |
|---|---|
global.http | Shared HTTP server for webhook drivers. Yunhu no longer binds its own port (see below). |
global.plugins | Driver/plugin selection, admin API credentials, restart policy. |
global.metrics | Prometheus counters at /_nextbridge/metrics. |
global.middleware | Receive/send middleware pipeline. |
global.send_timeout | Offloads slow sends to a background queue. |
global.sanitize_nickname | Strips zero-width and bidi characters from sender names. |
Per-driver key changes
Removed / renamed:
| Driver | v0.3 | v0.4 |
|---|---|---|
discord | send_as_bot_when_using_cqface_emoji | cqface_webhook_fallback ("bot" / "unicode") |
yunhu | webhook_port | removed — the webhook is served by the shared global.http server; see webhook_path |
qq | forward_render_cqface_gif | cqface_gif_host (old key still accepted as a deprecated alias) |
Added:
discord:enable_recall,enable_native_commands, mention controls (allow_mentions_everyone/allow_mentions_users/allow_mentions_roles,sanitize_mass_mentions),auto_link_image_hosts,auto_link_image_show_original_urltelegram:enable_recall,sanitize_accidental_mentions,photo_padding_colorqq:connection_mode,reverse_ws_path,edit_via_reply,edit_prefix,enable_recall,cqface_gif_hostdingtalk/feishu/googlechat/rocketchat/slack/teams/vocechat/yunhu:webhook_secret
Behaviour changes
- The rules file is validated at startup. A malformed
rules.*now refuses to start rather than silently ignoring rules at runtime. cqface_mode: "gif"can fetch remotely. Face GIFs are no longer bundled with NextBridge. Each face is looked up in the local database first and downloaded fromcqface_gif_hostinstead of being dropped; the default host moved to https://cqface.p.wyf9.top/dist/, and the oldnextbridge.siiway.org/db/cqface-gif/URLs 301 there. To keep a full local copy, runuv run scripts/sync_cqface.py— see the QQ driver page.- Admin API is fail-closed. With the admin API disabled, only
/_nextbridge/healthis public. - Slow sends no longer block the queue. Messages exceeding
send_timeoutcontinue in the background.
After upgrading
- Start NextBridge and watch the startup log for config validation errors.
- The database migrates itself (
5 -> 6adds themetrics_counterstable). - If you use the admin API, set
global.plugins.admin.user/password. - Reload config without a restart with
SIGHUPor the admin API.