排障与诊断

当遇到服务无法启动、模块未生效或连接异常时，可通过下方的交互式排障向导逐步排查；完整排查清单与高频问题汇总亦收录在下方，便于快速检索与定位。

常见问题排查清单

冲突端口	涉及服务	典型报错 / 现象	解决方案
`19132` (UDP)	BDS 主控程序	BDS 启动失败、崩溃或提示端口无法绑定	检查后台是否有僵死或残留的 `bedrock_server` 进程；Windows 使用任务管理器/netstat 结束对应 PID。
`3001` (TCP)	db-server 数据服务	启动日志输出 `EADDRINUSE :::3001`	在 `configs/db_config.json` 中调整 `db_port`，或通过环境变量 `DB_PORT=3011` 换用其他可用端口。
`3002` (TCP)	qq-bridge (LLBot WS)	LLBot 连接失败，反向 WS 拒绝连接	确认防火墙已放行对应端口，并确保未同时运行多个 QQ 桥接实例。

# Windows 查看端口占用 PID
netstat -ano | findstr 19132

# Linux / macOS 查看端口占用
lsof -i :3001

异常现象	可能原因	解决步骤
启动报错 `Cannot find module 'node:sqlite'`	Node.js 版本过低	将 Node.js 升级至 `22.13.0` 或更高版本（平台依赖 Node 内置的原生 SQLite 模块）。
数据持久化写入失败或报 `SQLITE_CORRUPT`	磁盘异常或非正常断电损坏	停止所有服务，从 `<SFMC_ROOT>/data/backups/` 备份文件夹中还原最近的 `.sqlite` 文件。
SAPI 模块调用数据服务报 `401 Unauthorized`	模块鉴权 Token 失效	确认 SAPI 启动阶段 `ConfigManager.init()` 顺利获取了启动快照，重新执行 `mod reload`。

# 测试本地 db-server 健康度状态
curl http://127.0.0.1:3001/api/health

代码与配置生效机制：
- 若修改了 sapi/src/ 中的 TypeScript 代码：执行 sfmc> mod reload 即可热重载生效。
- 若修改了 configs/*.json 或 manifest.json：必须重启 BDS 才能生效。
锁文件状态：确认 <SFMC_ROOT>/modules/module-lock.json 中该模块的 enabled 字段为 true。
生命周期时序：若模块在初始化阶段操作了实体或维度数据失败，检查 ModuleRegistry.register 是否应设置 afterWorldLoad: true。
前置依赖模块：检查 manifest.json 中的 dependencies 是否均已安装且处于 enabled 状态。

官方开放平台后端 (official)

LLBot / OneBot 后端 (llbot)

凭证核对：检查 configs/qq_config.json 中的 official.app_id 与 official.app_secret 是否正确填写。
IP 白名单配置：登录 QQ 开放平台开发者后台，确认公网 IP 已添加到调用白名单中。
事件订阅：确认在开放平台已开启 GROUP_AT_MESSAGE_CREATE（群聊 @ 消息事件）。
群标识回填：在群内首次 @ 机器人后，从控制台日志复制生成的 official.group_openid 并填回配置文件，随后重启服务。

现象	说明与排查应对
修改 `sapi/src` 源码后游戏内未生效	确认 VS Code 扩展 SFMC: Start Watch 处于运行状态；或在控制台手动执行 `sfmc mod reload` 触发重新打包与部署。
热重载提示成功，但新增命令无法响应	检查新命令的权限节点是否已在 `registerPermissions` 中声明；若修改了 `manifest.json` 权限节点或平台 JSON 配置，必须重启 BDS 才能生效。

如排查后仍未解决问题，欢迎前往 GitHub Issues 提交反馈，并请附上：