docs(script-monitor): make agent rollout guide self-contained
This commit is contained in:
WuYongJie
parent
ed7845be65
commit
82260e2517
@ -2,22 +2,62 @@
|
||||
|
||||
适用对象：负责在各台脚本机器上安装、配置和验收监控 Agent 的同事。
|
||||
|
||||
适用版本：产品平台生产版本 `85c31677` 及之后版本。
|
||||
适用版本：脚本监控 Agent `1.0.0`。
|
||||
|
||||
平台入口：供应链中心 → 脚本监控。
|
||||
|
||||
本文按“安装人员完全不了解产品平台代码和项目结构”编写。安装人员不需要取得产品平台源码、不需要理解 Git，也不需要登录代码仓库。
|
||||
|
||||
## 0. 开始前先确认
|
||||
|
||||
### 0.1 先选择一种接入方式
|
||||
|
||||
| 你的实际情况 | 选择 | 阅读范围 |
|
||||
| --- | --- | --- |
|
||||
| 只需要监控普通脚本、Cron、PM2 或结果文件 | 标准 Agent | 按第 1～17 节操作，不需要阅读附录 A |
|
||||
| 已经有影刀等专用采集程序，并且要由该程序直接推送应用和日志 | 自定义采集器 | 先读第 1～4 节，再由开发人员按附录 A 改造和验收 |
|
||||
|
||||
同一台机器、同一组 Agent 凭据只能有一个上报程序。禁止同时运行标准 `agent.mjs` 和自定义采集器，否则两个程序会互相覆盖脚本快照，页面数据会时有时无。
|
||||
|
||||
### 0.2 你应当拿到的资料
|
||||
|
||||
开始前必须具备：
|
||||
|
||||
1. 本手册；
|
||||
2. 这台机器独立的 `agentId` 和 `agentToken`，或平台生成的完整配置；
|
||||
3. 已确认的网络模式：内网、公网或自动；
|
||||
4. 本机需要监控的脚本清单，至少包含脚本名称、用途、运行方式和计划；
|
||||
5. 如果选择标准 Agent，能够在目标机器下载第 5 节的 4 个程序文件；
|
||||
6. 如果选择自定义采集器，能够修改采集程序的开发人员和附录 A。
|
||||
|
||||
缺少独立凭据、脚本清单或网络信息时，不要自行猜测，也不要复制其他机器的配置，应联系平台负责人补齐后再开始。
|
||||
|
||||
### 0.3 本文中的称呼
|
||||
|
||||
- “平台”：`https://cp.jiansun.vip` 中的“供应链中心 → 脚本监控”；
|
||||
- “平台负责人”：在平台创建机器、生成凭据并核对页面结果的人；
|
||||
- “安装人员”：在目标 Windows 或 Linux 机器部署 Agent 的人；
|
||||
- “Agent”：常驻在目标机器、主动向平台上报的程序；
|
||||
- “脚本 key”：一个脚本在本机长期不变的唯一标识，不是脚本名称。
|
||||
|
||||
### 0.4 什么情况下算接入完成
|
||||
|
||||
标准 Agent 必须同时满足：前台启动明确显示上报成功、平台机器在线、平台脚本数量与本机清单一致、状态和最近结果符合实际、重启后 Agent 自动恢复。
|
||||
|
||||
自定义采集器必须同时满足：`/report` 返回 HTTP 200、平台显示全部脚本、至少一条真实 `/run` 记录可见、连续两个上报周期没有 400/401/403/404/405。只有业务明确要求平台手动运行时，才把 `/commands/claim` 作为完成条件。
|
||||
|
||||
## 1. 任务目标
|
||||
|
||||
每台运行脚本的机器都安装一个常驻 Agent，由 Agent 主动向产品平台汇报：
|
||||
每台运行脚本的机器都需要一个常驻上报进程：选择标准 Agent 时运行 `agent.mjs`，选择自定义采集器时由已有采集程序承担同一职责。上报进程主动向产品平台汇报：
|
||||
|
||||
- 机器是否在线，以及本次通过内网还是公网连接；
|
||||
- 机器上配置或自动发现了哪些脚本、Cron、PM2 进程；
|
||||
- 脚本最近一次运行状态、时间、耗时、退出码和结果摘要；
|
||||
- 经明确授权的脚本，是否可以从平台点击“立即运行”。
|
||||
|
||||
Agent 只主动发起 HTTP 请求，目标机器不需要开放任何入站端口。
|
||||
Agent 只主动发起 HTTP 请求，目标机器不需要开放任何入站端口，也不需要把脚本文件上传到平台。
|
||||
|
||||
优先使用平台提供的 `agent.mjs`。影刀等工具如果使用自定义采集器直接调用平台 API，必须同时遵守本文“附录 A：自定义采集器 HTTP API 契约”；不能沿用旧脚本监控项目的 WebSocket 或 `/api/agent/...` 接口。
|
||||
普通机器优先使用平台提供的 `agent.mjs`。影刀等工具如果使用自定义采集器直接调用平台 API，必须由能够修改采集程序的开发人员按附录 A 接入；不能沿用旧脚本监控项目的 WebSocket 或 `/api/agent/...` 接口。
|
||||
|
||||
## 2. 必须遵守的安全规则
|
||||
|
||||
@ -28,9 +68,9 @@ Agent 只主动发起 HTTP 请求，目标机器不需要开放任何入站端
|
||||
5. 默认不要开启平台手动运行。只有已确认安全、可重复执行、不会等待人工输入的脚本，才允许设置 `"allowManualRun": true`。
|
||||
6. 订单写入、库存调整、财务、删除、批量覆盖等高风险脚本，未经业务负责人书面确认，不得开放手动运行。
|
||||
|
||||
## 3. 平台负责人先做什么
|
||||
## 3. 平台负责人准备，安装人员只需核对
|
||||
|
||||
每接入一台机器，都要单独执行一次：
|
||||
以下步骤由平台负责人执行，安装人员不需要登录平台管理页面。每接入一台机器，平台负责人都要单独执行一次：
|
||||
|
||||
1. 登录产品平台。
|
||||
2. 打开“供应链中心 → 脚本监控”。
|
||||
@ -43,6 +83,8 @@ Agent 只主动发起 HTTP 请求，目标机器不需要开放任何入站端
|
||||
|
||||
凭据只显示一次，关闭弹窗后不能再次查看当前 Token；遗失时应联系平台负责人重新生成，不能从数据库或日志中找回明文 Token。
|
||||
|
||||
安装人员收到配置后只核对三项：机器名称是否是本机、网络模式是否符合本机、`agentId`/`agentToken` 是否为非空占位符以外的真实值。不要把完整 Token 截图或转发到群聊。
|
||||
|
||||
## 4. 选择内网还是公网
|
||||
|
||||
| 机器网络情况 | `connectionMode` | `centerUrls` | 说明 |
|
||||
@ -61,11 +103,27 @@ https://cp.jiansun.vip
|
||||
|
||||
已知机器长期只处于一种网络时，优先选择固定的 `intranet` 或 `internet`，避免 `auto` 每次先等待不可达地址超时。
|
||||
|
||||
公网机器在安装前先验证基础连通性。Windows PowerShell：
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod -Uri 'https://cp.jiansun.vip/api/health' -Method Get -TimeoutSec 15
|
||||
```
|
||||
|
||||
Linux：
|
||||
|
||||
```bash
|
||||
curl -fsS --max-time 15 https://cp.jiansun.vip/api/health
|
||||
```
|
||||
|
||||
响应中应包含 `"success": true` 和 `"status": "healthy"`。这只证明机器能访问平台，不代表 Agent 凭据或上报数据已经正确；最终仍以第 10 节验收为准。内网机器的测试地址和端口由平台运维负责人提供。
|
||||
|
||||
不要在浏览器地址栏直接打开 `/api/internal/script-monitor/report` 判断接口是否正常：浏览器发送的是 GET，而上报接口只接受 POST，看到 405 属于测试方法错误。
|
||||
|
||||
## 5. 下载每台机器需要的文件
|
||||
|
||||
平台页面目前没有 Agent 安装包下载按钮。安装人员不需要取得整个产品平台项目，也不需要登录代码仓库；请从下面固定版本地址下载 4 个文件。
|
||||
平台页面目前没有 Agent 安装包下载按钮。安装人员不需要取得整个产品平台项目，也不需要登录代码仓库；直接执行本节与你操作系统对应的下载命令即可。
|
||||
|
||||
当前受支持版本：`Agent 1.0.0`，对应生产发布提交 `dc16d2b75c41a5009354ba56caf4c1517d77ccce`。
|
||||
当前受支持版本：`Agent 1.0.0`。
|
||||
|
||||
| 文件 | 固定下载地址 |
|
||||
| --- | --- |
|
||||
@ -74,7 +132,7 @@ https://cp.jiansun.vip
|
||||
| `ecosystem.config.cjs` | `http://git.1080p.hk/WuYongJie/furniture-3d-system-Wu/raw/commit/dc16d2b75c41a5009354ba56caf4c1517d77ccce/furniture-3d-system/agents/script-monitor/ecosystem.config.cjs` |
|
||||
| `config.example.json` | `http://git.1080p.hk/WuYongJie/furniture-3d-system-Wu/raw/commit/dc16d2b75c41a5009354ba56caf4c1517d77ccce/furniture-3d-system/agents/script-monitor/config.example.json` |
|
||||
|
||||
这些是固定提交地址，不会因为主线后续修改而改变内容。下载服务当前只提供 HTTP，因此必须按下面的命令自动核对 SHA256；校验不通过时禁止运行文件。
|
||||
这些地址中的文件内容固定不变。下载服务当前只提供 HTTP，因此必须按下面的命令自动核对 SHA256；校验不通过时禁止运行文件。安装人员不需要理解地址中的项目和版本信息。
|
||||
|
||||
### 5.1 Windows PowerShell 一次下载并校验
|
||||
|
||||
@ -93,7 +151,7 @@ $expectedHashes = @{
|
||||
New-Item -ItemType Directory -Path $agentDir -Force | Out-Null
|
||||
foreach ($fileName in $expectedHashes.Keys) {
|
||||
$targetPath = Join-Path $agentDir $fileName
|
||||
Invoke-WebRequest -Uri "$baseUrl/$fileName" -OutFile $targetPath
|
||||
Invoke-WebRequest -UseBasicParsing -Uri "$baseUrl/$fileName" -OutFile $targetPath
|
||||
$actualHash = (Get-FileHash -Algorithm SHA256 -LiteralPath $targetPath).Hash
|
||||
if ($actualHash -ne $expectedHashes[$fileName]) {
|
||||
Remove-Item -LiteralPath $targetPath -Force
|
||||
@ -131,7 +189,7 @@ cp config.example.json config.json
|
||||
chmod 600 config.json
|
||||
```
|
||||
|
||||
四行都显示 `OK` 才能继续安装。若目标机器不能访问 `git.1080p.hk`，由平台负责人从产品项目的 `furniture-3d-system/agents/script-monitor/` 目录取得同一版本的以下 4 个文件，打包后通过公司文件传输渠道发送；压缩包中不得包含任何机器的 `config.json`。
|
||||
四行都显示 `OK` 才能继续安装。若目标机器不能访问 `git.1080p.hk`，停止下载并联系平台负责人通过公司文件传输渠道发送同版本文件；安装人员不需要自行寻找其他下载网站。负责人提供的压缩包不得包含任何机器已经填写过的 `config.json`。
|
||||
|
||||
需要的文件清单：
|
||||
|
||||
@ -151,6 +209,22 @@ config.example.json
|
||||
- Windows 建议使用任务计划程序在开机时启动 Agent；
|
||||
- 目标机器需要能够主动访问所选平台地址。
|
||||
|
||||
下载完成后先检查 Node.js。Windows PowerShell：
|
||||
|
||||
```powershell
|
||||
node --version
|
||||
(Get-Command node).Source
|
||||
```
|
||||
|
||||
Linux：
|
||||
|
||||
```bash
|
||||
node --version
|
||||
command -v node
|
||||
```
|
||||
|
||||
版本低于 18 或提示找不到 `node` 时，停止安装并联系本机管理员安装 Node.js 20/22 LTS；不要从不明网站下载运行环境。
|
||||
|
||||
## 6. 安装目录
|
||||
|
||||
推荐目录：
|
||||
@ -174,6 +248,15 @@ Windows 请确认运行 Agent 的账号对安装目录、被监控脚本目录
|
||||
|
||||
将 `config.example.json` 复制为同目录的 `config.json`，再填入本机配置。
|
||||
|
||||
如果平台负责人已经发来本机完整配置，就用该内容覆盖新建的 `config.json`；不要把配置内容粘贴进 Word、聊天软件富文本或 Markdown 链接后再复制回来。`centerUrls` 必须是普通 URL，Token 中的下划线 `_` 必须原样保留，不能写成 `\_`。
|
||||
|
||||
平台生成的初始配置可能是 `"scripts": []`。这只代表机器凭据已经创建，不代表系统能够自动知道本机的全部脚本：
|
||||
|
||||
- Windows 不会自动发现任务计划程序或影刀应用，标准 Agent 必须在 `scripts` 数组中逐项配置；
|
||||
- Linux 只能自动发现当前运行账号的 Crontab，以及该账号可见的 PM2 进程；
|
||||
- 影刀自定义采集器按附录 A 直接生成 `scripts` 快照，不要同时启动标准 Agent；
|
||||
- 未列入配置或未被自动发现的脚本不会出现在平台页面。
|
||||
|
||||
### 7.1 公网 Windows 示例
|
||||
|
||||
```json
|
||||
@ -404,6 +487,8 @@ node .\agent.mjs
|
||||
|
||||
Agent 在线判断时间为“至少 3 分钟，或 3 倍上报间隔，取较大值”。例如 `reportIntervalSec` 为 60 秒时，超过约 3 分钟未上报会显示离线。
|
||||
|
||||
安装人员没有平台账号时，不需要索要账号或密码。请把前台成功输出、机器名称、预期脚本数量和验收时间发给平台负责人，由负责人完成以上页面核对并明确回复“通过”或具体差异。
|
||||
|
||||
## 11. 配置常驻运行
|
||||
|
||||
### 11.1 Linux 使用 PM2
|
||||
@ -426,11 +511,19 @@ pm2 logs furniture-script-monitor-agent --lines 50
|
||||
|
||||
### 11.2 Windows 使用任务计划程序
|
||||
|
||||
先在 PowerShell 执行：
|
||||
|
||||
```powershell
|
||||
(Get-Command node).Source
|
||||
```
|
||||
|
||||
把输出的真实 `node.exe` 路径填到下面的“程序”中，不要在实际路径不同时照抄示例。
|
||||
|
||||
打开 Windows“任务计划程序”，创建任务：
|
||||
|
||||
- 名称：`Furniture Script Monitor Agent`；
|
||||
- 触发器：启动时；
|
||||
- 程序：`C:\Program Files\nodejs\node.exe`；
|
||||
- 程序：上一步查到的真实 `node.exe` 路径，例如 `C:\Program Files\nodejs\node.exe`；
|
||||
- 参数：`C:\furniture-script-monitor\agent.mjs`；
|
||||
- 起始于：`C:\furniture-script-monitor`；
|
||||
- 选择“不管用户是否登录都要运行”；
|
||||
@ -477,7 +570,13 @@ pm2 logs furniture-script-monitor-agent --lines 50
|
||||
|
||||
## 14. 常见故障
|
||||
|
||||
### 14.1 提示“配置文件不存在”
|
||||
出现错误时先保留当前窗口，不要反复改 Token、改接口路径或换请求体。按本节定位一次，并按第 14.11 节的模板反馈。
|
||||
|
||||
### 14.1 提示找不到 `node`
|
||||
|
||||
说明 Node.js 未安装、版本不符合要求或不在当前账号的 PATH 中。把 `node --version` 和 `(Get-Command node).Source`（Windows）或 `command -v node`（Linux）的输出发给本机管理员；不要继续配置开机自启。
|
||||
|
||||
### 14.2 提示“配置文件不存在”
|
||||
|
||||
确认 `config.json` 与 `agent.mjs` 位于同一目录，或通过环境变量指定：
|
||||
|
||||
@ -485,15 +584,17 @@ pm2 logs furniture-script-monitor-agent --lines 50
|
||||
SCRIPT_MONITOR_CONFIG=/absolute/path/config.json
|
||||
```
|
||||
|
||||
### 14.2 返回 HTTP 401
|
||||
### 14.3 返回 HTTP 401
|
||||
|
||||
通常是 `agentId` 和 `agentToken` 不匹配、Token 被复制不完整，或使用了其他机器的凭据。不要反复猜 Token，联系平台负责人重新生成。
|
||||
|
||||
### 14.3 内网能通但 Agent 走了公网
|
||||
如果凭据曾经粘贴到群聊、公开文档或其他非授权位置，应在平台删除原机器接入记录并重新生成，旧 Token 不再继续使用。
|
||||
|
||||
### 14.4 内网能通但 Agent 走了公网
|
||||
|
||||
检查 `connectionMode`、`centerUrls.intranet` 和内网 DNS/端口。`auto` 会先尝试内网，内网失败后才走公网。
|
||||
|
||||
### 14.4 机器在线但没有脚本
|
||||
### 14.5 机器在线但没有脚本
|
||||
|
||||
检查：
|
||||
|
||||
@ -503,21 +604,61 @@ SCRIPT_MONITOR_CONFIG=/absolute/path/config.json
|
||||
- Windows 是否误以为能自动发现任务计划程序；
|
||||
- Agent 日志是否出现 HTTP 400 或 JSON 解析错误。
|
||||
|
||||
### 14.5 “立即运行”按钮不可用
|
||||
Windows 机器的 `scripts: []` 不会自动变成任务计划程序或影刀应用列表。影刀场景必须选择附录 A 的自定义采集器，或由负责人把每个应用人工配置为标准 Agent 脚本。
|
||||
|
||||
### 14.6 “立即运行”按钮不可用
|
||||
|
||||
页面会给出具体原因。重点检查 Agent 是否在线、脚本是否有 `command`，以及是否明确设置了 `"allowManualRun": true`。
|
||||
|
||||
### 14.6 结果文件明明存在，但页面显示失败
|
||||
### 14.7 结果文件明明存在，但页面显示失败
|
||||
|
||||
使用运行 Agent 的同一个系统账号检查文件权限、路径、更新时间和大小。相对路径容易受启动目录影响，`resultCheck.path` 必须使用绝对路径。
|
||||
|
||||
### 14.7 页面显示“最近成功”，但 Agent 离线
|
||||
### 14.8 页面显示“最近成功”，但 Agent 离线
|
||||
|
||||
“最近成功”表示脚本历史上的最后一次结果；“Agent 离线”表示机器当前没有继续上报，两者含义不同。先恢复 Agent，再判断脚本是否仍在正常执行。
|
||||
|
||||
### 14.9 返回 HTTP 400、403、404 或 405
|
||||
|
||||
- `400 / VALIDATION_003`：请求体格式错误；标准 Agent 检查 `config.json` 中的枚举、数字和 JSON 语法，自定义采集器按附录 A 对照；
|
||||
- `403`：请求被安全策略拒绝，保留完整响应正文和请求 ID 后联系平台负责人；
|
||||
- `404`：请求地址错误，自定义程序通常仍在使用旧接口；标准 Agent 不应自行修改接口路径；
|
||||
- `405`：实际请求方法不是 `POST`，浏览器地址栏直接打开接口得到 405 不能证明上报程序的 POST 请求正确。
|
||||
|
||||
### 14.10 JSON 配置无法读取
|
||||
|
||||
常见原因是 Windows 路径只写了一个反斜杠、复制了 Markdown 链接、Token 中出现 `\_`、末尾多逗号或使用了中文引号。使用文本编辑器保存为 UTF-8 JSON；不要使用 Word 编辑。可以在 Agent 目录执行以下命令验证 JSON 语法：
|
||||
|
||||
```powershell
|
||||
Get-Content -LiteralPath '.\config.json' -Raw | ConvertFrom-Json | Out-Null
|
||||
Write-Host 'config.json 语法正确'
|
||||
```
|
||||
|
||||
### 14.11 统一故障反馈模板
|
||||
|
||||
安装人员反馈问题时一次提供以下内容，避免只说“失败了”：
|
||||
|
||||
```text
|
||||
机器名称：
|
||||
操作系统及版本：
|
||||
选择的接入方式：标准 Agent / 自定义采集器
|
||||
Node.js 版本：
|
||||
网络模式：intranet / internet / auto
|
||||
执行时间（含时区）：
|
||||
执行的命令：
|
||||
预期脚本数量：
|
||||
Agent 实际发现/上报数量：
|
||||
最终 HTTP 方法和 URL（自定义采集器必填）：
|
||||
HTTP 状态码：
|
||||
完整响应正文或报错：
|
||||
最近 30 行 Agent 日志：
|
||||
```
|
||||
|
||||
反馈中禁止包含完整 `agentToken`、完整 `Authorization` 请求头或未脱敏的 `config.json`。如果必须说明凭据是否一致，只保留 Agent ID，Token 最多保留前后各 2 位并遮盖中间内容。
|
||||
|
||||
## 15. 升级 Agent
|
||||
|
||||
升级时只替换这些程序文件：
|
||||
只有平台负责人明确通知新版本时才升级，不要自行使用不明来源文件。升级时只替换这些程序文件：
|
||||
|
||||
```text
|
||||
agent.mjs
|
||||
@ -546,7 +687,9 @@ Windows：结束并重新运行对应任务计划，然后在平台确认一个
|
||||
|
||||
## 17. 单机完成清单
|
||||
|
||||
- [ ] 已明确选择标准 Agent 或自定义采集器，未使用同一凭据同时运行两种上报程序；
|
||||
- [ ] 平台为本机生成了独立凭据；
|
||||
- [ ] 已拿到本机脚本清单，实际脚本数量有明确依据；
|
||||
- [ ] `config.json` 未使用示例 Token，文件权限已收紧；
|
||||
- [ ] 网络模式和平台地址与机器实际网络一致；
|
||||
- [ ] 所有脚本都有唯一 key、清晰名称和正确工作目录；
|
||||
@ -561,7 +704,21 @@ Windows：结束并重新运行对应任务计划，然后在平台确认一个
|
||||
|
||||
## 附录 A：自定义采集器 HTTP API 契约
|
||||
|
||||
本附录适用于影刀等已有采集程序直接向平台推送数据的场景。使用官方 `agent.mjs` 时，不需要手工拼接这些请求；只需填写第 7 节的 `config.json`，Agent 会自动补全接口路径和 `connectionKind`。
|
||||
本附录适用于影刀等已有采集程序直接向平台推送数据的场景，执行人必须能够修改并调试采集程序。普通安装人员如果只能安装软件、不能修改代码，应停止在本附录继续尝试，改用标准 Agent 或把本附录交给采集程序开发人员。
|
||||
|
||||
使用官方 `agent.mjs` 时，不需要手工拼接这些请求；只需填写第 7 节的 `config.json`，Agent 会自动补全接口路径和 `connectionKind`。自定义采集器投入运行后，不得再使用同一组凭据启动官方 Agent。
|
||||
|
||||
### A.0 按顺序完成联调
|
||||
|
||||
不要一开始同时推送 16 个应用、17 条日志和手动运行。按以下顺序逐项验收，前一步未达到预期时不要进入下一步：
|
||||
|
||||
1. 使用 1 个真实影刀应用调用 `/report`，确认 HTTP 200，平台显示 1 个脚本；
|
||||
2. 改为上报全部 16 个应用，确认平台数量为 16，13 个有可靠成功记录的任务为 `SUCCESS`，其余为 `UNKNOWN`；
|
||||
3. 使用 1 条真实任务日志调用 `/run`，确认页面出现运行记录；
|
||||
4. 再补传其余日志，每条使用稳定唯一的 `externalRunId`；
|
||||
5. 最后才实现 `/commands/claim` 和平台手动运行；不需要手动运行时保持 `canManualRun: false`。
|
||||
|
||||
每一步都必须记录最终请求方法、最终 URL、HTTP 状态码和完整响应正文。只记录程序内部的 `success=False` 不算有效验收证据。
|
||||
|
||||
### A.1 接口和认证头
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user