MeshCentral 1.3.1 服务端 Docker Compose 部署指南

目标：用 Docker Compose 在单台 Ubuntu 22.04 服务器上从零部署 MeshCentral 1.3.1 服务端，完成「镜像选型 → 编排启动 → 首启日志解读 → 管理员注册 → 证书名称调整 → 数据持久化确认 → 设备纳管（Agent 安装上线）→ 远程命令验证」的完整链路。本文全部命令与回显已在 Docker Engine 29.9.2（Compose v5.6.1）环境实测通过，实测日期 2026-10-27。MeshCentral 的定位、功能边界与同类选型对比见《MeshCentral 1.3.1 介绍与选型指南》。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
Docker Engine：29.9.2，Docker Compose 插件 v5.6.1
MeshCentral 服务端版本：1.3.1（官方最新稳定版，安全修复版；Releases 页置顶公告要求所有旧版本升级至此版）
官方镜像：ghcr.io/ylianst/meshcentral:1.3.1（amd64，实测磁盘占用 993 MB，摘要 sha256:266b01942545829f11d53e6cecd5c2e48033d9edb48bbd3a9a569482ff1d050d）
内置运行时：NodeJS v24.22.1 / NPM 11.19.1（首启日志打印）
端口规划（本文实测映射，生产可按需改为标准端口）：
- 8131/TCP → 服务端 443/TCP：HTTPS 主服务（Web 管理台、Agent WebSocket 接入共用）
- 8133/TCP → 服务端 80/TCP：HTTP 重定向服务（自动跳转 HTTPS）
- 4433/TCP：Intel AMT 管理端口（MPS），本文未启用 AMT 纳管，不映射
编排目录：/opt/meshcentral/（示例路径，含 docker-compose.yml 与 data/、files/、backups/、web/ 四个数据子目录）
独立网络：meshcentral-1.3.1-net（bridge，实测网段 10.89.65.0/24），并为服务端附加网络别名 meshcentral.lab.local（与证书名称一致，供受管设备解析连接，见 4.6 节）
部署产物（实测确认）：Web 管理台 https://<服务器地址>:8131/，站点管理员账号 admin

二、镜像选型说明

MeshCentral 官方在 GitHub Container Registry（ghcr.io）发布服务端镜像，选型先定变体再定标签。

2.1 镜像变体

官方仓库 docker/README.md 列出的镜像变体（查询日期 2026-10-27）：

变体	内置内容	适用
`<版本>`（本文选用）	完整后端 + 全部数据库驱动（NeDB 内置 + MongoDB/PostgreSQL/MySQL 驱动）	部署一次覆盖所有数据库路线，后续切换外部数据库无需换镜像
`<版本>-slim`	仅本地数据库（NeDB）	固定使用内置 NeDB、追求最小体积
`<版本>-mongodb`	后端 + MongoDB 驱动	明确使用 MongoDB 的环境
`<版本>-postgresql`	后端 + PostgreSQL 驱动	明确使用 PostgreSQL 的环境
`<版本>-mysql`	后端 + MySQL/MariaDB 驱动	明确使用 MySQL 的环境

2.2 标签策略

标签	性质	适用
`1.3.1`	精确版本	生产推荐，与本文实测一致
`latest`	跟随最新稳定版	想自动获得安全修复；MeshCentral 安全更新频繁，此标签有其实用价值
`master`	主干开发版	仅测试环境

💡 说明：MeshCentral 1.3.1 是安全紧急修复版（官方公告存在针对服务端与客户端的主动利用攻击），任何旧版本都应尽快升级。生产环境建议「精确版本标签 + 定期跟踪 Releases 公告」的组合：先固定版本保证可复现，再按公告节奏手动升级。

三、前置条件

服务器已安装 Docker Engine 与 Compose 插件，验证：

docker version --format 'Engine {{.Server.Version}}'

实测输出：

Engine 29.9.2

docker compose version

实测输出：

Docker Compose version v5.6.1

规划的服务器端口未被占用：

ss -ltnp | grep -E ':(8131|8133)\b' || echo "ports free"

实测输出：

ports free

