docs(script-monitor): add per-machine agent rollout guide
This commit is contained in:
WuYongJie
parent
59634f8516
commit
0d12a94054
@ -2,6 +2,9 @@
|
||||
|
||||
每台运行脚本的机器部署一份 Agent。Agent 只主动向产品平台发起 HTTP 请求，不需要为被监控机器开放入站端口。
|
||||
|
||||
需要交给安装同事逐台执行时，请使用完整的
|
||||
[《脚本监控 Agent 逐台接入操作手册》](../../docs/workflow/脚本监控Agent逐台接入操作手册.md)。
|
||||
|
||||
## 接入
|
||||
|
||||
1. 在供应链中心的“脚本监控”页面点击“接入机器”，生成独立的 `agentId` 和 `agentToken`。
|
||||
|
||||
486
furniture-3d-system/docs/workflow/脚本监控Agent逐台接入操作手册.md
Normal file
486
furniture-3d-system/docs/workflow/脚本监控Agent逐台接入操作手册.md
Normal file
@ -0,0 +1,486 @@
|
||||
# 脚本监控 Agent 逐台接入操作手册
|
||||
|
||||
适用对象：负责在各台脚本机器上安装、配置和验收监控 Agent 的同事。
|
||||
适用版本：产品平台生产版本 `85c31677` 及之后版本。
|
||||
平台入口：供应链中心 → 脚本监控。
|
||||
|
||||
## 1. 任务目标
|
||||
|
||||
每台运行脚本的机器都安装一个常驻 Agent，由 Agent 主动向产品平台汇报：
|
||||
|
||||
- 机器是否在线，以及本次通过内网还是公网连接；
|
||||
- 机器上配置或自动发现了哪些脚本、Cron、PM2 进程；
|
||||
- 脚本最近一次运行状态、时间、耗时、退出码和结果摘要；
|
||||
- 经明确授权的脚本，是否可以从平台点击“立即运行”。
|
||||
|
||||
Agent 只主动发起 HTTP 请求，目标机器不需要开放任何入站端口。
|
||||
|
||||
## 2. 必须遵守的安全规则
|
||||
|
||||
1. 一台机器使用一套独立的 `agentId` 和 `agentToken`，禁止多台机器共用。
|
||||
2. Token 由平台负责人单独发给安装人员，不得发到群聊、工单正文或普通文档。
|
||||
3. `config.json` 不得提交到 Git；Linux 权限建议设为 `600`，Windows 只允许运行 Agent 的账号读取。
|
||||
4. 配置中的 `command` 不得直接写密码、Token、数据库连接串等敏感信息，应从目标机器原有安全环境变量或私有配置读取。
|
||||
5. 默认不要开启平台手动运行。只有已确认安全、可重复执行、不会等待人工输入的脚本，才允许设置 `"allowManualRun": true`。
|
||||
6. 订单写入、库存调整、财务、删除、批量覆盖等高风险脚本，未经业务负责人书面确认，不得开放手动运行。
|
||||
|
||||
## 3. 平台负责人先做什么
|
||||
|
||||
每接入一台机器，都要单独执行一次：
|
||||
|
||||
1. 登录产品平台。
|
||||
2. 打开“供应链中心 → 脚本监控”。
|
||||
3. 点击“接入机器”。
|
||||
4. 机器名称填写可识别名称，例如“杭州仓库脚本机 01”，不要只写“服务器”。
|
||||
5. 选择网络模式：内网、互联网或自动。
|
||||
6. 填写对应的平台地址。
|
||||
7. 点击“生成 Agent 凭据”。
|
||||
8. 立即复制完整配置，通过安全方式交给安装人员。
|
||||
|
||||
凭据只显示一次，关闭弹窗后不能再次查看当前 Token；遗失时应联系平台负责人重新生成，不能从数据库或日志中找回明文 Token。
|
||||
|
||||
## 4. 选择内网还是公网
|
||||
|
||||
| 机器网络情况 | `connectionMode` | `centerUrls` | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| 固定在公司/仓库内网，并能访问平台内网地址 | `intranet` | 只填 `intranet` | 推荐，所有上报只走内网 |
|
||||
| 只能访问互联网 | `internet` | 只填 `internet` | 公网生产地址必须使用 HTTPS |
|
||||
| 网络会在内外网之间切换 | `auto` | 内外网都填 | 优先内网，失败后再尝试公网 |
|
||||
|
||||
公网生产地址：
|
||||
|
||||
```text
|
||||
https://cp.jiansun.vip
|
||||
```
|
||||
|
||||
内网地址由平台运维负责人提供，文档中的 `<平台内网地址>` 只是占位符，不能照抄。
|
||||
|
||||
已知机器长期只处于一种网络时，优先选择固定的 `intranet` 或 `internet`，避免 `auto` 每次先等待不可达地址超时。
|
||||
|
||||
## 5. 每台机器需要的文件
|
||||
|
||||
从产品平台项目的 `agents/script-monitor/` 目录取得以下文件：
|
||||
|
||||
```text
|
||||
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. 安装目录
|
||||
|
||||
推荐目录：
|
||||
|
||||
```text
|
||||
Linux: /opt/furniture-script-monitor
|
||||
Windows: C:\furniture-script-monitor
|
||||
```
|
||||
|
||||
Linux 示例：
|
||||
|
||||
```bash
|
||||
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 示例
|
||||
|
||||
```json
|
||||
{
|
||||
"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 示例
|
||||
|
||||
```json
|
||||
{
|
||||
"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 执行：
|
||||
|
||||
```bash
|
||||
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 只查看“机器上有哪些任务”
|
||||
|
||||
开启自动发现：
|
||||
|
||||
```json
|
||||
{
|
||||
"autoDiscover": {
|
||||
"cron": true,
|
||||
"pm2": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Linux 可以发现当前运行账号的 Crontab；
|
||||
- 安装 PM2 的机器可以发现 PM2 进程；
|
||||
- Windows 不会自动发现任务计划程序；Windows 脚本必须写入 `scripts`；
|
||||
- 自动发现的 Cron 通常只能显示任务和计划，不能凭空知道真实执行结果；
|
||||
- 自动发现任务不允许平台手动运行。
|
||||
|
||||
### 9.2 定期检查当前结果
|
||||
|
||||
在脚本中配置 `resultCheck`。
|
||||
|
||||
检查文件：
|
||||
|
||||
```json
|
||||
{
|
||||
"resultCheck": {
|
||||
"type": "file",
|
||||
"path": "/absolute/path/to/result.log",
|
||||
"maxAgeSec": 1800,
|
||||
"minBytes": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
检查进程：
|
||||
|
||||
```json
|
||||
{
|
||||
"resultCheck": {
|
||||
"type": "process",
|
||||
"name": "python"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
检查 Linux systemd 服务：
|
||||
|
||||
```json
|
||||
{
|
||||
"resultCheck": {
|
||||
"type": "systemd",
|
||||
"service": "warehouse-sync.service"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Agent 的运行账号必须有权读取目标文件或查询目标进程/服务，否则页面会显示检查失败。
|
||||
|
||||
### 9.3 记录每次运行的真实结果
|
||||
|
||||
如果要记录开始时间、结束时间、耗时、退出码、标准输出和错误输出，应让原定时任务调用 `run-script.mjs`，由包装器再执行 `config.json` 中的真实 `command`。
|
||||
|
||||
Linux 示例：
|
||||
|
||||
```bash
|
||||
/usr/bin/node /opt/furniture-script-monitor/run-script.mjs warehouse-stock-sync
|
||||
```
|
||||
|
||||
Windows 任务计划程序：
|
||||
|
||||
```text
|
||||
程序：C:\Program Files\nodejs\node.exe
|
||||
参数：C:\furniture-script-monitor\run-script.mjs daily-finance-export
|
||||
起始于：C:\furniture-script-monitor
|
||||
```
|
||||
|
||||
改造定时任务后，必须确认原命令没有继续单独运行，否则会造成同一个脚本重复执行。
|
||||
|
||||
包装器上报失败时不会擅自把原脚本改成成功；原脚本退出码仍会原样保留。
|
||||
|
||||
## 10. 首次前台启动和验收
|
||||
|
||||
先不要配置开机自启，必须前台运行一次。
|
||||
|
||||
Linux：
|
||||
|
||||
```bash
|
||||
cd /opt/furniture-script-monitor
|
||||
node agent.mjs
|
||||
```
|
||||
|
||||
Windows PowerShell：
|
||||
|
||||
```powershell
|
||||
Set-Location C:\furniture-script-monitor
|
||||
node .\agent.mjs
|
||||
```
|
||||
|
||||
正确输出示例：
|
||||
|
||||
```text
|
||||
[script-monitor] 已通过内网上报 3 个脚本
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```text
|
||||
[script-monitor] 已通过公网上报 3 个脚本
|
||||
```
|
||||
|
||||
然后在平台检查：
|
||||
|
||||
1. 机器从“待接入”变为“在线 · 内网”或“在线 · 公网”。
|
||||
2. 顶部“在线/已接入”分母增加；从未上报的机器不会计入已接入分母。
|
||||
3. 页面脚本数量与本机配置一致。
|
||||
4. 每个脚本名称、计划和任务说明正确。
|
||||
5. `resultCheck` 状态符合本机实际情况。
|
||||
6. 关闭前台 Agent 后，等待至少 3 分钟，页面应显示“Agent 离线”。
|
||||
|
||||
Agent 在线判断时间为“至少 3 分钟，或 3 倍上报间隔，取较大值”。例如 `reportIntervalSec` 为 60 秒时，超过约 3 分钟未上报会显示离线。
|
||||
|
||||
## 11. 配置常驻运行
|
||||
|
||||
### 11.1 Linux 使用 PM2
|
||||
|
||||
```bash
|
||||
cd /opt/furniture-script-monitor
|
||||
npm install -g pm2
|
||||
pm2 start ecosystem.config.cjs
|
||||
pm2 save
|
||||
pm2 startup
|
||||
```
|
||||
|
||||
`pm2 startup` 会输出一条需要使用管理员权限执行的命令，按它的提示执行一次，然后再次运行：
|
||||
|
||||
```bash
|
||||
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. 平台手动运行
|
||||
|
||||
手动运行只有同时满足以下条件才可点击：
|
||||
|
||||
1. 当前用户有脚本监控编辑权限；
|
||||
2. Agent 在线；
|
||||
3. 本机脚本配置了 `command`；
|
||||
4. 本机明确设置 `"allowManualRun": true`；
|
||||
5. 当前没有等待或正在执行的同一任务。
|
||||
|
||||
平台不会下发任意命令，只下发脚本 `key`。Agent 收到 key 后，只执行本机 `config.json` 中预先保存的 `command`。
|
||||
|
||||
开放手动运行前逐项确认：
|
||||
|
||||
- 命令不需要人工输入；
|
||||
- 重复执行不会产生重复订单、重复扣减或覆盖数据；
|
||||
- 脚本自身有锁，避免与原定时任务同时执行；
|
||||
- 运行账号权限最小化；
|
||||
- 已在目标机器直接执行并确认退出码为 0；
|
||||
- 失败时能够从输出和错误日志定位原因。
|
||||
|
||||
手动运行请求约 5 分钟未被 Agent 领取会过期。Agent 默认每 5 秒主动领取一次，无需开放入站端口。
|
||||
|
||||
## 13. 重启验收
|
||||
|
||||
每台机器安装结束前必须重启一次或模拟一次开机启动：
|
||||
|
||||
1. 重启机器或停止并重新启动常驻任务。
|
||||
2. 确认 Agent 进程自动恢复。
|
||||
3. 等待一个上报周期。
|
||||
4. 在平台确认机器重新显示在线。
|
||||
5. 查看 Agent 日志，确认没有持续 401、超时或配置错误。
|
||||
|
||||
未完成重启验收，不算安装完成。
|
||||
|
||||
## 14. 常见故障
|
||||
|
||||
### 14.1 提示“配置文件不存在”
|
||||
|
||||
确认 `config.json` 与 `agent.mjs` 位于同一目录，或通过环境变量指定：
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
升级时只替换这些程序文件：
|
||||
|
||||
```text
|
||||
agent.mjs
|
||||
run-script.mjs
|
||||
ecosystem.config.cjs
|
||||
```
|
||||
|
||||
不要覆盖目标机器的 `config.json`。
|
||||
|
||||
Linux：
|
||||
|
||||
```bash
|
||||
pm2 restart furniture-script-monitor-agent
|
||||
pm2 logs furniture-script-monitor-agent --lines 50
|
||||
```
|
||||
|
||||
Windows：结束并重新运行对应任务计划，然后在平台确认一个上报周期内恢复在线。
|
||||
|
||||
## 16. 每台机器交接记录
|
||||
|
||||
安装人员每完成一台机器，填写一行；严禁在表格中记录 Token。
|
||||
|
||||
| 机器名称 | 操作系统 | 平台机器名称 | 网络模式 | 平台地址 | 安装目录 | 常驻方式 | 脚本数量 | 允许手动运行的脚本 | 负责人 | 安装时间 | 重启验收 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | ---: | --- | --- | --- | --- |
|
||||
| 示例：仓库脚本机 01 | Ubuntu 24.04 | 杭州仓库脚本机 01 | intranet | 由运维提供 | `/opt/furniture-script-monitor` | PM2 | 3 | warehouse-stock-sync | 张三 | 2026-08-28 | 通过 |
|
||||
|
||||
## 17. 单机完成清单
|
||||
|
||||
- [ ] 平台为本机生成了独立凭据；
|
||||
- [ ] `config.json` 未使用示例 Token，文件权限已收紧；
|
||||
- [ ] 网络模式和平台地址与机器实际网络一致；
|
||||
- [ ] 所有脚本都有唯一 key、清晰名称和正确工作目录；
|
||||
- [ ] 高风险脚本未开放手动运行；
|
||||
- [ ] 前台启动成功并显示内网或公网上报；
|
||||
- [ ] 平台机器由待接入变为在线；
|
||||
- [ ] 平台脚本数量与本机一致；
|
||||
- [ ] 至少一个脚本的结果检查或包装器运行已验证；
|
||||
- [ ] 常驻进程或任务计划已配置；
|
||||
- [ ] 重启后 Agent 能自动恢复；
|
||||
- [ ] 已填写单机交接记录，记录中不含 Token。
|
||||
Loading…
x
Reference in New Issue
Block a user