MeshCentral 命令行工具 meshctrl 实战

目标：掌握 MeshCentral 官方命令行工具 meshctrl 的获取安装、连接方式与核心动作，覆盖账号管理、设备组管理、Agent 分发、远程命令执行、事件审计等运维场景。本文全部命令与回显均在 MeshCentral 1.3.1 服务端环境实测通过（实测日期 2026-10-27），未实测的动作仅给出官方帮助原文并明确标注。服务端部署见《MeshCentral 1.3.1 服务端 Docker Compose 部署指南》。

一、环境信息

• MeshCentral 服务端：1.3.1（Docker Compose 部署，HTTPS 端口映射 8131→443，证书名称 meshcentral.lab.local）
• meshctrl 来源：随 1.3.1 服务端镜像分发的 meshctrl.js（单文件 Node.js 脚本）
• 执行环境：Ubuntu 22.04 LTS（x86_64），Node v22+（宿主机自带 Node.js 环境）
• 依赖：minimist、ws、https 三个 npm 包（首次使用需安装，见 4.1 节）
• 实测账号：admin（站点管理员）；工具用途验证命令均以该账号登录

二、工具概览

meshctrl 是 MeshCentral 官方维护的单文件命令行管理客户端：以 WebSocket（wss）通道登录服务端，把 Web 管理台的管理能力开放给脚本与自动化。它与 MeshCentral 同仓库发布（服务端镜像内自带），无需在服务端安装任何东西——任何能访问服务端 HTTPS 端口的机器上装好 Node.js 与三个依赖包即可使用。

实测 meshctrl --help 的完整动作清单（按用途分组）：

登录参数全局通用（见 4.2 节）。MeshCentral 另有一个面向受管设备侧的工具 MeshCmd（Windows 可执行文件，服务端首启缓存在 data 目录 agentbuilds/legacy-1.2.6/），用于在设备上做辅助诊断，与本文的服务端管理定位不同，不展开。

三、前置条件

1. MeshCentral 服务端已部署且 HTTPS 端口可达（本文 wss://<服务器地址>:8131）；
2. 执行机有 Node.js（v16+ 均可，本文用镜像同代运行时验证）与 npm；
3. 一个可登录的管理员账号（或具备相应权限的受限账号；本文实测均用站点管理员）。

四、各工具详解

4.1 获取与安装

方式一：从服务端镜像/安装目录提取（版本与服务器严格一致，推荐）。 服务端镜像内自带：

docker cp meshcentral-1.3.1-server:/opt/meshcentral/meshcentral/meshctrl.js .
mkdir -p meshctrl-lib && mv meshctrl.js meshctrl-lib/ && cd meshctrl-lib
npm install minimist ws https

实测安装输出（节选）：

added 3 packages in 5s
1 package is looking for funding
  run `npm fund` for details

方式二：从 GitHub 仓库主分支直接下载（版本可能与服务器不一致，升级频繁时注意）：

curl -LO https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshctrl.js

💡 说明：npm 上没有 meshctrl 包（实测 npm install meshctrl 返回 404），不要按包名安装。非 Windows 平台还需三个依赖包；Windows 下 MeshCentral 安装包自带可双击版本。

验证安装（不联网也会打印帮助）：

$ node meshctrl.js --help
MeshCtrl performs command line actions on a MeshCentral server.
Information at: https://meshcentral.com
No action specified, use MeshCtrl like this:

  meshctrl [action] [arguments]

4.2 连接与登录参数

每个动作后都可附加以下登录参数（下文示例统一省略为「<登录参数>」，即 --url wss://localhost:8131 --loginuser admin --loginpass q1w2e3r4 --tlsinvalidcert）：

