# Zabbix 单机 Docker 部署（zabbix-deploy）

本仓库托管 Zabbix 服务器单机 Docker Compose 部署文件与配置审计说明。

## 组件与版本
- `zabbix/zabbix-server-mysql:ubuntu-7.4.16`
- `zabbix/zabbix-web-nginx-mysql:ubuntu-7.4.16`
- `mysql:8.0.43`

> 镜像均为**精确版本锁定**，避免 `docker compose pull` 时被悄悄升级到新大版本。

## 文件
- `docker-compose.yaml` —— 生产用编排文件（当前 7.4.16）
- `compose-audit.md` —— 原 compose 的问题审计与缓存容量重估说明
- `bootstrap/zbx-bootstrap.py` —— 「自监控-only」清理脚本（启动后摘除自身 agent 模板）
- `bootstrap/docker-compose.bootstrap.yaml` —— 可选叠加编排：随 `up` 自动运行上述脚本

## 自监控-only：服务器自身主机不挂 agent（2026-11 变更）

Zabbix 服务端首次启动会自动创建名为 `Zabbix server` 的自身监控主机，默认挂
`Linux by Zabbix agent` + `Zabbix server health`。由于本机**不安装 zabbix-agent**，
agent 那批项永远空采，还会周期性尝试连本机 10050 而产生 "agent 不可用" 类无效告警/报错。

已做的调整（手工，一次）：
1. 解除自身主机上的 `Linux by Zabbix agent` 模板（连带其监控项/触发器），仅保留
   `Zabbix server health` —— 即“自己监控自己、不连 agent”，不再报错。
2. 关闭了遗留的 "Linux: Zabbix agent is not available" 触发器。
3. 首页 `Global view` 中原引用 agent 项（Available memory / CPU utilization）的 svggraph
   已改指向自身内部项 `Configuration cache, % used` / `History write cache, % used`
   （重命名为「Cache usage」），避免图报 "item not found"。

> 本机仍保留 11 个与未启用进程（IPMI/Java/Report/VMware/Connector 等）相关的内部项，
> 但已**禁用**，不会产生红点/报错。

## 启动即自动化（可选）：bootstrap 辅助容器

想让 `docker compose up` 时**自动**完成上面第 1 步（摘除自身 agent 模板），用附带的
叠加编排即可，无需改 Zabbix 源码：

```bash
# 启用（每次 up 自动跑一次；幂等）
docker compose -f docker-compose.yaml -f bootstrap/docker-compose.bootstrap.yaml up -d

# 手动单独重跑一次
docker compose -f docker-compose.yaml -f bootstrap/docker-compose.bootstrap.yaml run --rm zbx-bootstrap
```

- 原理：一次性容器 `python:3.12-slim` 运行 `bootstrap/zbx-bootstrap.py`，轮询等 API 就绪，
  再用 API 把「服务器自身主机」（带 `Zabbix server health` 模板的那台）上的
  `Linux by Zabbix agent` 模板摘除；已干净则跳过。
- 认证：默认 `Admin/zabbix` 登录；生产建议在 `.env` 设置 `ZBX_API_TOKEN`（API Token），
  脚本会优先使用它。
- 局限：`python:3.12-slim` 镜像首次拉取需外网；该步只负责“摘除自身 agent 模板”，
  首页那张 CPU/内存图的重指向属展示层，可在 UI 手动改（见上）。

## 部署位置
- 服务器：`10.160.10.213`
- 部署目录：`/opt/zabbix`
- Web 访问：`http://192.168.87.20:8080/`

## 首次/变更部署步骤
```bash
cd /opt/zabbix
cp -f docker-compose.yaml docker-compose.yaml.bak_$(date +%s)   # 先备份
docker compose -f docker-compose.yaml config -q                 # 语法校验
docker compose -p zabbix up -d                                  # 重建生效
docker compose -p zabbix ps                                     # 查看状态
```

## 升级步骤（同大版本补丁升级，如 7.4.x → 7.4.y）
1. **备份数据库（务必）**：
   ```bash
   docker exec -i zabbix-mysql sh -c \
     'MYSQL_PWD=****** mysqldump -uroot --single-transaction --quick \
      --routines --triggers --events --set-gtid-purged=OFF zabbix' \
     | gzip > /opt/zabbix/backup/zabbix_$(date +%Y%m%d_%H%M%S).sql.gz
   gzip -t /opt/zabbix/backup/zabbix_*.sql.gz   # 校验完整性
   ```
2. 修改 `docker-compose.yaml` 中 server / web 镜像 tag 到目标版本。
3. `docker compose -p zabbix up -d`，server 启动时会自动执行数据库结构升级（日志中可见 `starting automatic database upgrade ... fully completed`）。
4. 校验：`docker exec zabbix-server zabbix_server -V`，以及 Web HTTP 200、采集速率恢复正常。

> 注意：补丁升级可能推进数据库 optional 版本（例如 7.4.2→7.4.16 为 07040000→07040011），**回滚需还原备份**，因此第 1 步不可省略。

## 关键环境变量（可在 `.env` 覆盖）
- `MYSQL_ROOT_PASSWORD` / `MYSQL_PASSWORD`（默认已内置，建议外部 `.env` 管理）
- `TZ`（默认 `UTC`，可按需设为 `Africa/Casablanca` 等）
- 缓存：`ZBX_CACHESIZE`、`ZBX_VALUECACHESIZE`、`ZBX_TRENDCACHESIZE`、`ZBX_HISTORYCACHESIZE`、`ZBX_TRENDSINDEXCACHESIZE` 等
- 采集进程：`ZBX_STARTSNMPPOLLERS`、`ZBX_STARTLLDWORKERS`、`ZBX_STARTPREPROCESSORS`

## 端口
- Zabbix Server：`10051`
- Web（nginx）：容器内 `8080` / `8443`
- MySQL：容器内 `3306`（不对外暴露）

## L2 物理拓扑（WecomCenter 模块扩展）

模块 `web-modules/WecomCenter` 现包含 **L2 物理拓扑** 功能（展示页 + 配置页 + 采集器 + 历史库）：

- 展示页：`Monitoring → L2 Topology`（只读，含时间轴/深色/终端/搜索/速率&延迟&告警着色）。
- 配置页：`Administration → ROMAN 定制中心 → 「L2 拓扑」`（采集模板、刷新/采集间隔、速率配色、
  延迟阈值、分组规则、根框名、默认深色等）。
- 数据：每次全量采集把快照 gzip 写入 MySQL `l2_topology_history`（保留 7 天，可回看任意时间）；
  配置存 `l2_topology_config`，并镜像 `assets/l2topology/config.json`。
- 表结构：`L2Store::ensureSchema()` 幂等建表；`wecom-module-init` 侧车在 `up` 时也会建表。

### docker-compose 一键启用
`up -d` 时：`web-modules/` 挂入 web 容器 → `wecom-module-init` 自动登记并启用模块、创建 L2 表。
全新环境无需进 UI 点启用。`WEB_MODULES_DIR` 可覆盖挂载源路径。

### 采集器（宿主机）
采集器在 `collector/`，需装到 `/opt/zabbix/l2collector/` 并用 cron 调度（容器无法直接读交换机 SNMP）。
详见 `docs/使用说明.md` 第 10 章。只采集配置页所选模板（默认 `Huawei VRP by SNMP (walk)`）的主机。