确定服务端的「证书名称」：MeshCentral 首启会以此名称签发自签名 TLS 证书，受管设备也按此名称连接服务端。本文规划为 meshcentral.lab.local（内网 DNS/hosts 可解析的域名）。生产环境若有公网域名，建议直接用公网域名并配置 Let's Encrypt 自动证书。

四、部署步骤

MeshCentral 的全部持久化数据落在四个目录，先创建：

mkdir -p /opt/meshcentral/{data,files,backups,web}
cd /opt/meshcentral

四个目录的作用（首启后实测确认的内容，见第五章）：

目录	挂载到服务端内	存放内容
`data/`	`/opt/meshcentral/meshcentral-data`	最核心：config.json、四套 TLS 证书及私钥、内置数据库 meshcentral.db、Agent 二进制缓存 agentbuilds/、代码签名产物 signedagents/
`files/`	`/opt/meshcentral/meshcentral-files`	文件传输中转、会话录像等运行期文件
`backups/`	`/opt/meshcentral/meshcentral-backups`	数据库自动备份
`web/`	`/opt/meshcentral/meshcentral-web`	自定义静态资源

4.2 编写编排文件

创建 docker-compose.yml（本文实测版本，含健康检查与网络别名）：

name: meshcentral-1.3.1-stack
services:
  meshcentral:
    image: ghcr.io/ylianst/meshcentral:1.3.1
    container_name: meshcentral-1.3.1-server
    restart: unless-stopped
    environment:
      - HOSTNAME=meshcentral.lab.local
      - ALLOW_NEW_ACCOUNTS=true
    ports:
      - "8131:443"
      - "8133:80"
    healthcheck:
      test: ["CMD", "curl", "-k", "--fail", "https://localhost:443/health.ashx"]
      interval: 30s
      timeout: 5s
      start_period: 30s
      retries: 3
    volumes:
      - /opt/meshcentral/data:/opt/meshcentral/meshcentral-data
      - /opt/meshcentral/files:/opt/meshcentral/meshcentral-files
      - /opt/meshcentral/backups:/opt/meshcentral/meshcentral-backups
      - /opt/meshcentral/web:/opt/meshcentral/meshcentral-web
    networks:
      meshcentral-1.3.1-net:
        aliases:
          - meshcentral.lab.local
networks:
  meshcentral-1.3.1-net:
    name: meshcentral-1.3.1-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.65.0/24

编排要点：

HOSTNAME=meshcentral.lab.local：期望的证书名称。注意：该环境变量只在 DYNAMIC_CONFIG=true 时生效，默认（false）下以 config.json 的 settings.cert 为准——本文在 4.5 节实测了这一点，并演示了正确的调整方式；
ALLOW_NEW_ACCOUNTS=true：允许在登录页注册账号（首台服务器需要用它注册第一个管理员；生产收敛后可改回 false 并改由管理员手工建账号）；
healthcheck：官方推荐的健康检查命令，curl -k 忽略自签名证书访问 /health.ashx，正常时返回 ok；
aliases: meshcentral.lab.local：让同网络内的受管设备直接按证书名称解析到服务端，避免「证书名与连接地址不一致」的告警。

4.3 启动服务并解读首启日志

docker compose up -d

实测输出：

[+] Running 2/2
 ✔ Network meshcentral-1.3.1-net  Created
 ✔ Container meshcentral-1.3.1-server  Started

首启日志（docker compose logs meshcentral，实测逐行，按出现顺序）：

NodeJS: v24.22.1
NPM: 11.19.1
Tue Oct 27 07:15:30 UTC 2026
Config file: /opt/meshcentral/meshcentral-data/config.json
Placing template into the relevant directory: /opt/meshcentral/meshcentral-data
Leaving config as-is. Dynamic Configuration is off.
MeshCentral HTTP redirection server running on port 80.
Generating certificates, may take a few minutes...
Generating root certificate...
Generating HTTPS certificate...
Generating MeshAgent certificate...
Generating code signing certificate...
Generating Intel AMT MPS certificate...
MeshCentral v1.3.1, Hybrid (LAN + WAN) mode, Production mode.
Downloading 31 default agent files (119 MiB) from GitHub releases...
Default agent downloads are still running. Starting without them; they load when they finish.
MeshCentral Intel(R) AMT server running on myserver.mydomain.com:4433.
Server has no users, next new account will be site administrator.
MeshCentral HTTPS server running on myserver.mydomain.com:443.

