Merge pull request #200 from flashcatcloud/doc-review/2026-07-22-monit-agent-sync

docs: sync monit-agent target guides

Author: UlricQin

en/monitors/targets/configure-targets.mdx

@@ -51,7 +51,6 @@ host:
 
   shell_exec:
     enabled: true
-    pipeline_max_segments: 3
     default_max_lines: 200
     cat_max_file_size: 20971520
     user_allow_list: []
@@ -67,10 +66,6 @@ mongodb: []
 mongodb_mongos: []
 kafka: []
 elasticsearch: []
-
-script_tool:
-  enabled: false
-  dir: /opt/monit-agent/tools.d
 ```
 
 ## locator_mappings
@@ -121,7 +116,6 @@ Recommendations:
 host:
   shell_exec:
     enabled: true
-    pipeline_max_segments: 3
     default_max_lines: 200
     cat_max_file_size: 20971520
     user_allow_list: []
@@ -130,7 +124,10 @@ host:
 Recommendations:
 
 - Keep `enabled: true` when AI-SRE needs live host diagnostics. Only controlled shell commands can be executed.
-- If some shell commands are blocked by built-in guardrails, add them manually to `user_allow_list` only after confirming that they are safe, read-only, and do not expose sensitive information.
+- If a command is occasionally blocked, local root can [approve that command](/en/monitors/targets/install-agent#approve-a-blocked-shell-command).
+- For a command that needs to run repeatedly, add the complete command to `user_allow_list` only after confirming that it is safe, read-only, and does not expose sensitive information.
+
+Neither human approval nor `user_allow_list` can allow high-risk operations such as shutdown, reboot, system destruction, or reading sensitive credentials.
 
 To urgently disable a tool, use `tool_policy.disabled_tools`:
 
@@ -140,6 +137,8 @@ tool_policy:
     - shell.exec
 ```
 
+After changing `shell_exec.enabled` or `tool_policy.disabled_tools`, send SIGHUP to reload the configuration. The change takes effect without restarting the Agent.
+
 ## MySQL
 
 To diagnose MySQL, add instance configuration under `mysql:`. Use a read-only MySQL account, and preferably store the password in a separate credential file:
@@ -499,15 +498,3 @@ ES_PASSWORD=<ES_PASSWORD>
 | `credential` | If Elasticsearch security authentication is disabled, credential can be omitted. Configure a read-only account in production. |
 
 Elasticsearch does not use `locator_mappings`. The Agent automatically obtains `cluster_name` from the cluster and uses it as the object address in the console.
-
-## script_tool
-
-`script_tool` is used to add custom script tools. Most users can keep it disabled:
-
-```yaml
-script_tool:
-  enabled: false
-  dir: /opt/monit-agent/tools.d
-```
-
-Enable it only when you need custom diagnostic capabilities and can confirm that the script source and directory permissions are controlled.

en/monitors/targets/install-agent.mdx

@@ -13,7 +13,7 @@ Prepare the following information before installation:
 | Item | Description |
 |---|---|
 | Agent package download URL | `https://static.flashcat.cloud/monitagent/monitagent-v0.0.27-linux-amd64.tar.gz`. For ARM CPUs, replace `amd64` with `arm64`. |
