洱海月 MQTT工具命令行使用教程

Waylee · 发表于 2026-7-7 15:50

马上注册,查看网站隐藏内容!!

您需要登录才可以下载或查看，没有账号？register

×

本文说明服务端 gm_tool MQTT 通道的使用方法。示例以 Linux bash 为准。

1. 作用范围

服务端 gm_tool 会连接 MQTT broker，并订阅：

gm_tool/#

外部工具向对应 topic 发布 JSON 消息后，服务端执行 GM 操作，并把处理结果发布到：

原topic/done

例如发布到：

gm_tool/broadcast

处理结果会回到：

gm_tool/broadcast/done

当前网页版 GM 工具走的是 13013/manager HTTP 接口，不走 MQTT。MQTT 是另一套高权限远程 GM 通道。

2. 基础准备

安装命令行工具：

apt install -y mosquitto-clients

设置连接变量：

export MQTT_HOST='127.0.0.1'
export MQTT_PORT='1883'
export MQTT_USER='mqtt_user_9bd3284f'
export MQTT_PASS='替换为实际MQTT密码'

说明：

127.0.0.1 表示当前执行命令的机器。如果在 Windows 执行，它指 Windows 本机；如果 broker 在 Ubuntu 服务器，需要在服务器执行，或把 MQTT_HOST 改成服务器 IP。
普通 MQTT 默认端口是 1883。如果服务端配置 uri = "127.0.0.1" 没写端口，就是连接 127.0.0.1:1883。
示例里的 \ 是 Linux bash 换行符。PowerShell 不能用 \ 换行，PowerShell 要么写成一行，要么用反引号换行。

3. 监听回包

建议先开一个窗口监听所有 GM MQTT 消息：

mosquitto_sub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -v -t 'gm_tool/#'

如果广播命令处理成功，监听窗口会看到类似：

gm_tool/broadcast {"msg":"测试广播"}
gm_tool/broadcast/done {"msg":"测试广播","error":"","result":true}

排查规则：

看不到原 topic：发布命令没发到正确 broker，或账号、密码、端口不对。
能看到原 topic，但没有 /done：gm_tool 服务没启动、没连上 broker，或处理时抛错。
能看到 /done 且 result=true：MQTT 链路已经处理成功；如果游戏里没反应，继续查区服、在线玩家、world 广播。
/done 里 result=false：看 error 字段。

4. 常见 Topic 总览

Topic	功能简述	主要字段
`gm_tool/broadcast`	发送系统广播；不传 `area` 为全服广播	`msg`, `area`
`gm_tool/ban_account`	封禁账号，并踢下该账号角色	`account`
`gm_tool/unban_account`	解封账号	`account`
`gm_tool/ban_mac`	封禁 MAC	`mac`
`gm_tool/unban_mac`	解封 MAC	`mac`
`gm_tool/gm_tool_ban_chat`	禁言角色	`guid`
`gm_tool/gm_tool_unban_chat`	解除角色禁言	`guid`
`gm_tool/update_player_item_count`	给在线玩家更新资源/道具数量	`area`, `guid`, `item_id`, `item_count`
`gm_tool/change_top_point`	修改账号充值点数，可加可扣	`account`, `change_top_point_count`
`gm_tool/unlock_minor_password`	清除角色二级密码	`guid`
`gm_tool/change_account_password`	修改账号密码	`account`, `password`
`gm_tool/change_character_level`	修改角色等级；当前代码字段有疑点，见下文	`guid`, `target_level`, `level`
`gm_tool/limit_account_exchange`	限制账号交易	`account`
`gm_tool/unlimit_account_exchange`	解除账号交易限制	`account`
`gm_tool/add_can_get_award`	写入可领取奖励记录	`guid`, `award_name`, `award_list`
`gm_tool/call_script`	调用在线玩家脚本函数	`area`, `guid`, `script_id`, `func_name`, `params`
`gm_tool/check_password`	校验账号密码	`account`, `password`
`gm_tool/check_super_password`	校验账号超级密码	`account`, `super_password`

5. 命令示例

