From 38f8ee9301ac5899b5c43879b767f154d23f4c95 Mon Sep 17 00:00:00 2001 From: yuyr Date: Tue, 4 Nov 2025 15:20:08 +0800 Subject: [PATCH] =?UTF-8?q?[#37]=20=E6=B5=8B=E8=AF=95=E9=80=9A=E8=BF=87swa?= =?UTF-8?q?rm=E8=B7=A8=E6=9C=BA=E9=83=A8=E7=BD=B2=E8=8A=82=E7=82=B9?= =?UTF-8?q?=EF=BC=9B=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- deployment/build/build_client_package.sh | 9 ++- .../templates/client/INSTALL_CLIENT_zh.md | 7 +++ .../templates/client/PUBLISH_CLIENT_zh.md | 57 ++++++++++++++++++ .../templates/client/QUICK_NODE_DEPLOY_zh.md | 58 +++++++++++++++++++ .../build/templates/docs/INSTALL_SERVER.md | 11 ++-- .../build/templates/docs/INSTALL_SERVER_zh.md | 12 ++-- .../build/templates/docs/SWARM_DEPLOY_zh.md | 26 ++++++++- .../build/templates/docs/TROUBLESHOOTING.md | 3 +- .../templates/docs/TROUBLESHOOTING_zh.md | 4 +- 9 files changed, 166 insertions(+), 21 deletions(-) create mode 100644 deployment/build/templates/client/PUBLISH_CLIENT_zh.md create mode 100644 deployment/build/templates/client/QUICK_NODE_DEPLOY_zh.md diff --git a/deployment/build/build_client_package.sh b/deployment/build/build_client_package.sh index 2134e12..8c67cd7 100755 --- a/deployment/build/build_client_package.sh +++ b/deployment/build/build_client_package.sh @@ -68,20 +68,23 @@ out_name="argus-metric_$(echo "$VERSION" | sed 's/\./_/g').tar.gz" log "Client package ready: $PKG_DIR/$out_name" echo "$VERSION" > "$PKG_DIR/LATEST_VERSION" -# include publish helper and setup.sh for convenience +# include publish helper and setup.sh for convenience (place first) PUBLISH_TPL="$BUILD_DIR/templates/client/publish.sh" if [[ -f "$PUBLISH_TPL" ]]; then - cp "$PUBLISH_TPL" "$PKG_DIR/publish.sh" && chmod +x "$PKG_DIR/publish.sh" + cp "$PUBLISH_TPL" "$PKG_DIR/publish.sh" fi # also place a copy of setup.sh alongside SETUP_SRC="$ROOT_DIR/src/metric/client-plugins/all-in-one-full/scripts/setup.sh" [[ -f "$SETUP_SRC" ]] && cp "$SETUP_SRC" "$PKG_DIR/setup.sh" || true -# docs for end users +# docs for end users (this may overwrite file modes), then fix execute bits CLIENT_DOC_DIR="$BUILD_DIR/templates/client" if [[ -d "$CLIENT_DOC_DIR" ]]; then rsync -a "$CLIENT_DOC_DIR/" "$PKG_DIR/" >/dev/null 2>&1 || cp -r "$CLIENT_DOC_DIR/." "$PKG_DIR/" fi +# ensure helpers are executable +chmod +x "$PKG_DIR/publish.sh" "$PKG_DIR/setup.sh" 2>/dev/null || true + exit 0 diff --git a/deployment/build/templates/client/INSTALL_CLIENT_zh.md b/deployment/build/templates/client/INSTALL_CLIENT_zh.md index 4d0933b..cb01060 100644 --- a/deployment/build/templates/client/INSTALL_CLIENT_zh.md +++ b/deployment/build/templates/client/INSTALL_CLIENT_zh.md @@ -25,6 +25,13 @@ - `sudo /tmp/setup.sh --server --user ftpuser --password 'ZGClab1234!' --port 21` - 如需自定义安装根目录：`--install-dir /opt/argus-metric` +提示（容器接入 overlay 网络时）： +- 在执行 setup 前，先将容器内 DNS 指向 Bind9 的 overlay IP： + - `echo "nameserver " > /etc/resolv.conf` + - 这样 `master.argus.com`、`es.log.argus.com` 等域名即可解析；首次下载 `setup.sh` 仍建议使用 FTP 的 overlay IP。 + +更多快速步骤请参考：`QUICK_NODE_DEPLOY_zh.md`。 + ## 安装后自检（setup 自动执行） - setup 会等待最多 5 分钟，确认以下条件后才报告完成： - `/private/argus/agent//node.json` 已生成； diff --git a/deployment/build/templates/client/PUBLISH_CLIENT_zh.md b/deployment/build/templates/client/PUBLISH_CLIENT_zh.md new file mode 100644 index 0000000..94ca70a --- /dev/null +++ b/deployment/build/templates/client/PUBLISH_CLIENT_zh.md @@ -0,0 +1,57 @@ +# Argus Metric 客户端发布说明（FTP） + +本说明面向“发布人员”，讲清楚如何把客户端离线包发布到 FTP，供各节点通过 `curl` 自动安装。 + +## 目录结构（构建后） +- `client-YYYYMMDD/` + - `argus-metric_YYYYMMDD.tar.gz` 客户端离线包 + - `setup.sh` 客户端安装入口脚本（提供给节点用 curl 下载） + - `publish.sh` 发布脚本（将上述两项与 `LATEST_VERSION` 上传到 FTP） + - `LATEST_VERSION` 文本（内容为 `YYYYMMDD`，或 `YYYYMMDD-rN`） + - `INSTALL_CLIENT_zh.md` 本地安装指南（给使用者看，不会上载到 FTP） + - `PUBLISH_CLIENT_zh.md` 本说明 + +> 注意：`publish.sh`/`setup.sh` 为可执行脚本；构建脚本已保证二者具有执行权限。 + +## 前置条件 +- FTP 服务已运行（默认容器：`argus-ftp`），并打开端口：21、20、21100–21110（被动模式）。 +- FTP 账号：默认 `ftpuser / ZGClab1234!`（如有更改，以实际为准）。 + +## 发布步骤（在 server 机器或能直连 FTP 的任意机器上） +1) 进入发布目录： +- `cd client-YYYYMMDD` + +2) 执行发布： +- `./publish.sh --server --user --password '' [--port 21]` +- 例如在服务端本机：`./publish.sh --server localhost --user ftpuser --password 'ZGClab1234!' --port 21` + +脚本会上传三类文件到 FTP 根： +- `setup.sh` +- `argus-metric_YYYYMMDD[ -rN ].tar.gz` +- `LATEST_VERSION`（内容为当前版本号） + +3) 发布后验证： +- `curl -u ftpuser:****** -I ftp://:21/LATEST_VERSION` 应返回 200 +- `curl -u ftpuser:****** -fsSL ftp://:21/LATEST_VERSION` 内容为版本号（如 `20251104`） +- `curl -u ftpuser:****** -I ftp://:21/argus-metric_YYYYMMDD.tar.gz` 返回 200 + +## 节点侧使用方式（摘要） +- 首次下载用 FTP 的“IP 地址”： + - `curl -u ftpuser:****** -fsSL ftp://:21/setup.sh -o /tmp/setup.sh && chmod +x /tmp/setup.sh` +- 执行安装： + - 必需元数据：`AGENT_ENV/AGENT_USER/AGENT_INSTANCE`，以及 `MASTER_ENDPOINT=http://master.argus.com:3000` + - `sudo /tmp/setup.sh --server --user ftpuser --password '******' --port 21` +- overlay 容器场景： + - 先将容器内 DNS 指向 Bind9 的 overlay IP：`echo "nameserver " > /etc/resolv.conf` + - 然后再执行上述安装；安装后约 1–2 分钟内 DNS 即可解析 `*.argus.com` 域名。 + +## 常见问题 +- `530 Access denied`：用户名/密码错误或 FTP 目录无权限；请核对账号与 FTP 容器状态。 +- `Permission denied` 执行 `publish.sh`：为脚本权限问题；`chmod +x publish.sh`。构建脚本已修复默认权限。 +- 被动端口不通导致失败：请开放 21100–21110。 +- 客户端安装后短时 `curl http://master.argus.com:3000` 为 000：服务冷启动或 DNS 同步延迟，等待 1–2 分钟再试。 + +## 版本与回滚 +- `LATEST_VERSION` 决定客户端默认安装的版本号。 +- 如需回滚：将旧版本号写回 `LATEST_VERSION` 并重新发布（或手动指定 `--version` 安装）。 + diff --git a/deployment/build/templates/client/QUICK_NODE_DEPLOY_zh.md b/deployment/build/templates/client/QUICK_NODE_DEPLOY_zh.md new file mode 100644 index 0000000..45f47fe --- /dev/null +++ b/deployment/build/templates/client/QUICK_NODE_DEPLOY_zh.md @@ -0,0 +1,58 @@ +# Argus Metric 节点快速部署（Overlay 网络容器） + +本文档给出在 Docker Swarm external overlay 网络中，快速拉起一个测试节点并完成注册的最小可行步骤。 + +## 前提 +- 服务端已在 Manager 机安装完成并运行良好（`server-selfcheck` 通过）。 +- Overlay 网络名称：`argus-sys-net`（默认）。 +- 已通过 FTP 发布 `setup.sh` 与客户端包，且能从 FTP 获取 `LATEST_VERSION`。 +- 用于测试的镜像：`argus-sys-metric-test-node:latest` 已存在于目标机器。 + +## 步骤 + +- 获取 FTP 和 Bind 的 overlay IP（在 Manager 上执行） + - `FTPIP=$(docker inspect -f '{{ (index .NetworkSettings.Networks "argus-sys-net").IPAddress }}' argus-ftp)` + - `BINDIP=$(docker inspect -f '{{ (index .NetworkSettings.Networks "argus-sys-net").IPAddress }}' argus-bind-sys)` + - `echo "FTP=$FTPIP BIND=$BINDIP"` + +- 准备宿主挂载目录（以 s4 为例） + - `mkdir -p /home2/yuyr/deploy/test-metric-node/s4` + +- 启动测试节点容器（接入 overlay） + - `docker run -d --name argus-metric-test-node-s4 \ + --hostname dev2-yuyr-node002s4 \ + --network argus-sys-net \ + -v /home2/yuyr/deploy/test-metric-node/s4:/private/argus/agent \ + argus-sys-metric-test-node:latest sleep infinity` + +- 在容器内执行安装（先用 FTP IP 引导，DNS 指向 Bind） + - `docker exec -it argus-metric-test-node-s4 bash` + - `echo "nameserver $BINDIP" > /etc/resolv.conf` + - `curl --ftp-method nocwd -u ftpuser:ZGClab1234! -fsSL "ftp://$FTPIP:21/setup.sh" -o /tmp/setup.sh` + - `chmod +x /tmp/setup.sh` + - `export AGENT_ENV=dev2 AGENT_USER=yuyr AGENT_INSTANCE=node002s4` + - `export MASTER_ENDPOINT=http://master.argus.com:3000` + - `/tmp/setup.sh --server "$FTPIP" --user ftpuser --password 'ZGClab1234!' --port 21` + - 说明：setup 会自动执行安装后自检（最多 5 分钟），无需手动轮询。 + +## 验证（推荐在容器内执行，避免宿主权限问题） + +- 查看 node.json 关键字段 + - `cat /private/argus/agent/dev2-yuyr-node002s4/node.json | jq '{last_report, health}'` + - 期望：四个 health 全部 healthy；等待 ≥70s 再查看，`last_report` 持续更新。 + +- 指标端口 + - `curl -s -o /dev/null -w '%{http_code}\n' http://localhost:9100/metrics`（期望 200） + - （如测试 GPU）`curl -s -o /dev/null -w '%{http_code}\n' http://localhost:9400/metrics`（有 GPU 时 200） + +- 与服务端连通（域名经 Bind 解析） + - `curl -s -o /dev/null -w '%{http_code}\n' http://master.argus.com:3000/readyz`（期望 200） + - `curl -s -o /dev/null -w '%{http_code}\n' http://es.log.argus.com:9200/_cluster/health`（期望 200） + +## （可选）在服务器主机侧观察 Prometheus 目标更新 +- `cat /home2/yuyr/deploy/versions//private/argus/metric/prometheus/nodes.json | jq '.'` + +## 常见提示 +- 初次安装后短时 `curl` 域名返回 000/超时属正常，多等待 1–2 分钟 DNS 同步/组件冷启动完成。 +- 如在宿主直接读取挂载的 node.json 报 Permission denied，请使用 `docker exec` 在容器内查看。 +- MASTER_ENDPOINT 固定使用域名 `http://master.argus.com:3000`，客户端无需固定 IP。 diff --git a/deployment/build/templates/docs/INSTALL_SERVER.md b/deployment/build/templates/docs/INSTALL_SERVER.md index 652fe04..b511a14 100644 --- a/deployment/build/templates/docs/INSTALL_SERVER.md +++ b/deployment/build/templates/docs/INSTALL_SERVER.md @@ -7,11 +7,10 @@ ## Quick Start 1. Extract to a target dir, e.g. `/opt/argus-deploy/versions/` -2. `cd scripts && sudo ./server-prepare-dirs.sh` (recommended) -3. `./server-install.sh` (non‑root is supported: it will precreate minimal dirs and auto-fix Kibana/ES/Bind in containers) -4. `./server-status.sh` -5. `./server-selfcheck.sh` (on failure it auto-runs diagnose and writes logs under `logs/`) -6. `./server-uninstall.sh` to tear down +2. `./server-install.sh` (non‑root is supported: it will precreate minimal dirs and auto-fix Kibana/ES/Bind in containers) +3. `./server-status.sh` +4. `./server-selfcheck.sh` (on failure it auto-runs diagnose and writes logs under `logs/`) +5. `./server-uninstall.sh` to tear down ## What the Installer Does - Loads local images (`images/all-images.tar.gz`) @@ -29,7 +28,7 @@ - If you cannot use sudo, the installer will: - create minimal data dirs (incl. `private/argus/log/{elasticsearch,kibana}`) with permissive perms when possible; - ensure inside containers: Kibana `data` → `/private/argus/log/kibana`, Elasticsearch `data` → `/private/argus/log/elasticsearch`, and Bind `rndc.key` is generated. - You can still run `sudo ./server-prepare-dirs.sh` later to normalize ownership. + (Manual pre-creation scripts are no longer required.) ## Files & Layout - `compose/` (docker-compose.yml, .env) diff --git a/deployment/build/templates/docs/INSTALL_SERVER_zh.md b/deployment/build/templates/docs/INSTALL_SERVER_zh.md index 673193a..eb1fd7a 100644 --- a/deployment/build/templates/docs/INSTALL_SERVER_zh.md +++ b/deployment/build/templates/docs/INSTALL_SERVER_zh.md @@ -7,11 +7,10 @@ ## 快速开始 1. 解压到目标目录（例如 `/opt/argus-deploy/versions/`） -2. 进入 `scripts/`：`sudo ./server-prepare-dirs.sh`（推荐） -3. 安装：`./server-install.sh`（支持普通用户：会自动创建最小目录并在容器内修复 Kibana/ES/Bind） -4. 状态：`./server-status.sh` -5. 自检：`./server-selfcheck.sh`（失败会自动采集诊断） -6. 卸载：`./server-uninstall.sh` +2. 安装：`./server-install.sh`（支持普通用户：会自动创建最小目录并在容器内修复 Kibana/ES/Bind） +3. 状态：`./server-status.sh` +4. 自检：`./server-selfcheck.sh`（失败会自动采集诊断） +5. 卸载：`./server-uninstall.sh` ## 安装流程要点 - 仅启动 10 个服务端组件（不包含测试节点）； @@ -20,11 +19,10 @@ ## 兼容说明（NixOS 等） - 使用 `security_opt: ["label=disable"]` 与 `userns_mode: host`。 -- 若不能使用 sudo：安装器会创建最小目录（含 `private/argus/log/{elasticsearch,kibana}`），并在容器内完成： +- 非 root 场景：安装器会创建最小目录（含 `private/argus/log/{elasticsearch,kibana}`），并在容器内完成： - Kibana 的 `data` 软链到 `/private/argus/log/kibana` - Elasticsearch 的 `data` 软链到 `/private/argus/log/elasticsearch` - Bind 生成 `/etc/bind/rndc.key` - 安装后也可再执行 `sudo ./server-prepare-dirs.sh` 统一目录属主。 ## 故障排查（见下文 Troubleshooting_zh） - `./server-selfcheck.sh` → `logs/selfcheck.json` diff --git a/deployment/build/templates/docs/SWARM_DEPLOY_zh.md b/deployment/build/templates/docs/SWARM_DEPLOY_zh.md index bad4ab6..9f5b680 100644 --- a/deployment/build/templates/docs/SWARM_DEPLOY_zh.md +++ b/deployment/build/templates/docs/SWARM_DEPLOY_zh.md @@ -7,7 +7,6 @@ - 初始化 Swarm：`docker swarm init --advertise-addr ` - 创建 overlay：`docker network create --driver overlay --attachable argus-sys-net` - 解压离线包后执行： - - `cd scripts && sudo ./server-prepare-dirs.sh` - `./server-install.sh`（会验证 Swarm 状态、确保 overlay 存在、写入 dns.conf） - `./server-selfcheck.sh`（失败会自动触发诊断） @@ -24,3 +23,28 @@ - MASTER_ENDPOINT 永远使用域名：`http://master.argus.com:3000` - docker compose 改为 external overlay；容器内不使用 Docker 服务名；web-proxy 与组件上游统一用域名 +## 找回/轮换 Swarm 加入令牌与解锁密钥 + +在任意一个 Manager 节点上执行以下命令即可查看或轮换加入令牌（join token）： + +- 查看加入 Worker 的命令： + - `docker swarm join-token worker` +- 只打印 Worker 的 token： + - `docker swarm join-token -q worker` +- 查看加入 Manager 的命令： + - `docker swarm join-token manager` +- 只打印 Manager 的 token： + - `docker swarm join-token -q manager` + +在待加入节点执行（示例，替换 Manager_IP）： +- `docker swarm join --token <上面查到的token> :2377` + +轮换 token（怀疑泄露或需要更新时）： +- 轮换 Worker：`docker swarm join-token --rotate worker` +- 轮换 Manager：`docker swarm join-token --rotate manager` + +如果你指的是“解锁密钥”（autolock 的 unlock key），在 Manager 上： +- 查看：`docker swarm unlock-key` +- 轮换：`docker swarm unlock-key --rotate` + +提示：当看到 “This node is not a swarm manager.” 时，说明当前节点不是 Manager，需要到 Manager 节点执行，或在现有 Manager 上 `docker node promote ` 将其提升为 Manager。 diff --git a/deployment/build/templates/docs/TROUBLESHOOTING.md b/deployment/build/templates/docs/TROUBLESHOOTING.md index 49b5375..87f30e8 100644 --- a/deployment/build/templates/docs/TROUBLESHOOTING.md +++ b/deployment/build/templates/docs/TROUBLESHOOTING.md @@ -17,5 +17,4 @@ Kibana/ES: - Verify `es.log.argus.com` resolves inside Kibana Permissions: -- Ensure `sudo ./server-prepare-dirs.sh` ran and ownership matches runtime UID:GID - +- The installer auto-creates minimal dirs and applies container-side fixes (Kibana/ES/Bind). If you still see EACCES/lock errors, rerun `./server-install.sh` and review diagnose logs. diff --git a/deployment/build/templates/docs/TROUBLESHOOTING_zh.md b/deployment/build/templates/docs/TROUBLESHOOTING_zh.md index f03d158..2d19607 100644 --- a/deployment/build/templates/docs/TROUBLESHOOTING_zh.md +++ b/deployment/build/templates/docs/TROUBLESHOOTING_zh.md @@ -12,5 +12,5 @@ Web‑Proxy：8083=200/302/403；8084/8085 需包含 CORS Kibana：确认可解析 `es.log.argus.com` 权限： -- 非 root 安装时，安装器已创建最小目录并在容器内修复 Kibana/ES/Bind； -- 如仍有 `EACCES`/锁文件报错，可再运行 `sudo ./server-prepare-dirs.sh` 统一目录属主。 +- 非 root 安装时，安装器会创建最小目录并在容器内修复 Kibana/ES/Bind； +- 如仍有 `EACCES`/锁文件报错，先重跑 `./server-install.sh`（会重复容器内修复），并查看诊断日志。