MeshCentral 1.3.1 配置参数详解

目标：讲清 MeshCentral 主配置文件 config.json 的组织结构、查看与修改方式、核心参数的分类语义与安全相关行为，并给出一份可直接落地的生产配置模板。参数语义以官方 meshcentral-config-schema.json（master 分支，2026-10-27 查询）为准，关键行为（证书重生成、环境变量不写入、_ 前缀注释、meshctrl 配置动作）在 1.3.1 部署环境实测验证。部署过程见《MeshCentral 1.3.1 服务端 Docker Compose 部署指南》。

一、环境信息

• MeshCentral 版本：1.3.1（官方最新稳定版，Docker Compose 部署，实测环境与本文一致）
• 宿主系统：Ubuntu 22.04 LTS（x86_64）
• 配置文件路径：/opt/meshcentral/data/config.json（数据目录 bind mount 视角；服务端内为 /opt/meshcentral/meshcentral-data/config.json）
• 参数溯源来源：官方配置 Schema https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json（实测文件 209,723 字节，查询日期 2026-10-27）；首启自动生成的 config.json 模板；官方 Wiki 配置文档
• 实测行为取证：修改 settings.cert 重启（证书重生成范围）、meshctrl Config 动作、首启日志回显（详见各节）

二、前置条件

1. 已按部署指南完成 MeshCentral 服务端部署并能登录管理台（或使用 meshctrl 管理通道）；
2. 已获取官方 Schema 文件（推荐下载到本地，供编辑器校验）：

curl -LO https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json

3. 理解配置生效机制：config.json 位于 data 目录，服务端只在启动时读取一次，任何修改都需要重启服务端生效。

三、参数查看与修改方式

3.1 直接编辑 config.json（默认方式）

DYNAMIC_CONFIG=false（官方镜像默认）时，config.json 是唯一配置源。实测流程：

vi /opt/meshcentral/data/config.json
docker compose restart meshcentral   # 或 systemctl restart meshcentral

实测确认的三条规则：

1. 服务端不改写该文件：首启生成模板后，每次重启日志都回显 Pre-existing config found, not recreating... 与 Leaving config as-is. Dynamic Configuration is off.，手工编辑安全；
2. _ 前缀 = 注释：JSON 不支持注释，MeshCentral 约定以 _ 开头的键为「未启用项」，模板中 _sessionKey、_letsencrypt 整段都是示例；去掉 _ 前缀即启用该参数；
3. 键名大小写不敏感：官方模板写的是 AllowFraming、WebRTC、AgentPong、SelfUpdate（混合大小写），而 Schema 中定义为 allowFraming、webRTC、agentPong、selfUpdate，两种写法均正常生效——这是服务端读取配置时统一小写化处理的结果。

3.2 环境变量模式（DYNAMIC_CONFIG=true）

官方容器镜像支持以环境变量管理配置：设 DYNAMIC_CONFIG=true 后，HOSTNAME、ALLOW_NEW_ACCOUNTS、USE_MONGODB 等变量会在每次启动时动态生成 config.json。注意两种模式互斥：默认 false 模式下环境变量不写入 config.json（实测 HOSTNAME=meshcentral.lab.local 未生效，证书名称仍以 settings.cert 为准），必须改文件本身。变量清单见部署指南第六章。

3.3 meshctrl Config 动作

命令行工具 meshctrl 提供 Config 动作直接操作 config.json（工具安装见《MeshCentral 命令行工具 meshctrl 实战》）：

$ meshctrl Config --show

实测要点：该动作读取执行命令时工作目录下的 ./meshcentral-data/config.json 本地文件（不走服务端通道），因此需在能直接看到 data 目录的机器上执行——容器部署时可在宿主机建一个指向 data 目录的软链 meshcentral-data：

cd /opt/meshcentral && ln -s data meshcentral-data
meshctrl Config --show          # 实测：原样打印 config.json
meshctrl Config --listdomains   # 列出非默认域名

在错误的目录执行时实测报错：

Unable to find config.json.

修改类子动作（同样作用于本地文件，改完需重启服务端）：

meshctrl Config --adddomain "MyDomain" --title "My Server Name" --newAccounts false
meshctrl Config --settodomain "MyDomain" --themePack "Stylish-UI"
meshctrl Config --removefromdomain "MyDomain" --title
meshctrl Config --removedomain "MyDomain"

3.4 配置校验

config.json 首行的 $schema 指向官方 Schema，VS Code 等编辑器据此提供参数补全与类型校验；启动时配置不合法会在日志中明确报错并拒绝启用相关特性，属于「宁可启动失败也不静默错配」的取向。

四、参数总览

官方 Schema 的顶层配置节（实测统计，2026-10-27 master 版）：

本文第五章精讲日常运维高频参数；冷门参数以官方 Schema 描述为准。

五、核心参数分类详解

5.1 服务与端口（settings）

💡 说明：容器映射端口后，对 Agent 下发的连接地址来自 cert 名称 + port（或 aliasPort）。内网映射非标准端口（如部署指南的 8131→443）且设备从外部接入时，Agent 侧实际连接 wss://<cert名>:443——容器网络内由网络别名解析；跨网段接入需让 <cert名>:443 真实可达，或用 certUrl（见 5.5）指定下载与连接基准。

5.2 运行模式（settings）

5.3 会话与安全（settings）