--url [wss://server]        - 服务端地址，默认 wss://localhost:443
--loginuser [username]      - 登录用户名，默认 admin
--loginpass [password]      - 登录密码，留空则在终端交互输入
--token [number]            - 双因素认证令牌
--loginkey [hex]            - 服务器登录密钥（启用 loginKey 的站点）
--logindomain [domainid]    - 多域名站点的域 ID
--proxy [http://proxy:123]  - 经 HTTP 代理连接

自签名证书的站点（默认部署形态）必须加 --tlsinvalidcert 跳过证书校验，否则连接被拒。

实测确认的三条调用约定：

1. 动作名必须是第一个参数：meshctrl ServerInfo --url ... 正确；把动作写到选项后面（如 meshctrl --url ... ServerInfo）会打印帮助并提示 No action specified（实测踩坑）；
2. 参数名区分大小写且必须小写：实测 --LoginUser/--LoginPass 会被忽略，返回 Invalid login.；正确写法 --loginuser/--loginpass；
3. 免交互三种姿势（编写脚本推荐）：环境变量 MESHCTRL_URL、MESHCTRL_LOGINUSER、MESHCTRL_LOGINPASS、MESHCTRL_TOKEN；或配置文件 ~/.config/meshctrl/config.json：

{ "url": "wss://server:8131", "loginuser": "admin", "loginpass": "..." }

帮助原文明确优先级：命令行参数 > 环境变量 > 配置文件。

4.3 服务器与账号管理

ServerVersion / ServerInfo（连通性与版本确认）：

$ meshctrl ServerVersion <登录参数>
MeshCentral version: 1.3.1 (latest: 1.3.1) (stable: 1.3.1)

$ meshctrl ServerInfo <登录参数>
domain:
name: meshcentral.lab.local
mpsname: meshcentral.lab.local
mpsport: 4433
port: 443
emailcheck: false
domainauth: false
serverTime: 1793086356830
features: 1186336
features2: 129
...
tlshash: F0436703C2117C16191A13B82CA0AA30D51AE8C9FAFA7DC77D6B120B7B2CC05B2219D9581670114093488AEEA511FB97
agentCertHash: 0OjJ8hbbdIO$OcwuedklhKAf4eRla9Y$DtaYUFc84BGFOJEmnzL1tpDi$hftViS2
https: true
redirport: 80

UserInfo（当前登录账号与权限，siteadmin: 4294967295 即全量管理员）：

$ meshctrl UserInfo <登录参数>
_id: user//admin
name: admin
email: admin@example.com
creation: 1793086235
login: 1793086327
access: 1793086636
siteadmin: 4294967295
pastlogin: 1793086235
links: {
  'mesh//63Ruxn8h@c1xTJggJ@EagxbDB05$Zx@0mFg03p4$UXtSp99mA1InZ$V3ZmrLYo2s': { rights: 4294967295 }

AddUser / ListUsers / RemoveUser（账号生命周期，全部实测）：

$ meshctrl AddUser --user testuser --pass 'T3st!pass2026' <登录参数>
ok

$ meshctrl ListUsers <登录参数>
id, name, email
---------------
"admin", "admin", "admin@example.com"
"testuser", "testuser"

删除账号的参数是 --userid（实测 --id 会报错 Remove account userid missing, use --userid [id]）：

$ meshctrl RemoveUser --userid testuser <登录参数>
ok

$ meshctrl ListUsers <登录参数>
id, name, email
---------------
"admin", "admin", "admin@example.com"

ListUserSessions（在线会话，实测）：

$ meshctrl ListUserSessions <登录参数>
user//admin, 1 session.

LoginTokens（API 化登录令牌，实测完整生命周期）：

$ meshctrl LoginTokens --add clitoken <登录参数>
New login token created.
Token name: clitoken
Created: 10/27/2026, 3:54:50 PM
Username: ~t:ym7T8ZpDBBUrhX5s
Password: l8PFQigbxcGCUUJk1qZD

$ meshctrl LoginTokens <登录参数>
Name                        Username                    Expire
-------------------------------------------------------------------------------------
clitoken                    ~t:ym7T8ZpDBBUrhX5s         Unlimited

删除令牌必须用 ~t: 开头的令牌用户名（实测用令牌名 --remove clitoken 无效，令牌仍在；用 --remove '~t:ym7T8ZpDBBUrhX5s' 成功）：

$ meshctrl LoginTokens --remove '~t:ym7T8ZpDBBUrhX5s' <登录参数>
Name                        Username                    Expire
-------------------------------------------------------------------------------------
No login tokens

💡 说明：令牌用户名/密码等价于账号密码（用户名以 ~t: 前缀区分），适合给自动化脚本发独立凭据并单独吊销；--expire [分钟] 可设有效期，--json 输出 JSON。

4.4 设备组管理

AddDeviceGroup / ListDeviceGroups（实测）：

$ meshctrl AddDeviceGroup --name "Servers" <登录参数>
ok mesh//63Ruxn8h@c1xTJggJ@EagxbDB05$Zx@0mFg03p4$UXtSp99mA1InZ$V3ZmrLYo2s

$ meshctrl ListDeviceGroups <登录参数>
id, name
---------------
"63Ruxn8h@c1xTJggJ@EagxbDB05$Zx@0mFg03p4$UXtSp99mA1InZ$V3ZmrLYo2s", "Servers"

注意两种 ID 形态：AddDeviceGroup 返回带 mesh// 前缀的完整标识；后续动作（AgentDownload、GenerateInviteLink 等）用的是引号内的短 ID（实测用完整 mesh// 前缀调用 AgentDownload 会报 Invalid meshid.）。

GenerateInviteLink（生成限时安装邀请链接，实测）：

$ meshctrl GenerateInviteLink --group "Servers" --hours 24 <登录参数>
https://meshcentral.lab.local:443/agentinvite?c=g2IO5KTEPAx4DkW$QpIb4zfWHA$JIJx0B2qLdsjUzyCrqEcMLIULFmcY1xMcViUQdZPOJaMw987BNgaHuDgY1VE@nPjSZUuzwlSFiwKoJVxCPasmT3$BbWTQcMNNO0xUwMZEWSyYhqjdNarRvAnSiZ7JtoWm1AYpfxshBY9cyB3WPPtRi@BCVeuCAFER23uhYF946xt7sr4=

被邀请设备打开该链接即进入对应平台的 Agent 下载与安装引导；--hours 0 表示永久有效。成员管理类动作（AddUserToDeviceGroup、ListUsersOfDeviceGroup 等）用法同前，帮助可用 meshctrl Help <动作> 随时查看。

4.5 设备纳管与 Agent 分发

ListDevices（设备清单，实测；conn=1 表示 Agent 通道在线，pwr=1 表示开机状态）：

$ meshctrl ListDevices <登录参数>

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

DeviceInfo（设备详情，实测）：

$ meshctrl DeviceInfo --id 'yKZPga93o4M2Iaez2l8HpcOfgCvtMc4MyusxgsF$$RbgN53pskrMJxAowJPQYPP2' <登录参数>
--- General ---
  Server Name: af3c30214b67
  Computer Name: af3c30214b67
  Hostname: 10.89.65.3
  IP Address: 10.89.65.3
  Icon: 8
--- Operating System ---
  Name: af3c30214b67
  Version: Ubuntu 22.04.5 LTS
  Architecture: x86_64
  Kernel Release: 7.0.0-38-generic
...
--- Mesh Agent ---
  Mesh Agent: Linux 64bit

AgentDownload（按架构分发 Agent 二进制，实测）。架构号官方定义节选（2=Windows x86-64 控制台、4=Windows x86-64 服务、6=Linux x86-64、16=macOS x86-64，完整表见 Help AgentDownload 与官方 agenttypes 定义）：

$ meshctrl AgentDownload --id '63Ruxn8h@c1xTJggJ@EagxbDB05$Zx@0mFg03p4$UXtSp99mA1InZ$V3ZmrLYo2s' --type 6 <登录参数>
Downloaded 3757520 byte(s) to "meshagent"

实测教训：--type 4 下载到的是 Windows 版（meshagent64-Servers.exe，PE32+ 格式）——架构号先查帮助再使用。Linux 设备侧配合 .msh 配置文件即可上线（获取方式与上线步骤见部署指南 4.6 节）。

4.6 远程操作

RunCommand（远程执行 shell 命令，实测；--reply 等待并回传输出，适合脚本采集）：

$ meshctrl RunCommand --id 'yKZPga93o4M2Iaez2l8HpcOfgCvtMc4MyusxgsF$$RbgN53pskrMJxAowJPQYPP2' \
    --run 'hostname && uname -r && head -2 /etc/os-release' --reply <登录参数>
af3c30214b67
7.0.0-38-generic
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

Windows 设备可加 --powershell 以 PowerShell 执行；--runasuser/--runasuseronly 以登录用户身份执行。

交互式/文件类动作（官方帮助原文，本文未逐一实测）：Shell（进入设备命令 shell）、Upload/Download（文件上下行）、WebRelay（生成设备 Web 服务的代理链接）、DeviceOpenUrl、DeviceMessage/DeviceToast/GroupMessage/GroupToast（弹窗与通知）、DevicePower（唤醒/休眠/关机）、Broadcast（向全体在线用户广播）。

4.7 配置与审计

Config（操作 config.json，实测）。注意该动作读写的不是服务端，而是执行命令时工作目录下的 ./meshcentral-data/config.json 本地文件——在 data 目录父目录执行（或建 meshcentral-data 软链指向 data 目录），否则报错：

$ meshctrl Config --show
Unable to find config.json.

软链就绪后实测正常打印 config.json 全文；子动作 --listdomains、--adddomain、--settodomain、--removefromdomain、--removedomain 同样作用于该本地文件，改完需重启服务端生效。

ListEvents（服务器事件审计，实测；--count 控制条数）：

$ meshctrl ListEvents --count 3 <登录参数>
time,type,action,nodeid,userid,msg
"2026-10-27T07:40:46.079Z","user","accountcreate",,"user//testuser","Account created, username is testuser"
"2026-10-27T07:37:39.783Z","node","runcommands","node//yKZPga93o4M2Iaez2l8HpcOfgCvtMc4MyusxgsF$$RbgN53pskrMJxAowJPQYPP2","user//admin","Running commands"
"2026-10-27T07:36:50.943Z","node","addnode",,,"Added device af3c30214b67 to device group Servers"

事件流覆盖账号创建/登录、设备组创建、设备上线、远程命令执行等关键审计点（ShowEvents 为实时滚动版本）。

五、注意事项

1. 动作名必须是第一个参数，选项顺序其后（4.2 节实测）；
2. 参数名一律小写（--loginuser），驼峰写法静默失效返回 Invalid login.（4.2 节实测）；
3. 自签证书站点必加 --tlsinvalidcert；生产建议改用 Let's Encrypt 正式证书后去掉该参数，恢复完整校验；
4. ID 形态对号入座：设备组短 ID、设备 nodeid、令牌用户名（~t:）各动作要求不同，报 Invalid meshid. / userid missing 时先核对 ID 形态（4.4、4.3 节实测）；
5. 凭据安全：命令行密码会进 shell 历史，脚本场景优先用 MESHCTRL_LOGINPASS 环境变量或 ~/.config/meshctrl/config.json（权限设 600），并为自动化单独发 LoginTokens 以便单独吊销；
6. Config 动作是本地文件操作，与 --url 指向的服务端无关，容器部署注意 data 目录的可达路径（4.7 节实测）；
7. 批量操作（如批量建账号）可写循环调用 AddUser；meshctrl 每次 invoke 都建立独立 WebSocket 会话，大规模循环注意节奏。

六、常见问题

6.1 npm install meshctrl 返回 404

meshctrl 不在 npm 上，从服务端镜像/安装目录提取 meshctrl.js 或从 GitHub 仓库下载（4.1 节），并补装三个依赖包。

6.2 报 "Invalid login."

按序排查：参数用了大写（--LoginUser 失效，实测）；密码错误；账号无登录权限；服务端启用了 2FA（需补 --token）。

6.3 报 "No action specified" 并打印帮助

动作名没有放在第一个参数位置，或动作名拼写错误。正确：meshctrl ServerInfo --url ...。

6.4 报 "Unable to find config.json."

Config 动作在当前目录找 ./meshcentral-data/config.json。cd 到数据目录父目录、或建软链后再执行（4.7 节实测）。

6.5 连接不上服务端

确认 --url 是 wss://（不是 https）且端口正确；自签证书加 --tlsinvalidcert；中间有代理时用 --proxy；服务端防火墙放行 HTTPS 端口。

6.6 AgentDownload 下载的不是想要的平台

架构号与直觉不一致（4=Windows 服务版而非 Linux），先 meshctrl Help AgentDownload 查官方架构表再取值（4.5 节实测 6 才是 Linux x86-64）。

七、参考链接

• 《MeshCentral 1.3.1 介绍与选型指南》（本专栏）
• 《MeshCentral 1.3.1 服务端 Docker Compose 部署指南》（本专栏）
• 《MeshCentral 1.3.1 配置参数详解》（本专栏）
• meshctrl.js 源码（GitHub 主分支）：https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshctrl.js
• MeshCentral GitHub 仓库：https://github.com/Ylianst/MeshCentral
• 官方 Wiki（命令行与自动化文档入口）：https://github.com/Ylianst/MeshCentral/wiki