argus/src/sys/debug/README.md

ARGUS 系统调试部署模式

该目录提供基于系统级 E2E 测试构建的调试部署流程，便于本地快速复现与排查问题。核心特性：

• 独立 docker 网络 argus-debug-net（默认子网 172.30.0.0/16），避免与 src/sys/tests 冲突。
• 私有数据目录可通过参数自定义，例如 --private-root /tmp/argus-debug。
• 默认保留调试过程生成的文件，避免 down/bootstrap 自动删除。

快速开始

cd src/sys/debug

# 仅首次需要，创建 external 网络
./scripts/network-create.sh

# 初始化目录/构建 agent/写入 .env
./scripts/01_bootstrap.sh --private-root /tmp/argus-debug

# 启动调试栈
./scripts/02_up.sh

# 根据需要执行验证脚本（03～08）
./scripts/03_wait_ready.sh
...

# 调试结束停止服务
./scripts/09_down.sh

# 若需移除网络或数据
./scripts/network-destroy.sh
./scripts/clean-data.sh

提示：调试与测试栈不能同时运行，应保持 src/sys/tests 中的 argus-sys 栈已停止。

参数与环境变量

• --private-root <path>：同时指定核心服务与两个节点的私有目录根，脚本自动派生 private、private-nodea、private-nodeb。
• --private-core <path>、--private-nodea <path>、--private-nodeb <path>：分别覆盖单独目录。
• 环境变量可覆盖 .env 中写入的值，例如 export SYS_DEBUG_NETWORK_NAME=my-debug-net。
• .env 文件字段：
  • SYS_DEBUG_PRIVATE_CORE
  • SYS_DEBUG_PRIVATE_NODEA
  • SYS_DEBUG_PRIVATE_NODEB
  • SYS_DEBUG_TMP_DIR
  • SYS_DEBUG_NETWORK_NAME
  • SYS_DEBUG_NETWORK_SUBNET
  • SYS_DEBUG_NETWORK_GATEWAY
  • SYS_DEBUG_PROJECT_NAME
  • SYS_DEBUG_CONTAINER_PREFIX
  • ARGUS_BUILD_UID / ARGUS_BUILD_GID

脚本说明

• scripts/common.sh：通用函数与环境加载。
• scripts/network-create.sh / network-destroy.sh：管理 external 网络。
• scripts/00_debug_all.sh：顺序执行 01～08（默认不执行 09）。
• scripts/clean-data.sh：选择性清理宿主机私有数据。
• scripts/03_wait_ready.sh：除了等待各服务就绪，还会在 Elasticsearch 就绪后自动将磁盘水位阈值放宽（97%/98%/99%），避免在磁盘紧张的调试环境中分片分配失败。
• scripts/08_restart_agent_reregister.sh：将 node-b 切换到 SYS_DEBUG_NODEB_FIXED_IP（默认 172.30.0.200），如果目标地址与当前 IP 相同脚本会报错提醒重新选择地址。
• 其它 01～09 与测试目录对应，但针对参数化路径及网络做了调整。

注意事项

• 若宿主机未安装 Docker，脚本将提示错误并退出。
• 当指定的私有目录已存在数据时，脚本不会清理，请确认内容安全后再复用。
• 与测试环境共用镜像：请提前执行仓库根目录的 ./build/build_images.sh。