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

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

[comment]: # ({61181e12-58923c7d})
#### 概述

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

此菜单仅对 [SuperAdmin](/manual/config/users_and_usergroups/permissions) 类型的用户可用。

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

-   从各种前端位置（*仪表板*、*问题*、*最新数据*、*地图* 等）的 [主机菜单](/manual/web_interface/menu/host_menu)
-   从 [事件菜单](/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/concepts/server/server_params) 中设置 `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*|将显示使用该脚本的所有动作，并在前面标注这些动作的总数。<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]: # ({/61181e12-58923c7d})

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

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

-   *删除* - 删除脚本

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

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

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

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

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

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

[comment]: # ({/38c09c27-1c5dd978})

[comment]: # ({c3e70269-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>要了解还支持哪些其他宏，请在[supported macro](/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/concepts/proxy/proxy_params#enableremotecommands) 启用，则会在 proxy 上执行。<br>如果通过服务器参数 [EnableGlobalScripts](/manual/concepts/server/server_params#enableglobalscripts) 启用全局脚本，则会在服务器上执行。<br>**Zabbix server** - 脚本仅由 Zabbix 服务器执行。<br>如果通过服务器参数 [EnableGlobalScripts](/manual/concepts/server/server_params#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]: # ({/c3e70269-201a0633})

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

可在可折叠的 *高级配置* 部分中使用高级配置选项：

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

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

如果同时配置了手动用户输入和确认消息，它们将按顺序显示在连续的弹窗中。

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

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

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

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

要启用手动用户输入：

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

启用用户输入后，在脚本执行之前，将向用户显示一个*手动输入*弹出窗口，要求其提供自定义值。  
提供的值将替换脚本中的 {MANUALINPUT}。

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

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

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

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

手动用户输入仅适用于作用域为“手动主机操作”或“手动事件操作”的脚本。

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

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

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

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

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

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

请注意，对于在 Zabbix 服务器或 Zabbix proxy 上执行的脚本，[数据库限制](/manual/config/items/item#item-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]: # ({/9e2bfd47-ca68e16a})

[comment]: # ({6447bc3c-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/concepts/agent/agentd_params#timeout) 和 [Zabbix 服务器配置](/manual/concepts/server/server_params#timeout) 中的 `Timeout` 参数。

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

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

这意味着已在 [Zabbix agent 配置](/manual/concepts/agent/agentd_params) 中进行了修改，但还需要同时修改 [Zabbix 服务器配置](/manual/concepts/server/server_params) 中的 `Timeout` 参数。

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

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

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

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

[comment]: # ({/9a94b46e-f4f6f7e1})

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

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

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

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

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

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