# 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，请替换为贵方标准）：
  ```bash
  # 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` 补写）。