逐行解读：

Placing template into the relevant directory：首次启动把官方 config.json 模板写入 data 目录（Leaving config as-is 表示之后不再改写，一切以该文件为准）；
Generating certificates：生成五套自签名证书/密钥（根证书、HTTPS、Agent、代码签名、AMT MPS），全部落在 data 目录；
Hybrid (LAN + WAN) mode：默认混合模式，局域网与公网设备均可接入；
Downloading 31 default agent files (119 MiB)：后台从 GitHub 下载各平台 Agent 二进制（见 4.6 节与第十一章问题 1）；
Server has no users, next new account will be site administrator：数据库还没有账号，注册的第一个账号自动成为站点管理员——这是初始化的关键机制；
MeshCentral HTTPS server running on myserver.mydomain.com:443：当前证书名称仍是 config.json 模板默认值 myserver.mydomain.com（因为 DYNAMIC_CONFIG=false 时 HOSTNAME 环境变量不写入 config.json，见 4.5 节）。

验证服务就绪：

curl -sk https://localhost:8131/health.ashx

实测输出：

ok

curl -sI http://localhost:8133/

实测输出（HTTP 端口 302 跳转 HTTPS）：

HTTP/1.1 302 Found
strict-transport-security: max-age=60000; includeSubDomains
Referrer-Policy: no-referrer
x-frame-options: SAMEORIGIN

稍候片刻，健康检查转为 healthy：

docker compose ps

实测输出：

NAME                       IMAGE                               COMMAND                  SERVICE       CREATED         STATUS                   PORTS
meshcentral-1.3.1-server   ghcr.io/ylianst/meshcentral:1.3.1   "/bin/bash /opt/mesh…"   meshcentral   6 minutes ago   Up 6 minutes (healthy)   0.0.0.0:8133->80/tcp, [::]:8133->80/tcp, 0.0.0.0:8131->443/tcp, [::]:8131->443/tcp

4.4 注册站点管理员

方式一（Web 登录页）：浏览器打开 https://<服务器地址>:8131/，切换到「创建账号」（Create Account）表单，填写用户名/邮箱/密码提交。前提是允许注册：首启模板中 domains.""."NewAccounts": true 已默认开启（且当前无任何账号），或编排里设置了 ALLOW_NEW_ACCOUNTS=true。

方式二（命令行模拟注册请求，本文实测）：注册请求是提交到站点根路径的表单：

curl -sk -X POST https://localhost:8131/ \
  -d 'action=createaccount&username=admin&email=admin@example.com&password1=q1w2e3r4&password2=q1w2e3r4' \
  -o /dev/null -w '%{http_code}\n'

实测输出：

验证账号已创建且为站点管理员（查看内置数据库记录）：

grep -o '"_id":"user//admin".{0,80}' /opt/meshcentral/data/meshcentral.db

实测输出（siteadmin: 4294967295 即 0xFFFFFFFF 全量管理员权限）：

"_id":"user//admin","name":"admin","email":"admin@example.com","creation":1793086235,...,"siteadmin":4294967295,...

用浏览器以 admin / q1w2e3r4 登录 https://<服务器地址>:8131/ 即进入管理台。注意：第一个账号注册完成后，后续新账号不再自动获得管理员权限；生产环境建议注册完成后将编排中 ALLOW_NEW_ACCOUNTS 改回 false 并重建服务，后续账号由管理员在「我的账号 → 用户」中手工创建。

4.5 调整证书名称（环境变量不生效的正确处理）

把 config.json 中默认的证书名称改成规划的 meshcentral.lab.local：编辑 /opt/meshcentral/data/config.json，将 settings.cert 的值由 myserver.mydomain.com 改为 meshcentral.lab.local，然后重启服务端：

docker compose restart meshcentral

重启日志（实测，关键行）：

