Icinga 2.16.5 部署指南

目标：用 Docker Compose 在一台主机上把 Icinga 监控全家桶（Icinga 2 核心 + Icinga Web 2 + 内置 MariaDB）拉起来，完成数据持久化、Web 登录验收、API 验证与重启后的数据完整性检查。全部步骤与回显实测；镜像打包版本与上游最新稳定版的差异在第一节如实标注。

一、环境信息

• 宿主机：Ubuntu 24.04.3 LTS，x86_64，内核 6.8.0-138-generic
• Docker：29.8.1，Compose v2.40.4（docker compose version 实测）
• 镜像：jordan/icinga2:latest（社区维护的一体化镜像，2026-10-20 拉取）
• 镜像内实测组件版本（启动后 docker exec 逐个核对）：
  • Icinga 2：r2.16.1-1
  • Icinga Web 2：2.13.0
  • MariaDB：10.11.14-MariaDB-ubu2404
  • PHP：8.2.31
  • Apache：2.4.67
• 版本基准说明：组件最新稳定版为 Icinga 2.16.5（2026-08-18 发布，见《Icinga 2.16.5 介绍与选型指南》），本镜像打包的是 2.16.1——一体化镜像的版本节奏略滞后于官方 deb 包，对版本强敏感的场景请优先参考《Ubuntu 22.04 安装 Icinga 2.16.5 指南》的裸机方案；本篇面向"快速拉起一套可用监控"的场景。
• 网络与端口：自定义网络 icinga-compose-net（10.89.60.0/24）；宿主端口 8148（Web）、8150（API）
• 演示口令约定：MySQL root 与业务库口令、Web 管理员、API 均为 q1w2e3r4（实测值，生产请换强随机）

二、镜像选型说明

jordan/icinga2 社区热度：Docker Hub 拉取量约 4.2M（shields.io，2026-10-20），是事实上的主流一体化镜像。它首启时自动完成：MariaDB 初始化 → 创建 icinga2/icingaweb/director 库 → icinga2 主节点配置与 API 用户 → Icinga Web 2 全自动 Setup（免向导）→ supervisor 托管全部进程。

三、前置条件

1. 宿主机已安装 Docker 与 Compose v2（本文以 v2.40.4 实测）。
2. 端口 8148、8150 未被占用（ss -ltnp | grep -E '8148|8150' 确认）。
3. 网段 10.89.60.0/24 空闲（docker network ls -q | xargs docker network inspect --format '{{.Name}} {{range .IPAM.Config}}{{.Subnet}}{{end}}' 确认；被占用就换一个空闲槽位）。
4. 目录：为持久化数据准备一个工作目录（本文 /opt/icinga-deploy/，下文 Compose 文件与 data/ 卷都放这里）。

四、部署步骤

4.1 编写 docker-compose.yml

services:
  icinga2:
    image: jordan/icinga2:latest
    container_name: icinga-2-16-compose
    hostname: icinga-mon.example.com
    restart: unless-stopped
    environment:
      - SYSTEM_TIMEZONE=Asia/Shanghai
      - MYSQL_ROOT_PASSWORD=q1w2e3r4
      - DEFAULT_MYSQL_PASS=q1w2e3r4
      - ICINGAWEB2_ADMIN_USER=admin
      - ICINGAWEB2_ADMIN_PASS=q1w2e3r4
      - ICINGA2_FEATURE_DIRECTOR=false
    volumes:
      - ./data/mysql:/var/lib/mysql
      - ./data/icinga2:/etc/icinga2
      - ./data/icingaweb2:/etc/icingaweb2
    ports:
      - "8148:80"
      - "8150:5665"
    networks:
      icinga-compose-net:
        aliases:
          - icinga-mon.example.com

networks:
  icinga-compose-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.60.0/24

要点：

• DEFAULT_MYSQL_PASS 必须显式指定：镜像默认每次启动随机生成业务库口令，一旦挂载了持久卷，第二次启动就会用新随机口令连旧库，直接 Access denied 重启循环（实测踩坑，详见第十节 FAQ-1）。
• ICINGA2_FEATURE_DIRECTOR=false：关闭 Icinga Director 自动化模块（本篇不需要；需要配置自动化时设为 true）。
• 三个挂载卷覆盖"数据库 + 核心配置 + Web 配置"，容器销毁数据仍在。

4.2 启动并观察首启初始化

docker compose up -d
docker logs -f icinga-2-16-compose

首启日志实测（节选，初始化大约 40-60 秒）：

Setting up Icinga 2 Version: r2.16.1-1
Initializing MariaDB Database
Populating MariaDB Database Schema
Starting MariaDB
Setting up Icinga DB Web Config
Configuring Icinga 2: RDBMS Feature
Configuring Icinga 2: Certificate
Configuring Icinga 2: Main Config
Configuring Icinga 2: API Feature
Configuring Icinga Web 2: Preparing Setup
Configuring Icinga Web 2: Monitor Module
Configuring Icinga Web 2: Admin Account
Configuring Icinga Web 2: Setup
Finished first-boot setup, starting services...

