#平台与模块配置

SFMC 采用约定优于配置（Convention over Configuration）的设计理念，兼具开箱即用的自动化能力与生产级可定制性。

#1. 核心机制与设计原则

• 自动生成初始配置：首次启动任何服务（sfmc、db-server、qq-bridge）时，系统会自动探测并生成缺失的标准配置文件，填入安全的默认参数。
• 静态强校验（JSON Schema）：自动生成的 JSON 文件首行均预注入 $schema 契约指针。在编辑器中可提供字段悬停解释、代码补全与语法检查。
• 环境变量覆盖（Environment Overrides）：生产环境（如 Docker、CI/CD 或云服务器守护进程）下，可通过环境变量覆盖敏感凭证与关键路径。

<SFMC_ROOT>/
├── configs/
│   ├── db_config.json          # 数据库守护服务与 loopback 通信
│   ├── qq_config.json          # QQ 互通桥接（官方 Bot / LLBot）
│   ├── bds_updater.json        # BDS 版本检查、自动备份与崩溃重启
│   ├── pack-update.json        # 附加包自动更新与 CurseForge 接入
│   ├── permissions.json        # 全局玩家权限阶梯配置
│   ├── log-filter.json         # 统一日志降噪与过滤规则
│   └── <configKey>.json        # 各业务模块的独立私有配置
└── modules/
    ├── catalog.json            # 已安装模块镜像清单
    └── module-lock.json        # 模块启停状态锁文件

#2. 平台核心配置详解

#db_config.json：数据守护服务

管理 db-server 的 HTTP 监听端口、SQLite 存储位置与跨进程调用凭据。这是 SAPI 脚本、CLI 与 QQ 桥接共同依赖的中枢。

{
  "$schema": "../modules/sdk/@sfmc-sdk/schemas/db_config.schema.json",
  "db_port": 3001,
  "http_auth": "",
  "dbDir": "./data/sfmc_data.db",
  "modulesDir": "modules"
}

#qq_config.json：多端互通网关

配置 Minecraft 服务器与 QQ 群消息互通。官方机器人可在 official.transport 选择 websocket 或 webhook；LLBot 使用 OneBot 11 协议。

{
  "$schema": "../modules/sdk/@sfmc-sdk/schemas/qq_config.schema.json",
  "qq_enabled": true,
  "qq_backend": "official",
  "official": {
    "transport": "webhook",
    "app_id": "102030405",
    "app_secret": "your_app_secret_here",
    "group_openid": "YOUR_GROUP_OPENID",
    "sandbox": false,
    "admin_openids": [],
    "webhook": { "port": 3005, "path": "/qqbot/webhook" }
  },
  "llbot": { "enabled": false, "ws_port": 3002, "host": "127.0.0.1", "port": 3004 },
  "qq_events": {
    "enabled": true,
    "join": true,
    "leave": true,
    "death": true,
    "crash": true,
    "start": true,
    "stop": true
  }
}

#关键参数解析

• 后端选择 (qq_backend)：
  • "official"：使用腾讯 QQ 开放平台官方 API。免除本地 QQ 客户端挂机封号风险，支持主动推群与群面板指令交互。
  • "llbot"：使用 LLBot (OneBot 11)。连接设置放在 llbot 对象中。
• 接收方式 (official.transport)："websocket" 为游戏机本地 Gateway；"webhook" 为云端 HTTPS 回调，并启用云端配置自动同步。
• 官方凭据 (official.app_id / official.app_secret)：开放平台开发者凭证，请勿提交到公开 Git 仓库。
• 群标识 (official.group_openid)：官方机器人对应的群唯一 OpenID（注意：并非传统群号）。首次拉入机器人后在群内 @机器人，可在 qq-bridge 日志中查看自动捕获并打印的 OpenID。
• 事件推群开关 (qq_events)：细粒度控制进服、退服、玩家阵亡、服务器起停等系统广播是否转发至 QQ 群。

完整机器人联调步骤与权限申请指引，请参阅 QQ 互通配置手册。

#bds_updater.json：BDS 核心更新

管理 Bedrock Dedicated Server 的自动版本检测、热补丁下载与升级前安全备份。 进程崩溃拉起由 sfmc 后台守护进程负责，不再在此配置开关。

{
  "$schema": "../modules/sdk/@sfmc-sdk/schemas/bds_updater.schema.json",
  "bds_path": "./BedrockDedicatedServer",
  "backup_dir": "./backups",
  "channel": "release",
  "auto_check": true,
  "preserve": ["server.properties", "whitelist.json", "permissions.json", "worlds"],
  "qq_notify": true
}

#pack-update.json：附加包自动升级

为安装在世界中的第三方行为包/资源包提供 CurseForge 等上游提供商的版本探测与自动更新服务。