Config file: /opt/meshcentral/meshcentral-data/config.json
Pre-existing config found, not recreating...
Leaving config as-is. Dynamic Configuration is off.
MeshCentral HTTP redirection server running on port 80.
Error: meshcentral.lab.local does not match name in TLS certificate: myserver.mydomain.com, localhost
Generating certificates, may take a few minutes...
Generating HTTPS certificate...
Generating code signing certificate...
Generating Intel AMT MPS certificate...
MeshCentral v1.3.1, Hybrid (LAN + WAN) mode, Production mode.
MeshCentral Intel(R) AMT server running on meshcentral.lab.local:4433.
Server has no users, next new account will be site administrator.
MeshCentral HTTPS server running on meshcentral.lab.local:443.

三个实测结论：

HOSTNAME 环境变量在默认配置下不生效：日志 Leaving config as-is. Dynamic Configuration is off.——官方镜像约定 DYNAMIC_CONFIG=true 才由环境变量自动改写 config.json；默认 false 表示「用你自己的 config.json」，证书名称必须改文件本身；
证书按需重新生成：检测到 settings.cert 与现有证书名不匹配（日志中的 Error: 行是提示而非致命错误），自动重签 HTTPS、代码签名、AMT MPS 三套证书；根证书与 Agent 证书不重新生成，因此已部署的 Agent 不受影响；
用 OpenSSL 确认新证书（issuer 仍为自建根 CA，有效期特征为 2018-01-01 至 2049-12-31 的固定长周期）：

openssl x509 -in /opt/meshcentral/data/webserver-cert-public.crt -noout -subject -issuer -dates

实测输出：

subject=CN = meshcentral.lab.local
issuer=CN = MeshCentralRoot-ed6d4c, O = unknown, C = unknown
notBefore=Jan  1 00:00:00 2018 GMT
notAfter=Dec 31 00:00:00 2049 GMT

4.6 受管设备纳管：Agent 安装上线实测

MeshCentral 通过安装在受管设备上的 MeshAgent 主动回连服务端完成纳管。以下在另一台 Linux x86-64 设备（Ubuntu 22.04，与服务器网络可达）上实测完整流程。

第一步：创建设备组。 在管理台「我的设备 → 新建设备组」创建（本文用命令行工具 meshctrl 实测，工具详解见本专栏《MeshCentral 命令行工具 meshctrl 实战》）：

$ meshctrl AddDeviceGroup --name "Servers" --url wss://<服务器地址>:8131 --loginuser admin --loginpass q1w2e3r4 --tlsinvalidcert
ok mesh//63Ruxn8h@c1xTJggJ@EagxbDB05$Zx@0mFg03p4$UXtSp99mA1InZ$V3ZmrLYo2s

第二步：下载 Agent 二进制。 服务端首启已缓存 31 个平台的 Agent 文件（data 目录 agentbuilds/legacy-1.2.6/），可在管理台设备组的「Add Agent」面板按平台下载；命令行等价方式（--type 6 为 Linux x86-64）：

$ meshctrl AgentDownload --id '63Ruxn8h@c1xTJggJ@EagxbDB05$Zx@0mFg03p4$UXtSp99mA1InZ$V3ZmrLYo2s' --type 6 --url wss://<服务器地址>:8131 --loginuser admin --loginpass q1w2e3r4 --tlsinvalidcert
Downloaded 3757520 byte(s) to "meshagent"

第三步：获取组配置文件（.msh）。 Agent 需要一个与二进制同目录、同名的 .msh 配置文件（即 meshagent.msh），内容可从服务端获取（把设备组 ID 做 URL 编码后请求 /meshsettings）：

curl -sk "https://<服务器地址>:8131/meshsettings?id=<设备组ID>" | grep -E '^(Mesh|Server)'

实测输出（核心五行，MeshServer 即证书名称对应的连接地址）：

MeshName=Servers
MeshType=2
MeshID=0xEB746EC67F21F9CD714C982027E11A8316C3074E7F671FB4985834DE9E3F517B52A7DF6603522767F577666ACB628DAC
ServerID=D0E8C9F216DB7483BF39CC2E79D92584A01FE1E4656BD63F0ED69850573CE011853891269F32F5B690E2FE17ED5624B6
MeshServer=wss://meshcentral.lab.local:443/agent.ashx

💡 说明：MeshServer 的主机名来自 config.json 的证书名称。这就是 4.2 节给服务端加网络别名 meshcentral.lab.local 的原因——受管设备按证书名称解析并连接，证书校验才能通过。生产环境用公网域名时无此顾虑；纯内网环境可用 DNS/hosts 把证书名解析到服务器。

