芯化和云监控平台 — 安装手册

版本： 1.0.0
适用对象： 目标监控服务器（安装主平台）
更新日期： 2026-07-27

1. 安装前准备

1.1 服务器角色说明

角色	作用
下载站 / 构建机	提供安装包下载（示例：`https://downloads.monitor.chem-cloud.cn/`）
本手册目标机	下载安装包并运行监控平台
业务机	另装采集 Agent（Alloy），不在本手册范围内

不要在已占用 80 / 9090 / 3100 且跑着其它监控组件的机器上强行安装，以免端口冲突。

1.2 硬件要求

项目	最低（试用）	建议（生产）
CPU	2 核	4 核及以上
内存	4 GB	8 GB 及以上（16 GB 更稳）
磁盘	40 GB 可用	100 GB 及以上可用
架构	x86_64（amd64）	同左

说明：安装包约 500 MB；运行后 MySQL、Prometheus、Loki 数据会持续增长，磁盘请预留余量。

1.3 软件要求

软件	要求
操作系统	Linux（Ubuntu 20.04+ / CentOS 7+ / 同类发行版）
Docker Engine	已安装并开机自启（建议 24 及以上）
Docker Compose	支持 `docker compose` 命令（Compose 插件）

目标机不需要单独安装 Python、Node.js、Nginx、MySQL、Prometheus。

安装前自检：

docker --version
docker compose version
systemctl is-active docker

三条命令均正常即可继续。

1.4 网络与端口

端口	用途	是否必开
80（或自定义 `HTTP_PORT`）	管理平台 Web（HTTP）	必开（访问管理台）
443（或自定义 `HTTPS_PORT`）	管理平台 Web（HTTPS）	仅启用 HTTPS 时必开
9090	Alloy 推送指标；日报 Agent 读 Prometheus	有业务机采集或日报 Agent 时必开
3100	Alloy 推送日志；日报 Agent 读 Loki	有业务机采集或日报 Agent 时必开
3306（或自定义 `MYSQL_PORT`）	日报 Agent 读监控平台库	仅使用运维日报 Agent 时必开

目标机需能访问安装包下载地址（示例：https://downloads.monitor.chem-cloud.cn/）。
安装完成后，业务机需能访问本机的 9090、3100（建议安全组按业务机 IP 白名单放行）。
若使用运维日报 Agent，运行 Agent 的机器还需能访问本机的 9090、3100、3306 及管理台 HTTP/HTTPS。

1.5 获取安装包

下载页：https://downloads.monitor.chem-cloud.cn/

文件	用途
`monitor-product-1.0.0.tar.gz`	完整安装包（含镜像），主平台安装用这个
`monitor-images-1.0.0.tar`	仅镜像，单独导入时用
`alloy-linux-amd64.zip`	业务机采集 Agent（Grafana Alloy）
`install_alloy.sh`	业务机 Alloy 一键安装 / 重配置脚本
`ops-report-agent.zip`	运维日报 Agent（WorkBuddy skills 包）
`install-manual.html`	安装手册（独立页面）

2. 安装步骤

以下命令在目标机以有 Docker 权限的用户执行（通常为 root）。

2.1 下载并解压

curl -fLO https://downloads.monitor.chem-cloud.cn/monitor-product-1.0.0.tar.gz
tar xzf monitor-product-1.0.0.tar.gz
cd monitor-product-1.0.0

2.2 配置环境变量

cp .env.example .env
vi .env    # 或使用 nano / vim

至少修改：

变量	含义	示例
`PUBLIC_HOST`	本机 IP（浏览器用 IP 访问时填写；Prometheus/Loki 说明地址也用它）	`192.168.1.50`
`HTTP_PORT`	Web HTTP 端口，默认 80	`80`（若被占用可改为 `8080`）

MYSQL_ROOT_PASSWORD、MYSQL_PASSWORD、JWT_SECRET 可留空，由 install.sh 自动生成。

