docker/ip-util-check

网络检查工具镜像文档

镜像概述和主要用途

网络检查工具镜像（network-checker）是一款轻量级自动化工具，用于在引擎升级前对目标网络环境进行系统性检查。其核心用途是通过验证网络连通性、服务可用性及关键性能指标，确保网络环境满足引擎升级的前置要求，降低因网络问题导致升级失败或服务中断的风险。

核心功能和特性

核心功能

• 网络连通性验证：支持ICMP（Ping）测试、TCP/UDP端口连通性检查
• DNS解析测试：验证目标域名解析有效性，支持自定义DNS服务器
• 服务可用性检测：检查指定端口的服务响应状态（如HTTP 200、数据库握手）
• 网络性能评估：测量网络延迟、丢包率，可选带宽测试
• 报告生成：输出结构化检查结果（文本/JSON格式），自动判定是否满足升级条件

特性

• 轻量级：基于Alpine构建，镜像体积<20MB，资源占用低
• 高度可配置：通过环境变量自定义检查目标、项目及参数
• 易于集成：支持嵌入CI/CD流程、自动化运维脚本（Ansible/SaltStack）
• 跨平台兼容：支持Linux/Windows/macOS Docker环境
• 无依赖运行：容器内置所有检查工具，无需额外安装

使用场景和适用范围

适用场景

• 数据库引擎（MySQL、PostgreSQL、MongoDB）升级前网络预检
• 应用服务器（Nginx、Tomcat、IIS）升级前端口/服务可用性验证
• 容器引擎（Docker、Kubernetes）升级前节点间网络连通性检查
• 云服务（EC2、Azure VM、阿里云ECS）升级前公网/内网访问测试

适用范围

• 环境：开发、测试、生产环境的引擎升级前检查
• 角色：运维工程师、DevOps团队、系统管理员的升级准备流程
• 流程：手动升级前验证、自动化部署流水线（Jenkins/GitLab CI）的前置检查步骤

详细使用方法和配置说明

基本使用方法

Docker Run 命令示例

bash
docker run -it --rm \
  --cap-add=NET_RAW \  # 如需ICMP(Ping)检查需添加此权限
  -e TARGET_HOST="prod-db.example.com" \
  -e CHECK_PORTS="3306,22" \
  -e CHECK_TYPE="ping,tcp,dns" \
  -e OUTPUT_FORMAT="text" \
  network-checker:latest

Docker Compose 配置示例

yaml
version: '3.8'
services:
  pre-upgrade-check:
    image: docker.xuanyuan.run/network-checker:latest
    cap_add:
      - NET_RAW  # 启用Ping功能
    environment:
      TARGET_HOST: "kube-apiserver.cluster.local"
      CHECK_PORTS: "6443,2379,2380"
      PING_COUNT: 3
      TIMEOUT: 15
      DNS_SERVER: "10.96.0.10"  # Kubernetes DNS
      OUTPUT_FORMAT: "json"
    restart: "no"  # 一次性任务

配置参数说明（环境变量）

高级用法

自定义检查脚本

通过挂载外部脚本扩展检查逻辑：

bash
docker run -it --rm \
  -v $(pwd)/custom-checks.sh:/app/custom.sh \
  docker.xuanyuan.run/network-checker:latest \
  /app/custom.sh

GitLab CI集成示例

在.gitlab-ci.yml中添加升级前检查阶段：

yaml
stages:
  - pre-upgrade
  - upgrade

network-validation:
  stage: pre-upgrade
  image: docker.xuanyuan.run/network-checker:latest
  variables:
    TARGET_HOST: "prod-app-server"
    CHECK_PORTS: "8080,9090"
    OUTPUT_FORMAT: "json"
  script:
    - /app/run-check.sh
    - cat check-result.json | jq -e '.conclusion == "network_ok"'  # 非0退出码阻断后续流程
  artifacts:
    paths: [check-result.json]

输出说明

文本格式（OUTPUT_FORMAT=text）

=== 网络检查报告 ===
目标主机: prod-db.example.com
检查时间: 2023-10-20 15:30:00
检查项: ping, tcp, dns

[PING] 结果: 通过 (平均延迟: 18ms, 丢包率: 0%)
[TCP] 端口 3306: 开放 (响应时间: 42ms)
[TCP] 端口 22: 开放 (响应时间: 12ms)
[DNS] 解析 prod-db.example.com: 成功 (IP: 10.20.30.40)

=== 结论: 网络环境满足升级要求 ===

JSON格式（OUTPUT_FORMAT=json）

json
{
  "target_host": "prod-db.example.com",
  "timestamp": "2023-10-20T15:30:00Z",
  "check_items": ["ping", "tcp", "dns"],
  "results": {
    "ping": {"status": "pass", "avg_latency_ms": 18, "packet_loss": 0},
    "tcp": [
      {"port": 3306, "status": "open", "response_ms": 42},
      {"port": 22, "status": "open", "response_ms": 12}
    ],
    "dns": {"status": "pass", "ips": ["10.20.30.40"]}
  },
  "conclusion": "network_ok"
}

注意事项

1. 权限要求：ICMP（Ping）检查需容器具备NET_RAW权限（添加--cap-add=NET_RAW参数）。
2. 生产环境建议：降低PING_COUNT（如设为2），避免网络负载；优先使用TCP检查替代Ping。
3. 防火墙配置：确保目标主机防火墙放行检查所需协议/端口（ICMP、TCP/UDP）。
4. 结果判定：conclusion为network_ok表示网络正常；network_issue时需修复问题后执行升级。
5. 超时设置：生产环境建议将TIMEOUT设为10-15秒，避免因网络波动导致误判。