第四步：设备侧启动 Agent。 把 meshagent 与 meshagent.msh 放到受管设备同一目录并启动：

chmod +x meshagent
./meshagent

缺 .msh 文件时 Agent 会明确提示（实测回显）：

Generating Certificate...
No MeshCentral settings found, place .msh file with this executable and restart.

第五步：确认上线并验证远程控制。 设备上线后在管理台「我的设备」中即时可见（在线状态、公网/内网 IP、平台信息）；命令行确认（conn=1 表示 Agent 通道在线）：

$ meshctrl ListDevices --url wss://<服务器地址>:8131 --loginuser admin --loginpass q1w2e3r4 --tlsinvalidcert

Device group: "Servers"
id, name, icon, conn, pwr
-------------------------
"yKZPga93o4M2Iaez2l8HpcOfgCvtMc4MyusxgsF$$RbgN53pskrMJxAowJPQYPP2", "af3c30214b67", 8, 1, 1

在设备上远程执行命令验证（实测回显为受管设备真实输出）：

$ meshctrl RunCommand --id 'yKZPga93o4M2Iaez2l8HpcOfgCvtMc4MyusxgsF$$RbgN53pskrMJxAowJPQYPP2' \
    --run 'hostname && uname -r && head -2 /etc/os-release' --reply \
    --url wss://<服务器地址>:8131 --loginuser admin --loginpass q1w2e3r4 --tlsinvalidcert
af3c30214b67
7.0.0-38-generic
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

远程终端、远程桌面、文件传输等交互功能在管理台该设备的右侧操作面板中直接使用。服务端重启期间已上线设备会自动重连（本文重建服务端后实测 Agent 自动恢复 conn=1），无需设备侧重装 Agent。

五、数据持久化

MeshCentral 无外部数据库时（默认内置 NeDB），全部状态都在 data 目录，本文逐项确认的落盘清单：

/opt/meshcentral/data/
├── config.json                     # 主配置文件（首启生成的官方模板，后续手工维护）
├── meshcentral.db                  # 内置数据库：账号、设备组、设备等核心数据
├── meshcentral-events.db           # 事件流水
├── meshcentral-power.db            # 设备电源状态
├── meshcentral-stats.db            # 统计数据
├── serverstate.txt                 # 服务端运行状态
├── root-cert-public.crt / root-cert-private.key        # 自建根 CA（签发下面四套证书）
├── webserver-cert-public.crt / webserver-cert-private.key   # HTTPS 证书
├── agentserver-cert-public.crt / agentserver-cert-private.key  # Agent 接入证书
├── codesign-cert-public.crt / codesign-cert-private.key     # Agent 代码签名证书
├── mpsserver-cert-public.crt / mpsserver-cert-private.key   # Intel AMT MPS 证书
├── agentbuilds/legacy-1.2.6/       # 31 个平台的 Agent 二进制缓存（119 MiB）+ SHA256SUMS
└── signedagents/                   # 用代码签名证书签好名的 Windows Agent（MeshService64.exe 等 6 个）

要点：

备份 data 目录 = 备份整个 MeshCentral：账号、设备关系、证书、组配置全在其中；files/（传输/录像）与 backups/（数据库自动备份）按需纳入。本文编排用宿主目录 bind mount，直接 cp -a 即可备份；
换服务器迁移：停服务 → 拷贝整个 data 目录 → 新服务器启动，Agent 凭证书与 .msh 中的 ServerID 自动回连；
内置 NeDB 适合中小规模（数百台设备）；规模更大或需要多实例共享数据时，通过环境变量切换 MongoDB/PostgreSQL/MariaDB（见第六章），数据仍在 data 目录的机制不变，由外部数据库承接主数据。

六、环境变量表

官方镜像通过环境变量控制配置。实测关键约定：DYNAMIC_CONFIG=false（默认）时，下表绝大多数变量不会写入 config.json，仅作为参数传入服务进程；想「环境变量全权管理配置」需设 DYNAMIC_CONFIG=true。本文默认值全部来自官方 docker/README.md（查询日期 2026-10-27）。

6.1 通用变量