5.1 全服广播

功能：

向所有 .world 节点发送系统广播。不传 area 时为全服广播。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/broadcast' \
  -m '{"msg":"服务器将于10分钟后维护"}' -q 1

指定区服：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/broadcast' \
  -m '{"area":"Game_tlbb_1","msg":"服务器将于10分钟后维护"}' -q 1

字段说明：

msg：广播内容。
area：可选，指定区服节点名；不传表示全服。

成功回包示例：

{"msg":"服务器将于10分钟后维护","error":"","result":true}

5.2 封禁账号

功能：

封禁账号，并向所有 .gamed 节点发送踢人请求。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/ban_account' \
  -m '{"account":"test001"}' -q 1

字段说明：

account：账号名。

成功回包示例：

{"account":"test001","error":"","result":true}

5.3 解封账号

功能：

把账号状态恢复为正常。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/unban_account' \
  -m '{"account":"test001"}' -q 1

字段说明：

account：账号名。

成功回包示例：

{"account":"test001","error":"","result":true}

5.4 封禁 MAC

功能：

向所有 .logind 节点发送 MAC 封禁。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/ban_mac' \
  -m '{"mac":"AA-BB-CC-DD-EE-FF"}' -q 1

字段说明：

mac：要封禁的 MAC 字符串，格式保持和登录服记录一致。

成功回包示例：

{"mac":"AA-BB-CC-DD-EE-FF","error":"","result":true}

5.5 解封 MAC

功能：

向所有 .logind 节点发送 MAC 解封。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/unban_mac' \
  -m '{"mac":"AA-BB-CC-DD-EE-FF"}' -q 1

字段说明：

mac：要解封的 MAC 字符串，格式保持和登录服记录一致。

成功回包示例：

{"mac":"AA-BB-CC-DD-EE-FF","error":"","result":true}

5.6 禁言角色

功能：

向所有 .gamed 节点发送角色禁言。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/gm_tool_ban_chat' \
  -m '{"guid":123456789}' -q 1

字段说明：

guid：角色 GUID。保持和 .gamed 的 ban_chat 接口需要的格式一致。
注意 topic 名是 gm_tool/gm_tool_ban_chat，不是 gm_tool/ban_chat。

成功回包示例：

{"guid":123456789,"error":"","result":true}

5.7 解除角色禁言

功能：

向所有 .gamed 节点发送解除角色禁言。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/gm_tool_unban_chat' \
  -m '{"guid":123456789}' -q 1

字段说明：

guid：角色 GUID。保持和 .gamed 的 unlock_chat 接口需要的格式一致。
注意 topic 名是 gm_tool/gm_tool_unban_chat，不是 gm_tool/unban_chat。

成功回包示例：

{"guid":123456789,"error":"","result":true}

5.8 更新玩家资源/道具数量

功能：

调用指定在线玩家 agent 的 resource_update，用于增减资源或道具。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/update_player_item_count' \
  -m '{"area":"Game_tlbb_1","guid":123456789,"item_id":20101001,"item_count":10}' -q 1

扣除示例：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/update_player_item_count' \
  -m '{"area":"Game_tlbb_1","guid":123456789,"item_id":20101001,"item_count":-10}' -q 1

字段说明：

area：区服节点名，例如 Game_tlbb_1。
guid：在线玩家 GUID，通常用十进制数值。
item_id：资源或道具 ID。
item_count：变化数量，正数增加，负数扣除。

成功回包示例：

{"area":"Game_tlbb_1","guid":123456789,"item_id":20101001,"item_count":10,"new_count":20,"result":true}

注意：

这个命令走在线 agent，玩家不在线或区服错误时可能返回失败。
item_id 和资源类型是否允许更新，以玩家 agent 的 resource_update 实现为准。

5.9 修改充值点数

功能：

修改账号 top_up_point，可增加也可扣除。

增加点数：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/change_top_point' \
  -m '{"account":"test001","change_top_point_count":1000}' -q 1

扣除点数：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/change_top_point' \
  -m '{"account":"test001","change_top_point_count":-1000}' -q 1

