WuYongJie/furniture-3d-system-Wu

Fork 0

WuYongJie 3e89996a49 docs(script-monitor): clean rollout guide formatting

2026-08-28 19:03:14 +08:00

16 KiB

Raw Blame History

脚本监控 Agent 逐台接入操作手册

适用对象：负责在各台脚本机器上安装、配置和验收监控 Agent 的同事。

适用版本：产品平台生产版本 85c31677 及之后版本。

平台入口：供应链中心 → 脚本监控。

1. 任务目标

每台运行脚本的机器都安装一个常驻 Agent，由 Agent 主动向产品平台汇报：

机器是否在线，以及本次通过内网还是公网连接；
机器上配置或自动发现了哪些脚本、Cron、PM2 进程；
脚本最近一次运行状态、时间、耗时、退出码和结果摘要；
经明确授权的脚本，是否可以从平台点击“立即运行”。

Agent 只主动发起 HTTP 请求，目标机器不需要开放任何入站端口。

2. 必须遵守的安全规则

一台机器使用一套独立的 agentId 和 agentToken，禁止多台机器共用。
Token 由平台负责人单独发给安装人员，不得发到群聊、工单正文或普通文档。
config.json 不得提交到 Git；Linux 权限建议设为 600，Windows 只允许运行 Agent 的账号读取。
配置中的 command 不得直接写密码、Token、数据库连接串等敏感信息，应从目标机器原有安全环境变量或私有配置读取。
默认不要开启平台手动运行。只有已确认安全、可重复执行、不会等待人工输入的脚本，才允许设置 "allowManualRun": true。
订单写入、库存调整、财务、删除、批量覆盖等高风险脚本，未经业务负责人书面确认，不得开放手动运行。

3. 平台负责人先做什么

每接入一台机器，都要单独执行一次：

登录产品平台。
打开“供应链中心 → 脚本监控”。
点击“接入机器”。
机器名称填写可识别名称，例如“杭州仓库脚本机 01”，不要只写“服务器”。
选择网络模式：内网、互联网或自动。
填写对应的平台地址。
点击“生成 Agent 凭据”。
立即复制完整配置，通过安全方式交给安装人员。

凭据只显示一次，关闭弹窗后不能再次查看当前 Token；遗失时应联系平台负责人重新生成，不能从数据库或日志中找回明文 Token。

4. 选择内网还是公网

机器网络情况	`connectionMode`	`centerUrls`	说明
固定在公司/仓库内网，并能访问平台内网地址	`intranet`	只填 `intranet`	推荐，所有上报只走内网
只能访问互联网	`internet`	只填 `internet`	公网生产地址必须使用 HTTPS
网络会在内外网之间切换	`auto`	内外网都填	优先内网，失败后再尝试公网

公网生产地址：

https://cp.jiansun.vip

内网地址由平台运维负责人提供，文档中的 <平台内网地址> 只是占位符，不能照抄。

已知机器长期只处于一种网络时，优先选择固定的 intranet 或 internet，避免 auto 每次先等待不可达地址超时。

5. 每台机器需要的文件

从产品平台项目的 agents/script-monitor/ 目录取得以下文件：

agent.mjs
run-script.mjs
ecosystem.config.cjs
config.example.json

不要复制其他机器的 config.json。

运行环境要求：

Node.js 20 或 22 LTS，最低不得低于 Node.js 18；
Linux 建议安装 PM2 作为常驻进程管理器；
Windows 建议使用任务计划程序在开机时启动 Agent；
目标机器需要能够主动访问所选平台地址。

6. 安装目录

推荐目录：

Linux:   /opt/furniture-script-monitor
Windows: C:\furniture-script-monitor

Linux 示例：

sudo mkdir -p /opt/furniture-script-monitor
sudo chown -R <运行账号>:<运行账号组> /opt/furniture-script-monitor
chmod 700 /opt/furniture-script-monitor

Windows 请确认运行 Agent 的账号对安装目录、被监控脚本目录和结果文件有读取权限；需要手动运行时，还必须有执行权限。

7. 编写 `config.json`

将 config.example.json 复制为同目录的 config.json，再填入本机配置。

7.1 公网 Windows 示例

{
  "agentId": "由平台生成，禁止照抄",
  "agentToken": "由平台生成，禁止照抄",
  "agentName": "财务脚本机 01",
  "connectionMode": "internet",
  "centerUrls": {
    "internet": "https://cp.jiansun.vip"
  },
  "reportIntervalSec": 60,
  "commandPollIntervalSec": 5,
  "requestTimeoutMs": 10000,
  "autoDiscover": {
    "cron": false,
    "pm2": true
  },
  "scripts": [
    {
      "key": "daily-finance-export",
      "name": "每日财务导出",
      "taskDescription": "生成每日财务导出文件",
      "jobType": "OTHER",
      "schedule": "Windows 任务计划：每天 02:00",
      "expectedIntervalSec": 86400,
      "allowManualRun": false,
      "command": "C:\\Python311\\python.exe D:\\scripts\\daily_finance_export.py",
      "cwd": "D:\\scripts",
      "resultCheck": {
        "type": "file",
        "path": "D:\\scripts\\output\\latest.xlsx",
        "maxAgeSec": 90000,
        "minBytes": 1
      }
    }
  ]
}