环境变量	默认值	说明
`DYNAMIC_CONFIG`	`false`	false=使用 data 目录中的 config.json（模板仅首启生成）；true=由以下环境变量动态生成配置
`CONFIG_FILE`	`/opt/meshcentral/meshcentral-data/config.json`	配置文件路径
`HOSTNAME`	`localhost`	证书名称（仅 DYNAMIC_CONFIG=true 时写入 config.json 的 settings.cert）
`PORT` / `REDIR_PORT`	`443` / `80`	HTTPS 端口 / HTTP 重定向端口
`NODE_ENV`	`production`	运行模式
`ARGS`	空	追加 MeshCentral 命令行参数，如 `--cert=meshcentral.lab.local`
`ALLOW_NEW_ACCOUNTS`	`false`	允许登录页注册新账号（映射 domains.NewAccounts）
`ALLOW_PLUGINS`	`false`	启用插件系统
`MINIFY`	`true`	Web 界面启用压缩版前端资源
`ALLOWED_ORIGIN` / `REVERSE_PROXY` / `REVERSE_PROXY_TLS_PORT`	`false` / 空 / `443`	反向代理场景：跨域来源、代理地址与对外 TLS 端口
`IFRAME` / `WEBRTC` / `TLS_OFFLOAD` / `TRUSTED_PROXY`	`false`	iframe 嵌入、WebRTC 通道、TLS 卸载、可信代理
`LOCAL_SESSION_RECORDING`	`true`	本地会话录像
`REGEN_SESSIONKEY`	`false`	重启时重新生成会话加密密钥（会使已有会话失效）
`SESSION_KEY`	空	显式指定会话加密密钥（多实例共享时使用）

6.2 数据库变量

环境变量	说明
`USE_MONGODB` / `USE_POSTGRESQL` / `USE_MARIADB`	设为 `true` 启用对应外部数据库，默认 `false`（内置 NeDB）
`MONGO_URL`	MongoDB 连接串，如 `mongodb://user:pass@host:27017/meshcentral`
`MONGO_HOST` / `MONGO_PORT` / `MONGO_USERNAME` / `MONGO_PASS`	MongoDB 分项连接参数
`PSQL_HOST` / `PSQL_PORT` / `PSQL_USER` / `PSQL_PASS` / `PSQL_DATABASE`	PostgreSQL 连接参数
`MARIADB_HOST` / `MARIADB_PORT` / `MARIADB_USER` / `MARIADB_PASS` / `MARIADB_DATABASE`	MySQL/MariaDB 连接参数

6.3 健康检查与构建参数

健康检查命令（官方推荐，本文 4.2 编排已实测 healthy）：curl -k --fail https://localhost:443/health.ashx；
自定义构建镜像时可用构建参数：DISABLE_MINIFY、DISABLE_TRANSLATE、INCLUDE_MONGODB_TOOLS、INCLUDE_POSTGRESQL_TOOLS、INCLUDE_MARIADB_TOOLS、PREINSTALL_LIBS。

七、配置参数说明

DYNAMIC_CONFIG=false 时一切以 data 目录的 config.json 为准。首启生成的官方模板（本文实测内容）结构如下，_ 前缀键是未启用的注释项（MeshCentral 用该约定代替 JSON 注释，去掉下划线即生效）：

{
  "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
  "settings": {
    "plugins": { "enabled": false },
    "cert": "meshcentral.lab.local",
    "_WANonly": true,
    "_LANonly": true,
    "_sessionKey": "MyReallySecretPassword1",
    "port": 443,
    "_aliasPort": 443,
    "redirPort": 80,
    "_redirAliasPort": 80,
    "AgentPong": 300,
    "tlsOffload": false,
    "_trustedProxy": "",
    "SelfUpdate": false,
    "AllowFraming": false,
    "WebRTC": false,
    "_mongoDb": "",
    "_postgres": { "host": "", "port": "", "user": "", "password": "", "database": "" },
    "_mariaDB": { "host": "", "port": "", "user": "", "password": "", "database": "" }
  },
  "domains": {
    "": {
      "_title": "MyServer",
      "_title2": "Servername",
      "minify": false,
      "NewAccounts": true,
      "localSessionRecording": true,
      "_userNameIsEmail": true,
      "_certUrl": "my.reverse.proxy",
      "allowedOrigin": false
    }
  },
  "_letsencrypt": {
    "_email": "myemail@mydomain.com",
    "_names": "myserver.mydomain.com",
    "production": false
  }
}