字段说明：

account：账号名。
change_top_point_count：变化点数，正数增加，负数扣除。

限制：

单次变化范围是 -10000000 到 10000000。
扣除后小于 0 时，会被修正为 0。

成功回包示例：

{"account":"test001","change_top_point_count":1000,"old_count":0,"new_count":1000,"error":"","result":true}

5.10 清除二级密码

功能：

删除角色存档里的 minor_password 字段。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/unlock_minor_password' \
  -m '{"guid":"75bcd15"}' -q 1

字段说明：

guid：十六进制角色 GUID 字符串。服务端会按 16 进制转换。

成功回包示例：

{"guid":"75bcd15","error":"","result":true}

5.11 修改账号密码

功能：

修改账号登录密码。如果服务端配置了 password_salt，会按盐值 SHA1 后写库。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/change_account_password' \
  -m '{"account":"test001","password":"NewPassword123"}' -q 1

字段说明：

account：账号名。
password：新密码明文，由服务端按当前密码规则处理。

成功回包示例：

{"account":"test001","new_password":"NewPassword123","error":"","result":true}

注意：

这是高危命令，不建议在共享 shell 历史里直接写真实密码。

5.12 修改角色等级

功能：

修改角色存档等级。

当前代码注意事项：

服务端校验字段是 target_level。
实际写库时当前代码使用的是 request.level。
因此在修代码前，如果必须使用，payload 里同时传 target_level 和 level，并保持两者一致。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/change_character_level' \
  -m '{"guid":"75bcd15","target_level":80,"level":80}' -q 1

字段说明：

guid：十六进制角色 GUID 字符串。服务端会按 16 进制转换。
target_level：用于校验和回包展示。
level：当前代码实际写入 attrib.level 的值。

限制：

等级范围是 1 到 119。

成功回包示例：

{"guid":"75bcd15","target_level":80,"error":"修改成功","result":true}

建议：

这个 topic 建议先修正服务端字段名后再正式使用，把写库字段统一为 target_level。

5.13 限制账号交易

功能：

把账号 right 设置为 2，用于限制交易。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/limit_account_exchange' \
  -m '{"account":"test001"}' -q 1

字段说明：

account：账号名。

成功回包示例：

{"account":"test001","error":"","result":true}

5.14 解除账号交易限制

功能：

把账号 right 设置为 0，用于解除交易限制。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/unlimit_account_exchange' \
  -m '{"account":"test001"}' -q 1

字段说明：

account：账号名。

成功回包示例：

{"account":"test001","error":"","result":true}

5.15 添加可领取奖励

功能：

向 can_get_awards 集合写入一条可领取奖励记录。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/add_can_get_award' \
  -m '{"guid":"75bcd15","award_name":"测试礼包","award_list":[{"item_id":20101001,"count":1}]}' -q 1

字段说明：

guid：十六进制角色 GUID 字符串。服务端会按 16 进制转换后写入。
award_name：奖励名称。
award_list：奖励内容，具体结构要和领取奖励的业务读取逻辑保持一致。

成功回包示例：

{"guid":"75bcd15","award_name":"测试礼包","award_list":[{"item_id":20101001,"count":1}],"result":true}

注意：

award_list 的内部格式没有在 gm_tool_core.lua 内校验，错误格式可能会导致后续领取逻辑无法识别。

5.16 调用在线玩家脚本

功能：

调用指定在线玩家 agent 的 call_script。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/call_script' \
  -m '{"area":"Game_tlbb_1","guid":"75bcd15","script_id":900066,"func_name":"SomeFunc","params":{}}' -q 1

字段说明：

area：区服节点名，例如 Game_tlbb_1。
guid：十六进制角色 GUID 字符串。服务端会按 16 进制转换。
script_id：脚本 ID。
func_name：要调用的脚本函数名。
params：传给脚本函数的参数。

回包说明：

如果调用成功，回包内容取决于脚本函数返回值。
如果调用异常，通常返回：

{"error":"调用异常"}

注意：

