dev_1.0.0_yuyr_2：重新提交 PR，增加 master/agent 以及系统集成测试 (#17)

Reviewed-on: #17
Reviewed-by: sundapeng <sundp@mail.zgclab.edu.cn>
Reviewed-by: xuxt <xuxt@zgclab.edu.cn>

src/agent/.gitignore

@@ -0,0 +1,5 @@
+build/
+*.egg-info/
+__pycache__/
+
+.env

src/agent/README.md

@@ -0,0 +1,66 @@
+# Argus Agent 模块
+
+Argus Agent 是一个轻量级 Python 进程，负责向 Argus Master 注册节点、汇报健康数据，并维护本地持久化信息。模块现以 PyInstaller 打包为独立可执行文件，便于在普通容器或虚机中直接运行。
+
+## 构建可执行文件
+
+```bash
+cd src/agent
+./scripts/build_binary.sh  # 生成 dist/argus-agent
+```
+
+脚本默认会在 Docker 容器 (`python:3.11-slim-bullseye`) 内执行 PyInstaller，确保产物运行时兼容 glibc 2.31+（覆盖 2.35 环境）。构建流程注意事项：
+
+- 每次构建前会清理 `build/`、`dist/` 并在容器内重新创建虚拟环境。
+- 需要使用内网 Python 镜像时，可通过 `PIP_INDEX_URL`、`PIP_EXTRA_INDEX_URL`、`PIP_TRUSTED_HOST` 等环境变量传入，脚本会自动透传给容器。
+- 如果宿主机无法运行 Docker，可设置 `AGENT_BUILD_USE_DOCKER=0` 回退到本地构建；此时代码必须在 glibc ≤ 2.35 的机器上执行。
+
+构建结束后脚本会在 `build/compat_check/` 下解包关键动态库并输出最高 `GLIBC_x.y` 版本，便于快速核对兼容性。如果结果中缺少 `libssl.so.3` / `libcrypto.so.3`，表示系统会在目标宿主机上使用本地 OpenSSL 库，无需额外处理。
+
+例如：
+
+```bash
+strings build/compat_check/libpython*.so.1.0 | grep -Eo 'GLIBC_[0-9]+\.[0-9]+' | sort -Vu | tail -n1
+```
+
+如遇构建失败，常见原因是 Docker 不可用（请改用 `AGENT_BUILD_USE_DOCKER=0`）或无法访问 Python 包镜像（先设置上述镜像环境变量后重试）。
+
+## 运行时配置
+
+Agent 不再依赖配置文件；所有参数均由环境变量与主机名推导：
+
+| 变量 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `MASTER_ENDPOINT` | 是 | N/A | Master 基础地址，可写 `http://host:3000` 或 `host:3000`（自动补全 `http://`）。 |
+| `REPORT_INTERVAL_SECONDS` | 否 | `60` | 状态上报间隔（秒）。必须为正整数。 |
+| `AGENT_HOSTNAME` | 否 | `$(hostname)` | 覆盖容器内主机名，便于测试或特殊命名需求。 |
+
+派生路径：
+
+- 节点信息：`/private/argus/agent/<hostname>/node.json`
+- 子模块健康目录：`/private/argus/agent/<hostname>/health/`
+
+健康目录中的文件需遵循 `<模块前缀>-*.json` 命名（例如 `log-fluentbit.json`、`metric-node-exporter.json`），文件内容会原样并入上报的 `health` 字段。
+
+## 日志与持久化
+
+- Agent 会在成功注册、状态上报、异常重试等关键节点输出结构化日志，便于聚合分析。
+- `node.json` 保存 Master 返回的最新节点对象，用于重启后继续使用既有节点 ID。
+
+## 端到端测试
+
+仓库内提供 Docker Compose 测试栈（master + ubuntu 容器）：
+
+```bash
+cd src/agent/tests
+./scripts/00_e2e_test.sh
+```
+
+测试脚本会：
+
+1. 构建 master 镜像与 agent 可执行文件。
+2. 以 `ubuntu:24.04` 启动 agent 容器，并通过环境变量注入 `MASTER_ENDPOINT`、`REPORT_INTERVAL_SECONDS`。
+3. 验证注册、健康上报、nodes.json 生成、统计接口，以及“容器重启 + IP 变化”重注册流程。
+4. 清理 `tests/private/` 与临时容器网络。
+
+如需在真实环境部署，只需将 `dist/argus-agent` 连同健康目录挂载到目标主机，并按上表设置环境变量即可。

src/agent/app/client.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+import requests
+
+from .log import get_logger
+
+LOGGER = get_logger("argus.agent.client")
+
+
+class MasterAPIError(Exception):
+    def __init__(self, message: str, status_code: int, payload: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload or {}
+
+
+class AgentClient:
+    def __init__(self, base_url: str, *, timeout: int = 10) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+
+    def register_node(self, body: Dict[str, Any]) -> Dict[str, Any]:
+        """调用 master 注册接口，返回节点对象。"""
+        url = f"{self._base_url}/api/v1/master/nodes"
+        response = self._session.post(url, json=body, timeout=self._timeout)
+        return self._parse_response(response, "Failed to register node")
+
+    def update_status(self, node_id: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        """上报健康信息，由 master 更新 last_report。"""
+        url = f"{self._base_url}/api/v1/master/nodes/{node_id}/status"
+        response = self._session.put(url, json=body, timeout=self._timeout)
+        return self._parse_response(response, "Failed to update node status")
+
+    def _parse_response(self, response: requests.Response, error_prefix: str) -> Dict[str, Any]:
+        content_type = response.headers.get("Content-Type", "")
+        payload: Dict[str, Any] | None = None
+        if "application/json" in content_type:
+            try:
+                payload = response.json()
+            except json.JSONDecodeError:
+                LOGGER.warning("Response contained invalid JSON", extra={"status": response.status_code})
+
+        if response.status_code >= 400:
+            message = payload.get("error") if isinstance(payload, dict) else response.text
+            raise MasterAPIError(
+                f"{error_prefix}: {message}",
+                status_code=response.status_code,
+                payload=payload if isinstance(payload, dict) else None,
+            )
+
+        if payload is None:
+            try:
+                payload = response.json()
+            except json.JSONDecodeError as exc:
+                raise MasterAPIError("Master returned non-JSON payload", response.status_code) from exc
+        return payload

src/agent/app/collector.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import os
+import re
+import socket
+import subprocess
+from pathlib import Path
+from typing import Any, Dict
+
+from .config import AgentConfig
+from .log import get_logger
+
+LOGGER = get_logger("argus.agent.collector")
+
+_HOSTNAME_PATTERN = re.compile(r"^([^-]+)-([^-]+)-([^-]+)-.*$")
+
+
+def collect_metadata(config: AgentConfig) -> Dict[str, Any]:
+    """汇总节点注册需要的静态信息。"""
+    hostname = config.hostname
+    env, user, instance = _parse_hostname(hostname)
+    meta = {
+        "hostname": hostname,
+        "ip": _detect_ip_address(),
+        "env": env,
+        "user": user,
+        "instance": instance,
+        "cpu_number": _detect_cpu_count(),
+        "memory_in_bytes": _detect_memory_bytes(),
+        "gpu_number": _detect_gpu_count(),
+    }
+    return meta
+
+
+def _parse_hostname(hostname: str) -> tuple[str, str, str]:
+    """按照约定的 env-user-instance 前缀拆解主机名。"""
+    match = _HOSTNAME_PATTERN.match(hostname)
+    if not match:
+        LOGGER.warning("Hostname does not match expected pattern", extra={"hostname": hostname})
+        return "", "", ""
+    return match.group(1), match.group(2), match.group(3)
+
+
+def _detect_cpu_count() -> int:
+    count = os.cpu_count()
+    return count if count is not None else 0
+
+
+def _detect_memory_bytes() -> int:
+    """优先读取 cgroup 限额，失败时退回 /proc/meminfo。"""
+    cgroup_path = Path("/sys/fs/cgroup/memory.max")
+    try:
+        raw = cgroup_path.read_text(encoding="utf-8").strip()
+        if raw and raw != "max":
+            return int(raw)
+    except FileNotFoundError:
+        LOGGER.debug("cgroup memory.max not found, falling back to /proc/meminfo")
+    except ValueError:
+        LOGGER.warning("Failed to parse memory.max, falling back", extra={"value": raw})
+
+    try:
+        with open("/proc/meminfo", "r", encoding="utf-8") as handle:
+            for line in handle:
+                if line.startswith("MemTotal:"):
+                    parts = line.split()
+                    if len(parts) >= 2:
+                        return int(parts[1]) * 1024
+    except FileNotFoundError:
+        LOGGER.error("/proc/meminfo not found; defaulting memory to 0")
+    return 0
+
+
+def _detect_gpu_count() -> int:
+    """采集 GPU 数量，如无法探测则默认为 0。"""
+    try:
+        proc = subprocess.run(
+            ["nvidia-smi", "-L"],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=5,
+        )
+    except FileNotFoundError:
+        LOGGER.debug("nvidia-smi not available; assuming 0 GPUs")
+        return 0
+    except subprocess.SubprocessError as exc:
+        LOGGER.warning("nvidia-smi invocation failed", extra={"error": str(exc)})
+        return 0
+
+    if proc.returncode != 0:
+        LOGGER.debug("nvidia-smi returned non-zero", extra={"stderr": proc.stderr.strip()})
+        return 0
+
+    count = sum(1 for line in proc.stdout.splitlines() if line.strip())
+    return count
+
+
+def _detect_ip_address() -> str:
+    """尝试通过 UDP socket 获得容器出口 IP，失败则回退解析主机名。"""
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+            sock.connect(("8.8.8.8", 80))
+            return sock.getsockname()[0]
+    except OSError:
+        LOGGER.debug("UDP socket trick failed; falling back to hostname lookup")
+    try:
+        return socket.gethostbyname(socket.gethostname())
+    except OSError:
+        LOGGER.warning("Unable to resolve hostname to IP; defaulting to 127.0.0.1")
+        return "127.0.0.1"

src/agent/app/config.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import os
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from .version import VERSION
+
+DEFAULT_REPORT_INTERVAL_SECONDS: Final[int] = 60
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    hostname: str
+    node_file: str
+    version: str
+    master_endpoint: str
+    report_interval_seconds: int
+    health_dir: str
+    request_timeout_seconds: int = 10
+
+
+def _normalise_master_endpoint(value: str) -> str:
+    value = value.strip()
+    if not value:
+        raise ValueError("MASTER_ENDPOINT environment variable is required")
+    if not value.startswith("http://") and not value.startswith("https://"):
+        value = f"http://{value}"
+    return value.rstrip("/")
+
+
+def _read_report_interval(raw_value: str | None) -> int:
+    if raw_value is None or raw_value.strip() == "":
+        return DEFAULT_REPORT_INTERVAL_SECONDS
+    try:
+        interval = int(raw_value)
+    except ValueError as exc:
+        raise ValueError("REPORT_INTERVAL_SECONDS must be an integer") from exc
+    if interval <= 0:
+        raise ValueError("REPORT_INTERVAL_SECONDS must be positive")
+    return interval
+
+
+def _resolve_hostname() -> str:
+    return os.environ.get("AGENT_HOSTNAME") or socket.gethostname()
+
+
+def load_config() -> AgentConfig:
+    """从环境变量推导配置，移除了外部配置文件依赖。"""
+
+    hostname = _resolve_hostname()
+    node_file = f"/private/argus/agent/{hostname}/node.json"
+    health_dir = f"/private/argus/agent/{hostname}/health/"
+
+    master_endpoint_env = os.environ.get("MASTER_ENDPOINT")
+    if master_endpoint_env is None:
+        raise ValueError("MASTER_ENDPOINT environment variable is not set")
+    master_endpoint = _normalise_master_endpoint(master_endpoint_env)
+
+    report_interval_seconds = _read_report_interval(os.environ.get("REPORT_INTERVAL_SECONDS"))
+
+    Path(node_file).parent.mkdir(parents=True, exist_ok=True)
+    Path(health_dir).mkdir(parents=True, exist_ok=True)
+
+    return AgentConfig(
+        hostname=hostname,
+        node_file=node_file,
+        version=VERSION,
+        master_endpoint=master_endpoint,
+        report_interval_seconds=report_interval_seconds,
+        health_dir=health_dir,
+    )

src/agent/app/health_reader.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict
+
+from .log import get_logger
+
+LOGGER = get_logger("argus.agent.health")
+
+
+def read_health_directory(path: str) -> Dict[str, Any]:
+    """读取目录中所有 <prefix>-*.json 文件并返回 JSON 映射。"""
+    result: Dict[str, Any] = {}
+    directory = Path(path)
+    if not directory.exists():
+        LOGGER.debug("Health directory does not exist", extra={"path": str(directory)})
+        return result
+
+    for health_file in sorted(directory.glob("*.json")):
+        if "-" not in health_file.stem:
+            LOGGER.debug("Skipping non-prefixed health file", extra={"file": health_file.name})
+            continue
+        try:
+            with health_file.open("r", encoding="utf-8") as handle:
+                content = json.load(handle)
+            result[health_file.stem] = content
+        except json.JSONDecodeError as exc:
+            LOGGER.warning("Failed to parse health file", extra={"file": health_file.name, "error": str(exc)})
+        except OSError as exc:
+            LOGGER.warning("Failed to read health file", extra={"file": health_file.name, "error": str(exc)})
+    return result

src/agent/app/log.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import logging
+import os
+
+
+_LOG_FORMAT = "%(asctime)s %(levelname)s %(name)s - %(message)s"
+
+
+def setup_logging() -> None:
+    level_name = os.environ.get("AGENT_LOG_LEVEL", "INFO").upper()
+    level = getattr(logging, level_name, logging.INFO)
+    logging.basicConfig(level=level, format=_LOG_FORMAT)
+
+
+def get_logger(name: str) -> logging.Logger:
+    setup_logging()
+    return logging.getLogger(name)

src/agent/app/main.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import signal
+import time
+from datetime import datetime, timezone
+from typing import Optional
+
+from .client import AgentClient, MasterAPIError
+from .collector import collect_metadata
+from .config import AgentConfig, load_config
+from .health_reader import read_health_directory
+from .log import get_logger, setup_logging
+from .state import clear_node_state, load_node_state, save_node_state
+
+LOGGER = get_logger("argus.agent")
+
+
+def _current_timestamp() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+class StopSignal:
+    def __init__(self) -> None:
+        self._stop = False
+
+    def set(self, *_args) -> None:  # type: ignore[override]
+        self._stop = True
+
+    def is_set(self) -> bool:
+        return self._stop
+
+
+def main(argv: Optional[list[str]] = None) -> int:  # noqa: ARG001 - 保留签名以兼容入口调用
+    setup_logging()
+
+    stop_signal = StopSignal()
+    signal.signal(signal.SIGTERM, stop_signal.set)
+    signal.signal(signal.SIGINT, stop_signal.set)
+
+    try:
+        config = load_config()
+    except Exception as exc:
+        LOGGER.error("Failed to load configuration", extra={"error": str(exc)})
+        return 1
+
+    LOGGER.info(
+        "Agent starting",
+        extra={
+            "hostname": config.hostname,
+            "master_endpoint": config.master_endpoint,
+            "node_file": config.node_file,
+        },
+    )
+
+    client = AgentClient(config.master_endpoint, timeout=config.request_timeout_seconds)
+
+    node_state = load_node_state(config.node_file) or {}
+    node_id = node_state.get("id")
+
+    # 与 master 建立注册关系（支持重注册），失败则重试
+    register_response = _register_with_retry(client, config, node_id, stop_signal)
+    if register_response is None:
+        LOGGER.info("Registration aborted due to shutdown signal")
+        return 0
+
+    node_id = register_response.get("id")
+    if not node_id:
+        LOGGER.error("Master did not return node id; aborting")
+        return 1
+    save_node_state(config.node_file, register_response)
+
+    LOGGER.info("Entering status report loop", extra={"node_id": node_id})
+    _status_loop(client, config, node_id, stop_signal)
+    return 0
+
+
+def _register_with_retry(
+    client: AgentClient,
+    config: AgentConfig,
+    node_id: Optional[str],
+    stop_signal: StopSignal,
+):
+    backoff = 5
+    while not stop_signal.is_set():
+        payload = {
+            "name": config.hostname,
+            "type": "agent",
+            "meta_data": collect_metadata(config),
+            "version": config.version,
+        }
+        if node_id:
+            payload["id"] = node_id
+
+        try:
+            response = client.register_node(payload)
+            LOGGER.info("Registration successful", extra={"node_id": response.get("id")})
+            save_node_state(config.node_file, response)
+            return response
+        except MasterAPIError as exc:
+            if exc.status_code == 404 and node_id:
+                LOGGER.warning(
+                    "Master does not recognise node id; clearing local node state",
+                    extra={"node_id": node_id},
+                )
+                clear_node_state(config.node_file)
+                node_id = None
+            elif exc.status_code == 500 and node_id:
+                # id 与 name 不匹配通常意味着配置异常，记录但继续重试
+                LOGGER.error(
+                    "Master rejected node due to id/name mismatch; will retry",
+                    extra={"node_id": node_id},
+                )
+            else:
+                LOGGER.error("Registration failed", extra={"status_code": exc.status_code, "error": str(exc)})
+            time.sleep(min(backoff, 60))
+            backoff = min(backoff * 2, 60)
+        except Exception as exc:  # pragma: no cover - defensive
+            LOGGER.exception("Unexpected error during registration", extra={"error": str(exc)})
+            time.sleep(min(backoff, 60))
+            backoff = min(backoff * 2, 60)
+    return None
+
+
+def _status_loop(
+    client: AgentClient,
+    config: AgentConfig,
+    node_id: str,
+    stop_signal: StopSignal,
+) -> None:
+    interval = config.report_interval_seconds
+    while not stop_signal.is_set():
+        timestamp = _current_timestamp()
+        health_payload = read_health_directory(config.health_dir)
+        body = {
+            "timestamp": timestamp,
+            "health": health_payload,
+        }
+        try:
+            response = client.update_status(node_id, body)
+            LOGGER.info(
+                "Status report succeeded",
+                extra={"node_id": node_id, "health_keys": list(health_payload.keys())},
+            )
+            save_node_state(config.node_file, response)
+        except MasterAPIError as exc:
+            # 保持循环继续执行，等待下一次重试
+            LOGGER.error(
+                "Failed to report status",
+                extra={"status_code": exc.status_code, "error": str(exc)},
+            )
+        except Exception as exc:  # pragma: no cover - defensive
+            LOGGER.exception("Unexpected error during status report", extra={"error": str(exc)})
+
+        for _ in range(interval):
+            if stop_signal.is_set():
+                break
+            time.sleep(1)
+
+    LOGGER.info("Stop signal received; exiting status loop")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/agent/app/state.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .log import get_logger
+
+LOGGER = get_logger("argus.agent.state")
+
+
+def load_node_state(path: str) -> Optional[Dict[str, Any]]:
+    """读取本地 node.json，容器重启后沿用之前的 ID。"""
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            return json.load(handle)
+    except FileNotFoundError:
+        return None
+    except json.JSONDecodeError as exc:
+        LOGGER.warning("node.json is invalid JSON; ignoring", extra={"error": str(exc)})
+        return None
+
+
+def save_node_state(path: str, data: Dict[str, Any]) -> None:
+    """原子化写入 node.json，避免并发读取坏数据。"""
+    directory = Path(path).parent
+    directory.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile("w", dir=directory, delete=False, encoding="utf-8") as tmp:
+        json.dump(data, tmp, separators=(",", ":"))
+        tmp.flush()
+        os.fsync(tmp.fileno())
+        temp_path = tmp.name
+    os.replace(temp_path, path)
+
+
+def clear_node_state(path: str) -> None:
+    try:
+        os.remove(path)
+    except FileNotFoundError:
+        return
+    except OSError as exc:
+        LOGGER.warning("Failed to remove node state file", extra={"error": str(exc), "path": path})

src/agent/app/version.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+import importlib.metadata
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+def _candidate_paths() -> list[Path]:
+    paths = []
+    bundle_dir: Optional[str] = getattr(sys, "_MEIPASS", None)
+    if bundle_dir:
+        paths.append(Path(bundle_dir) / "pyproject.toml")
+    paths.append(Path(__file__).resolve().parent.parent / "pyproject.toml")
+    paths.append(Path(__file__).resolve().parent / "pyproject.toml")
+    paths.append(Path.cwd() / "pyproject.toml")
+    return paths
+
+
+def _read_from_pyproject() -> Optional[str]:
+    for path in _candidate_paths():
+        if not path.exists():
+            continue
+        try:
+            with path.open("rb") as handle:
+                data = tomllib.load(handle)
+        except (OSError, tomllib.TOMLDecodeError):
+            continue
+        project = data.get("project")
+        if isinstance(project, dict):
+            version = project.get("version")
+            if isinstance(version, str):
+                return version
+        tool = data.get("tool")
+        if isinstance(tool, dict):
+            argus_cfg = tool.get("argus")
+            if isinstance(argus_cfg, dict):
+                version = argus_cfg.get("version")
+                if isinstance(version, str):
+                    return version
+    return None
+
+
+def _detect_version() -> str:
+    try:
+        return importlib.metadata.version("argus-agent")
+    except importlib.metadata.PackageNotFoundError:
+        pass
+    override = os.environ.get("AGENT_VERSION_OVERRIDE")
+    if override:
+        return override
+    fallback = _read_from_pyproject()
+    if fallback:
+        return fallback
+    return "0.0.0"
+
+
+VERSION: str = _detect_version()
+
+
+def get_version() -> str:
+    return VERSION

src/agent/entry.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import sys
+
+from app.main import main as agent_main
+
+
+if __name__ == "__main__":
+    sys.exit(agent_main())

src/agent/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "argus-agent"
+version = "1.1.0"
+description = "Argus agent binary"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "requests==2.31.0"
+]
+
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.argus]
+entry = "app.main:main"
+
+[tool.setuptools]
+packages = ["app"]

src/agent/scripts/agent_deployment_verify.sh

@@ -0,0 +1,690 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LOG_PREFIX="[AGENT-VERIFY]"
+MASTER_ENDPOINT_DEFAULT=""
+AGENT_DATA_ROOT_DEFAULT="/private/argus/agent"
+AGENT_ETC_ROOT_DEFAULT="/private/argus/etc"
+REPORT_INTERVAL_DEFAULT="2"
+
+ALLOW_CONFIG_TOUCH="false"
+KEEP_TEST_HEALTH="false"
+
+log_info() {
+  echo "${LOG_PREFIX} INFO  $*"
+}
+
+log_warn() {
+  echo "${LOG_PREFIX} WARN  $*" >&2
+}
+
+log_error() {
+  echo "${LOG_PREFIX} ERROR $*" >&2
+}
+
+usage() {
+  cat <<'USAGE'
+Usage: agent_deployment_verify.sh [options]
+
+Options:
+  --allow-config-touch   Enable optional config PUT dry-run check.
+  --keep-test-health     Keep the temporary verify health file after checks.
+  -h, --help             Show this help message.
+
+Environment variables:
+  MASTER_ENDPOINT        (required) Master API base endpoint, e.g. http://master:3000
+  AGENT_DATA_ROOT        (default: /private/argus/agent)
+  AGENT_ETC_ROOT         (default: /private/argus/etc)
+  VERIFY_HOSTNAME        (default: output of hostname)
+  REPORT_INTERVAL_SECONDS (default: 2) Agent report interval in seconds
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --allow-config-touch)
+      ALLOW_CONFIG_TOUCH="true"
+      shift
+      ;;
+    --keep-test-health)
+      KEEP_TEST_HEALTH="true"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      log_error "Unknown option: $1"
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+MASTER_ENDPOINT="${MASTER_ENDPOINT:-$MASTER_ENDPOINT_DEFAULT}"
+AGENT_DATA_ROOT="${AGENT_DATA_ROOT:-$AGENT_DATA_ROOT_DEFAULT}"
+AGENT_ETC_ROOT="${AGENT_ETC_ROOT:-$AGENT_ETC_ROOT_DEFAULT}"
+VERIFY_HOSTNAME="${VERIFY_HOSTNAME:-$(hostname)}"
+REPORT_INTERVAL_SECONDS="${REPORT_INTERVAL_SECONDS:-$REPORT_INTERVAL_DEFAULT}"
+
+if [[ -z "$MASTER_ENDPOINT" ]]; then
+  log_error "MASTER_ENDPOINT is required"
+  exit 2
+fi
+
+if ! [[ "$REPORT_INTERVAL_SECONDS" =~ ^[0-9]+$ ]] || [[ "$REPORT_INTERVAL_SECONDS" -le 0 ]]; then
+  log_warn "Invalid REPORT_INTERVAL_SECONDS='$REPORT_INTERVAL_SECONDS', fallback to $REPORT_INTERVAL_DEFAULT"
+  REPORT_INTERVAL_SECONDS="$REPORT_INTERVAL_DEFAULT"
+fi
+
+normalize_endpoint() {
+  local endpoint="$1"
+  if [[ "$endpoint" != http://* && "$endpoint" != https://* ]]; then
+    endpoint="http://$endpoint"
+  fi
+  endpoint="${endpoint%/}"
+  echo "$endpoint"
+}
+
+MASTER_BASE="$(normalize_endpoint "$MASTER_ENDPOINT")"
+
+NODE_DIR="$AGENT_DATA_ROOT/$VERIFY_HOSTNAME"
+NODE_JSON="$NODE_DIR/node.json"
+HEALTH_DIR="$NODE_DIR/health"
+DNS_CONF="$AGENT_ETC_ROOT/dns.conf"
+UPDATE_SCRIPT="$AGENT_ETC_ROOT/update-dns.sh"
+
+declare -a RESULTS_PASS=()
+declare -a RESULTS_WARN=()
+declare -a RESULTS_FAIL=()
+
+add_result() {
+  local level="$1" message="$2"
+  case "$level" in
+    PASS)
+      RESULTS_PASS+=("$message")
+      log_info "$message"
+      ;;
+    WARN)
+      RESULTS_WARN+=("$message")
+      log_warn "$message"
+      ;;
+    FAIL)
+      RESULTS_FAIL+=("$message")
+      log_error "$message"
+      ;;
+  esac
+}
+
+HAS_JQ="0"
+if command -v jq >/dev/null 2>&1; then
+  HAS_JQ="1"
+fi
+
+if ! command -v curl >/dev/null 2>&1; then
+  log_error "curl command not found; please install curl (e.g. apt-get install -y curl)"
+  exit 2
+fi
+
+if [[ "$HAS_JQ" == "0" ]] && ! command -v python3 >/dev/null 2>&1; then
+  log_error "Neither jq nor python3 is available for JSON processing"
+  exit 2
+fi
+
+CURL_OPTS=(--fail --show-error --silent --max-time 10)
+
+curl_json() {
+  local url="$1"
+  if ! curl "${CURL_OPTS[@]}" "$url"; then
+    return 1
+  fi
+}
+
+json_query() {
+  local json="$1" jq_expr="$2" py_expr="$3"
+  if [[ "$HAS_JQ" == "1" ]]; then
+    if ! output=$(printf '%s' "$json" | jq -e -r "$jq_expr" 2>/dev/null); then
+      return 1
+    fi
+    printf '%s' "$output"
+    return 0
+  fi
+
+  python3 - "$py_expr" <<'PY'
+import json
+import sys
+
+expr = sys.argv[1]
+try:
+    data = json.load(sys.stdin)
+    value = eval(expr, {}, {"data": data})
+except Exception:
+    sys.exit(1)
+if value is None:
+    sys.exit(1)
+if isinstance(value, (dict, list)):
+    print(json.dumps(value))
+else:
+    print(value)
+PY
+}
+
+json_length() {
+  local json="$1" jq_expr="$2" py_expr="$3"
+  if [[ "$HAS_JQ" == "1" ]]; then
+    if ! output=$(printf '%s' "$json" | jq -e "$jq_expr" 2>/dev/null); then
+      return 1
+    fi
+    printf '%s' "$output"
+    return 0
+  fi
+
+  python3 - "$py_expr" <<'PY'
+import json
+import sys
+
+expr = sys.argv[1]
+try:
+    data = json.load(sys.stdin)
+    value = eval(expr, {}, {"data": data})
+except Exception:
+    sys.exit(1)
+try:
+    print(len(value))
+except Exception:
+    sys.exit(1)
+PY
+}
+
+json_has_key() {
+  local json="$1" jq_expr="$2" py_expr="$3"
+  if [[ "$HAS_JQ" == "1" ]]; then
+    if printf '%s' "$json" | jq -e "$jq_expr" >/dev/null 2>&1; then
+      return 0
+    fi
+    return 1
+  fi
+
+  python3 - "$py_expr" <<'PY'
+import json
+import sys
+
+expr = sys.argv[1]
+try:
+    data = json.load(sys.stdin)
+    value = eval(expr, {}, {"data": data})
+except Exception:
+    sys.exit(1)
+if value:
+    sys.exit(0)
+sys.exit(1)
+PY
+}
+
+iso_to_epoch() {
+  local value="$1"
+  if command -v date >/dev/null 2>&1; then
+    date -d "$value" +%s 2>/dev/null && return 0
+  fi
+  if command -v python3 >/dev/null 2>&1; then
+    python3 - "$value" <<'PY'
+import sys
+from datetime import datetime
+
+value = sys.argv[1]
+if value is None or value == "":
+    sys.exit(1)
+if value.endswith('Z'):
+    value = value[:-1] + '+00:00'
+try:
+    dt = datetime.fromisoformat(value)
+except ValueError:
+    sys.exit(1)
+print(int(dt.timestamp()))
+PY
+    return $?
+  fi
+  return 1
+}
+
+validate_json_file() {
+  local path="$1"
+  if [[ "$HAS_JQ" == "1" ]]; then
+    jq empty "$path" >/dev/null 2>&1 && return 0
+    return 1
+  fi
+  if command -v python3 >/dev/null 2>&1; then
+    python3 - "$path" <<'PY'
+import json
+import sys
+path = sys.argv[1]
+with open(path, 'r', encoding='utf-8') as handle:
+    json.load(handle)
+PY
+    return $?
+  fi
+  return 0
+}
+
+ensure_directory() {
+  local dir="$1"
+  if [[ ! -d "$dir" ]]; then
+    log_warn "Creating missing directory $dir"
+    mkdir -p "$dir"
+  fi
+}
+
+TEST_HEALTH_FILE=""
+TEST_HEALTH_BACKUP=""
+TEST_HEALTH_EXISTED="false"
+
+cleanup() {
+  if [[ -n "$TEST_HEALTH_FILE" ]]; then
+    if [[ "$TEST_HEALTH_EXISTED" == "true" ]]; then
+      printf '%s' "$TEST_HEALTH_BACKUP" > "$TEST_HEALTH_FILE"
+    elif [[ "$KEEP_TEST_HEALTH" == "true" ]]; then
+      :
+    else
+      rm -f "$TEST_HEALTH_FILE"
+    fi
+  fi
+}
+
+trap cleanup EXIT
+
+log_info "Starting agent deployment verification for hostname '$VERIFY_HOSTNAME'"
+
+# 4.2 Master health checks
+health_resp=""
+if ! health_resp=$(curl "${CURL_OPTS[@]}" -w '\n%{http_code} %{time_total}' "$MASTER_BASE/healthz" 2>/tmp/agent_verify_healthz.err); then
+  error_detail=$(cat /tmp/agent_verify_healthz.err || true)
+  add_result FAIL "GET /healthz failed: $error_detail"
+else
+  http_meta=$(tail -n1 <<<"$health_resp")
+  payload=$(head -n -1 <<<"$health_resp" || true)
+  status_code=${http_meta%% *}
+  elapsed=${http_meta##* }
+  add_result PASS "GET /healthz status=$status_code elapsed=${elapsed}s payload=$payload"
+fi
+rm -f /tmp/agent_verify_healthz.err
+
+if ! readyz_resp=$(curl "${CURL_OPTS[@]}" -w '\n%{http_code} %{time_total}' "$MASTER_BASE/readyz" 2>/tmp/agent_verify_readyz.err); then
+  error_detail=$(cat /tmp/agent_verify_readyz.err || true)
+  add_result FAIL "GET /readyz failed: $error_detail"
+  readyz_payload=""
+else
+  readyz_meta=$(tail -n1 <<<"$readyz_resp")
+  readyz_payload=$(head -n -1 <<<"$readyz_resp" || true)
+  readyz_status=${readyz_meta%% *}
+  readyz_elapsed=${readyz_meta##* }
+  add_result PASS "GET /readyz status=$readyz_status elapsed=${readyz_elapsed}s"
+fi
+rm -f /tmp/agent_verify_readyz.err
+
+# 4.3 Nodes list and detail
+if ! nodes_json=$(curl_json "$MASTER_BASE/api/v1/master/nodes" 2>/tmp/agent_verify_nodes.err); then
+  error_detail=$(cat /tmp/agent_verify_nodes.err || true)
+  add_result FAIL "GET /api/v1/master/nodes failed: $error_detail"
+  nodes_json=""
+fi
+rm -f /tmp/agent_verify_nodes.err
+
+NODE_ENTRY=""
+NODE_ID=""
+NODE_IP=""
+if [[ -n "$nodes_json" ]]; then
+  if [[ "$HAS_JQ" == "1" ]]; then
+    NODE_ENTRY=$(printf '%s' "$nodes_json" | jq -e --arg name "$VERIFY_HOSTNAME" '.[] | select(.name == $name)') || NODE_ENTRY=""
+  else
+    NODE_ENTRY=$(python3 - "$VERIFY_HOSTNAME" <<'PY'
+import json
+import sys
+
+hostname = sys.argv[1]
+nodes = json.load(sys.stdin)
+for node in nodes:
+    if node.get("name") == hostname:
+        import json as _json
+        print(_json.dumps(node))
+        sys.exit(0)
+sys.exit(1)
+PY
+    ) || NODE_ENTRY=""
+  fi
+
+  if [[ -z "$NODE_ENTRY" ]]; then
+    add_result FAIL "Current node '$VERIFY_HOSTNAME' not found in master nodes list"
+  else
+    if NODE_ID=$(json_query "$NODE_ENTRY" '.id' 'data["id"]'); then
+      add_result PASS "Discovered node id '$NODE_ID' for hostname '$VERIFY_HOSTNAME'"
+    else
+      add_result FAIL "Failed to extract node id from master response"
+    fi
+  fi
+
+  if [[ -n "$NODE_ENTRY" ]] && NODE_DETAIL=$(curl_json "$MASTER_BASE/api/v1/master/nodes/$NODE_ID" 2>/tmp/agent_verify_node_detail.err); then
+    NODE_DETAIL_JSON="$NODE_DETAIL"
+    add_result PASS "Fetched node detail for $NODE_ID"
+    if NODE_IP=$(json_query "$NODE_DETAIL_JSON" '.meta_data.ip // .meta_data.host_ip // empty' 'data.get("meta_data", {}).get("ip") or data.get("meta_data", {}).get("host_ip") or ""'); then
+      if [[ -n "$NODE_IP" ]]; then
+        add_result PASS "Registered node IP=$NODE_IP"
+      else
+        add_result INFO "Node detail does not expose IP fields"
+      fi
+    fi
+  else
+    error_detail=$(cat /tmp/agent_verify_node_detail.err 2>/dev/null || true)
+    add_result FAIL "Failed to fetch node detail for $NODE_ID: $error_detail"
+    NODE_DETAIL_JSON=""
+  fi
+  rm -f /tmp/agent_verify_node_detail.err
+
+  if stats_json=$(curl_json "$MASTER_BASE/api/v1/master/nodes/statistics" 2>/tmp/agent_verify_stats.err); then
+    if total_nodes=$(json_query "$stats_json" '.total // .total_nodes' 'data.get("total") or data.get("total_nodes")'); then
+      if [[ "$total_nodes" =~ ^[0-9]+$ ]] && [[ "$total_nodes" -ge 1 ]]; then
+        add_result PASS "Statistics total=$total_nodes"
+      else
+        add_result WARN "Statistics total field not numeric: $total_nodes"
+      fi
+    else
+      add_result WARN "Unable to read total field from statistics"
+    fi
+
+    active_nodes=""
+    if [[ "$HAS_JQ" == "1" ]]; then
+      active_nodes=$(printf '%s' "$stats_json" | jq -e 'if .status_statistics then (.status_statistics[] | select(.status == "online") | .count) else empty end' 2>/dev/null | head -n1 || true)
+    elif command -v python3 >/dev/null 2>&1; then
+      active_nodes=$(printf '%s' "$stats_json" | python3 -c 'import json,sys; data=json.load(sys.stdin); print(next((row.get("count") for row in data.get("status_statistics", []) if row.get("status")=="online"), ""))' 2>/dev/null)
+    fi
+    if [[ -n "$active_nodes" ]]; then
+      add_result PASS "Online nodes reported by master: $active_nodes"
+    fi
+
+    if [[ "$HAS_JQ" == "1" ]]; then
+      node_count=$(printf '%s' "$nodes_json" | jq 'length')
+    else
+      node_count=$(json_length "$nodes_json" 'length' 'len(data)')
+    fi
+    if [[ "$total_nodes" =~ ^[0-9]+$ ]] && [[ "$node_count" =~ ^[0-9]+$ ]] && [[ "$total_nodes" -lt "$node_count" ]]; then
+      add_result WARN "Statistics total=$total_nodes less than nodes list count=$node_count"
+    fi
+  else
+    error_detail=$(cat /tmp/agent_verify_stats.err 2>/dev/null || true)
+    add_result FAIL "Failed to fetch node statistics: $error_detail"
+  fi
+  rm -f /tmp/agent_verify_stats.err
+else
+  NODE_DETAIL_JSON=""
+fi
+
+# 4.4 Agent persistence checks
+if [[ -f "$NODE_JSON" ]]; then
+  node_file_content="$(cat "$NODE_JSON")"
+  if node_id_local=$(json_query "$node_file_content" '.id' 'data["id"]'); then
+    if [[ "$NODE_ID" != "" && "$node_id_local" == "$NODE_ID" ]]; then
+      add_result PASS "node.json id matches master ($NODE_ID)"
+    else
+      add_result FAIL "node.json id '$node_id_local' differs from master id '$NODE_ID'"
+    fi
+  else
+    add_result FAIL "Unable to extract id from node.json"
+  fi
+  if node_name_local=$(json_query "$node_file_content" '.name' 'data["name"]'); then
+    if [[ "$node_name_local" == "$VERIFY_HOSTNAME" ]]; then
+      add_result PASS "node.json name matches $VERIFY_HOSTNAME"
+    else
+      add_result FAIL "node.json name '$node_name_local' differs from hostname '$VERIFY_HOSTNAME'"
+    fi
+  else
+    add_result FAIL "Unable to extract name from node.json"
+  fi
+
+  if register_time=$(json_query "$node_file_content" '.register_time' 'data.get("register_time")'); then
+    if iso_to_epoch "$register_time" >/dev/null 2>&1; then
+      add_result PASS "node.json register_time valid ISO timestamp"
+    else
+      add_result WARN "node.json register_time invalid: $register_time"
+    fi
+  else
+    add_result WARN "node.json missing register_time"
+  fi
+
+  if last_updated=$(json_query "$node_file_content" '.last_updated' 'data.get("last_updated")'); then
+    if iso_to_epoch "$last_updated" >/dev/null 2>&1; then
+      add_result PASS "node.json last_updated valid ISO timestamp"
+    else
+      add_result WARN "node.json last_updated invalid: $last_updated"
+    fi
+  else
+    add_result WARN "node.json missing last_updated"
+  fi
+else
+  add_result FAIL "node.json not found at $NODE_JSON"
+  node_file_content=""
+fi
+
+ensure_directory "$HEALTH_DIR"
+
+if [[ -d "$HEALTH_DIR" ]]; then
+  shopt -s nullglob
+  health_files=("$HEALTH_DIR"/*.json)
+  shopt -u nullglob
+  if [[ ${#health_files[@]} -eq 0 ]]; then
+    add_result WARN "Health directory $HEALTH_DIR is empty"
+  else
+    for hf in "${health_files[@]}"; do
+      base=$(basename "$hf")
+      if [[ "$base" != *-* ]]; then
+        add_result WARN "Health file $base does not follow <module>-*.json"
+        continue
+      fi
+      if ! validate_json_file "$hf" >/dev/null 2>&1; then
+        add_result WARN "Health file $base is not valid JSON"
+      fi
+    done
+  fi
+else
+  add_result WARN "Health directory $HEALTH_DIR missing"
+fi
+
+if getent hosts master.argus.com >/dev/null 2>&1; then
+  resolved_ips=$(getent hosts master.argus.com | awk '{print $1}' | xargs)
+  add_result PASS "master.argus.com resolves to $resolved_ips"
+else
+  add_result FAIL "Failed to resolve master.argus.com"
+fi
+
+# 4.5 Master-Node status consistency
+sleep_interval=$((REPORT_INTERVAL_SECONDS + 2))
+
+if [[ -n "$NODE_DETAIL_JSON" ]]; then
+  detail_pre="$NODE_DETAIL_JSON"
+else
+  detail_pre=""
+fi
+
+if [[ -z "$detail_pre" && -n "$NODE_ID" ]]; then
+  if detail_pre=$(curl_json "$MASTER_BASE/api/v1/master/nodes/$NODE_ID" 2>/tmp/agent_verify_detail_pre.err); then
+    add_result PASS "Fetched node detail pre-check"
+  else
+    error_detail=$(cat /tmp/agent_verify_detail_pre.err 2>/dev/null || true)
+    add_result FAIL "Unable to fetch node detail for status check: $error_detail"
+  fi
+  rm -f /tmp/agent_verify_detail_pre.err
+fi
+
+server_ts_pre=""
+agent_ts_pre=""
+server_ts_post=""
+agent_ts_post=""
+
+if [[ -n "$detail_pre" ]]; then
+  server_ts_pre=$(json_query "$detail_pre" '.last_report' 'data.get("last_report")' || echo "")
+  agent_ts_pre=$(json_query "$detail_pre" '.agent_last_report' 'data.get("agent_last_report")' || echo "")
+  log_info "Captured initial last_report timestamps server='$server_ts_pre' agent='$agent_ts_pre'"
+
+  sleep "$sleep_interval"
+
+  if detail_post=$(curl_json "$MASTER_BASE/api/v1/master/nodes/$NODE_ID" 2>/tmp/agent_verify_detail_post.err); then
+    server_ts_post=$(json_query "$detail_post" '.last_report' 'data.get("last_report")' || echo "")
+    agent_ts_post=$(json_query "$detail_post" '.agent_last_report' 'data.get("agent_last_report")' || echo "")
+    if [[ "$server_ts_post" != "$server_ts_pre" ]]; then
+      add_result PASS "last_report.server_timestamp advanced (pre=$server_ts_pre post=$server_ts_post)"
+    else
+      add_result FAIL "last_report.server_timestamp did not change after ${sleep_interval}s"
+    fi
+    if [[ "$agent_ts_post" != "$agent_ts_pre" ]]; then
+      add_result PASS "last_report.agent_timestamp advanced"
+    else
+      add_result FAIL "last_report.agent_timestamp did not change"
+    fi
+
+    if [[ -n "$node_file_content" ]]; then
+      if node_last_updated=$(json_query "$node_file_content" '.last_updated' 'data.get("last_updated")'); then
+        if epoch_post=$(iso_to_epoch "$server_ts_post" 2>/dev/null); then
+          if node_epoch=$(iso_to_epoch "$node_last_updated" 2>/dev/null); then
+            diff=$((epoch_post - node_epoch))
+            [[ $diff -lt 0 ]] && diff=$((-diff))
+            tolerance=$((REPORT_INTERVAL_SECONDS * 2))
+            if [[ $diff -le $tolerance ]]; then
+              add_result PASS "last_report.server_timestamp and node.json last_updated within tolerance ($diff s)"
+            else
+              add_result WARN "Timestamp gap between master ($server_ts_post) and node.json ($node_last_updated) is ${diff}s"
+            fi
+          fi
+        fi
+      fi
+    fi
+
+    NODE_DETAIL_JSON="$detail_post"
+  else
+    error_detail=$(cat /tmp/agent_verify_detail_post.err 2>/dev/null || true)
+    add_result FAIL "Failed to fetch node detail post-check: $error_detail"
+  fi
+  rm -f /tmp/agent_verify_detail_post.err
+fi
+
+# 4.6 Health simulation
+TEST_HEALTH_FILE="$HEALTH_DIR/verify-master.json"
+ensure_directory "$HEALTH_DIR"
+
+if [[ -f "$TEST_HEALTH_FILE" ]]; then
+  TEST_HEALTH_EXISTED="true"
+  TEST_HEALTH_BACKUP="$(cat "$TEST_HEALTH_FILE")"
+else
+  TEST_HEALTH_EXISTED="false"
+fi
+
+create_health_file() {
+  local message="$1"
+  cat > "$TEST_HEALTH_FILE" <<HEALTHJSON
+{"status":"ok","message":"$message"}
+HEALTHJSON
+}
+
+validate_health_in_master() {
+  local expected_message="$1"
+  local detail_json="$2"
+  local message
+  if message=$(json_query "$detail_json" '.health["verify-master"].message' 'data.get("health", {}).get("verify-master", {}).get("message")'); then
+    if [[ "$message" == "$expected_message" ]]; then
+      return 0
+    fi
+  fi
+  return 1
+}
+
+remove_health_from_master() {
+  local detail_json="$1"
+  if json_has_key "$detail_json" '(.health | has("verify-master"))' '"verify-master" in data.get("health", {})'; then
+    return 1
+  fi
+  return 0
+}
+
+health_message_one="verify $(date +%s)"
+create_health_file "$health_message_one"
+add_result PASS "Created test health file $TEST_HEALTH_FILE"
+
+sleep "$sleep_interval"
+if detail_health_one=$(curl_json "$MASTER_BASE/api/v1/master/nodes/$NODE_ID" 2>/tmp/agent_verify_health1.err); then
+  if validate_health_in_master "$health_message_one" "$detail_health_one"; then
+    add_result PASS "Master reflects verify-master health message"
+  else
+    add_result FAIL "Master health payload does not match test message"
+  fi
+else
+  error_detail=$(cat /tmp/agent_verify_health1.err 2>/dev/null || true)
+  add_result FAIL "Failed to fetch node detail during health validation: $error_detail"
+  detail_health_one=""
+fi
+rm -f /tmp/agent_verify_health1.err
+
+health_message_two="verify $(date +%s)-update"
+create_health_file "$health_message_two"
+sleep "$sleep_interval"
+if detail_health_two=$(curl_json "$MASTER_BASE/api/v1/master/nodes/$NODE_ID" 2>/tmp/agent_verify_health2.err); then
+  if validate_health_in_master "$health_message_two" "$detail_health_two"; then
+    add_result PASS "Master health updated to new message"
+  else
+    add_result FAIL "Master health message did not update"
+  fi
+else
+  error_detail=$(cat /tmp/agent_verify_health2.err 2>/dev/null || true)
+  add_result FAIL "Failed to fetch node detail after health update: $error_detail"
+  detail_health_two=""
+fi
+rm -f /tmp/agent_verify_health2.err
+
+rm -f "$TEST_HEALTH_FILE"
+sleep "$sleep_interval"
+if detail_health_three=$(curl_json "$MASTER_BASE/api/v1/master/nodes/$NODE_ID" 2>/tmp/agent_verify_health3.err); then
+  if remove_health_from_master "$detail_health_three"; then
+    add_result PASS "Master health no longer lists verify-master after removal"
+  else
+    add_result FAIL "Master health still contains verify-master after file deletion"
+  fi
+else
+  error_detail=$(cat /tmp/agent_verify_health3.err 2>/dev/null || true)
+  add_result FAIL "Failed to fetch node detail after health removal: $error_detail"
+fi
+rm -f /tmp/agent_verify_health3.err
+
+if [[ "$TEST_HEALTH_EXISTED" == "true" ]]; then
+  printf '%s' "$TEST_HEALTH_BACKUP" > "$TEST_HEALTH_FILE"
+fi
+
+# Optional config touch
+if [[ "$ALLOW_CONFIG_TOUCH" == "true" ]]; then
+  if [[ -n "$NODE_ID" ]]; then
+    payload='{"label": {"verify": "true"}}'
+    if curl "${CURL_OPTS[@]}" -X PUT -H 'Content-Type: application/json' -d "$payload" "$MASTER_BASE/api/v1/master/nodes/$NODE_ID/config" >/tmp/agent_verify_config.log 2>&1; then
+      add_result PASS "Config PUT dry-run succeeded"
+    else
+      add_result WARN "Config PUT dry-run failed: $(cat /tmp/agent_verify_config.log)"
+    fi
+    rm -f /tmp/agent_verify_config.log
+  fi
+else
+  add_result WARN "Config PUT dry-run skipped (enable with --allow-config-touch)"
+fi
+
+# Result summary
+echo
+echo "==== Verification Summary ===="
+for entry in "${RESULTS_PASS[@]}"; do
+  printf 'PASS: %s\n' "$entry"
+done
+for entry in "${RESULTS_WARN[@]}"; do
+  printf 'WARN: %s\n' "$entry"
+done
+for entry in "${RESULTS_FAIL[@]}"; do
+  printf 'FAIL: %s\n' "$entry"
+done
+
+if [[ ${#RESULTS_FAIL[@]} -gt 0 ]]; then
+  exit 1
+fi
+
+exit 0

src/agent/scripts/build_binary.sh

@@ -0,0 +1,269 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MODULE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+BUILD_ROOT="$MODULE_ROOT/build"
+DIST_DIR="$MODULE_ROOT/dist"
+PYINSTALLER_BUILD="$BUILD_ROOT/pyinstaller"
+PYINSTALLER_SPEC="$PYINSTALLER_BUILD/spec"
+PYINSTALLER_WORK="$PYINSTALLER_BUILD/work"
+VENV_DIR="$BUILD_ROOT/venv"
+
+AGENT_BUILD_IMAGE="${AGENT_BUILD_IMAGE:-python:3.11-slim-bullseye}"
+AGENT_BUILD_USE_DOCKER="${AGENT_BUILD_USE_DOCKER:-1}"
+USED_DOCKER=0
+
+run_host_build() {
+  echo "[INFO] Using host Python environment for build" >&2
+  rm -rf "$BUILD_ROOT" "$DIST_DIR"
+  mkdir -p "$PYINSTALLER_BUILD" "$DIST_DIR"
+  python3 -m venv --copies "$VENV_DIR"
+  # shellcheck disable=SC1091
+  source "$VENV_DIR/bin/activate"
+
+  pip install --upgrade pip
+  pip install .
+  pip install "pyinstaller==6.6.0"
+
+  pyinstaller \
+    --clean \
+    --onefile \
+    --name argus-agent \
+    --distpath "$DIST_DIR" \
+    --workpath "$PYINSTALLER_WORK" \
+    --specpath "$PYINSTALLER_SPEC" \
+    --add-data "$MODULE_ROOT/pyproject.toml:." \
+    "$MODULE_ROOT/entry.py"
+
+  chmod +x "$DIST_DIR/argus-agent"
+  deactivate
+}
+
+run_docker_build() {
+  if ! command -v docker >/dev/null 2>&1; then
+    echo "[ERROR] docker 命令不存在，无法在容器内构建。请安装 Docker 或设置 AGENT_BUILD_USE_DOCKER=0" >&2
+    exit 1
+  fi
+
+  USED_DOCKER=1
+  echo "[INFO] Building agent binary inside $AGENT_BUILD_IMAGE" >&2
+
+  local host_uid host_gid
+  host_uid="$(id -u)"
+  host_gid="$(id -g)"
+  docker_env=("--rm" "-v" "$MODULE_ROOT:/workspace" "-w" "/workspace" "--env" "TARGET_UID=${host_uid}" "--env" "TARGET_GID=${host_gid}")
+
+  pass_env_if_set() {
+    local var="$1"
+    local value="${!var:-}"
+    if [[ -n "$value" ]]; then
+      docker_env+=("--env" "$var=$value")
+    fi
+  }
+
+  pass_env_if_set PIP_INDEX_URL
+  pass_env_if_set PIP_EXTRA_INDEX_URL
+  pass_env_if_set PIP_TRUSTED_HOST
+  pass_env_if_set HTTP_PROXY
+  pass_env_if_set HTTPS_PROXY
+  pass_env_if_set NO_PROXY
+  pass_env_if_set http_proxy
+  pass_env_if_set https_proxy
+  pass_env_if_set no_proxy
+
+build_script=$(cat <<'INNER'
+set -euo pipefail
+cd /workspace
+apt-get update >/dev/null
+apt-get install -y --no-install-recommends binutils >/dev/null
+rm -rf /var/lib/apt/lists/*
+rm -rf build dist
+mkdir -p build/pyinstaller dist
+python3 -m venv --copies build/venv
+source build/venv/bin/activate
+pip install --upgrade pip
+pip install .
+pip install pyinstaller==6.6.0
+pyinstaller \
+  --clean \
+  --onefile \
+  --name argus-agent \
+  --distpath dist \
+  --workpath build/pyinstaller/work \
+  --specpath build/pyinstaller/spec \
+  --add-data /workspace/pyproject.toml:. \
+  entry.py
+chmod +x dist/argus-agent
+
+TARGET_UID="${TARGET_UID:-0}"
+TARGET_GID="${TARGET_GID:-0}"
+chown -R "$TARGET_UID:$TARGET_GID" dist build 2>/dev/null || true
+
+python3 - <<'PY'
+from pathlib import Path
+from PyInstaller.archive.readers import CArchiveReader
+import sys
+
+archive = Path('dist/argus-agent')
+out_dir = Path('build/compat_check')
+out_dir.mkdir(parents=True, exist_ok=True)
+
+major, minor = sys.version_info[:2]
+libpython = f'libpython{major}.{minor}.so.1.0'
+expected_libs = [
+    libpython,
+    'libssl.so.3',
+    'libcrypto.so.3',
+]
+reader = CArchiveReader(str(archive))
+extracted = []
+missing = []
+for name in expected_libs:
+    try:
+        data = reader.extract(name)
+    except KeyError:
+        missing.append(name)
+        continue
+    (out_dir / name).write_bytes(data)
+    extracted.append(name)
+(out_dir / 'manifest').write_text('\n'.join(extracted))
+if extracted:
+    print('[INFO] Extracted libraries: ' + ', '.join(extracted))
+if missing:
+    print('[WARN] Missing expected libraries in bundle: ' + ', '.join(missing))
+PY
+
+compat_check() {
+  local lib_path="$1"
+  if [[ ! -f "$lib_path" ]]; then
+    echo "[WARN] Missing $lib_path for GLIBC check"
+    return
+  fi
+  local max_glibc
+  max_glibc=$(strings -a "$lib_path" | grep -Eo 'GLIBC_[0-9]+\.[0-9]+' | sort -Vu | tail -n 1 || true)
+  if [[ -n "$max_glibc" ]]; then
+    echo "[INFO] $lib_path references up to $max_glibc"
+  else
+    echo "[INFO] $lib_path does not expose GLIBC version strings"
+  fi
+}
+
+compat_libs=()
+if [[ -f build/compat_check/manifest ]]; then
+  mapfile -t compat_libs < build/compat_check/manifest
+fi
+
+if [[ ${#compat_libs[@]} -eq 0 ]]; then
+  echo "[WARN] No libraries captured for GLIBC inspection"
+else
+  for lib in "${compat_libs[@]}"; do
+    compat_check "build/compat_check/$lib"
+  done
+fi
+
+deactivate
+INNER
+  )
+
+  if ! docker run "${docker_env[@]}" "$AGENT_BUILD_IMAGE" bash -lc "$build_script"; then
+    echo "[ERROR] Docker 构建失败，请检查 Docker 权限或设置 AGENT_BUILD_USE_DOCKER=0 在兼容主机上构建" >&2
+    exit 1
+  fi
+}
+
+if [[ "$AGENT_BUILD_USE_DOCKER" == "1" ]]; then
+  run_docker_build
+else
+  run_host_build
+fi
+
+if [[ ! -f "$DIST_DIR/argus-agent" ]]; then
+  echo "[ERROR] Agent binary was not produced" >&2
+  exit 1
+fi
+
+if [[ "$USED_DOCKER" != "1" ]]; then
+  if [[ ! -x "$VENV_DIR/bin/python" ]]; then
+    echo "[WARN] PyInstaller virtualenv missing at $VENV_DIR; skipping compatibility check" >&2
+  else
+    COMPAT_DIR="$BUILD_ROOT/compat_check"
+    rm -rf "$COMPAT_DIR"
+    mkdir -p "$COMPAT_DIR"
+
+    EXTRACT_SCRIPT=$(cat <<'PY'
+from pathlib import Path
+from PyInstaller.archive.readers import CArchiveReader
+import sys
+
+archive = Path('dist/argus-agent')
+out_dir = Path('build/compat_check')
+out_dir.mkdir(parents=True, exist_ok=True)
+
+major, minor = sys.version_info[:2]
+libpython = f'libpython{major}.{minor}.so.1.0'
+expected_libs = [
+    libpython,
+    'libssl.so.3',
+    'libcrypto.so.3',
+]
+reader = CArchiveReader(str(archive))
+extracted = []
+missing = []
+for name in expected_libs:
+    try:
+        data = reader.extract(name)
+    except KeyError:
+        missing.append(name)
+        continue
+    (out_dir / name).write_bytes(data)
+    extracted.append(name)
+(out_dir / 'manifest').write_text('\n'.join(extracted))
+if extracted:
+    print('[INFO] Extracted libraries: ' + ', '.join(extracted))
+if missing:
+    print('[WARN] Missing expected libraries in bundle: ' + ', '.join(missing))
+PY
+)
+
+    "$VENV_DIR/bin/python" - <<PY
+$EXTRACT_SCRIPT
+PY
+
+    compat_libs=()
+    if [[ -f "$COMPAT_DIR/manifest" ]]; then
+      mapfile -t compat_libs < "$COMPAT_DIR/manifest"
+    fi
+
+    check_glibc_version() {
+      local lib_path="$1"
+      if [[ ! -f "$lib_path" ]]; then
+        echo "[WARN] Skipping GLIBC check; file not found: $lib_path" >&2
+        return
+      fi
+      if command -v strings >/dev/null 2>&1; then
+        local max_glibc
+        max_glibc=$(strings -a "$lib_path" | grep -Eo 'GLIBC_[0-9]+\.[0-9]+' | sort -Vu | tail -n 1 || true)
+        if [[ -n "$max_glibc" ]]; then
+          echo "[INFO] $lib_path references up to $max_glibc"
+        else
+          echo "[INFO] $lib_path does not expose GLIBC version strings"
+        fi
+      else
+        echo "[WARN] strings command unavailable; cannot inspect $lib_path" >&2
+      fi
+    }
+
+    if [[ ${#compat_libs[@]} -eq 0 ]]; then
+      echo "[WARN] No libraries captured for GLIBC inspection" >&2
+    else
+      for lib in "${compat_libs[@]}"; do
+        check_glibc_version "$COMPAT_DIR/$lib"
+      done
+    fi
+  fi
+else
+  echo "[INFO] Compatibility check executed inside container"
+fi
+
+echo "[INFO] Agent binary generated at $DIST_DIR/argus-agent"

src/agent/tests/.gitignore

@@ -0,0 +1,2 @@
+private/
+tmp/

src/agent/tests/docker-compose.yml

@@ -0,0 +1,69 @@
+services:
+  bind:
+    image: ${BIND_IMAGE_TAG:-argus-bind9:latest}
+    container_name: argus-bind-agent-e2e
+    volumes:
+      - ./private:/private
+    networks:
+      default:
+        ipv4_address: 172.28.0.2
+    environment:
+      - "ARGUS_BUILD_UID=${ARGUS_BUILD_UID:-2133}"
+      - "ARGUS_BUILD_GID=${ARGUS_BUILD_GID:-2015}"
+    restart: always
+
+  master:
+    image: argus-master:latest
+    container_name: argus-master-agent-e2e
+    depends_on:
+      - bind
+    environment:
+      - OFFLINE_THRESHOLD_SECONDS=6
+      - ONLINE_THRESHOLD_SECONDS=2
+      - SCHEDULER_INTERVAL_SECONDS=1
+      - "ARGUS_BUILD_UID=${ARGUS_BUILD_UID:-2133}"
+      - "ARGUS_BUILD_GID=${ARGUS_BUILD_GID:-2015}"
+    ports:
+      - "32300:3000"
+    volumes:
+      - ./private/argus/master:/private/argus/master
+      - ./private/argus/metric/prometheus:/private/argus/metric/prometheus
+      - ./private/argus/etc:/private/argus/etc
+    networks:
+      default:
+        ipv4_address: 172.28.0.10
+    restart: always
+
+  agent:
+    image: ubuntu:22.04
+    container_name: argus-agent-e2e
+    hostname: dev-e2euser-e2einst-pod-0
+    depends_on:
+      - master
+      - bind
+    environment:
+      - MASTER_ENDPOINT=http://master.argus.com:3000
+      - REPORT_INTERVAL_SECONDS=2
+      - "ARGUS_BUILD_UID=${ARGUS_BUILD_UID:-2133}"
+      - "ARGUS_BUILD_GID=${ARGUS_BUILD_GID:-2015}"
+    volumes:
+      - ./private/argus/agent/dev-e2euser-e2einst-pod-0:/private/argus/agent/dev-e2euser-e2einst-pod-0
+      - ./private/argus/agent/dev-e2euser-e2einst-pod-0/health:/private/argus/agent/dev-e2euser-e2einst-pod-0/health
+      - ./private/argus/etc:/private/argus/etc
+      - ../dist/argus-agent:/usr/local/bin/argus-agent:ro
+      - ./scripts/agent_entrypoint.sh:/usr/local/bin/agent-entrypoint.sh:ro
+      - ../scripts/agent_deployment_verify.sh:/usr/local/bin/agent_deployment_verify.sh:ro
+    entrypoint:
+      - /usr/local/bin/agent-entrypoint.sh
+    networks:
+      default:
+        ipv4_address: 172.28.0.20
+    restart: always
+
+networks:
+  default:
+    driver: bridge
+    ipam:
+      driver: default
+      config:
+        - subnet: 172.28.0.0/16

src/agent/tests/scripts/00_e2e_test.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPTS=(
+  "01_bootstrap.sh"
+  "02_up.sh"
+  "03_wait_and_assert_registration.sh"
+  "04_write_health_files.sh"
+  "08_verify_agent.sh"
+  "05_assert_status_on_master.sh"
+  "06_restart_agent_and_reregister.sh"
+  "07_down.sh"
+)
+
+for script in "${SCRIPTS[@]}"; do
+  echo "[TEST] Running $script"
+  "$SCRIPT_DIR/$script"
+  echo "[TEST] $script completed"
+  echo
+done
+
+echo "[TEST] Agent module E2E tests completed"

src/agent/tests/scripts/01_bootstrap.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+AGENT_ROOT="$(cd "$TEST_ROOT/.." && pwd)"
+MASTER_ROOT="$(cd "$AGENT_ROOT/../master" && pwd)"
+REPO_ROOT="$(cd "$AGENT_ROOT/../.." && pwd)"
+PRIVATE_ROOT="$TEST_ROOT/private"
+TMP_ROOT="$TEST_ROOT/tmp"
+
+AGENT_HOSTNAME="dev-e2euser-e2einst-pod-0"
+AGENT_CONFIG_DIR="$PRIVATE_ROOT/argus/agent/$AGENT_HOSTNAME"
+AGENT_HEALTH_DIR="$PRIVATE_ROOT/argus/agent/$AGENT_HOSTNAME/health"
+MASTER_PRIVATE_DIR="$PRIVATE_ROOT/argus/master"
+METRIC_PRIVATE_DIR="$PRIVATE_ROOT/argus/metric/prometheus"
+DNS_DIR="$PRIVATE_ROOT/argus/etc"
+BIND_IMAGE_TAG="${BIND_IMAGE_TAG:-argus-bind9:latest}"
+BIND_ROOT="$(cd "$MASTER_ROOT/../bind" && pwd)"
+
+ensure_image() {
+  local image="$1"
+  if ! docker image inspect "$image" >/dev/null 2>&1; then
+    echo "[ERROR] Docker image '$image' 未找到，请先运行统一构建脚本 (例如 ./build/build_images.sh) 生成所需镜像" >&2
+    exit 1
+  fi
+}
+
+mkdir -p "$AGENT_CONFIG_DIR"
+mkdir -p "$AGENT_HEALTH_DIR"
+mkdir -p "$MASTER_PRIVATE_DIR"
+mkdir -p "$METRIC_PRIVATE_DIR"
+mkdir -p "$TMP_ROOT"
+mkdir -p "$DNS_DIR"
+
+touch "$AGENT_HEALTH_DIR/.keep"
+
+# 中文提示：准备 bind 模块提供的 update-dns.sh，模拟生产下发
+if [[ -f "$BIND_ROOT/build/update-dns.sh" ]]; then
+  cp "$BIND_ROOT/build/update-dns.sh" "$DNS_DIR/update-dns.sh"
+  chmod +x "$DNS_DIR/update-dns.sh"
+else
+  echo "[WARN] bind update script missing at $BIND_ROOT/build/update-dns.sh"
+fi
+
+ensure_image "argus-master:latest"
+ensure_image "$BIND_IMAGE_TAG"
+
+AGENT_BINARY="$AGENT_ROOT/dist/argus-agent"
+
+pushd "$AGENT_ROOT" >/dev/null
+./scripts/build_binary.sh
+popd >/dev/null
+
+if [[ ! -x "$AGENT_BINARY" ]]; then
+  echo "[ERROR] Agent binary not found at $AGENT_BINARY" >&2
+  exit 1
+fi
+
+echo "$AGENT_BINARY" > "$TMP_ROOT/agent_binary_path"
+echo "$BIND_IMAGE_TAG" > "$TMP_ROOT/bind_image_tag"
+
+echo "[INFO] Agent E2E bootstrap complete"

src/agent/tests/scripts/02_up.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$TEST_ROOT/../../.." && pwd)"
+
+TMP_ROOT="$TEST_ROOT/tmp"
+ENV_FILE="$TEST_ROOT/.env"
+
+source "$REPO_ROOT/scripts/common/build_user.sh"
+load_build_user
+export ARGUS_BUILD_UID ARGUS_BUILD_GID
+
+cat > "$ENV_FILE" <<EOF
+ARGUS_BUILD_UID=$ARGUS_BUILD_UID
+ARGUS_BUILD_GID=$ARGUS_BUILD_GID
+EOF
+
+if [[ ! -f "$TMP_ROOT/agent_binary_path" ]]; then
+  echo "[ERROR] Agent binary path missing; run 01_bootstrap.sh first" >&2
+  exit 1
+fi
+
+AGENT_BINARY="$(cat "$TMP_ROOT/agent_binary_path")"
+if [[ ! -x "$AGENT_BINARY" ]]; then
+  echo "[ERROR] Agent binary not executable: $AGENT_BINARY" >&2
+  exit 1
+fi
+
+BIND_IMAGE_TAG_VALUE="argus-bind9:latest"
+if [[ -f "$TMP_ROOT/bind_image_tag" ]]; then
+  BIND_IMAGE_TAG_VALUE="$(cat "$TMP_ROOT/bind_image_tag")"
+fi
+
+compose() {
+  if docker compose version >/dev/null 2>&1; then
+    docker compose "$@"
+  else
+    docker-compose "$@"
+  fi
+}
+
+docker container rm -f argus-agent-e2e argus-master-agent-e2e argus-bind-agent-e2e >/dev/null 2>&1 || true
+
+docker network rm tests_default >/dev/null 2>&1 || true
+
+pushd "$TEST_ROOT" >/dev/null
+compose down --remove-orphans || true
+BIND_IMAGE_TAG="$BIND_IMAGE_TAG_VALUE" compose up -d
+popd >/dev/null
+
+echo "[INFO] Master+Agent stack started"

src/agent/tests/scripts/03_wait_and_assert_registration.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+TMP_ROOT="$TEST_ROOT/tmp"
+API_BASE="http://localhost:32300/api/v1/master"
+AGENT_HOSTNAME="dev-e2euser-e2einst-pod-0"
+NODE_FILE="$TEST_ROOT/private/argus/agent/$AGENT_HOSTNAME/node.json"
+
+mkdir -p "$TMP_ROOT"
+
+node_id=""
+for _ in {1..30}; do
+  sleep 2
+  response=$(curl -sS "$API_BASE/nodes" || true)
+  if [[ -z "$response" ]]; then
+    continue
+  fi
+  list_file="$TMP_ROOT/nodes_list.json"
+  echo "$response" > "$list_file"
+  node_id=$(python3 - "$list_file" <<'PY'
+import json, sys
+with open(sys.argv[1]) as handle:
+    nodes = json.load(handle)
+print(nodes[0]["id"] if nodes else "")
+PY
+)
+  if [[ -n "$node_id" ]]; then
+    break
+  fi
+ done
+
+if [[ -z "$node_id" ]]; then
+  echo "[ERROR] Agent did not register within timeout" >&2
+  exit 1
+fi
+
+echo "$node_id" > "$TMP_ROOT/node_id"
+
+if [[ ! -f "$NODE_FILE" ]]; then
+  echo "[ERROR] node.json not created at $NODE_FILE" >&2
+  exit 1
+fi
+
+python3 - "$NODE_FILE" <<'PY'
+import json, sys
+with open(sys.argv[1]) as handle:
+    node = json.load(handle)
+assert "id" in node and node["id"], "node.json missing id"
+PY
+
+detail_file="$TMP_ROOT/initial_detail.json"
+curl -sS "$API_BASE/nodes/$node_id" -o "$detail_file"
+python3 - "$detail_file" "$TMP_ROOT/initial_ip" <<'PY'
+import json, sys, pathlib
+with open(sys.argv[1]) as handle:
+    node = json.load(handle)
+ip = node["meta_data"].get("ip")
+if not ip:
+    raise SystemExit("meta_data.ip missing")
+pathlib.Path(sys.argv[2]).write_text(ip)
+PY
+
+echo "[INFO] Agent registered with node id $node_id"

src/agent/tests/scripts/04_write_health_files.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+HEALTH_DIR="$TEST_ROOT/private/argus/agent/dev-e2euser-e2einst-pod-0/health"
+
+cat > "$HEALTH_DIR/log-fluentbit.json" <<JSON
+{
+  "status": "healthy",
+  "timestamp": "2023-10-05T12:05:00Z"
+}
+JSON
+
+cat > "$HEALTH_DIR/metric-node-exporter.json" <<JSON
+{
+  "status": "healthy",
+  "timestamp": "2023-10-05T12:05:00Z"
+}
+JSON
+
+echo "[INFO] Health files written"

src/agent/tests/scripts/05_assert_status_on_master.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+TMP_ROOT="$TEST_ROOT/tmp"
+API_BASE="http://localhost:32300/api/v1/master"
+NODE_ID="$(cat "$TMP_ROOT/node_id")"
+NODES_JSON="$TEST_ROOT/private/argus/metric/prometheus/nodes.json"
+
+success=false
+detail_file="$TMP_ROOT/agent_status_detail.json"
+for _ in {1..20}; do
+  sleep 2
+  if ! curl -sS "$API_BASE/nodes/$NODE_ID" -o "$detail_file"; then
+    continue
+  fi
+  if python3 - "$detail_file" <<'PY'
+import json, sys
+with open(sys.argv[1]) as handle:
+    node = json.load(handle)
+if node["status"] != "online":
+    raise SystemExit(1)
+health = node.get("health", {})
+if "log-fluentbit" not in health or "metric-node-exporter" not in health:
+    raise SystemExit(1)
+PY
+  then
+    success=true
+    break
+  fi
+done
+
+if [[ "$success" != true ]]; then
+  echo "[ERROR] Node did not report health data in time" >&2
+  exit 1
+fi
+
+if [[ ! -f "$NODES_JSON" ]]; then
+  echo "[ERROR] nodes.json missing at $NODES_JSON" >&2
+  exit 1
+fi
+
+python3 - "$NODES_JSON" <<'PY'
+import json, sys
+with open(sys.argv[1]) as handle:
+    nodes = json.load(handle)
+assert len(nodes) == 1, nodes
+entry = nodes[0]
+assert entry["node_id"], entry
+PY
+
+echo "[INFO] Master reflects agent health and nodes.json entries"

src/agent/tests/scripts/06_restart_agent_and_reregister.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+TMP_ROOT="$TEST_ROOT/tmp"
+API_BASE="http://localhost:32300/api/v1/master"
+NODE_ID="$(cat "$TMP_ROOT/node_id")"
+AGENT_HOSTNAME="dev-e2euser-e2einst-pod-0"
+NETWORK_NAME="tests_default"
+NEW_AGENT_IP="172.28.0.200"
+ENTRYPOINT_SCRIPT="$SCRIPT_DIR/agent_entrypoint.sh"
+ENV_FILE="$TEST_ROOT/.env"
+
+# 中文提示：重启场景也需要同样的入口脚本，确保 DNS 注册逻辑一致
+if [[ ! -f "$ENTRYPOINT_SCRIPT" ]]; then
+  echo "[ERROR] agent entrypoint script missing at $ENTRYPOINT_SCRIPT" >&2
+  exit 1
+fi
+
+if [[ ! -f "$TMP_ROOT/agent_binary_path" ]]; then
+  echo "[ERROR] Agent binary path missing; rerun bootstrap" >&2
+  exit 1
+fi
+
+AGENT_BINARY="$(cat "$TMP_ROOT/agent_binary_path")"
+if [[ ! -x "$AGENT_BINARY" ]]; then
+  echo "[ERROR] Agent binary not executable: $AGENT_BINARY" >&2
+  exit 1
+fi
+
+if [[ -f "$ENV_FILE" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  source "$ENV_FILE"
+  set +a
+else
+  REPO_ROOT="$(cd "$TEST_ROOT/../../.." && pwd)"
+  # shellcheck disable=SC1090
+  source "$REPO_ROOT/scripts/common/build_user.sh"
+  load_build_user
+fi
+
+AGENT_UID="${ARGUS_BUILD_UID:-2133}"
+AGENT_GID="${ARGUS_BUILD_GID:-2015}"
+
+compose() {
+  if docker compose version >/dev/null 2>&1; then
+    docker compose "$@"
+  else
+    docker-compose "$@"
+  fi
+}
+
+before_file="$TMP_ROOT/before_restart.json"
+curl -sS "$API_BASE/nodes/$NODE_ID" -o "$before_file"
+prev_last_updated=$(python3 - "$before_file" <<'PY'
+import json, sys
+with open(sys.argv[1]) as handle:
+    node = json.load(handle)
+print(node.get("last_updated", ""))
+PY
+)
+prev_ip=$(python3 - "$before_file" <<'PY'
+import json, sys
+with open(sys.argv[1]) as handle:
+    node = json.load(handle)
+print(node["meta_data"].get("ip", ""))
+PY
+)
+initial_ip=$(cat "$TMP_ROOT/initial_ip")
+if [[ "$prev_ip" != "$initial_ip" ]]; then
+  echo "[ERROR] Expected initial IP $initial_ip, got $prev_ip" >&2
+  exit 1
+fi
+
+pushd "$TEST_ROOT" >/dev/null
+compose rm -sf agent
+popd >/dev/null
+
+docker container rm -f argus-agent-e2e >/dev/null 2>&1 || true
+
+AGENT_DIR="$TEST_ROOT/private/argus/agent/$AGENT_HOSTNAME"
+HEALTH_DIR="$TEST_ROOT/private/argus/agent/$AGENT_HOSTNAME/health"
+
+# 先以 sleep 方式启动容器，确保我们掌握注册时的网络状态
+if ! docker run -d \
+  --name argus-agent-e2e \
+  --hostname "$AGENT_HOSTNAME" \
+  --network "$NETWORK_NAME" \
+  --ip "$NEW_AGENT_IP" \
+  -v "$AGENT_DIR:/private/argus/agent/$AGENT_HOSTNAME" \
+  -v "$HEALTH_DIR:/private/argus/agent/$AGENT_HOSTNAME/health" \
+  -v "$TEST_ROOT/private/argus/etc:/private/argus/etc" \
+  -v "$AGENT_BINARY:/usr/local/bin/argus-agent:ro" \
+  -v "$ENTRYPOINT_SCRIPT:/usr/local/bin/agent-entrypoint.sh:ro" \
+  -e MASTER_ENDPOINT=http://master.argus.com:3000 \
+  -e REPORT_INTERVAL_SECONDS=2 \
+  -e ARGUS_BUILD_UID="$AGENT_UID" \
+  -e ARGUS_BUILD_GID="$AGENT_GID" \
+  --entrypoint /usr/local/bin/agent-entrypoint.sh \
+  ubuntu:22.04 >/dev/null; then
+  echo "[ERROR] Failed to start agent container with custom IP" >&2
+  exit 1
+fi
+
+success=false
+detail_file="$TMP_ROOT/post_restart.json"
+for _ in {1..20}; do
+  sleep 3
+  if ! curl -sS "$API_BASE/nodes/$NODE_ID" -o "$detail_file"; then
+    continue
+  fi
+  if python3 - "$detail_file" "$prev_last_updated" "$NODE_ID" "$prev_ip" "$NEW_AGENT_IP" <<'PY'
+import json, sys
+with open(sys.argv[1]) as handle:
+    node = json.load(handle)
+prev_last_updated = sys.argv[2]
+expected_id = sys.argv[3]
+old_ip = sys.argv[4]
+expected_ip = sys.argv[5]
+last_updated = node.get("last_updated")
+current_ip = node["meta_data"].get("ip")
+assert node["id"] == expected_id
+if current_ip != expected_ip:
+    raise SystemExit(1)
+if current_ip == old_ip:
+    raise SystemExit(1)
+if not last_updated or last_updated == prev_last_updated:
+    raise SystemExit(1)
+PY
+  then
+    success=true
+    break
+  fi
+done
+
+if [[ "$success" != true ]]; then
+  echo "[ERROR] Agent did not report expected new IP $NEW_AGENT_IP after restart" >&2
+  exit 1
+fi
+
+echo "[INFO] Agent restart produced successful re-registration with IP change"

src/agent/tests/scripts/07_down.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ENV_FILE="$TEST_ROOT/.env"
+
+compose() {
+  if docker compose version >/dev/null 2>&1; then
+    docker compose "$@"
+  else
+    docker-compose "$@"
+  fi
+}
+
+docker container rm -f argus-agent-e2e >/dev/null 2>&1 || true
+
+pushd "$TEST_ROOT" >/dev/null
+compose down --remove-orphans
+popd >/dev/null
+
+if [[ -d "$TEST_ROOT/private" ]]; then
+  docker run --rm \
+    -v "$TEST_ROOT/private:/target" \
+    ubuntu:24.04 \
+    chown -R "$(id -u):$(id -g)" /target >/dev/null 2>&1 || true
+  rm -rf "$TEST_ROOT/private"
+fi
+
+rm -rf "$TEST_ROOT/tmp"
+
+if [[ -f "$ENV_FILE" ]]; then
+  rm -f "$ENV_FILE"
+fi
+
+echo "[INFO] Agent E2E environment cleaned up"

src/agent/tests/scripts/08_verify_agent.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+VERIFY_SCRIPT="$(cd "$TEST_ROOT/.." && pwd)/scripts/agent_deployment_verify.sh"
+
+if ! docker ps --format '{{.Names}}' | grep -q '^argus-agent-e2e$'; then
+  echo "[WARN] agent container not running; skip verification"
+  exit 0
+fi
+
+if docker exec -i argus-agent-e2e bash -lc 'command -v curl >/dev/null && command -v jq >/dev/null'; then
+  echo "[INFO] curl/jq already installed in agent container"
+else
+  echo "[INFO] Installing curl/jq in agent container"
+  docker exec -i argus-agent-e2e bash -lc 'apt-get update >/dev/null 2>&1 && apt-get install -y curl jq >/dev/null 2>&1' || true
+fi
+
+if docker exec -i argus-agent-e2e bash -lc 'command -v /usr/local/bin/agent_deployment_verify.sh >/dev/null'; then
+  docker exec -i argus-agent-e2e /usr/local/bin/agent_deployment_verify.sh
+elif [[ -x "$VERIFY_SCRIPT" ]]; then
+  docker exec -i argus-agent-e2e "$VERIFY_SCRIPT"
+else
+  echo "[WARN] agent_deployment_verify.sh not found"
+fi

src/agent/tests/scripts/agent_entrypoint.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LOG_PREFIX="[AGENT-ENTRYPOINT]"
+DNS_SCRIPT="/private/argus/etc/update-dns.sh"
+DNS_CONF="/private/argus/etc/dns.conf"
+TARGET_DOMAIN="master.argus.com"
+AGENT_UID="${ARGUS_BUILD_UID:-2133}"
+AGENT_GID="${ARGUS_BUILD_GID:-2015}"
+AGENT_HOSTNAME="${HOSTNAME:-unknown}"
+AGENT_DATA_DIR="/private/argus/agent/${AGENT_HOSTNAME}"
+AGENT_HEALTH_DIR="${AGENT_DATA_DIR}/health"
+RUNTIME_GROUP="argusagent"
+RUNTIME_USER="argusagent"
+
+log() {
+  echo "${LOG_PREFIX} $*"
+}
+
+mkdir -p "$AGENT_DATA_DIR" "$AGENT_HEALTH_DIR"
+chown -R "$AGENT_UID:$AGENT_GID" "$AGENT_DATA_DIR" "$AGENT_HEALTH_DIR" 2>/dev/null || true
+chown -R "$AGENT_UID:$AGENT_GID" "/private/argus/etc" 2>/dev/null || true
+
+if ! getent group "$AGENT_GID" >/dev/null 2>&1; then
+  groupadd -g "$AGENT_GID" "$RUNTIME_GROUP"
+else
+  RUNTIME_GROUP="$(getent group "$AGENT_GID" | cut -d: -f1)"
+fi
+
+if ! getent passwd "$AGENT_UID" >/dev/null 2>&1; then
+  useradd -u "$AGENT_UID" -g "$AGENT_GID" -M -s /bin/bash "$RUNTIME_USER"
+else
+  RUNTIME_USER="$(getent passwd "$AGENT_UID" | cut -d: -f1)"
+fi
+
+log "运行用户: $RUNTIME_USER ($AGENT_UID:$AGENT_GID)"
+
+# 中文提示：等待 bind 下发的 update-dns.sh 脚本
+for _ in {1..30}; do
+  if [[ -x "$DNS_SCRIPT" ]]; then
+    break
+  fi
+  log "等待 update-dns.sh 准备就绪..."
+  sleep 1
+done
+
+if [[ -x "$DNS_SCRIPT" ]]; then
+  log "执行 update-dns.sh 更新容器 DNS"
+  while true; do
+    if "$DNS_SCRIPT"; then
+      log "update-dns.sh 执行成功"
+      break
+    fi
+    log "update-dns.sh 执行失败，3 秒后重试"
+    sleep 3
+  done
+else
+  log "未获取到 update-dns.sh，使用镜像默认 DNS"
+fi
+
+# 中文提示：记录当前 dns.conf 内容，便于排查
+if [[ -f "$DNS_CONF" ]]; then
+  log "dns.conf 内容: $(tr '\n' ' ' < "$DNS_CONF")"
+else
+  log "dns.conf 暂未生成"
+fi
+
+# 中文提示：尝试解析 master 域名，失败不阻塞但会打日志
+for _ in {1..30}; do
+  if getent hosts "$TARGET_DOMAIN" >/dev/null 2>&1; then
+    MASTER_IP=$(getent hosts "$TARGET_DOMAIN" | awk '{print $1}' | head -n 1)
+    log "master.argus.com 解析成功: $MASTER_IP"
+    break
+  fi
+  sleep 1
+done
+
+log "启动 argus-agent"
+exec su -s /bin/bash -c /usr/local/bin/argus-agent "$RUNTIME_USER"