看到最后两行即初始化完成。docker compose ps 实测：

NAME                  IMAGE                 COMMAND    SERVICE    CREATED          STATUS         PORTS
icinga-2-16-compose   jordan/icinga2:latest "/init"    icinga2    3 minutes ago    Up 3 minutes   443/tcp, 0.0.0.0:8148->80/tcp, [::]:8148->80/tcp, 0.0.0.0:8150->5665/tcp, [::]:8150->5665/tcp

（443/tcp 是镜像 EXPOSE 声明，未映射宿主，忽略即可。）

4.3 验证 Web 界面

浏览器访问 http://<宿主机IP>:8148/icingaweb2，用 admin / q1w2e3r4 登录。实测登录后标题为 Current Incidents :: Dashboard :: Icinga Web，Dashboard 正常出监控视图。

命令行层面的验收（宿主机执行）：

curl -sk http://localhost:8148/icingaweb2/authentication/login -o /dev/null -w '%{http_code}\n'

302

（未登录状态 302 正常——跳转到登录页。）

4.4 固化 API 口令并验证

本镜像会为 API 用户 root 生成随机口令（ICINGA2_PASSWORD 环境变量在该版本中不作用于 ApiUser，实测无效），演示环境把它固化成约定值：

docker exec icinga-2-16-compose bash -c 'grep -A3 "object ApiUser" /etc/icinga2/conf.d/api-users.conf | head -8'

/**
 * The ApiUser objects are used for authentication against the API.
 */
object ApiUser "root" {
  password = "967043fe7b41268b"
  // client_cn = ""

  permissions = [ "*" ]
}

docker exec icinga-2-16-compose bash -c \
  'sed -i "s/967043fe7b41268b/q1w2e3r4/" /etc/icinga2/conf.d/api-users.conf && supervisorctl restart icinga2'

icinga2: stopped
icinga2: started

⚠️ 注意：本镜像的 Web 端命令通道走的是本地管道（/var/run/icinga2/cmd/icinga2.cmd，实测 /etc/icingaweb2/modules/monitoring/commandtransports.ini 中 transport = "local"），不依赖 API 口令；改 API 口令只影响外部 API 调用方，改完 supervisorctl restart icinga2 即可。

验证 API（宿主机执行，8150 映射）：

curl -sk -u root:q1w2e3r4 -H "Accept: application/json" \
  -X GET "https://localhost:8150/v1/status/IcingaApplication"

{"results":[{"name":"IcingaApplication","perfdata":[],"status":{"icingaapplication":{"app":{"node_name":"icinga-mon.example.com","pid":11579,"program_start":1792443182.129388,"version":"r2.16.1-1", ...}}}}]}

node_name 取自 Compose 的 hostname（icinga-mon.example.com），说明网络别名与节点名按预期生效。

五、数据持久化说明

三个挂载卷与容器生命周期的关系：

重启持久化实测（数据完整性验收）：

docker compose restart
docker compose ps --format '{{.Name}} {{.Status}}'
curl -sk -u root:q1w2e3r4 -H "Accept: application/json" -X GET "https://localhost:8150/v1/objects/hosts" | head -c 160