{
  "$schema": "../modules/sdk/@sfmc-sdk/schemas/pack_update.schema.json",
  "enabled": true,
  "checkOnBdsStart": true,
  "applyOnBdsStart": false,
  "match": {
    "nameMinScore": 0.85,
    "stripFolderTags": true
  },
  "providers": {
    "curseforge": {
      "apiKey": ""
    }
  }
}

• 安全防御：applyOnBdsStart 默认设为 false。建议服主在启动时仅检查（checkOnBdsStart: true），确认版本更新日志后再手动执行 packs update，防止未知上游更新破坏世界一致性。
• API Key 注入：providers.curseforge.apiKey 可留空，直接在宿主环境注入 CURSEFORGE_API_KEY 环境变量。

#permissions.json：全服权限阶梯矩阵

定义游戏内玩家与后台操作者的权限级别。SFMC 采用声明式、自顶向下的四级权限控制阶梯：

[
  {
    "player_name": "Steve",
    "level": 3
  },
  {
    "player_name": "Alex",
    "level": 2
  }
]

#log-filter.json：统一日志降噪

BDS 控制台或高频实体脚本常常会打印过量无效信息。通过 log-filter.json，可声明式拦截无意义刷屏：

{
  "$schema": "../modules/sdk/@sfmc-sdk/schemas/log_filter.schema.json",
  "enabled": true,
  "mode": "drop",
  "applyTo": "display",
  "rules": [
    {
      "enabled": true,
      "sources": ["bds"],
      "levels": ["info"],
      "contains": "Player disconnected: "
    }
  ]
}

• mode: "drop"（命中规则丢弃）或 "keep"（白名单模式，仅保留命中项）。
• applyTo: "display"（仅在控制台终端/REPL 中隐藏，落盘文件仍保留便于复盘）或 "all"（连同磁盘日志一同过滤）。

#server.properties：BDS 原生配置与本地化辅助

位于 <bds_path>/server.properties，是 Minecraft 基岩版官方独立服务端（BDS）的核心配置文件，控制网络端口、视距、正版验证、默认游戏模式与世界难度等关键底层参数。

SFMC 平台提供了 server.properties 本地化与配置辅助功能（由 @sfmc-bds/bds-tools 提供）：

1. 自动本地化注释（多语言翻译）：
   • 生效时机：执行 sfmc update（安装或版本更新解压后）、或日常通过 sfmc start 启动 BDS 进程前自动执行。
   • 保留自定义配置：基于属性解析，不修改配置键名，保留服主自定义修改的配置值（如端口、地图名、最大人数等），未知新增项与自定义注释原样保留。
   • 结构化中文说明：涵盖官方约 40 个常用配置项，提供功能概述、合法取值枚举与注意事项。
   • 语言环境联动：根据 configs/runtime.json#locale、--lang 参数或系统语言自动判定；非中文环境（如 en）保持原版英文。
2. EULA 遥测合规补丁（emit-server-telemetry=true）：
   • 根据 Mojang EULA 协议约定，当服主在初始化向导同意 EULA 后，平台会在启动和升级阶段自动确保 emit-server-telemetry=true 写入并附带中文说明。
3. 幂等性与安全编码：
   • 保证幂等写入（多次启动或更新不会导致注释重复追加），采用无 BOM 的标准 UTF-8 编码。

#3. 模块状态与私有配置

#模块运行时状态文件

位于 <SFMC_ROOT>/modules/ 目录下，记录当前工作区的模块状态：

#模块私有配置（<configKey>.json）

当某个模块需要对外暴露参数时（如挂机判定时间、传送冷却、经济初始金额），规范要求其配置独立存放于 configs/<configKey>.json（通常为小写下划线命名，如 configs/economy.json）。

模块包通过 configs-default/<configKey>.json 携带默认值。安装、更新或 link 时，CLI 会创建工作目录配置，或递归补入新增字段；用户已有值、数组和自定义字段不会被覆盖。

模块内部可通过 SDK 的 @sfmc-bds/sdk/sapi/config 模块完成透明读写与持久化，服主可根据各模块文档直接编辑对应的 JSON 文件。

#4. 配置修改与生效边界

不同配置在架构中所处的层次不同，其生效机制亦存在明确边界：

1. 热重载（无需重启 BDS）：
   • 启停模块：运行 sfmc mod enable/disable <id> 后紧接着执行 sfmc mod reload。
   • 规则与权限：支持热同步的模块会实时从 db-server 获取变更。
2. 需要重启服务进程：
   • 修改 db_config.json（如端口、token）：必须重启 db-server。
   • 修改 qq_config.json：必须重启 qq-bridge 与 db-server（更新出站凭据）。
3. 需要重启 BDS 游戏服务端：
   • 涉及 server.properties、BDS 核心二进制更新、全新附加包导入、以及在 SAPI 启动初始化（startup 阶段）固化参数的底层模块。