这是最高风险命令之一，必须确认脚本函数、参数和在线玩家都正确。
玩家不在线、区服错误、脚本函数不存在，都可能导致调用失败或返回空。

5.17 校验账号密码

功能：

校验传入密码是否和账号库中的 pwd 匹配。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/check_password' \
  -m '{"account":"test001","password":"Password123"}' -q 1

字段说明：

account：账号名。
password：待校验密码。如果服务端配置了 password_salt，会先按盐值 SHA1 后再比对。

成功回包示例：

{"error":"","check_success":true,"result":true}

注意：

当前代码会把校验过程写日志，涉及密码相关信息，不建议在生产环境频繁使用。

5.18 校验账号超级密码

功能：

校验传入超级密码是否和账号库中的 super_pwd 匹配。

命令：

mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'gm_tool/check_super_password' \
  -m '{"account":"test001","super_password":"SuperPassword123"}' -q 1

字段说明：

account：账号名。
super_password：待校验超级密码。如果服务端配置了 password_salt，会先按盐值 SHA1 后再比对。

成功回包示例：

{"error":"","check_success":true,"result":true}

注意：

当前代码会把校验过程写日志，涉及密码相关信息，不建议在生产环境频繁使用。

6. 重启 gm_tool

gm_tool 在 Tool 进程里，进程 ID 是 6。修改 gm_tool_core.lua 后，需要重启 Tool 进程才会生效。

单区发布模式：

cd /home/ubuntu/tlbb
SKIP_BUILD=1 bash ./r.sh publish 6 Tool

双区发布模式：

cd /home/ubuntu/tlbb
SKIP_BUILD=1 bash ./r.sh publish_2zone 6 Tool

debug 模式：

cd /home/ubuntu/tlbb
SKIP_BUILD=1 bash ./r.sh debug 6 Tool

确认服务已起来：

printf 'list\n' | nc -w 2 127.0.0.1 6006 | grep -E 'gm_tool|mqttor|hs_admin'

影响范围：

会短暂中断 gm_tool MQTT。
会短暂中断 hs_admin 13013 HTTP 管理口。
不会重启 Game 进程。

7. 常见问题

7.1 发了命令但游戏没有反应

先监听：

mosquitto_sub -h "$MQTT_HOST" -p "$MQTT_PORT" \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -v -t 'gm_tool/#'

然后看现象：

没看到你发的 topic：broker 地址、端口、账号密码或命令执行位置不对。
看到原 topic，但没有 /done：gm_tool 没启动、没有连接 broker，或处理时出错。
看到 /done result=true，游戏没显示：继续查 area 是否正确、玩家是否在线、world 广播是否可达。
看到 /done result=false：按 error 字段处理。

7.2 为什么命令里可以不写端口

普通 MQTT 默认端口是 1883。下面两条等价：

mosquitto_pub -h 127.0.0.1 -t 'gm_tool/broadcast' -m '{"msg":"测试"}'

mosquitto_pub -h 127.0.0.1 -p 1883 -t 'gm_tool/broadcast' -m '{"msg":"测试"}'

如果 broker 不是 1883，命令必须加 -p，服务端配置也要写成类似：

uri = "127.0.0.1:1884"

7.3 Windows PowerShell 怎么写

PowerShell 里不要使用 \ 续行。建议先写成一行：

mosquitto_pub -h 127.0.0.1 -p 1883 -u mqtt_user_9bd3284f -P '<MQTT密码>' -t 'gm_tool/broadcast' -m '{"msg":"测试广播"}' -q 1

或者使用 PowerShell 反引号续行。

8. 安全注意事项

MQTT GM 通道权限很高，可以封号、改密码、改点数、发奖励、调用脚本。必须按高危管理入口处理：

不要把 MQTT broker 暴露到公网。
broker 尽量只监听 127.0.0.1 或内网地址。
配置 MQTT ACL，限制账号只能发布必要 topic。
密码泄露后立即轮换。
高风险 topic 如 change_account_password、call_script、check_password、check_super_password 应尽量少用，并保留操作审计。

账号		自动登录	找回密码
密码			register