[comment]: # translation:outdated

[comment]: # ({e4e11bc3-542796d3})
# 3 脚本

[comment]: # ({/e4e11bc3-542796d3})

[comment]: # ({197a4c77-58923c7d})
#### 概述

在 *Alerts > Scripts* 部分，可以配置和维护用户自定义的全局脚本。

根据已配置的作用范围以及用户权限，全局脚本可用于执行：

-   可从多个前端位置的 [主机菜单](/manual/web_interface/menu/host_menu) 中执行（*Dashboard*、*Problems*、*Latest data*、*Maps* 等）
-   可从 [事件菜单](/manual/web_interface/menu/event_menu) 中执行
-   可作为动作操作运行

脚本会在 Zabbix agent、Zabbix 服务器（proxy）或仅在 Zabbix 服务器上执行
另请参见 [命令执行](/manual/appendix/command_execution)。

在 Zabbix agent 和 Zabbix proxy 上，远程脚本默认均处于禁用状态。
可通过以下方式启用：

-   对于在 Zabbix agent 上执行的远程命令：
    - 在 agent 配置中为每个允许的命令添加 `AllowKey=system.run[<command>,\*]` 参数，`\*` 表示 wait 和 nowait 模式；
-   对于在 Zabbix proxy 上执行的远程命令：
    - **警告：如果远程命令是在由 Zabbix proxy 监控的 Zabbix agent 上执行，则无需在 Zabbix proxy 上启用远程命令。** 但是，如果确实需要在 Zabbix proxy 上执行远程命令，请在 proxy 配置中将 *EnableRemoteCommands* 参数设置为 '1'。

可通过在 [服务器配置](/manual/appendix/config/zabbix_server) 中设置 `EnableGlobalScripts=0` 来禁用 Zabbix 服务器上的全局脚本执行。
对于新安装，从 Zabbix 7.0 开始，Zabbix 服务器上的全局脚本执行默认处于禁用状态。

系统会显示现有脚本及其详细信息列表。

![](../../../../../assets/en/manual/web_interface/scripts.png){width="600"}

显示的数据：

