实战：用 SoftAgent 远程管控一台展厅电脑

器材清单

名称	数量	说明
SoftAgent	1	装在被控电脑上，本节的主角；免费版就够跑完全程
Windows 被控电脑	1	模拟展厅里那台播放/互动主机，需预装 .NET 10 桌面运行时
控制端电脑	1	用来发指令，和被控机同网段即可，用你自己的笔记本就行
交换机 + 网线	1 套	两台机器能互相 ping 通就行

本节会用到关机、注销这类破坏性指令。请务必在测试机上做，不要拿正在展出的设备练手。 关机验证一律用"延时 + 取消"的方式，文中会讲。

这一节要做出什么

做完之后，你会得到一台能被网络指令完全管住的展厅电脑：坐在自己工位上敲一条命令，就能让它关机、锁屏、调音量、启停播放软件；它还会每隔十秒主动告诉你"我还活着"。

这是整个远程运维体系的地基。前面远程运维与排障讲的是思路，这一节把思路落到一台真机上。

为什么是"代理"这种形态

动手前先想清楚这件事，不然容易走弯路。

展厅电脑的远程管理有两条路。一条是远程桌面（向日葵、ToDesk 那类），把画面传给你，你用鼠标操作。另一条是装个代理程序，它常驻在被控机上监听网络指令，收到什么执行什么。

代理这条路的好处是便宜且能批量：一条指令可以同时发给三十台机器，占用的带宽几乎可以忽略，还能挂在定时任务上自动跑。代价是它只能干预先定义好的那些事，碰上"弹了个陌生对话框要点确定"就抓瞎。

所以两条路是配合用的，不是二选一，详细的分工判断见远程桌面还是指令代理。这一节练的是代理这一层。

第一步：装上 SoftAgent

从产品页下载安装包，在被控电脑上安装。装的时候注意两点：

一是需要管理员权限。 SoftAgent 要执行关机、改系统设置这类动作，程序清单里声明了 requireAdministrator，启动时会弹 UAC 提权。这是正常的，同意即可。

二是需要 .NET 10 桌面运行时。 如果机器上没装，程序起不来。展厅那些出厂就没动过的工控机大概率没有，提前装好。

装完启动，你会看到一个带四个标签页的窗口：基础、程序、守护、设置。首次安装会自动开启 30 天试用，这期间等同企业版全集；试用到期后自动回落免费版继续用，不会锁死。

你应该看到——「基础」标签页上有一排操作磁贴（音量、锁屏、关机之类），下方状态条里显示着当前音量、守护运行数，以及一串 agentId。这个 agentId 是这台机器的唯一标识，由系统的 MachineGuid 派生而来，不依赖网卡 MAC，所以换网卡、插拔 USB 网卡都不会变。记住它，后面看心跳要用。

第二步：确认端口通了

SoftAgent 默认监听 UDP 6500。在「设置」标签页可以改，但改完要重启进程才生效——这一点界面上会提示"需重启"，别改完就直接发指令然后困惑为什么不通。

先在控制端 ping 一下被控机的 IP，确认二层通。然后确认防火墙：Windows 防火墙默认会拦截入站的 UDP，安装程序通常会加规则，但如果现场装了第三方安全软件，得手动放行 6500。

这一步不通的话，后面全是白搭。判断方法很简单：下一步发 ping 指令，收不到回执就是这里的问题。

第三步：发出第一条指令

不需要装任何客户端，PowerShell 就能发。在控制端打开 PowerShell，把 IP 换成你被控机的：

function Send-Agent {
    param([string]$Ip, [string]$Cmd, [int]$Port = 6500)
    $c = New-Object Net.Sockets.UdpClient
    $c.Client.ReceiveTimeout = 3000
    $b = [Text.Encoding]::UTF8.GetBytes($Cmd)
    $c.Send($b, $b.Length, $Ip, $Port) | Out-Null
    try {
        $ep = New-Object Net.IPEndPoint([Net.IPAddress]::Any, 0)
        $r = $c.Receive([ref]$ep)
        [Text.Encoding]::UTF8.GetString($r)
    } catch {
        '（超时，没收到回执）'
    } finally { $c.Close() }
}

Send-Agent -Ip '192.168.1.50' -Cmd 'ping'

你应该看到——返回 ok:pong。