HTTPS / 域名不是必选项。 不配则继续用 http://IP 访问；需要时见下文「2.5 配置 HTTPS 与域名访问」。

2.3 执行安装

chmod +x install.sh
./install.sh

脚本将依次：检查 Docker → 生成密钥 → 导入镜像 → 启动全部容器。首次导入镜像可能需要数分钟，请耐心等待。

2.4 验证

查看容器：

docker compose ps

各服务状态应为 running（或 healthy）。

浏览器访问：

未启用 HTTPS：http://<PUBLIC_HOST>（若改了端口则为 http://<PUBLIC_HOST>:<HTTP_PORT>）
已启用 HTTPS：https://<DOMAIN>（见 2.5）
默认账号：admin
默认密码：Admin@123（登录后请立即修改）

可选检查：

curl -s http://127.0.0.1:9090/-/ready
curl -s http://127.0.0.1:3100/ready

2.5 配置 HTTPS 与域名访问（可选）

适用于希望用自己的域名、并通过 HTTPS 打开管理台的场景。
不配置时跳过本节即可，继续用 IP + HTTP 访问，不影响平台使用。

步骤概览

在贵司域名控制台，将域名（如 demo.com 或 monitor.demo.com）的 A 记录 解析到本机公网/内网 IP（即 PUBLIC_HOST 对应的地址）。
自行准备 SSL 证书与私钥（免费或收费均可，本产品不代为申请）。
将证书文件放到安装目录下的 certs/（安装包已预置该目录）。
编辑 .env 启用 HTTPS 并填写域名。
重新执行 ./install.sh。
浏览器使用 https://你的域名 访问。

放置证书

假设安装目录为 monitor-product-1.0.0/：

monitor-product-1.0.0/
├── .env
├── certs/
│   ├── fullchain.pem    ← 证书（完整链）
│   └── privkey.pem      ← 私钥
├── install.sh
└── ...

若证书文件名不同，拷入 certs/ 后，在 .env 里把 SSL_CERT_FILE / SSL_KEY_FILE 改成实际文件名即可（只写文件名，不要写绝对路径）。

修改 `.env`

vi .env

示例：

PUBLIC_HOST=192.168.1.50
HTTP_PORT=80

HTTPS_ENABLED=true
DOMAIN=demo.com
HTTPS_PORT=443
SSL_CERT_FILE=fullchain.pem
SSL_KEY_FILE=privkey.pem
HTTPS_REDIRECT=true

变量	含义
`HTTPS_ENABLED`	设为 `true` 启用 HTTPS；`false` 或不配则仍用 HTTP
`DOMAIN`	对外访问域名（须已解析到本机）
`HTTPS_PORT`	HTTPS 端口，默认 `443`
`SSL_CERT_FILE`	`certs/` 下的证书文件名
`SSL_KEY_FILE`	`certs/` 下的私钥文件名
`HTTPS_REDIRECT`	`true` 时访问 80 端口会自动跳到 HTTPS（推荐）

应用配置

./install.sh

脚本会检查：域名是否填写、certs/ 下证书/私钥是否存在；通过后生成 Nginx 配置并映射 443 端口。

访问方式

管理台：https://demo.com（以你的 DOMAIN 为准）
若 HTTPS_PORT 不是 443：https://demo.com:端口
默认仍可用 IP 访问 HTTP；若开启了 HTTPS_REDIRECT=true，访问 80 会被跳转到 HTTPS 域名

注意

域名解析未生效前，浏览器可能打不开或证书校验失败，请先用 ping / nslookup 确认已解析到本机。
安全组 / 防火墙需放行 443（或你自定义的 HTTPS_PORT）。
证书到期后，替换 certs/ 中的文件，再执行一次 ./install.sh（或 docker compose ... up -d --force-recreate web）。
Prometheus（9090）、Loki（3100）仍按 HTTP + IP 使用，不必跟管理台域名绑定。

3. 安装后说明

3.1 已启动的主要服务

