# Argus 容器部署手册（客户环境）

本文面向在客户 Ubuntu 服务器上以 Docker 方式部署 Argus 的实施人员。
交付包只包含**运行镜像与配置模板，不含任何源码**。

---

## 1. 交付物清单

| 文件 | 说明 |
|---|---|
| `argus-<版本>-image.tar.gz` | 运行镜像（编译产物 + 生产依赖，无源码/sourcemap/私钥） |
| `install.sh` | 一键安装/升级脚本（版本号已内置） |
| `docker-compose.yml` | 服务编排（api + collector 共用一个镜像） |
| `env.example` | 环境变量模板（复制为 `.env` 后填写） |
| `deploy-docker.md` | 本手册 |
| `SHA256SUMS` | 全部交付文件的 SHA256 校验和 |

收到交付包后先校验完整性：

```bash
sha256sum -c SHA256SUMS
```

## 2. 前置条件

- Ubuntu 20.04 / 22.04 / 24.04（x86_64）
- 内存 ≥ 2G，磁盘剩余 ≥ 5G
- 服务器可访问被纳管设备所在局域网（采集器探测 SNMP/ICMP/SSH）

安装 Docker（已有可跳过）：

```bash
curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
```

> 若客户环境无法访问公网，请提前在厂商侧下载 docker 离线安装包。

## 3. 一键安装（推荐）

服务器能访问发布站时，**一条命令完成全部部署**：

```bash
curl -fsSL http://112.126.72.86:18001/releases/1.1.5/install.sh | sudo bash
```

脚本自动完成：环境检查 → 下载并校验交付包 → 载入镜像 → 生成 `.env`（含随机
`JWT_SECRET` / `CREDENTIAL_ENC_KEY`）→ 数据库迁移 → 创建管理员 → 启动 → 健康检查。

结束时终端会打印控制台地址、管理员账号和**随机生成的口令**（同时保存在
`/opt/argus/.admin-password`，权限 600）。首次登录后请修改口令并删除该文件。

### 3.1 带参数安装

管道模式下参数要跟在 `bash -s --` 后面：

```bash
# 自己指定管理员口令（不给则随机生成）
curl -fsSL http://112.126.72.86:18001/releases/1.1.5/install.sh | sudo bash -s -- \
     --admin-password 'YourStrongPass'

# 换端口
curl -fsSL http://112.126.72.86:18001/releases/1.1.5/install.sh | sudo bash -s -- --port 18080

# 服务器没装 Docker，让脚本一并安装
curl -fsSL http://112.126.72.86:18001/releases/1.1.5/install.sh | sudo bash -s -- --install-docker
```

| 参数 | 说明 | 默认 |
|---|---|---|
| `--version <x.y.z>` | 指定版本（脚本已内置，一般不用给） | 脚本内置 |
| `--port <端口>` | 控制台端口 | 18080 |
| `--install-dir <目录>` | 程序目录 | `/opt/argus` |
| `--data-dir <目录>` | 数据目录（SQLite 所在） | `/var/lib/argus` |
| `--admin-password <口令>` | 初始管理员口令 | 随机生成 |
| `--mirror <url>` | 发布站基地址 | `http://112.126.72.86:18001/releases` |
| `--install-docker` | 未装 Docker 时自动安装 | 关闭 |
| `--local` | 用脚本同目录的文件（离线包） | 关闭 |
| `--no-start` | 只初始化，不启动服务 | 关闭 |
| `--force` | 覆盖已有安装 / 重新载入镜像 | 关闭 |

### 3.2 离线安装（客户内网不能出网）

把交付包 6 个文件放到同一目录，然后：

```bash
cd /opt/argus-pkg
sudo bash install.sh --local
```

### 3.3 升级

```bash
curl -fsSL http://112.126.72.86:18001/releases/<新版本>/install.sh | sudo bash
```

脚本识别到已有安装后：备份 `.env` → 切换镜像版本 → 执行数据库迁移 → 重启服务，
**保留原配置、密钥、账号与数据**，不会重置管理员口令。

### 3.4 重装 / 覆盖

```bash
curl -fsSL http://112.126.72.86:18001/releases/<版本>/install.sh | sudo bash -s -- --force
```

> 脚本是幂等的：中途失败可直接重跑，会复用已生成的 `.env`（不重新生成密钥，避免已加密
> 数据无法解密）并继续完成初始化。

---

## 4. 手动部署步骤（一键脚本不适用时）

### 4.1 目录与镜像