JSON 中的 Windows 路径必须使用双反斜杠，例如 D:\\scripts。

7.2 内网 Linux 示例

{
  "agentId": "由平台生成，禁止照抄",
  "agentToken": "由平台生成，禁止照抄",
  "agentName": "仓库脚本机 01",
  "connectionMode": "intranet",
  "centerUrls": {
    "intranet": "<平台内网地址>"
  },
  "reportIntervalSec": 60,
  "commandPollIntervalSec": 5,
  "requestTimeoutMs": 5000,
  "autoDiscover": {
    "cron": true,
    "pm2": true
  },
  "scripts": [
    {
      "key": "warehouse-stock-sync",
      "name": "仓库库存同步",
      "taskDescription": "同步仓库库存到业务系统",
      "jobType": "CRON",
      "schedule": "*/15 * * * *",
      "expectedIntervalSec": 900,
      "allowManualRun": true,
      "command": "/usr/bin/bash /opt/scripts/warehouse-stock-sync.sh",
      "cwd": "/opt/scripts",
      "resultCheck": {
        "type": "file",
        "path": "/var/log/warehouse-stock-sync/latest.log",
        "maxAgeSec": 1800,
        "minBytes": 1
      }
    }
  ]
}

配置完成后，Linux 执行：

chmod 600 /opt/furniture-script-monitor/config.json

8. 脚本字段怎么填

字段	必填	填写要求
`key`	是	本机唯一且长期不变，只用英文、数字、短横线，后续不要随意改
`name`	是	页面显示名称，要让非开发人员看得懂
`taskDescription`	建议	说明脚本做什么、处理什么数据
`jobType`	是	只能是 `CRON`、`PM2`、`SYSTEMD`、`MANUAL`、`OTHER`
`schedule`	否	Cron 表达式或“Windows 任务计划：每天 02:00”等说明
`expectedIntervalSec`	否	预期运行间隔，单位秒；配合运行结果上报判断静默/超时
`command`	需要执行时	使用绝对路径，必须是本机已经验证过的真实命令
`cwd`	建议	命令工作目录，使用绝对路径
`allowManualRun`	是	默认 `false`；只有审核通过后才改为 `true`
`resultCheck`	建议	Agent 定期判断当前结果是否有效

同一台机器内不得配置重复 key。显式配置的脚本会覆盖相同 key 的自动发现结果。

9. 三种接入深度

9.1 只查看“机器上有哪些任务”

开启自动发现：

{
  "autoDiscover": {
    "cron": true,
    "pm2": true
  }
}

Linux 可以发现当前运行账号的 Crontab；
安装 PM2 的机器可以发现 PM2 进程；
Windows 不会自动发现任务计划程序；Windows 脚本必须写入 scripts；
自动发现的 Cron 通常只能显示任务和计划，不能凭空知道真实执行结果；
自动发现任务不允许平台手动运行。

9.2 定期检查当前结果

在脚本中配置 resultCheck。

检查文件：

{
  "resultCheck": {
    "type": "file",
    "path": "/absolute/path/to/result.log",
    "maxAgeSec": 1800,
    "minBytes": 1
  }
}

检查进程：

{
  "resultCheck": {
    "type": "process",
    "name": "python"
  }
}

检查 Linux systemd 服务：

{
  "resultCheck": {
    "type": "systemd",
    "service": "warehouse-sync.service"
  }
}

Agent 的运行账号必须有权读取目标文件或查询目标进程/服务，否则页面会显示检查失败。

9.3 记录每次运行的真实结果

如果要记录开始时间、结束时间、耗时、退出码、标准输出和错误输出，应让原定时任务调用 run-script.mjs，由包装器再执行 config.json 中的真实 command。

Linux 示例：

/usr/bin/node /opt/furniture-script-monitor/run-script.mjs warehouse-stock-sync

Windows 任务计划程序：

程序：C:\Program Files\nodejs\node.exe
参数：C:\furniture-script-monitor\run-script.mjs daily-finance-export
起始于：C:\furniture-script-monitor

改造定时任务后，必须确认原命令没有继续单独运行，否则会造成同一个脚本重复执行。

包装器上报失败时不会擅自把原脚本改成成功；原脚本退出码仍会原样保留。

10. 首次前台启动和验收

先不要配置开机自启，必须前台运行一次。

Linux：

cd /opt/furniture-script-monitor
node agent.mjs