服务	说明
web	前端页面 + Nginx（反代 `/api`）
api	后台接口
engine	规则引擎
mysql	业务数据库
prometheus	指标存储（9090）
loki	日志存储（3100）
blackbox	拨测探针

3.2 常用运维命令

在产品目录 monitor-product-1.0.0/ 下执行：

docker compose ps          # 查看状态
docker compose logs -f api # 查看 API 日志
docker compose restart     # 重启全部
docker compose down        # 停止（默认保留数据卷）

3.3 业务机 Alloy 安装（采集 Agent）

管理平台装在监控服务器上；被监控的业务机需单独安装 Alloy，用于推送主机指标与系统日志。

下载站：https://downloads.monitor.chem-cloud.cn/

文件	用途
`install_alloy.sh`	业务机一键安装 / 重配置脚本
`alloy-linux-amd64.zip`	Alloy 二进制（脚本会自动下载）

一键安装

在业务机上以 root 执行（需能访问下载站，并能访问监控服务器的 9090、3100）。

方式 A：管道执行（不把脚本保存到本机）

curl -fsSL https://downloads.monitor.chem-cloud.cn/install_alloy.sh | sudo bash

说明：该命令不会在业务机上留下 install_alloy.sh 文件，只是下载后立刻执行。安装完成后本机仅保留 Alloy 程序与配置（见下方默认路径）。

方式 B：先下载脚本再执行（方便以后重配置）

curl -fLO https://downloads.monitor.chem-cloud.cn/install_alloy.sh
chmod +x install_alloy.sh
sudo ./install_alloy.sh install

脚本会交互询问：

监控服务器地址（IP 或域名，不要带端口）
自动检测 9090 / 3100 连通性（不通则中止，请先在监控服务器放行这两个端口）
本机标识 IP（会过滤 Docker 网桥；尽量探测公网 IP；不对时可选手动输入）

然后自动：按系统选择配置模板（Ubuntu 系 / CentOS 系）→ 检查本机日志文件是否存在（仅采集存在的路径） → 下载并安装 Alloy → 写入 /etc/alloy/config.alloy → 注册并启动 alloy 服务。

默认只采集三类日志（不采集应用日志）： 系统、授权、防火墙。

系统	检查路径
Ubuntu / Debian	`/var/log/syslog`（系统）、`/var/log/auth.log`（授权）、`/var/log/ufw.log`（防火墙）
CentOS / RHEL 系	`/var/log/messages`（系统）、`/var/log/secure`（授权）、`/var/log/firewalld`（防火墙）

不存在的文件会跳过；若全部不存在，仍会安装并只上报主机指标。

默认路径：

路径	说明
`/usr/bin/alloy`	可执行文件
`/etc/alloy/config.alloy`	配置文件
`/var/lib/alloy/`	数据目录

重新配置

更换监控服务器地址或本机 IP 时，不必重装，只跑配置流程即可。

若当初用管道安装（本机没有 install_alloy.sh）：

# 正确写法（注意是 bash -s -- config）
curl -fsSL https://downloads.monitor.chem-cloud.cn/install_alloy.sh | sudo bash -s -- config

注意：下面这种写法是错误的，不要用：

# 错误：bash 会去找名为 config 的本地文件
curl -fsSL https://downloads.monitor.chem-cloud.cn/install_alloy.sh | sudo bash config

若本机已下载过脚本：

sudo ./install_alloy.sh config

安装后

systemctl status alloy 确认服务为 active
在监控平台管理台添加「主机」资产，host 填写安装结束时打印的本机标识 IP
稍后在「日志查询」中应能看到该主机相关日志（需时间范围覆盖近期）

常用命令

systemctl status alloy
journalctl -u alloy -f
systemctl restart alloy

3.4 本手册未覆盖内容

告警规则 / 资产 / 拨测的详细业务配置（请在管理台操作）
企业内部 WorkBuddy 账号开通与自动化调度策略

运维日报 Agent 的下载与安装见 第 12 章。

4. 常见问题与处理

4.1 `docker: command not found` 或找不到 `docker compose`