默认已生效键的实测语义：

settings.cert：证书名称与对外服务名（4.5 节实测修改后自动重签证书）；
settings.port / settings.redirPort：HTTPS 与 HTTP 重定向监听端口；
settings.AgentPong：Agent 心跳间隔（秒，默认 300）；
settings.AllowFraming: false：禁止页面被 iframe 嵌套（防点击劫持）；
settings.SelfUpdate: false：关闭自更新（容器部署下更新走「拉新镜像重建」）；
domains.""：默认域名站点配置；NewAccounts: true 允许登录页注册（4.4 节管理员注册依赖它）；localSessionRecording: true 设备侧保留会话录像；
_letsencrypt 整段为注释状态：去掉 _ 前缀、填入邮箱与域名即可启用 Let's Encrypt 自动证书（需 80 端口可达）。

完整的逐参数详解（含 SMTP 邮件、双因素认证、多域名、外部数据库调优等）见本专栏《MeshCentral 配置参数详解》。

八、配置文件挂载

config.json 通过 data 目录的 bind mount 直接暴露在宿主机：

vi /opt/meshcentral/data/config.json
docker compose restart meshcentral

实测注意事项：

服务端不会改写该文件（Leaving config as-is），手工编辑安全；但不要在服务端运行时期望环境变量改动同步进来（默认模式不生效，见 4.5 节）；
修改后必须重启生效；涉及证书名称的修改会触发证书重签（4.5 节实测），涉及端口的修改需同步调整编排端口映射；
$schema 键指向官方 JSON Schema，编辑器（VS Code 等）可据此获得参数补全与校验；
若选择 DYNAMIC_CONFIG=true，则由第六章环境变量在每次启动时动态生成配置，两种模式二选一，不要混用。

九、等价 docker run 命令

与本文编排等价的单命令形态（便于理解各参数含义）：

docker run -d \
  --name meshcentral-1.3.1-server \
  --restart unless-stopped \
  -p 8131:443 -p 8133:80 \
  -e HOSTNAME=meshcentral.lab.local \
  -e ALLOW_NEW_ACCOUNTS=true \
  -v /opt/meshcentral/data:/opt/meshcentral/meshcentral-data \
  -v /opt/meshcentral/files:/opt/meshcentral/meshcentral-files \
  -v /opt/meshcentral/backups:/opt/meshcentral/meshcentral-backups \
  -v /opt/meshcentral/web:/opt/meshcentral/meshcentral-web \
  --network meshcentral-1.3.1-net \
  --network-alias meshcentral.lab.local \
  ghcr.io/ylianst/meshcentral:1.3.1

与编排的差异：docker run 无法自动创建网络与别名记录到编排清单、无健康检查（需另配 --health-cmd 等参数），长期维护仍建议使用 Compose。

十、常用运维命令

# 状态与健康（STATUS 列显示 healthy 才算真正就绪）
cd /opt/meshcentral && docker compose ps

# 实时日志（关注证书重签、Agent 下载、账号注册事件）
docker compose logs -f meshcentral

# 修改 config.json 后重启生效
docker compose restart meshcentral

# 升级版本：改 docker-compose.yml 中镜像标签后
docker compose pull && docker compose up -d

# 备份核心数据（停服冷备最稳妥；热备至少备份 data 目录）
docker compose stop meshcentral
tar czf meshcentral-data-$(date +%F).tar.gz data/
docker compose start meshcentral

健康状态单查：

docker inspect meshcentral-1.3.1-server --format '{{.State.Health.Status}}'

实测输出：

healthy

十一、常见问题

11.1 首启日志出现 GitHub 下载 Agent 超时 WARNING

实测回显：

WARNING: Unable to download the 31 default agent files from GitHub: Connection timed out. Retrying in the background. On a server without internet access, download them from https://github.com/Ylianst/MeshAgent/releases/tag/legacy-1.2.6 and https://github.com/Ylianst/MeshCentralAndroidAgent/releases/tag/legacy-1.2.6 into "/opt/meshcentral/meshcentral-data/agentbuilds/legacy-1.2.6".