5.4 Agent 通道（settings）

5.5 反向代理与对外暴露（settings + domains）

5.6 数据库（settings）

💡 说明：切换外部数据库不迁移既有 NeDB 数据（需用导出工具或重新纳管）。大规模（数千设备）或需要高可用时选 PostgreSQL/MongoDB；容器镜像请配套选择 -postgresql/-mongodb 变体或用全量镜像。

5.7 站点域名（domains）

domains 以域名为键，"" 即默认域名（访问根路径的站点）。高频参数（每域独立生效）：

多域名：domains 下新增键即新增子站点（如 "mysite": {...}，经 /mysite 路径访问；配 dns 参数可绑定独立域名）。domaindefaults 节为所有域的公共默认。

5.8 邮件与消息通知（smtp / messaging）

smtp（启用后支持邮件验证、设备上下线通知、邀请邮件、账号找回）：

messaging（设备上下线的即时通知与双因素登录推送）：telegram（botId+token）、discord（url webhook）、xmpp、ntfy（boolean 或对象配置自建 ntfy）、pushover、slack、callmebot、zulip。用户在个人账号设置里绑定接收账号后生效。

5.9 Let's Encrypt 自动证书（letsEncrypt）

去掉整节的 _ 前缀并填入实际值即启用（需 80 端口公网可达，production 默认 false 先取测试证书）：

六、生产配置模板

以下模板整合本文高频参数（按内网域名 + SMTP 通知 + 关闭注册的收敛形态；证书名称、邮箱、密钥按实际替换）：

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "settings": {
    "cert": "mesh.example.com",
    "port": 443,
    "redirPort": 80,
    "WANonly": true,
    "sessionKey": "换成64位以上随机字符串",
    "sessionTime": 480,
    "AgentPong": 300,
    "agentIdleTimeout": 150,
    "exactPorts": true,
    "lockAgentDownload": true,
    "allowFraming": false,
    "WebRTC": false,
    "SelfUpdate": false,
    "plugins": { "enabled": false }
  },
  "domains": {
    "": {
      "title": "运维管理台",
      "NewAccounts": false,
      "localSessionRecording": true,
      "userSessionIdleTimeout": 30,
      "welcomeText": "内部设备管理系统，账号请联系管理员开通",
      "nightMode": 0
    }
  },
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "from": "meshcentral@example.com",
    "user": "meshcentral@example.com",
    "pass": "SMTP密码",
    "tls": false,
    "emailDelaySeconds": 60
  },
  "_letsEncrypt": {
    "_comment": "公网部署时去掉本节 _ 前缀启用自动证书，names 需与 settings.cert 一致",
    "email": "admin@example.com",
    "names": "mesh.example.com",
    "production": false
  }
}

要点复核：sessionKey 必设（否则重启全员掉线）；WANonly + NewAccounts: false + lockAgentDownload 是公网收敛三件套；exactPorts 让端口冲突在启动时显式报错；SMTP 启用后管理员可在「我的账号」开启设备上下线邮件通知。

七、常见问题

7.1 改了参数没有生效

按顺序检查：① 参数键是否带 _ 前缀（带 = 注释未启用）；② 是否重启了服务端（配置仅启动时读取）；③ DYNAMIC_CONFIG 模式确认——false 模式下环境变量全部无效（部署指南 4.5 节实测）；④ 键名拼写（大小写不敏感但拼写必须准确，用编辑器 Schema 校验兜底）。

7.2 修改 settings.cert 后日志报 Error 且证书重生成

预期行为：先提示名称不匹配，再重签 HTTPS/代码签名/AMT MPS 三套证书；根证书不变，已上线 Agent 无感（部署指南 4.5 节实测，含 OpenSSL 输出）。想保留现有证书不重签可加 keepCerts: true。

7.3 每次重启后所有用户都要重新登录

未设置 settings.sessionKey，服务端每次启动随机生成会话加密密钥，旧 Cookie 全部失效。设置固定 sessionKey（随机长字符串）即可，多实例部署必须一致。

7.4 meshctrl Config --show 报 "Unable to find config.json."

该动作读的是本机当前目录下的 ./meshcentral-data/config.json，不经过服务端（5.3 节实测）。在 data 目录的父目录执行，或按 5.3 节建软链。

7.5 反向代理后 Agent 连不上或证书校验失败

反代改变了 Agent 看到的地址与证书链：设置 domains.""."certUrl" 指向对外 HTTPS 地址，配合 tlsOffload/trustedProxy 信任代理转发的头部，aliasPort 对齐对外端口。调试期可临时 ignoreAgentHashCheck，定位后务必关闭。

7.6 Let's Encrypt 签发失败

最常见原因：80 端口未放行（HTTP-01 挑战必须走 80）、names 与实际域名不符、production: false 拿到的是测试证书（浏览器仍报不可信）。反代环境可设 skipChallengeVerification: true 跳过本地自检。

八、参考链接

• 《MeshCentral 1.3.1 介绍与选型指南》（本专栏）
• 《MeshCentral 1.3.1 服务端 Docker Compose 部署指南》（本专栏）
• 官方配置 Schema（参数全集与权威描述）：https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json
• 官方 Wiki 配置文档入口：https://github.com/Ylianst/MeshCentral/wiki
• MeshCentral GitHub 仓库：https://github.com/Ylianst/MeshCentral