原因： 未安装 Docker 或未安装 Compose 插件。

处理： 先安装 Docker Engine 与 Compose 插件，再重新执行 ./install.sh。

4.2 下载失败 / `curl: (7) Failed to connect`

原因： 无法访问下载站，或安全组未放行下载端口（如 8088）。

处理：

在目标机测试：curl -I https://downloads.monitor.chem-cloud.cn/
确认下载站安全组已放行对应端口
备用：从可访问机器下载后，用 scp 拷到目标机再解压安装

4.3 `./install.sh: Permission denied`

处理：

chmod +x install.sh
./install.sh

4.4 端口已被占用（如 80、443、9090、3100）

现象： 容器启动失败，日志中出现 bind / address already in use。

处理：

查占用：ss -lntp | grep -E ':80|:443|:9090|:3100'
Web HTTP 端口：修改 .env 中 HTTP_PORT 后重新 ./install.sh
Web HTTPS 端口：修改 .env 中 HTTPS_PORT 后重新 ./install.sh
9090 / 3100：停止冲突进程，或更换机器安装（产品默认映射这两端口供 Alloy 使用）

4.5 浏览器无法打开管理台

处理顺序：

docker compose ps 确认 web、api、mysql 为运行中
本机：curl -I http://127.0.0.1:<HTTP_PORT>；若启用了 HTTPS：curl -Ik https://127.0.0.1:<HTTPS_PORT>
确认安全组 / 防火墙已放行对应端口
用域名访问时：确认 DNS 已解析到本机，且 .env 中 DOMAIN、证书文件正确
确认 .env 中 PUBLIC_HOST 填写正确（不影响本机 curl，但影响对外说明地址）

4.5.1 启用 HTTPS 时报错找不到证书

现象： ERROR: 找不到证书文件 或 找不到私钥文件。

处理： 确认文件已放在安装目录的 certs/ 下，文件名与 .env 中 SSL_CERT_FILE、SSL_KEY_FILE 一致，再执行 ./install.sh。

4.6 页面能开，接口报错 / 登录失败

处理：

docker compose logs --tail=100 api
docker compose logs --tail=100 mysql

确认 MySQL 已 healthy，API 无持续报错后，再试登录。默认账号为 admin / Admin@123。

4.7 磁盘空间不足

现象： docker load 或启动失败，提示 no space。

处理： 清理磁盘后重试；确保至少数十 GB 可用空间。

4.8 需要重新安装

在产品目录下：

docker compose down
# 若需清空业务数据（谨慎）：
# docker compose down -v

然后检查 .env 后再次执行 ./install.sh。
删除数据卷会清空数据库，操作前请确认已备份。

4.9 升级到新版本

备份重要数据（至少备份 MySQL 数据或做快照）
下载新版本完整包并解压到新目录（或覆盖说明以发版说明为准）
保留原 .env 中的密码与密钥，避免数据库连不上
执行新版本 ./install.sh 或按发版说明操作

5. 快速检查清单

安装前：

机器为 Linux amd64，磁盘与内存满足要求
Docker、Compose 可用
80（或自定义端口）、9090、3100 无冲突或已规划
（如需 HTTPS）443 已放行，域名已解析，证书已放入 certs/
可访问安装包下载地址

安装后：

docker compose ps 中关键服务为运行中
浏览器可打开管理台并登录（HTTP 用 IP，或 HTTPS 用域名）
已修改默认管理员密码
（如需采集）业务机可访问监控服务器 9090、3100，并已安装 Alloy
（如需采集）管理台已添加主机资产，host 与 Alloy 本机 IP 一致
（如需日报 Agent）已保存安装结束打印的 config.env，并配置 WECOM_WEBHOOK

12. 运维日报 Agent（可选）

在已安装主监控服务端的前提下，可另装 运维日报 Agent：只读本环境的 Prometheus / Loki / 监控库 MySQL，生成 HTML 日报，经主监控上传 API 发布后推送到企业微信。

