argus/deployment_new/templates/server/docs/INSTALL_SERVER_zh.md

Argus Server 安装指南（deployment_new）

适用：通过 Server 安装包在 Docker Swarm + external overlay 网络一体化部署 Argus 服务端组件。

—— 本文强调“怎么做、看什么、符合了才继续”。

一、准备条件（开始前确认）

• Docker 与 Docker Compose v2 已安装；docker info 正常；docker compose version 可执行。
• 具备 root/sudo 权限；磁盘可用空间 ≥ 10GB（包根与 /var/lib/docker）。
• 你知道本机管理地址（SWARM_MANAGER_ADDR），该 IP 属于本机某网卡，可被其他节点访问。
• 很重要：以统一账户 argus（UID=2133，GID=2015）执行后续安装与运维，并将其加入 docker 组；示例命令如下（如需不同 UID/GID，请替换为贵方标准）：

  # 1) 创建主组（GID=2015，组名 argus；若已存在可跳过）
  sudo groupadd --gid 2015 argus || true
  
  # 2) 创建用户 argus（UID=2133、主组 GID=2015，创建家目录并用 bash 作为默认 shell；若已存在可用 usermod 调整）
  sudo useradd --uid 2133 --gid 2015 --create-home --shell /bin/bash argus || true
  sudo passwd argus
  
  # 3) 将 argus 加入 docker 组，使其能调用 Docker Daemon（新登录后生效）
  sudo usermod -aG docker argus
  
  # 4) 验证（重新登录或执行 newgrp docker 使组生效）
  su - argus -c 'id; docker ps >/dev/null && echo OK || echo NO_DOCKER_PERMISSION'
  

  后续的解压与执行（config/install/selfcheck 等）均使用该 argus 账户进行。

二、解包与目录结构

• 解压：tar -xzf server_YYYYMMDD.tar.gz。
• 进入：cd server_YYYYMMDD/
• 你应当能看到：
  • images/（逐服务镜像 tar.gz，如 argus-master-YYYYMMDD.tar.gz）
  • compose/（docker-compose.yml 与 .env.example）
  • scripts/（安装/运维脚本）
  • private/argus/（数据与配置骨架）
  • docs/（中文文档）

三、配置 config（生成 .env 与 SWARM_MANAGER_ADDR）

命令：

export SWARM_MANAGER_ADDR=<本机管理IP>
./scripts/config.sh

脚本做了什么：

• 检查依赖与磁盘空间；
• 自动从“端口 20000 起”分配所有服务端口，确保“系统未占用”且“彼此不冲突”；
• 写入 compose/.env（包含端口、镜像 tag、overlay 名称与 UID/GID 等）；
• 将当前执行账户的 UID/GID 写入 ARGUS_BUILD_UID/GID（若主组名是 docker，会改用“与用户名同名的组”的 GID，避免拿到 docker 组 999）；
• 更新/追加 cluster-info.env 中的 SWARM_MANAGER_ADDR（不会覆盖其他键）。

看到什么才算成功：

• 终端输出：已生成 compose/.env 并更新 cluster-info.env 的 SWARM_MANAGER_ADDR。
• compose/.env 打开应当看到：
  • 端口均 ≥20000 且没有重复；
  • ARGUS_BUILD_UID/GID 与 id -u/-g 一致；
  • SWARM_MANAGER_ADDR=<你的IP>。

遇到问题：

• 端口被异常占用：可删去 .env 后再次执行 config.sh，或手工编辑端口再执行 install.sh。

四、安装 install（一次到位）

命令：

./scripts/install.sh

脚本做了什么：

• 若 Swarm 未激活：执行 docker swarm init --advertise-addr $SWARM_MANAGER_ADDR；
• 确保 external overlay argus-sys-net 存在；
• 导入 images/*.tar.gz 到本机 Docker；
• docker compose up -d 启动服务；
• 等待“六项就绪”：
  • Master /readyz=200、ES /_cluster/health=200、Prometheus TCP 可达、Grafana /api/health=200、Alertmanager /api/v2/status=200、Kibana /api/status level=available；
• 校验 Docker DNS + overlay alias：在 argus-web-proxy 内通过 getent hosts 与 curl 检查 master.argus.com、grafana.metric.argus.com 等域名连通性；
• 写出 cluster-info.env（含 SWARM_JOIN_TOKEN_{WORKER,MANAGER}/SWARM_MANAGER_ADDR；compose 架构下不再依赖 BINDIP/FTPIP）；
• 生成 安装报告_YYYYMMDD-HHMMSS.md（端口、健康检查摘要与提示）。

看到什么才算成功：

• docker compose ps 全部是 Up；
• 安装报告_…md 中各项 HTTP 检查为 200/available；
• cluster-info.env 包含五个关键键：
  • SWARM_MANAGER_ADDR=...
  • SWARM_MANAGER_ADDR=... SWARM_JOIN_TOKEN_*=...
  • SWARM_JOIN_TOKEN_WORKER=SWMTKN-...
  • SWARM_JOIN_TOKEN_MANAGER=SWMTKN-...

五、健康自检与常用操作

• 健康自检：./scripts/selfcheck.sh
  • 期望输出：selfcheck OK -> logs/selfcheck.json
  • 文件 logs/selfcheck.json 中 overlay_net/es/kibana/master_readyz/prometheus/grafana/alertmanager/web_proxy_cors 为 true。
• 状态：./scripts/status.sh（相当于 docker compose ps）。
• 诊断：./scripts/diagnose.sh（收集容器/HTTP/CORS/ES 细节，输出到 logs/diagnose_*.log）。
• 卸载：./scripts/uninstall.sh（Compose down）。
• ES 磁盘水位临时放宽/还原：./scripts/es-watermark-relax.sh / ./scripts/es-watermark-restore.sh。

六、下一步：分发 cluster-info.env 给 Client

• 将 cluster-info.env 拷贝给安装 Client 的同事；
• 对方在 Client 机器的包根放置该文件（或设置 CLUSTER_INFO=/绝对路径）即可。

七、故障排查快览

• Proxy 502 或 8080 连接复位：通常是 overlay alias 未生效或 web-proxy 尚未解析到其它服务；重跑 install.sh（会重启栈并在容器内校验 DNS），或查看 logs/diagnose_error.log。
• Kibana 不 available：等待 1–2 分钟、查看 argus-kibana-sys 日志；
• cluster-info.env 的 SWARM_MANAGER_ADDR 为空：重新 export SWARM_MANAGER_ADDR=<IP>; ./scripts/config.sh 或 ./scripts/install.sh（会回读 .env 补写）。