这四个字符说明整条链路通了：网络通、端口通、进程活着、指令被正确解析。收不到就回头查第二步，八成是防火墙或 IP 写错。

回执的格式有固定套路，现在花一分钟记住它，后面排错全靠它：

• ok:<码> —— 执行成功，比如 ok:pong、ok:volup；
• err:<码> —— 执行失败，错误码告诉你原因，比如 err:dispatch.unknownVerb 是指令名写错了；
• JSON —— 带数据返回的指令（比如下面的 describe）直接回一段 JSON。

再试两条无害的：

Send-Agent -Ip '192.168.1.50' -Cmd 'volup'      # 音量升一档
Send-Agent -Ip '192.168.1.50' -Cmd 'mute'       # 切换静音

你应该看到——被控机的音量条真的动了，界面状态条上的音量百分比同步变化。到这里，你已经在远程控制这台机器了。

第四步：搞清楚这台机器能干什么

与其翻文档，不如直接问它：

Send-Agent -Ip '192.168.1.50' -Cmd 'describe'

返回的是一段 JSON，列出了所有可用指令，每条带这么几个字段：

字段	含义	怎么用
name	指令名	就是你要发的那个 verb
description	干什么的	中文说明
parameterSchema	参数格式	为 null 表示不带参数
risk	风险等级	Safe / Disruptive / Destructive
requiresConfirm	要不要确认	true 表示执行前应该有人工或策略确认
requiredEdition	需要什么授权	Free / Standard / Enterprise

这个自省能力比它看起来有用。 你写批量脚本时不用硬编码指令表，直接问机器；上层要接 AI 编排时，risk 和 requiresConfirm 就是决策依据——AI 可以自动放行 Safe 的、对 Destructive 的先要人确认。

顺带看一眼 discover，它返回一份精简的状态快照，控制端用来发现和识别设备：

Send-Agent -Ip '192.168.1.50' -Cmd 'discover'

第五步：安全地试一次关机

关机是最常用也最容易出事的指令。正确姿势是延时下发 + 随时可取消，永远不要在生产环境直接发立即关机。

Send-Agent -Ip '192.168.1.50' -Cmd 'shutdown:60'      # 60 秒后关机

你应该看到——被控机弹出系统的关机倒计时提示。

现在别慌，赶紧取消：

Send-Agent -Ip '192.168.1.50' -Cmd 'cancelshutdown'

你应该看到——倒计时消失，机器活得好好的。

这一收一放就是关机类指令的标准打法。展厅闭馆的定时关机也该这么配：给个 60 秒延时，万一发错了、或者现场还有人在，有一分钟的窗口能救回来。直接发 shutdown 不带参数是立即执行的，救不回来。

同类的破坏性指令还有 reboot（同样支持延时）和 logoff（注销）。describe 里它们的 requiresConfirm 都是 true，就是在提醒你：这些动作上层应该先确认再执行。

第六步：配受管程序，远程启停播放软件

这是展厅最实用的功能之一——播放软件卡住了，不用跑现场，远程重启一下。

在被控机的「程序」标签页里，用"名称 + 路径 + 浏览"表单把播放程序加进去。注意这个列表的顺序就是指令里的序号，从 0 开始数，行可以拖拽重排。

配好之后回到控制端：

Send-Agent -Ip '192.168.1.50' -Cmd 'startpro:0'   # 启动第 1 个受管程序
Send-Agent -Ip '192.168.1.50' -Cmd 'killpro:0'    # 停止它
Send-Agent -Ip '192.168.1.50' -Cmd 'killall'      # 停止全部受管程序

你应该看到——被控机上程序真的起来了/关掉了，「程序」页对应行的运行状态跟着变。

有个细节值得一提：killpro 会先杀记录在案的 pid，如果代理重启过、pid 记录丢了，它会退而按可执行文件路径去停。这是为了覆盖"代理重启后失忆"这种现实情况，不用你操心。

免费版这里有个限制：受管程序最多 2 个。 展厅典型场景就是"播放软件 + 中控客户端"，通常够用；不够再考虑升级授权。

第七步：打开心跳，用"有没有信"判断死活

前面几步都是"我主动问"，这一步反过来——让设备主动报告。这是从"三十台逐个连远程桌面确认"变成"看一眼汇总"的关键。

