Skip to content

Commit 4172402

Browse files
RhenCloudRhenCloud
committed
feat(qq): add ws_ssl_verify config and enable qid support
1 parent 8b3d0b4 commit 4172402

3 files changed

Lines changed: 152 additions & 131 deletions

File tree

‎docs/drivers/qq.md‎

Lines changed: 51 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ NextBridge connects to QQ through a single driver with three protocol modes:
1212

1313
Use these links to choose and deploy your QQ bot server implementation (non-LLMS docs):
1414

15-
| Mode | Website / docs | Repository |
16-
|---|---|---|
17-
| `napcat` | https://napneko.github.io | https://github.com/NapNeko/NapCatQQ |
18-
| `lagrange` | https://lagrangedev.github.io/Lagrange.Doc | https://github.com/LagrangeDev/Lagrange.OneBot |
19-
| `onebot_v11` | https://11.onebot.dev | https://github.com/botuniverse/onebot-11 |
15+
| Mode | Website / docs | Repository |
16+
| ------------ | ------------------------------------------ | ---------------------------------------------- |
17+
| `napcat` | https://napneko.github.io | https://github.com/NapNeko/NapCatQQ |
18+
| `lagrange` | https://lagrangedev.github.io/Lagrange.Doc | https://github.com/LagrangeDev/Lagrange.OneBot |
19+
| `onebot_v11` | https://11.onebot.dev | https://github.com/botuniverse/onebot-11 |
2020

2121
## Setup
2222

