[comment]: # translation:outdated

[comment]: # ({39c4b215-26ad891b})
# 10 环境变量

[comment]: # ({/39c4b215-26ad891b})

[comment]: # ({5b980b7e-72128caf})
#### 概述

环境变量允许在不将值硬编码到配置文件中的情况下配置 Zabbix 组件。
这使得在动态环境中管理配置变得更加容易，例如 Docker，在这类环境中可以在运行时传递变量，以适应不同的设置。

在最简单的情况下，将 Zabbix 服务器的 [DebugLevel](/manual/appendix/config/zabbix_server#debuglevel) 配置参数值设置为环境变量后，便可以在启动时使用它来配置服务器：

```bash
# Zabbix 服务器配置文件：
DebugLevel=${NEW_DEBUG_LEVEL}

# 启动 Zabbix 服务器：
NEW_DEBUG_LEVEL=5 /usr/sbin/zabbix_server
```

以下 Zabbix 组件支持环境变量：

-   [服务器](/manual/appendix/config/zabbix_server)
-   [Proxy](/manual/appendix/config/zabbix_proxy)
-   agent（[UNIX](/manual/appendix/config/zabbix_agentd) 或 [Windows](/manual/appendix/config/zabbix_agentd_win)）
-   Agent 2（[UNIX](/manual/appendix/config/zabbix_agent2) 或 [Windows](/manual/appendix/config/zabbix_agent2_win)），包括 [插件](/manual/appendix/config/zabbix_agent2_plugins)
-   [Web 服务](/manual/appendix/config/zabbix_web_service)
-   Zabbix sender（使用 [-c, --config option](/manpages/zabbix_sender#options) 时）

[comment]: # ({/5b980b7e-72128caf})

[comment]: # ({8d252f3a-7598ffff})
#### 重要说明

-   当某个配置参数被设置为环境变量，而在运行组件时未指定该环境变量时，将使用该参数的默认值。
-   使用[运行时命令](/manual/concepts/agent#runtime-control)时（例如，提高 agent 日志级别），必须指定之前使用过的所有环境变量。这是因为 Zabbix 组件使用其配置文件来执行运行时命令；如果省略环境变量，将使用配置参数的默认值。请参见[示例](#examples)。
-   `userparameter_reload` [运行时命令](/manual/concepts/agent#runtime-control)不支持重新加载环境变量。在重新加载期间，变量会被忽略，只有具有常规值的参数会被重新加载。
-   在 Zabbix 组件启动后，配置文件中使用的进程当前环境变量会被清除。这可确保子进程（例如由 Zabbix 执行的远程脚本）无法访问这些变量。但请注意，进程初始变量仍然可以被获取（例如，通过 `/proc/<PID>/environ` 文件）。

[comment]: # ({/8d252f3a-7598ffff})

[comment]: # ({c33cd6ee-5d8ec091})
#### 语法

环境变量必须使用以下语法：${alphanumerics/underscores}。

变量名只能包含字母 (a-z, A-Z)、下划线 (\_) 和数字 (0-9)，且不能以数字开头。

不符合所需语法或与常规值组合使用的变量将被视为常规值，这可能会产生错误。

正确的变量语法：

```ini
DebugLevel=${NEW_DEBUG_LEVEL}
Hostname=${ZBX_HOSTNAME}
LogFile=${LogFile_001}
```

错误的变量语法：

```ini
DebugLevel=${5_DebugLevel}
Hostname=${ZBX.HOSTNAME 1}
LogFile=/${HOME}/zabbix/zabbix_server.log
```

::: noteclassic
在 Windows 中，环境变量名称不区分大小写。
:::

[comment]: # ({/c33cd6ee-5d8ec091})

[comment]: # ({b319b360-c638a080})
#### 示例

以下示例展示了如何在 Zabbix 组件中配置和使用环境变量。

[comment]: # ({/b319b360-c638a080})

[comment]: # ({78b82896-0382a339})
##### 示例 1：配置并测试 Zabbix agent

1\. 在 agent 配置文件中设置环境变量：

```ini
Hostname=${ZBX_HOSTNAME}
ServerActive=${ServerActive}
```

2\. 测试配置文件：

```bash
ZBX_HOSTNAME="New Zabbix agent" ServerActive=127.0.0.1 /usr/sbin/zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf --test-config
```

3\. 使用环境变量启动 agent：

```bash
ZBX_HOSTNAME="New Zabbix agent" ServerActive=127.0.0.1 /usr/sbin/zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf
```

使用[运行时命令](/manual/concepts/agent#runtime-control)时（例如，提高 agent 日志级别），必须指定之前使用过的所有环境变量：

```bash
ZBX_HOSTNAME="New Zabbix agent" ServerActive=127.0.0.1 /usr/sbin/zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf -R log_level_increase
```

这是因为 agent 会使用其配置文件来执行运行时命令；如果省略环境变量，将使用配置参数的默认值。

或者，在 agent 配置文件中设置环境变量后，您也可以使其对进程可用（例如，使用 `export` 命令）。
这样可以降低因变量缺失或设置不正确而导致意外行为的风险。

```bash
export ZBX_HOSTNAME="New Zabbix agent"
export ServerActive=127.0.0.1
/usr/sbin/zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf --test-config
/usr/sbin/zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf
/usr/sbin/zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf -R log_level_increase
```

[comment]: # ({/78b82896-0382a339})

[comment]: # ({6e772927-6852ff3f})
##### 示例 2：为容器配置 Zabbix agent

如果您正在为 Zabbix 组件（例如 Zabbix agent）创建并配置自己的自定义镜像，则可以使用环境变量定义配置参数，然后使用这些变量启动容器。

1\. 准备镜像时，在 agent 配置文件中设置环境变量：

```ini
Hostname=${ZBX_HOSTNAME}
BufferSize=${BUFSZ}
ListenPort=${LISTENPORT}
UserParameter=${_UsrPar01}
UserParameter=${_UsrPar02}
```

2\. 构建容器镜像后，使用环境变量启动 agent 容器（例如 Docker）：

```bash
docker run --name my-zabbix-agent -e ZBX_HOSTNAME="new-hostname" -e BUFSZ=1000 -e LISTENPORT=20050 -e _UsrPar01="key1,ls" -e _UsrPar02="key2,pwd" --init -d my-zabbix-agent:latest
```

3\. 使用[运行时命令](/manual/concepts/agent#runtime-control)时（例如，提高 agent 日志级别），请进入容器 shell 并执行运行时命令：

```bash
docker exec -it <containerid> sh
/usr/sbin/zabbix_agentd -R log_level_increase
```

::: noteimportant
`userparameter_reload` 运行时命令不支持重新加载环境变量。  
重新加载期间，这些变量会被忽略，只有具有常规值的参数会被重新加载。
:::

[comment]: # ({/6e772927-6852ff3f})