icinga-2-16-compose  Up 24 seconds
{"results":[{"attrs":{"__name":"icinga-mon.example.com","acknowledgement":0,"address":"127.0.0.1","check_command":"hostalive", ...}

重启后主机对象仍在、API 正常应答，docker compose down（不删卷）再 up 亦同；docker compose down -v 不会删除 bind mount 的 ./data，真正清库要 rm -rf ./data。

六、环境变量表

镜像支持的关键环境变量（来源：镜像 /opt/run 与 /opt/setup/* 实测解析，已验证项标注✅）：

💡 说明：变量以实测为准的口径列出——✅ 为本篇部署中实际验证过效果的项；镜像其余未验证变量（Grafana 集成、外部 MySQL 指向、Graphite 等）建议用 docker run --rm --entrypoint sh jordan/icinga2:latest -c 'grep -E "ICINGA|MYSQL" /opt/run' 自查。

七、配置参数说明与配置文件挂载

容器内关键路径（均已实测核对）：

进程托管：容器内由 supervisor 管理，改核心配置后重启核心进程：

docker exec icinga-2-16-compose supervisorctl status
docker exec icinga-2-16-compose supervisorctl restart icinga2

apache2                          RUNNING   pid 1743, uptime 0:12:05
icinga2                          RUNNING   pid 11579, uptime 0:04:31
icinga2-notification             RUNNING   pid 1753, uptime 0:12:04
mariadb                          RUNNING   pid 1739, uptime 0:12:06

💡 技术拓展：在容器里新增监控对象有两条路——挂载 ./data/icinga2 后直接改宿主 ./data/icinga2/conf.d/hosts.conf 再 supervisorctl restart icinga2；或打开 ICINGA2_FEATURE_DIRECTOR=true 用 Director 界面管配置。想让 icinga2 订阅宿主外的主机，把 hosts.conf 的对象写法与裸机一致即可，API 端口 8150 对 agent 侧 node setup --endpoint <宿主>,8150 暴露。

八、等价 docker run

不想用 Compose 时，以下单命令与 4.1 节 Compose 等价：

docker run -d --name icinga-2-16-compose --hostname icinga-mon.example.com \
  --restart unless-stopped \
  -e SYSTEM_TIMEZONE=Asia/Shanghai \
  -e MYSQL_ROOT_PASSWORD=q1w2e3r4 \
  -e DEFAULT_MYSQL_PASS=q1w2e3r4 \
  -e ICINGAWEB2_ADMIN_USER=admin \
  -e ICINGAWEB2_ADMIN_PASS=q1w2e3r4 \
  -e ICINGA2_FEATURE_DIRECTOR=false \
  -v /opt/icinga-deploy/data/mysql:/var/lib/mysql \
  -v /opt/icinga-deploy/data/icinga2:/etc/icinga2 \
  -v /opt/icinga-deploy/data/icingaweb2:/etc/icingaweb2 \
  -p 8148:80 -p 8150:5665 \
  jordan/icinga2:latest

九、常用运维命令

docker compose ps                     # 状态
docker compose logs -f --tail 100     # 跟踪日志
docker compose restart                # 整体重启（数据持久）
docker compose down                   # 停止并移除容器（保留 ./data）
docker compose up -d                  # 再次拉起
docker exec icinga-2-16-compose icinga2 feature list      # 核心特性
docker exec icinga-2-16-compose icingacli module list     # Web 模块
docker exec icinga-2-16-compose supervisorctl status      # 容器内进程
curl -sk -u root:q1w2e3r4 https://localhost:8150/v1/objects/hosts  # API 查主机

十、常见问题（FAQ）

Q1：重启后 MariaDB 起不来，日志报 Access denied for user 'icinga2'@'localhost'，容器反复重启？ 持久卷 + 未固定 DEFAULT_MYSQL_PASS 的典型组合：首启用随机口令建了库，第二次启动又生成新随机口令去连旧库。修法：在 environment 里固定 DEFAULT_MYSQL_PASS=q1w2e3r4（与 MYSQL_ROOT_PASSWORD 同理），删除 ./data 后重新首启（本篇 4.1 的 Compose 已包含该变量，实测固定后多次 restart 均正常）。

Q2：docker logs 里出现 critical/ApiListener: Another instance of Icinga (PID: xxx, Endpoint: 'icinga-mon.example.com') is running 后服务自动恢复？ supervisor 拉起时机竞争的无害竞态：旧进程未完全退出时新进程抢注导致，supervisor 会自动重试，最终 supervisorctl status 全 RUNNING 即可，无需处理（实测自愈）。

Q3：443 端口没有监听，HTTPS 打不开？ 本镜像默认只在 80 跑 Apache（ss -ltnp 实测容器内仅 :80），443 仅是镜像 EXPOSE 声明。需要 HTTPS 时在前面加反代（Nginx/Traefik 终结 TLS 后转 8148），不要指望容器自己起 443。

Q4：API 返回 Unauthorized. Please check your user credentials.？ API 用户口令是首启随机生成的，不是 ICINGA2_PASSWORD 环境变量。按 4.4 节查看并固化口令后重试。

Q5：Web 能登但界面里看不到监控数据？ 确认核心与 Web 的库都正常：docker exec icinga-2-16-compose supervisorctl status 里 mariadb/icinga2/apache2 均 RUNNING；再 icingacli monitoring list hosts 看有无输出。首次启动后 1-2 分钟内 IDO 数据才有首批落库，稍等再刷新。

Q6：如何接入第一批被监控主机？ 容器自带的本机对象开箱即用。监控外部主机走 agent 模式（参考 CLI 篇第十、十二节的 pki/node 命令，--parent_host 指向宿主 8150 端口），或简单场景在挂载的 ./data/icinga2/conf.d/hosts.conf 里加 object Host + check_command = "hostalive"，重启核心生效。

十一、升级与镜像切换

docker compose pull                 # 拉新镜像（如 jordan/icinga2 发布新版本）
docker compose up -d                # 用新镜像重建容器（./data 卷保留配置与数据）

升级前把 ./data 整目录备份（tar -czf icinga-data-$(date +%F).tgz data/）；跨大版本升级先读官方 upgrade 文档核对数据库迁移说明。若要从一体化镜像切回官方裸机/多容器形态，用 icingacli/mysqldump 导出 Web 配置与数据后重建，两者配置结构同源，成本可控。

十二、参考链接

• jordan/icinga2 镜像页：https://hub.docker.com/r/jordan/icinga2
• Icinga 2 官方文档：https://icinga.com/docs/icinga-2/latest/
• Icinga Web 2 官方文档：https://icinga.com/docs/icinga-web-2/latest/
• 组件选型背景：见《Icinga 2.16.5 介绍与选型指南》
• 裸机安装（版本最新）：见《Ubuntu 22.04 安装 Icinga 2.16.5 指南》
• 命令行与 REST API 详解：见《Icinga 2.16.5 常用 CLI 命令与工具详解》