在「设置」标签页的高级区，填上报地址（控制端的 IP:端口）和心跳间隔（默认 10 秒，可设 5~600 秒）。这两个字段是热生效的，改完不用重启。

在控制端起一个最简接收器看看效果：

$listener = New-Object Net.Sockets.UdpClient(6600)
$ep = New-Object Net.IPEndPoint([Net.IPAddress]::Any, 0)
while ($true) {
    $data = $listener.Receive([ref]$ep)
    $json = [Text.Encoding]::UTF8.GetString($data)
    Write-Host "$(Get-Date -f 'HH:mm:ss') 收到心跳: $json"
}

你应该看到——每隔十秒刷出一行 JSON，里面带着 agentId、IP、音量、守护状态这些信息。上线的瞬间也会立刻报一次，不用等第一个周期。

这个东西的价值不在于技术多复杂，而在于它把运维模式反过来了。 以前是"我怀疑那台有问题，去连一下看看"，现在是"哪台超过一分钟没心跳，它就是有问题"。三十台设备的巡检，从半小时压缩到看一眼。

真要做成看板还得有个服务端接收、存库、展示，那是设备在线监控与告警体系那一节的事。这里先建立"心跳能用来判死活"这个概念。

第八步：设开机自启

最后一步，也是最容易漏的一步：让代理自己活过每一次断电。

展厅每天断电关机，如果 SoftAgent 不能随机启动，第二天来电后它就没了，所有远程能力归零，而你完全不知道——直到某次需要远程操作时才发现连不上。

在「设置」页打开开机自启，可以设 0~300 秒的延迟。它的实现方式是注册一条登录时触发、以最高权限运行的计划任务，这样开机后不需要人点任何东西。

延迟建议设 20~60 秒，理由和端侧定时任务里讲的一样：开机瞬间系统正忙着初始化网络、加载驱动，这时候起来容易连不上网。

验证方法：重启被控机，什么都别碰，等一分钟后从控制端发 ping。 收到 ok:pong 才算成功。

排错表

症状	多半原因	怎么办
发指令超时无回执	防火墙拦 UDP 6500 / IP 写错 / 进程没跑	先 ping 通，再查防火墙入站规则，再看托盘图标在不在
改了端口就连不上	端口变更需重启进程	重启 SoftAgent，界面有"需重启"提示
回 err:dispatch.unknownVerb	指令名拼错，或该版本没这条指令	发 describe 看实际支持的指令表
回 err:license.required	用了超出当前授权档位的能力	看回执里的 requiredEdition；免费版有 2 个程序/2 项守护/2 个定时的配额
关机指令发了没反应	权限不足，没以管理员运行	确认程序是提权启动的
收不到心跳	上报地址填错，或控制端没在监听	核对 IP:端口，控制端先起接收器再看
重启后代理没了	没设开机自启	「设置」页打开开机自启，重启实测一次
心跳时有时无	网络抖动，或心跳间隔设太长	心跳是尽力而为不重传，判死活时留够容忍窗口（比如 3 个周期）

最后一条要特别说明：心跳丢一两次是正常的，UDP 本身不保证送达，代理侧也刻意做成"尽力而为、不阻塞主流程"。所以判断设备离线时别用"丢一次就告警"，至少留三个周期的容忍，否则告警会吵得没人看。

到这一步你拥有了什么

回头看，这台电脑现在具备四件事：

1. 能被远程指挥——关机、锁屏、音量、启停程序，一条命令的事；
2. 能安全地被指挥——破坏性动作走延时+取消，发错了有后悔药；
3. 会主动报平安——心跳让你不用逐台去看；
4. 能自己活过断电——开机自启保证这些能力不会因为一次闭馆就消失。

把这四件事复制到全场每一台机器上，"展厅远程运维"这件事的地基就打好了。剩下的是往上盖：程序崩了自动拉起（故障自愈设计）、几十台的状态怎么看（设备在线监控与告警）、配置怎么统一管（设备资产台账与配置管理）。

下一步

本节只用了 SoftAgent 最基础的那部分能力。它还能直接给投影机发 PJLink、给播放器发 TCP/UDP/HTTP 报文，等于把设备控制那层也接管了——那是SoftAgent 直控投影机与播放器那一节的内容。

如果你的痛点是"播放软件老崩"，可以直接跳到用 SoftAgent 守住播放软件，那一节讲守护配置。