@@ -28,24 +28,25 @@ Use these links to choose and deploy your QQ bot server implementation (non-LLMS
2828

2929
Add under `qq.<instance_id>` in `config.json`:
3030

31-
| Key | Required | Default | Description |
32-
|---|---|---|---|
33-
| `protocol` | No | `napcat` | Protocol mode: `napcat`, `lagrange`, or `onebot_v11` |
34-
| `ws_url` | No | `ws://127.0.0.1:3001` | WebSocket URL of the QQ bot server |
35-
| `ws_token` | No | — | Access token (appended as `?access_token=...`) |
36-
| `max_file_size` | No | `10485760` (10 MB) | Maximum bytes to download per attachment when sending |
37-
| `cqface_mode` | No | `"gif"` | How to represent QQ face segments. `"gif"` uploads faces from the local `db/cqface-gif/` database; `"emoji"` renders inline text like `:cqface306:`. |
38-
| `file_send_mode` | No | `"stream"` | Upload mode used by NapCat. `"stream"` uses `upload_file_stream`; `"base64"` sends `base64://...` payloads directly. Lagrange and generic OneBot modes fall back to path-based upload for files. |
39-
| `stream_threshold` | No | `0` (disabled) | If greater than 0, switches to `stream` mode for large files when using NapCat, regardless of `file_send_mode`. |
40-
| `forward_render_enabled` | No | `false` | Enable merged-forward rendering to HTML pages. Supported in `napcat` and `lagrange` modes. |
41-
| `forward_render_ttl_seconds` | No | `15552000` (180 days) | TTL for merged-forward HTML pages. Minimum is 60 seconds. |
42-
| `forward_render_mount_path` | No | `"/qq-forward"` | Mount path for merged-forward pages on the shared HTTP server. The default becomes `"/qq-forward/<instance_id>"` automatically. |
43-
| `forward_render_persist_enabled` | No | `false` | Persist merged-forward pages to the database so links survive restarts. |
44-
| `forward_render_image_method` | No | `"url"` | How images are rendered in merged-forward HTML. `"url"` stores bytes in DB; `"base64"` embeds data URIs. |
45-
| `forward_render_base_url` | No | `""` | Public URL prefix for forward links. If set, links are generated as `${forward_render_base_url}/{page_id}`. |
46-
| `forward_render_asset_ttl_seconds` | No | `1209600` (14 days) | TTL for merged-forward image assets served by the bridge. Set to `0` for infinite validity. |
47-
| `forward_render_cqface_gif` | No | `true` | Rendering strategy for `face` segments inside merged-forward HTML. |
48-
| `proxy` | No | — | Proxy URL for WebSocket connection and media downloading. Set to `null` to disable proxy for this instance. |
31+
| Key | Required | Default | Description |
32+
| ---------------------------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
33+
| `protocol` | No | `napcat` | Protocol mode: `napcat`, `lagrange`, or `onebot_v11` |
34+
| `ws_url` | No | `ws://127.0.0.1:3001` | WebSocket URL of the QQ bot server |
35+
| `ws_token` | No | — | Access token (appended as `?access_token=...`) |
36+
| `ws_ssl_verify` | No | `true` | Whether to verify TLS certificates for `wss://` WebSocket URLs. Set to `false` only when your bot server uses a self-signed/private CA certificate. |
37+
| `max_file_size` | No | `10485760` (10 MB) | Maximum bytes to download per attachment when sending |
38+
| `cqface_mode` | No | `"gif"` | How to represent QQ face segments. `"gif"` uploads faces from the local `db/cqface-gif/` database; `"emoji"` renders inline text like `:cqface306:`. |
39+
| `file_send_mode` | No | `"stream"` | Upload mode used by NapCat. `"stream"` uses `upload_file_stream`; `"base64"` sends `base64://...` payloads directly. Lagrange and generic OneBot modes fall back to path-based upload for files. |
40+
| `stream_threshold` | No | `0` (disabled) | If greater than 0, switches to `stream` mode for large files when using NapCat, regardless of `file_send_mode`. |
41+
| `forward_render_enabled` | No | `false` | Enable merged-forward rendering to HTML pages. Supported in `napcat` and `lagrange` modes. |
42+
| `forward_render_ttl_seconds` | No | `15552000` (180 days) | TTL for merged-forward HTML pages. Minimum is 60 seconds. |
43+
| `forward_render_mount_path` | No | `"/qq-forward"` | Mount path for merged-forward pages on the shared HTTP server. The default becomes `"/qq-forward/<instance_id>"` automatically. |
44+
| `forward_render_persist_enabled` | No | `false` | Persist merged-forward pages to the database so links survive restarts. |
45+
| `forward_render_image_method` | No | `"url"` | How images are rendered in merged-forward HTML. `"url"` stores bytes in DB; `"base64"` embeds data URIs. |
46+
| `forward_render_base_url` | No | `""` | Public URL prefix for forward links. If set, links are generated as `${forward_render_base_url}/{page_id}`. |
47+
| `forward_render_asset_ttl_seconds` | No | `1209600` (14 days) | TTL for merged-forward image assets served by the bridge. Set to `0` for infinite validity. |
48+
| `forward_render_cqface_gif` | No | `true` | Rendering strategy for `face` segments inside merged-forward HTML. |
49+
| `proxy` | No | — | Proxy URL for WebSocket connection and media downloading. Set to `null` to disable proxy for this instance. |
4950

5051
Forward link base URL priority:
5152
1. `forward_render_base_url` (no mount-path auto-append)
@@ -68,8 +69,8 @@ Forward link base URL priority:
6869

6970
Use under `channels` or `from`/`to` in `rules.json`:
7071

71-
| Key | Description |
72-
|---|---|
72+
| Key | Description |
73+
| ---------- | ---------------------------------- |
7374
| `group_id` | QQ group number (string or number) |
7475

7576
```json
@@ -84,29 +85,29 @@ NextBridge currently bridges **group messages** only. Private messages are not r
8485

8586
## Behavior by protocol
8687

87-
| Feature | napcat | lagrange | onebot_v11 |
88-
|---|---|---|---|
89-
| Message receive/send | Yes | Yes | Yes |
90-
| Merged-forward rendering | Yes | Yes | No |
91-
| `upload_file_stream` | Yes | No | No |
92-
| Group file upload | Yes | Yes | Best effort |
93-
| Group file URL lookup | Yes | Yes | Best effort |
88+
| Feature | napcat | lagrange | onebot_v11 |
89+
| ------------------------ | ------ | -------- | ----------- |
90+
| Message receive/send | Yes | Yes | Yes |
91+
| Merged-forward rendering | Yes | Yes | No |
92+
| `upload_file_stream` | Yes | No | No |
93+
| Group file upload | Yes | Yes | Best effort |
94+
| Group file URL lookup | Yes | Yes | Best effort |
9495

9596
## Message segments
9697

9798
Incoming messages are parsed from OneBot 11 segment arrays:
9899

99-
| Segment type | Handling |
100-
|---|---|
101-
| `text` | Becomes message text |
102-
| `at` | Converted to `@name` text |
103-
| `image` | Forwarded as `image` attachment; in merged-forward: image rendering follows `forward_render_image_method` (`url` or `base64`) |
104-
| `record` | Forwarded as `voice` attachment; in merged-forward: embedded as playable audio, with AMR transcoded to OGG when possible |
105-
| `video` | Forwarded as `video` attachment; in merged-forward: embedded with `<video controls>` |
106-
| `file` | Forwarded as `file` attachment; for `napcat` mode, streamed via `upload_file_stream`, otherwise uploaded through a local temporary path and then sent with `upload_group_file` (best when the bot can see the same filesystem path) |
107-
| `forward` | Calls `get_forward_msg`, renders a temporary HTML page, and forwards the link; nested forward nodes are rendered recursively |
108-
| `face` | Rendered from the local cqface GIF database or inline text, depending on `cqface_mode` |
109-
| Others (`reply`, `json`, `mface`, etc.) | Parsed when possible; unsupported types are skipped or shown as text fallback |
100+
| Segment type | Handling |
101+
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102+
| `text` | Becomes message text |
103+
| `at` | Converted to `@name` text |
104+
| `image` | Forwarded as `image` attachment; in merged-forward: image rendering follows `forward_render_image_method` (`url` or `base64`) |
105+
| `record` | Forwarded as `voice` attachment; in merged-forward: embedded as playable audio, with AMR transcoded to OGG when possible |
106+
| `video` | Forwarded as `video` attachment; in merged-forward: embedded with `<video controls>` |
107+
| `file` | Forwarded as `file` attachment; for `napcat` mode, streamed via `upload_file_stream`, otherwise uploaded through a local temporary path and then sent with `upload_group_file` (best when the bot can see the same filesystem path) |
108+
| `forward` | Calls `get_forward_msg`, renders a temporary HTML page, and forwards the link; nested forward nodes are rendered recursively |
109+
| `face` | Rendered from the local cqface GIF database or inline text, depending on `cqface_mode` |
110+
| Others (`reply`, `json`, `mface`, etc.) | Parsed when possible; unsupported types are skipped or shown as text fallback |
110111

111112
Merged-forward image behavior:
112113
- In `url` mode, image clicks open bridge-served assets (`/asset/...`) instead of original QQ CDN links.
@@ -142,12 +143,12 @@ NextBridge does not auto-fallback between host URLs.
142143

143144
## Sending
144145

145-
| Attachment type | Method |
146-
|---|---|
147-
| `image` | Downloaded and sent as base64 (`base64://...`) |
148-
| `voice` | Downloaded and sent as base64 (`base64://...`) |
149-
| `video` | In `napcat` mode: sent by `file_send_mode` (`stream`/`base64`); in `lagrange`/`onebot_v11`: best-effort path-based upload |
150-
| `file` | In `napcat` mode: sent by `file_send_mode` (`stream`/`base64`); in `lagrange`/`onebot_v11`: best-effort path-based upload |
146+
| Attachment type | Method |
147+
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
148+
| `image` | Downloaded and sent as base64 (`base64://...`) |
149+
| `voice` | Downloaded and sent as base64 (`base64://...`) |
150+
| `video` | In `napcat` mode: sent by `file_send_mode` (`stream`/`base64`); in `lagrange`/`onebot_v11`: best-effort path-based upload |
151+
| `file` | In `napcat` mode: sent by `file_send_mode` (`stream`/`base64`); in `lagrange`/`onebot_v11`: best-effort path-based upload |
151152

152153
Voice compatibility: when forwarding to other platforms, if QQ voice is detected as AMR (for example `.amr`), NextBridge first attempts transcoding to `audio/ogg` (Opus), which improves compatibility on platforms like Discord. If transcoding fails, it falls back to the original audio.
153154

@@ -161,3 +162,4 @@ AMR transcoding requires `ffmpeg` to be available on the host. Without ffmpeg, v
161162

162163
- Self-message echo: some QQ bot servers echo the bot's own outgoing messages as inbound events. NextBridge filters these by comparing `user_id` and `self_id`.
163164
- Reconnection: if the WebSocket connection drops, NextBridge reconnects automatically every 5 seconds.
165+
- TLS certificates: if `wss://` connection fails with `CERTIFICATE_VERIFY_FAILED` and your deployment uses self-signed/internal CA certs, set `ws_ssl_verify` to `false` for that QQ instance.

0 commit comments

Comments
 (0)