不影响服务启动，服务端会在后台自动重试（本文实测重试成功，后续日志出现 Default agent files downloaded, loading them.）。完全离线的服务器按官方日志给出的离线路径：从 MeshAgent 的 legacy-1.2.6 Release 下载各平台 Agent 放入 data/agentbuilds/legacy-1.2.6/（附官方 SHA256SUMS 可校验），重启服务端即加载。

11.2 HOSTNAME 环境变量没有生效

DYNAMIC_CONFIG=false（默认）时证书名称只认 config.json 的 settings.cert。处理：直接改 config.json 后重启（4.5 节实测），或在编排中设 DYNAMIC_CONFIG=true 改用环境变量管理模式。

11.3 重启日志出现 "Error: xxx does not match name in TLS certificate"

这是改了 settings.cert 后的预期提示行：服务端检测到证书名与新配置不符，随后自动重签 HTTPS/代码签名/AMT MPS 三套证书（根证书不变，已上线 Agent 不受影响，4.5 节实测）。确认日志末尾 MeshCentral HTTPS server running on <新名称>:443 即成功。

11.4 错过了第一个账号的注册，第二个账号不是管理员

只有数据库中第一个注册的账号自动成为站点管理员（日志 Server has no users, next new account will be site administrator）。若已错过且无管理员可用：停止服务端，删除 data 目录中的 meshcentral.db 等内置数据库文件后重启，重新注册（会丢失账号与设备分组关系，仅限初始化阶段使用）。

11.5 Agent 装好后一直不在线

按顺序排查：① 受管设备能否解析 MeshServer 中的主机名（.msh 来自证书名称，内网需 DNS/hosts 或服务端网络别名，见 4.6 节）；② 服务端 443（或映射端口）是否可达；③ 服务端日志是否有 Agent 接入记录；④ 设备侧直接前台运行 ./meshagent 观察输出；⑤ 确认 .msh 与二进制同目录同名（缺 .msh 时 Agent 提示 No MeshCentral settings found）。

11.6 健康检查一直 unhealthy

编排的健康检查命令 curl -k --fail https://localhost:443/health.ashx 在服务端内部执行：确认没有改过 settings.port（默认 443）；镜像内自带 curl 无需额外安装；首启证书生成需数秒到数十秒，start_period 不要小于 30 秒。手动在服务端内验证：docker compose exec meshcentral curl -k https://localhost:443/health.ashx，正常返回 ok。

十二、参考链接

《MeshCentral 1.3.1 介绍与选型指南》（本专栏）
MeshCentral GitHub 仓库：https://github.com/Ylianst/MeshCentral
官方容器部署文档（docker/README.md，环境变量与镜像变体来源）：https://github.com/Ylianst/MeshCentral/blob/master/docker/README.md
config.json 官方 Schema：https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json
Agent 离线包（legacy-1.2.6 Release）：https://github.com/Ylianst/MeshAgent/releases/tag/legacy-1.2.6
官方 Wiki（安装与配置文档入口）：https://github.com/Ylianst/MeshCentral/wiki

MeshCentral 1.3.1 服务端 Docker Compose 部署指南

MeshCentral 1.3.1 服务端 Docker Compose 部署指南

一、环境信息

二、镜像选型说明

2.1 镜像变体

2.2 标签策略

三、前置条件

四、部署步骤

4.1 准备编排目录与数据目录

4.2 编写编排文件

4.3 启动服务并解读首启日志

4.4 注册站点管理员

4.5 调整证书名称（环境变量不生效的正确处理）

4.6 受管设备纳管：Agent 安装上线实测

五、数据持久化

六、环境变量表

6.1 通用变量

6.2 数据库变量

6.3 健康检查与构建参数

七、配置参数说明

八、配置文件挂载

九、等价 docker run 命令

十、常用运维命令

十一、常见问题

11.1 首启日志出现 GitHub 下载 Agent 超时 WARNING

11.2 HOSTNAME 环境变量没有生效

11.3 重启日志出现 "Error: xxx does not match name in TLS certificate"

11.4 错过了第一个账号的注册，第二个账号不是管理员

11.5 Agent 装好后一直不在线

11.6 健康检查一直 unhealthy

十二、参考链接