Windows PowerShell：

Set-Location C:\furniture-script-monitor
node .\agent.mjs

正确输出示例：

[script-monitor] 已通过内网上报 3 个脚本

或：

[script-monitor] 已通过公网上报 3 个脚本

然后在平台检查：

机器从“待接入”变为“在线 · 内网”或“在线 · 公网”。
顶部“在线/已接入”分母增加；从未上报的机器不会计入已接入分母。
页面脚本数量与本机配置一致。
每个脚本名称、计划和任务说明正确。
resultCheck 状态符合本机实际情况。
关闭前台 Agent 后，等待至少 3 分钟，页面应显示“Agent 离线”。

Agent 在线判断时间为“至少 3 分钟，或 3 倍上报间隔，取较大值”。例如 reportIntervalSec 为 60 秒时，超过约 3 分钟未上报会显示离线。

11. 配置常驻运行

11.1 Linux 使用 PM2

cd /opt/furniture-script-monitor
npm install -g pm2
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup

pm2 startup 会输出一条需要使用管理员权限执行的命令，按它的提示执行一次，然后再次运行：

pm2 save
pm2 status furniture-script-monitor-agent
pm2 logs furniture-script-monitor-agent --lines 50

11.2 Windows 使用任务计划程序

打开 Windows“任务计划程序”，创建任务：

名称：Furniture Script Monitor Agent；
触发器：启动时；
程序：C:\Program Files\nodejs\node.exe；
参数：C:\furniture-script-monitor\agent.mjs；
起始于：C:\furniture-script-monitor；
选择“不管用户是否登录都要运行”；
勾选“使用最高权限运行”；
失败后每 1 分钟重启，至少重试 3 次；
不要设置短于脚本运行时间的自动停止时限。

任务使用哪个 Windows 账号运行，该账号就必须能读取 config.json、脚本目录和结果文件，并有权执行已开放的命令。

12. 平台手动运行

手动运行只有同时满足以下条件才可点击：

当前用户有脚本监控编辑权限；
Agent 在线；
本机脚本配置了 command；
本机明确设置 "allowManualRun": true；
当前没有等待或正在执行的同一任务。

平台不会下发任意命令，只下发脚本 key。Agent 收到 key 后，只执行本机 config.json 中预先保存的 command。

开放手动运行前逐项确认：

命令不需要人工输入；
重复执行不会产生重复订单、重复扣减或覆盖数据；
脚本自身有锁，避免与原定时任务同时执行；
运行账号权限最小化；
已在目标机器直接执行并确认退出码为 0；
失败时能够从输出和错误日志定位原因。

手动运行请求约 5 分钟未被 Agent 领取会过期。Agent 默认每 5 秒主动领取一次，无需开放入站端口。

13. 重启验收

每台机器安装结束前必须重启一次或模拟一次开机启动：

重启机器或停止并重新启动常驻任务。
确认 Agent 进程自动恢复。
等待一个上报周期。
在平台确认机器重新显示在线。
查看 Agent 日志，确认没有持续 401、超时或配置错误。

未完成重启验收，不算安装完成。

14. 常见故障

14.1 提示“配置文件不存在”

确认 config.json 与 agent.mjs 位于同一目录，或通过环境变量指定：

SCRIPT_MONITOR_CONFIG=/absolute/path/config.json

14.2 返回 HTTP 401

通常是 agentId 和 agentToken 不匹配、Token 被复制不完整，或使用了其他机器的凭据。不要反复猜 Token，联系平台负责人重新生成。

14.3 内网能通但 Agent 走了公网

检查 connectionMode、centerUrls.intranet 和内网 DNS/端口。auto 会先尝试内网，内网失败后才走公网。

14.4 机器在线但没有脚本

检查：

scripts 是否为 JSON 数组；
每一项是否都有唯一的 key 和非空 name；
jobType 是否使用支持的枚举值；
Windows 是否误以为能自动发现任务计划程序；
Agent 日志是否出现 HTTP 400 或 JSON 解析错误。

14.5 “立即运行”按钮不可用

页面会给出具体原因。重点检查 Agent 是否在线、脚本是否有 command，以及是否明确设置了 "allowManualRun": true。

14.6 结果文件明明存在，但页面显示失败

使用运行 Agent 的同一个系统账号检查文件权限、路径、更新时间和大小。相对路径容易受启动目录影响，resultCheck.path 必须使用绝对路径。

14.7 页面显示“最近成功”，但 Agent 离线

“最近成功”表示脚本历史上的最后一次结果；“Agent 离线”表示机器当前没有继续上报，两者含义不同。先恢复 Agent，再判断脚本是否仍在正常执行。

15. 升级 Agent

升级时只替换这些程序文件：

agent.mjs
run-script.mjs
ecosystem.config.cjs

不要覆盖目标机器的 config.json。