下载：ops-report-agent.zip
规划说明见 docs/客户agent规划.md。

12.1 前置条件

主监控已 ./install.sh 安装成功，并保存结束时打印的 config.env 配置块。
防火墙已放行 9090、3100、3306（及管理台端口），且运行 Agent 的机器能访问这些地址。
本机已安装 Python 3.8+，以及 WorkBuddy（若用对话触发）。

12.2 下载与安装到 WorkBuddy

在运行 WorkBuddy 的机器上：

curl -fLO https://downloads.monitor.chem-cloud.cn/ops-report-agent.zip
unzip ops-report-agent.zip
cd ops-report-agent   # 或以实际解压目录名为准

将主监控安装结束打印的配置保存为 config.env（可放在解压目录下，或 ~/.workbuddy/ops-report-agent/config.env）。
填写 WECOM_WEBHOOK（企微群机器人完整 URL 或仅 key；可留空，则只生成本地报告、不推送）。
将 skills/ 下全部子目录（含 _lib）复制到 ~/.workbuddy/skills/。
安装依赖：

pip install requests pymysql pillow
# 可选：封面截图需本机 Chrome，或另装 playwright

12.3 运行

python ~/.workbuddy/skills/monitor-master/scripts/run_master.py
# 仅出报告、不推企微：
python ~/.workbuddy/skills/monitor-master/scripts/run_master.py --no-push

常用参数：--modules monitor-hardware monitor-alerts、--report-only、--debug。

输出默认在 ~/WorkBuddy/Claw/monitor_master_report.html；配置了 REPORT_PUBLISH_* 且填写了企微 webhook 时，会上传到 {管理台}/agent-reports/ 并推送图文。

12.4 说明

报告 HTML 经管理台 POST /api/agent-reports/upload（头 X-Report-Token）上传，无需主监控服务器 SSH 账号密码。
未装 Alloy、未配拨测/库探针时，对应章节会显示「未接入」，属正常。
建议将日报 Agent 调度到每日固定时间（如 08:30）自动执行。

附录：完整安装命令汇总

# 1. 确认 Docker
docker --version && docker compose version

# 2. 下载安装
curl -fLO https://downloads.monitor.chem-cloud.cn/monitor-product-1.0.0.tar.gz
tar xzf monitor-product-1.0.0.tar.gz
cd monitor-product-1.0.0
cp .env.example .env
# 编辑 PUBLIC_HOST、必要时修改 HTTP_PORT
./install.sh

# 3. 验证
docker compose ps

芯化和云监控平台 — 安装手册

1. 安装前准备

1.1 服务器角色说明

1.2 硬件要求

1.3 软件要求

1.4 网络与端口

1.5 获取安装包

2. 安装步骤

2.1 下载并解压

2.2 配置环境变量

2.3 执行安装

2.4 验证

2.5 配置 HTTPS 与域名访问（可选）

步骤概览

放置证书

修改 .env

应用配置

访问方式

注意

3. 安装后说明

3.1 已启动的主要服务

3.2 常用运维命令

3.3 业务机 Alloy 安装（采集 Agent）

一键安装

重新配置

安装后

常用命令

3.4 本手册未覆盖内容

4. 常见问题与处理

4.1 docker: command not found 或找不到 docker compose

4.2 下载失败 / curl: (7) Failed to connect

4.3 ./install.sh: Permission denied

4.4 端口已被占用（如 80、443、9090、3100）

4.5 浏览器无法打开管理台

4.5.1 启用 HTTPS 时报错找不到证书

4.6 页面能开，接口报错 / 登录失败

4.7 磁盘空间不足

4.8 需要重新安装

4.9 升级到新版本

5. 快速检查清单

12. 运维日报 Agent（可选）

12.1 前置条件

12.2 下载与安装到 WorkBuddy

12.3 运行

12.4 说明

修改 `.env`

4.1 `docker: command not found` 或找不到 `docker compose`

4.2 下载失败 / `curl: (7) Failed to connect`

4.3 `./install.sh: Permission denied`