监控部署（单机）

适用场景：同机已用 Docker 部署 FinClaw 业务栈的单机环境。监控栈通过 monitor-offline-release 离线包部署，独立于业务栈运行，可选部署、不影响业务栈，全程零外网访问。

一、监控包说明

项	说明
包名	monitor-offline-release-1.0.2-linux-amd64.tar.gz（版本以实际交付为准）
组件	Prometheus、Alertmanager、Grafana、Loki、Alloy、node-exporter、cAdvisor、blackbox-exporter，及 PostgreSQL / TimescaleDB / Redis / NATS exporter
端口	Grafana 26190（对外）；Prometheus 26191（无鉴权，建议仅内网开放）；Alertmanager 26192（仅本机排障用）
数据	全部落在 deploy/data/ 本地目录，重装自动保留

开箱即用的 Grafana 大盘：finclaw 日志（容器日志查看 / 关键字过滤 / 下载）、finclaw 容器信息、Node Exporter Full（主机）、PostgreSQL / Redis（中间件）。

二、快速安装

tar xzf monitor-offline-release-1.0.2-linux-amd64.tar.gz && cd monitor-offline-release-1.0.2-linux-amd64

./deploy/scripts/load-images.sh          # 1. 校验 checksum 并加载镜像
cp deploy/.env.example deploy/.env        # 2. 生成环境配置
vi deploy/.env                           # 3. 必改：GRAFANA_ADMIN_PASSWORD、ALERT_WEBHOOK_URL
./deploy/scripts/monitor.sh up           # 4. 启动
./deploy/scripts/doctor.sh               # 5. 体检（FAIL 需处理后重跑）

安装完成后浏览器访问 http://<主机IP>:26190，账号密码见 .env，界面默认中文。

GRAFANA_ADMIN_PASSWORD 仅在 Grafana 数据卷首次初始化时生效，后续改密请走 Grafana 界面。

三、关键配置（.env）

配置	默认值	说明
GRAFANA_ADMIN_PASSWORD	change-me（必改）	Grafana 管理员密码
ALERT_WEBHOOK_URL	必填	告警统一转发地址（企业微信 / 飞书机器人等），留空启动直接报错
PROM_RETENTION / LOKI_RETENTION	15d / 168h	指标 / 日志保留时长，磁盘占用约与时长成正比
CHATKIT_HOST	host.docker.internal	业务栈地址；业务栈在其它机器时改为其 IP，并同步修改 deploy/config/prometheus/targets/chatkit-services.yml 与 prometheus.yml 中的 host.docker.internal 字面量
CHATKIT_CONTAINER_REGEX	^chatkit-	日志采集的容器名过滤正则（仅采集 finclaw 业务容器，天然排除监控栈自身）
PG_EXPORTER_* / TSDB_EXPORTER_*	postgres / convstore	中间件 exporter 连接账密

修改生效方式：

修改内容	生效方式
告警 webhook、LOKI_RETENTION 等渲染配置	./deploy/scripts/monitor.sh restart
端口 / BIND / CHATKIT_CONTAINER_REGEX 等 compose 级配置	./deploy/scripts/monitor.sh up（自动重建受影响容器）

四、常用维护

./deploy/scripts/monitor.sh up|down|status|logs   # 启停与日志
./deploy/scripts/doctor.sh                        # 体检：FAIL=监控栈自身故障；WARN=业务服务异常等提示

• 增删探活服务：编辑 deploy/config/prometheus/targets/chatkit-services.yml（file_sd 方式，30 秒自动生效，无需重启）
• 告警时延：新分组按 group_wait（默认 30s）送达；告警加入已存在分组时受 group_interval（默认 5m）限制，需更快送达可调 deploy/config/alertmanager/alertmanager.yml.tmpl
• 升级 / 重装：monitor.sh down 后重跑安装步骤；数据在 deploy/data/，彻底清空删除该目录内容即可