|Column|Description|
|--|--------|
|*Name*|脚本名称。单击脚本名称会打开脚本[配置表单](scripts#configuring-a-global-script)。|
|*Scope*|脚本的作用范围 - 动作操作、手动主机操作或手动事件操作。此设置决定脚本可用的位置。|
|*Used in actions*|显示使用该脚本的所有动作，（自 Zabbix 7.0.4 起）前面会标注这些动作的总数。<br>单击动作名称会打开动作配置表单。如果用户没有该动作的权限，则名称不可点击。|
|*Type*|显示脚本类型 - *URL*、*Webhook*、*Script*、*SSH*、*Telnet* 或 *IPMI* 命令。|
|*Execute on*|显示脚本将在 Zabbix agent、Zabbix proxy 或服务器上执行，还是仅在 Zabbix 服务器上执行。|
|*Commands*|显示脚本中要执行的所有命令。<br>webhook 不显示此项内容。|
|*User group*|显示该脚本可供使用的用户组（或对所有用户组显示 *All*）。|
|*Host group*|显示该脚本适用的主机组（或对所有主机组显示 *All*）。|
|*Host access*|显示主机组的权限级别 - *Read* 或 *Write*。只有具有所需权限级别的用户才能执行该脚本。|

要配置新脚本，请单击右上角的 *Create script* 按钮。

[comment]: # ({/197a4c77-58923c7d})

[comment]: # ({c3aba318-44c45ea0})
##### 批量编辑选项

列表下方的一个按钮提供了一项批量编辑选项：

-   *删除* - delete 脚本

要使用此选项，请在相应脚本前的复选框中打勾，然后点击 *删除*。

[comment]: # ({/c3aba318-44c45ea0})

[comment]: # ({3804292d-1c5dd978})
##### 使用过滤器

您可以使用过滤器仅显示您感兴趣的脚本。
为了获得更好的搜索性能，搜索数据时不会解析宏。

*Filter* 链接位于脚本列表上方。
单击该链接后，会显示一个过滤器，您可以按名称和范围筛选脚本。

![](../../../../../assets/en/manual/web_interface/script_filter.png){width="600"}

[comment]: # ({/3804292d-1c5dd978})

[comment]: # ({88c26402-201a0633})
#### 配置全局脚本

![](../../../../../assets/en/manual/web_interface/script.png){width="600"}

::: noteclassic
建议在全局脚本中使用[宏函数](/manual/config/macros/macro_functions)而不是普通宏，以增强安全性，因为宏不会自动转义。
:::

脚本属性：

|Parameter|<|Description|
|-|----------|----------------------------------------|
|*Name*|<|脚本的唯一名称。<br>例如：`Clear /tmp filesystem`|
|*Scope*|<|脚本的范围 - 动作操作、手动主机操作或手动事件操作。此设置决定脚本可在何处使用 - 分别用于动作操作中的远程命令、从[主机菜单](/manual/web_interface/menu/host_menu)或从[事件菜单](/manual/web_interface/menu/event_menu)中使用。<br>将范围设置为“Action operation”后，脚本可供所有有权访问 *Alerts* > *Actions* 的用户使用。<br>如果脚本实际已在某个动作中使用，则其范围不能再更改为“action operation”之外的其他值。<br>**宏支持**<br>范围会影响可用宏的范围。例如，支持与用户相关的宏（{USER.\*}）用于脚本中，以便传递启动脚本的用户信息。但是，如果脚本范围为 action operation，则不支持这些宏，因为动作操作是自动执行的。<br>{MANUALINPUT} 宏允许在脚本执行时指定手动输入。它支持手动主机操作和手动事件操作脚本。<br>要了解还支持哪些其他宏，请在[支持的宏](/manual/appendix/macros/supported_by_location)表中搜索“Trigger-based notifications and commands/Trigger-based commands”、“Manual host action scripts”和“Manual event action scripts”。请注意，如果某个宏解析后的值可能包含空格（例如主机名），请务必按需加引号。|
|*Menu path*|<|脚本的目标菜单路径。例如，`Default` 或 `Default/` 会将脚本显示在相应目录中。菜单可以嵌套，例如 `Main menu/Sub menu1/Sub menu2`。通过监控部分中的主机/事件菜单访问脚本时，它们将按照给定目录进行组织。<br>仅当 *Scope* 选择“Manual host action”或“Manual event action”时，才显示此字段。|
|*Type*|<|点击相应按钮选择脚本类型：<br>**URL**、**Webhook**、**Script**、**SSH**、**Telnet** 或 **[IPMI](/manual/config/notifications/action/operation/remote_command#ipmi-remote-commands)** 命令。<br>仅当 *Scope* 选择“Manual host action”或“Manual event action”时，**URL** 类型才可用。 |
| |脚本类型：**URL**|<|
|^|*URL*|指定用于从[主机菜单](/manual/web_interface/menu/host_menu)或[事件菜单](/manual/web_interface/menu/event_menu)快速访问的 URL。<br>支持[宏](/manual/appendix/macros/supported_by_location)和自定义[用户宏](/manual/config/macros/user_macros)。宏支持取决于脚本的范围（见上面的 *Scope*）。<br>在此字段中使用 {MANUALINPUT} 宏，以便在脚本执行时指定手动输入，例如：<br>`http://{MANUALINPUT}/zabbix/zabbix.php?action=dashboard.view`<br>宏值不得进行 URL 编码。 |
|^|*Open in new window*|确定 URL 是在新的浏览器标签页中打开，还是在同一标签页中打开。|
| |脚本类型：**Webhook**|<|
|^|*Parameters*|以属性-值对的形式指定 webhook 变量。<br>另请参见：[Webhook](/manual/config/notifications/media/webhook) 媒介配置。<br>参数值支持[宏](/manual/appendix/macros/supported_by_location)和自定义[用户宏](/manual/config/macros/user_macros)。宏支持取决于脚本的范围（见上面的 *Scope*）。|
|^|*Script*|在参数字段中单击，或单击其旁边的铅笔图标时打开的模态编辑器中输入 JavaScript 代码。<br>宏支持取决于脚本的范围（见上面的 *Scope*）。<br>另请参见：[Webhook](/manual/config/notifications/media/webhook) 媒介配置、[Additional Javascript objects](/manual/config/items/preprocessing/javascript/javascript_objects)。|
|^|*Timeout*|JavaScript 执行超时时间（1-60 秒，默认 30 秒）。<br>支持时间后缀，例如 30s、1m。|
| |脚本类型：**Script**|<|
|^|*Execute on*|点击相应按钮，将 shell 脚本执行在：<br>**Zabbix agent** - 如果目标主机上的 system.run 监控项已被[允许](/manual/config/items/restrict_checks)，则脚本将由 Zabbix agent 执行<br>**Zabbix proxy or server** - 脚本将由 Zabbix proxy 或服务器执行，具体取决于该主机是由 proxy 还是服务器监控。<br>如果已通过 [EnableRemoteCommands](/manual/appendix/config/zabbix_proxy#enableremotecommands) 启用，则会在 proxy 上执行。<br>如果已通过 [EnableGlobalScripts](/manual/appendix/config/zabbix_server#enableglobalscripts) 服务器参数启用全局脚本，则会在服务器上执行。<br>**Zabbix server** - 脚本仅由 Zabbix 服务器执行。<br>如果通过 [EnableGlobalScripts](/manual/appendix/config/zabbix_server#enableglobalscripts) 服务器参数禁用了全局脚本，则此选项不可用。|
|^|*Commands*|输入要在脚本中执行的命令的完整路径。<br>宏支持取决于脚本的范围（见上面的 *Scope*）。支持自定义[用户宏](/manual/config/macros/user_macros)。|
| |脚本类型：**SSH**|<|
|^|*Authentication method*|选择认证方法 - 密码或公钥。|
|^|*Username*|输入用户名。|
|^|*Password*|输入密码。<br>仅当选择“Password”作为认证方法时，此字段可用。|
|^|*Public key file*|输入公钥文件路径。<br>仅当选择“Public key”作为认证方法时，此字段可用。|
|^|*Private key file*|输入私钥文件路径。<br>仅当选择“Public key”作为认证方法时，此字段可用。|
|^|*Passphrase*|输入口令。<br>仅当选择“Public key”作为认证方法时，此字段可用。|
|^|*Port*|输入 Zabbix 将连接的目标主机上的远程 SSH 服务端口。|
|^|*Commands*|输入命令。<br>宏支持取决于脚本的范围（见上面的 *Scope*）。支持自定义[用户宏](/manual/config/macros/user_macros)。|
| |脚本类型：**Telnet**|<|
|^|*Username*|输入用户名。|
|^|*Password*|输入密码。|
|^|*Port*|输入 Zabbix 将连接的目标主机上的远程 Telnet 服务端口。|
|^|*Commands*|输入命令。<br>宏支持取决于脚本的范围（见上面的 *Scope*）。支持自定义[用户宏](/manual/config/macros/user_macros)。|
| |脚本类型：**IPMI**|<|
|^|*Command*|输入 IPMI 命令。<br>宏支持取决于脚本的范围（见上面的 *Scope*）。支持自定义[用户宏](/manual/config/macros/user_macros)。|
|*Description*|<|输入脚本描述。|
|*Host group*|<|选择脚本可用的主机组（或选择 *All* 表示所有主机组）。|
|*User group*|<|选择脚本可供使用的用户组（或选择 *All* 表示所有用户组）。<br>仅当 *Scope* 选择“Manual host action”或“Manual event action”时，才显示此字段。|
|*Required host permissions*|<|选择主机组所需的权限级别 - *Read* 或 *Write*。只有具有所需权限级别的用户才能执行该脚本。<br>仅当 *Scope* 选择“Manual host action”或“Manual event action”时，才显示此字段。|
|*Advanced configuration*|<|单击 *Advanced configuration* 标题可显示[高级配置](#advanced-configuration)选项。<br>仅当 *Scope* 选择“Manual host action”或“Manual event action”时，才显示此字段。|

[comment]: # ({/88c26402-201a0633})

[comment]: # ({cdcf3a33-71b76cf1})
#### 高级配置

高级配置选项位于可折叠的 *高级配置（Advanced configuration）* 部分中：

![](../../../../../assets/en/manual/web_interface/script_advanced.png){width="600"}

| 参数 | 描述 |
|----------|----------------------------------------|
| *Enable user input* | 勾选此复选框以在执行脚本前启用手动用户输入。<br>手动用户输入将替换脚本中的 {MANUALINPUT} 宏值。<br>另请参阅：[手动用户输入](#manual-user-input)。 |
| *Input prompt* | 输入自定义文本以提示用户进行自定义输入。该文本将显示在 *手动输入（Manual input）* 弹出窗口中的输入字段上方。<br>要预览 *手动输入（Manual input）* 弹出窗口，请点击 *测试用户输入（Test user input）*。预览还允许测试输入的 string 是否符合输入验证规则（见以下参数）。<br>宏和用户宏的支持取决于脚本的作用域（参见通用脚本配置参数中的 *作用域（Scope）*）。 |
| *Input type* | 选择手动输入类型：<br>**string** - 单个 string；<br>**下拉框（Dropdown）** - 从多个下拉选项中选择值。 |
| *Dropdown options* | 在逗号分隔的列表中输入用户输入下拉框的唯一值。<br>要在下拉框中包含一个空选项，请在列表的开头、中间或末尾添加一个额外的逗号。<br>仅当选择“下拉框（Dropdown）”作为 *输入类型（Input type）* 时，此字段才会显示。 |
| *Default input string* | 输入用户输入的默认 string（或不输入）。<br>此处输入的值将根据 *输入验证规则（Input validation rule）* 字段中提供的正则表达式进行验证。<br>此处输入的值将在 *手动输入（Manual input）* 弹出窗口中默认显示。<br>仅当选择“string”作为 *输入类型（Input type）* 时，此字段才会显示。 |
| *Input validation rule* | 输入正则表达式以验证用户输入的 string。<br>支持全局正则表达式。<br>仅当选择“string”作为 *输入类型（Input type）* 时，此字段才会显示。 |
| *Enable confirmation* | 勾选此复选框以在执行脚本前显示确认消息。此功能可能在执行潜在危险操作（如重启脚本）或耗时较长的操作时特别有用。 |
| *Confirmation text* | 输入自定义确认文本以用于上方复选框启用的确认弹出窗口（例如，*远程系统将被重启。您确定吗？*）。要查看文本的显示效果，请点击字段旁边的 *测试确认（Test confirmation）*。<br>支持 [Macros](/manual/appendix/macros/supported_by_location) 和自定义 [user macros](/manual/config/macros/user_macros)。<br>*注意：* 测试确认消息时，宏不会展开。 |
如果同时配置了手动用户输入和确认消息，它们将在连续的弹出窗口中显示。

[comment]: # ({/cdcf3a33-71b76cf1})

[comment]: # ({90545584-346cf40f})
#### 手动用户输入

手动用户输入允许在每次执行脚本时提供一个自定义参数。
这样就无需创建多个类似的用户脚本，仅仅因为参数不同。

例如，您可能希望在执行期间向脚本提供不同的整数或不同的 URL 地址。

要启用手动用户输入：

-   在需要的位置于脚本（命令、脚本、脚本参数）中使用 {MANUALINPUT} 宏；或者在 URL 脚本的 URL 字段中使用；
-   在[高级脚本配置](#advanced-configuration)中，启用手动用户输入并配置输入选项。

启用用户输入后，在脚本执行之前，用户会看到一个 *Manual input* 弹窗，要求提供自定义值。
所提供的值将替换脚本中的 {MANUALINPUT}。

根据配置不同，系统会要求用户输入一个字符串值：

![](../../../../../assets/en/manual/web_interface/manual_input_field.png)

或者从预定义选项的下拉列表中选择一个值：

![](../../../../../assets/en/manual/web_interface/manual_input_field2.png)

手动用户输入仅适用于作用域为“Manual host action”或“Manual event action”的脚本。

[comment]: # ({/90545584-346cf40f})

[comment]: # ({a5032892-ca68e16a})
#### 脚本执行和结果

由 Zabbix 服务器运行的脚本会按照 [命令执行页面](/manual/appendix/command_execution) 中描述的顺序执行。

脚本结果会显示在脚本运行后出现的弹出窗口中。
脚本的返回值为标准输出：

-   如果脚本成功完成（[退出码](/manual/appendix/command_execution#exit-code-checking) `0`），返回值限制为 16MB（包括会被截断的尾随空白字符）。
-   如果脚本以错误退出（非零退出码），返回值为标准错误，限制为 2KB。

Zabbix 默认不会存储扩展的脚本输出。
要保留完整的输出详情，您可以在脚本内部实现日志记录（例如，将输出重定向到本地日志文件）。

请注意，对于在 Zabbix 服务器或 Zabbix proxy 上执行的脚本，也同样适用 [数据库限制](/manual/config/items/item#text-data-limits)。

下面是脚本及其结果窗口的示例：

```bash
uname -v
/tmp/non_existing_script.sh
echo "This script was started by {USER.USERNAME}"
```

![](../../../../../assets/en/manual/web_interface/frontend_sections/administration/script_result.png)

脚本结果不会显示脚本本身。

[comment]: # ({/a5032892-ca68e16a})

[comment]: # ({e2de8f0f-5b600786})
#### Zabbix agent 上的脚本超时

您可能会遇到在执行脚本时发生超时的情况。

下面是一个在 Zabbix agent 上运行脚本及其结果窗口的示例：

```bash
sleep 5
df -h
```

![](../../../../../assets/en/manual/web_interface/frontend_sections/administration/script_timeout_1.png)

在这种情况下，错误信息如下：

```default
Timeout while executing a shell script.
```

为避免此类情况，建议优化脚本本身（在上面的示例中是“5”），而不是调整 [Zabbix agent 配置](/manual/appendix/config/zabbix_agentd#timeout) 和 [Zabbix 服务器配置](/manual/appendix/config/zabbix_server#timeout) 中的 `Timeout` 参数。

如果已在 [Zabbix agent 配置](/manual/appendix/config/zabbix_agentd) 中更改了 `Timeout` 参数，则会出现以下错误信息：

```default
Get value from agent failed: ZBX_TCP_READ() timed out.
```

这意味着修改已在 [Zabbix agent 配置](/manual/appendix/config/zabbix_agentd) 中完成，但还需要同时修改 [Zabbix 服务器配置](/manual/appendix/config/zabbix_server) 中的 `Timeout` 参数。

[comment]: # ({/e2de8f0f-5b600786})

[comment]: # ({9970c016-f4f6f7e1})
#### 活动 agent 上的脚本超时

只能在以主动模式运行的 agent 上执行 [脚本](/manual/web_interface/frontend_sections/alerts/scripts)（自 Zabbix 7.0 起）。
一旦脚本执行由动作 [操作](/manual/config/notifications/action/operation) 或手动脚本执行触发，该命令就会包含在主动检查配置中，并在活动 agent 收到后执行。

手动脚本会连同用于脚本执行的服务器/proxy 超时一起发送给活动 agent。请增加默认的 [服务器](/manual/appendix/config/zabbix_server#timeout)/[proxy](/manual/appendix/config/zabbix_proxy#timeout) 脚本执行超时时间。
该超时时间必须高于主动检查刷新频率，否则在活动 agent 收到脚本并能够返回结果之前，就会发生超时。

[comment]: # ({/9970c016-f4f6f7e1})

[comment]: # ({b2fcdb2b-0b38e381})
#### Zabbix 服务器/proxy 上的脚本超时

请看下面在 Zabbix 服务器上运行脚本及其结果窗口的示例：

```bash
sleep 11
df -h
```

![](../../../../../assets/en/manual/web_interface/frontend_sections/administration/script_timeout_3.png)

还建议优化脚本本身（而不是通过修改 [Zabbix 服务器配置](/manual/appendix/config/zabbix_server) 来将 `TrapperTimeout` 参数调整为相应的值（在我们的示例中，> `11`））。

[comment]: # ({/b2fcdb2b-0b38e381})