```bash
mkdir -p /opt/argus && cd /opt/argus
# 将交付文件放到此目录
docker load -i argus-<版本>-image.tar.gz
# 输出 Loaded image: argus:<版本>
```

### 4.2 配置环境变量

```bash
cp env.example .env
chmod 600 .env
vi .env
```

**必填项**（其余项用默认值即可）：

```bash
# 数据目录（SQLite 数据库所在位置，须与 compose 卷一致）
DB_FILE=/var/lib/argus/argus.db

# 安全凭据，两个都必须替换：
#   JWT_SECRET      ≥32 字符随机串
#   CREDENTIAL_ENC_KEY  32 字节 base64（主机凭据加密密钥，一旦设定不可更换，否则历史凭据无法解密）
# 生成方式：
#   node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"
#   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
JWT_SECRET=<替换>
CREDENTIAL_ENC_KEY=<替换>

# 控制台访问地址（通知邮件里的跳转链接）
CONSOLE_BASE_URL=http://<服务器IP>:18080
```

### 4.3 初始化数据库

```bash
mkdir -p /var/lib/argus
# 迁移（建表/升级 schema）
docker compose run --rm api node apps/api/dist/cli/migrate.js
# 初始化管理员账号（通过 SEED_ADMIN_PASSWORD 注入初始密码，务必使用强口令；只在首次部署执行）
docker compose run --rm -e SEED_ADMIN_PASSWORD='<初始管理员密码>' api node apps/api/dist/cli/seed.js
# 修正数据目录属主（容器内以非 root 用户 argus 运行）
docker compose run --rm -u root api chown -R argus:argus /var/lib/argus
```

### 4.4 启动

```bash
docker compose up -d
docker compose ps          # api 与 collector 均应为 running/healthy
curl -s http://127.0.0.1:18080/health    # 应返回 ok
```

浏览器访问 `http://<服务器IP>:18080`，用 seed 时设置的管理员账号登录。

### 4.5 镜像版本

`docker-compose.yml` 默认使用 `argus:${ARGUS_IMAGE_TAG:-latest}`。镜像 tag 若带版本号（如 `argus:0.1.0`），在 `.env` 中加一行：

```bash
ARGUS_IMAGE_TAG=0.1.0
```

## 5. 日常运维

### 5.1 查看日志

```bash
docker compose logs -f --tail 200 api
docker compose logs -f --tail 200 collector
```

### 5.2 数据备份

数据库是 SQLite 单文件（`/var/lib/argus/argus.db`）。系统内置每日自动备份（「系统设置 → 数据备份」）；手动备份：

```bash
# 直接冷备（建议停写窗口内执行，或接受 WAL 场景下的一致性快照）：
cp /var/lib/argus/argus.db /backup/argus-$(date +%F).db
```

> 系统内置每日自动备份（「系统设置 → 数据备份」），优先使用内置机制。

### 5.3 升级

```bash
cd /opt/argus
docker load -i argus-<新版本>-image.tar.gz
# 修改 .env 中 ARGUS_IMAGE_TAG=<新版本>
docker compose run --rm api node apps/api/dist/cli/migrate.js   # 数据库升级（自动跳过已完成版本）
docker compose up -d
```

升级前建议先备份：`cp /var/lib/argus/argus.db /var/lib/argus/argus.pre-upgrade-$(date +%s).db`

### 5.4 回滚

```bash
# 修改 .env 中 ARGUS_IMAGE_TAG=<旧版本>
docker compose up -d
# 数据库回滚需厂商指导（migrate down 会清数据，禁止自行执行）
```

## 6. 安全说明

- 容器以非 root 用户（argus）运行；数据卷 `/var/lib/argus` 是容器内唯一可写位置
- `.env` 含安全凭据，权限必须为 600，且属于客户机敏感文件，不得外传
- 镜像中不含源码与调试符号；license 验签私钥由厂商保管，镜像内只有公钥
- 建议 18080 端口仅对管理网段开放（防火墙/安全组控制），不要暴露到公网

## 7. 常见问题

| 现象 | 处理 |
|---|---|
| `docker compose ps` 显示 unhealthy | `docker compose logs api` 看报错；常见为 `.env` 缺 JWT_SECRET 或 DB_FILE 目录不可写 |
| 采集器探测不到设备 | collector 使用 host 网络，确认服务器能 ping 通目标设备；防火墙放行出站 SNMP(161/udp)、ICMP |
| 登录页打不开 | 检查 `PORT` 与 compose 端口映射是否一致；检查防火墙 |
| 数据库磁盘满 | 清理 `/var/lib/argus` 下旧备份；调整 `.env` 中各保留天数 |