-| Edge address | For example, `ws://edge.example.com:6868` or `wss://edge.example.com:6868`. Edge version must be `>= v0.46.0`. View the Edge list and installation method [here](https://console.flashcat.cloud/monit/engine/list). |
+| Edge address | For example, `ws://edge.example.com:6868` or `wss://edge.example.com:6868`. Edge version must be `>= v0.47.0`. View the Edge list and installation method [here](https://console.flashcat.cloud/monit/engine/list). |
 | Local host object address | Use the current host's fixed private IP or DNS name, such as `10.0.1.12`. If omitted, the Agent uses the IP address associated with the local default route. |
 | Read-only accounts for databases and middleware | To diagnose MySQL, Redis, PostgreSQL, MongoDB, Kafka, Elasticsearch, and other services, prepare read-only accounts and credentials in advance. |
 
@@ -132,6 +132,30 @@ If you modify the Edge address, Basic Auth, TLS parameters, or `hostLocator`, re
 sudo systemctl kill -s HUP monitagent
 ```
 
+## Approve a blocked Shell command
+
+`shell.exec` automatically runs read-only diagnostic commands that meet its built-in safety rules. If a command does not pass the automatic rules but you have confirmed that it is appropriate for the current machine, sign in to the Linux host running the Agent and open an approval session as root:
+
+```bash
+sudo /opt/monit-agent/monitagent shell-approval
+```
+
+After the session connects, it displays a waiting status. When commands need approval, the terminal shows only the commands and a ten-second countdown:
+
+- Press Enter to approve every command in the current batch.
+- Press `n` to reject every command in the current batch.
+- If you do not respond within ten seconds, the batch is rejected automatically. Concurrent commands that arrive later are queued and receive a full ten-second window after they are displayed.
+- Input while no command is pending does not execute anything; the terminal continues to display the waiting status.
+- Press `Ctrl-C` to close the approval session.
+
+Only one approval session can be active for an Agent. To take over an existing session, run:
+
+```bash
+sudo /opt/monit-agent/monitagent shell-approval --replace
+```
+
+Only root can open or replace a session. Pending commands are rejected if the Agent restarts or the session disconnects, and you must open a new session after a restart. High-risk operations such as shutdown, reboot, system destruction, or reading sensitive credentials cannot be enabled through human approval.
+
 ## Next step
 
 After the Agent starts successfully, a host object usually appears on the monitoring object page within a few seconds. Next, read [Configure Monitoring Objects](/en/monitors/targets/configure-targets) to add database and middleware objects in `agent.yaml`.

en/monitors/targets/overview.mdx

@@ -81,6 +81,6 @@ After objects appear, enable controlled query tools such as `mysql.query`, `redi
     Prepare the Edge address, download the Agent, and start it in the foreground or as a system service.
   </Card>
   <Card title="Configure Monitoring Objects" icon="sliders" href="/en/monitors/targets/configure-targets">
-    Configure hosts, databases, middleware, and custom script tools.
+    Configure hosts, databases, middleware, and controlled diagnostic tools.
   </Card>
 </CardGroup>

en/monitors/targets/reload-and-verify.mdx

@@ -10,7 +10,7 @@ Different `monit-agent` configuration changes take effect in different ways. Thi
 
 | Change | How it takes effect |
 |---|---|
-| Host collection, MySQL, Redis, PostgreSQL, MongoDB, Kafka, Elasticsearch, and other configurations in `agent.yaml` | Send SIGHUP to reload |
+| Host collection, tool switches, MySQL, Redis, PostgreSQL, MongoDB, Kafka, Elasticsearch, and other configurations in `agent.yaml` | Send SIGHUP to reload |
 | Edge address, Basic Auth, TLS, `hostLocator`, audit directory | Restart the Agent |
 
 Send SIGHUP:
@@ -29,6 +29,8 @@ sudo systemctl restart monitagent
 If you only add or adjust object configuration in `agent.yaml`, use SIGHUP reload first. Restart is needed only when startup parameters or service-level parameters change.
 </Note>
 
+After changing tool switches, a successful reload updates the diagnostic tools currently available from the Agent. No restart is required.
+
 ## Verify successful onboarding
 
 After the Agent starts, a host object usually appears on the monitoring object page within a few seconds.

zh/monitors/targets/configure-targets.mdx

@@ -51,7 +51,6 @@ host:
 
   shell_exec:
     enabled: true
-    pipeline_max_segments: 3
     default_max_lines: 200
     cat_max_file_size: 20971520
     user_allow_list: []
@@ -67,10 +66,6 @@ mongodb: []
 mongodb_mongos: []
 kafka: []
 elasticsearch: []
-
-script_tool:
-  enabled: false
-  dir: /opt/monit-agent/tools.d
 ```
 
 ## locator_mappings
@@ -121,7 +116,6 @@ locator_mappings:
 host:
   shell_exec:
     enabled: true
-    pipeline_max_segments: 3
     default_max_lines: 200
     cat_max_file_size: 20971520
     user_allow_list: []
@@ -130,7 +124,10 @@ host:
 建议：
 
 - 需要 AI-SRE 做主机现场诊断时，保持 `enabled: true`。只有受控的 shell 才能执行，放心开启。
-- 如果发现有些 shell 被内置护栏阻断，可以手工添加到 `user_allow_list`。只有确认命令安全、只读、不会输出敏感信息时才添加。
+- 命令偶尔被拦截时，可以由本机 root [人工审批该命令](/zh/monitors/targets/install-agent#人工审批被拦截的-shell-命令)。
+- 对于需要长期重复使用的命令，确认其安全、只读且不会输出敏感信息后，再将完整命令添加到 `user_allow_list`。
+
+人工审批和 `user_allow_list` 都不能放开关机、重启、破坏系统或读取敏感凭据等高危操作。
 
 如需紧急禁用某个工具，可以使用 `tool_policy.disabled_tools`：
 
@@ -140,6 +137,8 @@ tool_policy:
     - shell.exec
 ```
 
+修改 `shell_exec.enabled` 或 `tool_policy.disabled_tools` 后，发送 SIGHUP reload 即可生效，无需重启 Agent。
+
 ## MySQL
 
 如果需要诊断 MySQL，在 `mysql:` 中添加实例配置。推荐使用只读 MySQL 账号，并优先把密码放到独立凭据文件中：
@@ -499,15 +498,3 @@ ES_PASSWORD=<ES_PASSWORD>
 | `credential` | 如果 Elasticsearch 未启用安全认证，可以不配置。生产环境建议配置只读账号。 |
 
 Elasticsearch 不使用 `locator_mappings`，`cluster_name` 自动从集群获取作为页面上的对象地址。
-
-## script_tool
-
-`script_tool` 用于接入自定义脚本工具。普通用户可以保持关闭：
-
-```yaml
-script_tool:
-  enabled: false
-  dir: /opt/monit-agent/tools.d
-```
-
-只有在需要扩展自定义诊断能力，并且确认脚本来源和目录权限可控时，才建议开启。

zh/monitors/targets/install-agent.mdx

@@ -13,7 +13,7 @@ keywords: ["monit-agent", "Agent 安装", "Edge 地址", "系统服务", "监控
 | 准备项 | 说明 |
 |---|---|
 | Agent 安装包下载地址 | `https://static.flashcat.cloud/monitagent/monitagent-v0.0.27-linux-amd64.tar.gz`。如果是 arm 的 CPU，则把 `amd64` 换成 `arm64`。 |
-| Edge 地址 | 例如 `ws://edge.example.com:6868` 或 `wss://edge.example.com:6868`。Edge 版本需要 `>= v0.46.0`，Edge 列表和安装方法[点此查看](https://console.flashcat.cloud/monit/engine/list)。 |
+| Edge 地址 | 例如 `ws://edge.example.com:6868` 或 `wss://edge.example.com:6868`。Edge 版本需要 `>= v0.47.0`，Edge 列表和安装方法[点此查看](https://console.flashcat.cloud/monit/engine/list)。 |
 | 本机对象地址 | 建议使用当前主机的固定内网 IP 或 DNS 名称，例如 `10.0.1.12`。不指定的话默认会使用本机默认路由对应的 IP。 |
 | 数据库/中间件只读账号 | 如需诊断 MySQL、Redis、PostgreSQL、MongoDB、Kafka、Elasticsearch 等服务，需提前准备对应的只读账号和凭据。 |
 
@@ -132,6 +132,30 @@ sudo journalctl -u monitagent -f
 sudo systemctl kill -s HUP monitagent
 ```
 
+## 人工审批被拦截的 Shell 命令
+
+`shell.exec` 会自动执行符合内置安全规则的只读诊断命令。如果某条命令未通过自动规则，但你确认它可以在当前机器上执行，可以提前登录 Agent 所在的 Linux 主机，用 root 打开审批会话：
+
+```bash
+sudo /opt/monit-agent/monitagent shell-approval
+```
+
+审批会话连接成功后会显示等待提示。出现待审批命令时，终端只展示命令本身和 10 秒倒计时：
+
+- 按回车批准当前批次中的全部命令。
+- 按 `n` 拒绝当前批次中的全部命令。
+- 10 秒内没有操作时自动拒绝；并发到达的后续命令会排队，并在显示后获得完整的 10 秒审批时间。
+- 没有待审批命令时，输入不会触发执行，终端会继续显示等待状态。
+- 按 `Ctrl-C` 退出审批会话。
+
+同一台 Agent 同时只允许一个审批会话。如果已有会话且你需要接管，使用：
+
+```bash
+sudo /opt/monit-agent/monitagent shell-approval --replace
+```
+
+只有 root 可以打开或接管会话。Agent 重启或会话断开时，待审批命令会被拒绝；重启后需要重新打开会话。关机、重启、破坏系统或读取敏感凭据等高危操作不能通过人工审批放开。
+
 ## 下一步
 
 Agent 启动成功后，通常几秒内可以在监控对象页面看到一个主机对象。接下来可以继续阅读[配置监控对象](/zh/monitors/targets/configure-targets)，在 `agent.yaml` 中添加数据库和中间件对象。

zh/monitors/targets/overview.mdx

@@ -81,6 +81,6 @@ keywords: ["监控对象", "monit-agent", "AI-SRE", "对象接入", "现场诊
     准备 Edge 地址，下载 Agent，并配置前台启动或系统服务。
   </Card>
   <Card title="配置监控对象" icon="sliders" href="/zh/monitors/targets/configure-targets">
-    配置主机、数据库、中间件和自定义脚本工具。
+    配置主机、数据库、中间件和受控诊断工具。
   </Card>
 </CardGroup>

zh/monitors/targets/reload-and-verify.mdx

@@ -10,7 +10,7 @@ keywords: ["monit-agent", "配置生效", "SIGHUP", "重启 Agent", "接入验
 
 | 变更内容 | 生效方式 |
 |---|---|
-| `agent.yaml` 中的主机采集、MySQL、Redis、PostgreSQL、MongoDB、Kafka、Elasticsearch 等配置 | 发送 SIGHUP reload |
+| `agent.yaml` 中的主机采集、工具开关、MySQL、Redis、PostgreSQL、MongoDB、Kafka、Elasticsearch 等配置 | 发送 SIGHUP reload |
 | Edge 地址、Basic Auth、TLS、`hostLocator`、审计目录 | 重启 Agent |
 
 发送 SIGHUP：
@@ -29,6 +29,8 @@ sudo systemctl restart monitagent
 如果只是新增或调整 `agent.yaml` 中的对象配置，优先使用 SIGHUP reload。只有启动参数或服务级参数变化时才需要重启。
 </Note>
 
+修改工具开关后，成功 reload 即可更新 Agent 当前可用的诊断工具，无需重启。
+
 ## 验证接入是否成功
 
 启动 Agent 后，通常几秒内可以在监控对象页面看到一个主机对象。