Monitoring Deployment (Single-Node)

Applicable to single-node environments where the FinClaw business stack is already deployed with Docker on the same machine. The monitoring stack is deployed via the monitor-offline-release offline package, runs independently of the business stack, is optional and does not affect the business stack, and requires zero internet access.

1. About the Package

Item	Notes
Package name	monitor-offline-release-1.0.2-linux-amd64.tar.gz (replace with the actually delivered version)
Components	Prometheus, Alertmanager, Grafana, Loki, Alloy, node-exporter, cAdvisor, blackbox-exporter, plus PostgreSQL / TimescaleDB / Redis / NATS exporters
Ports	Grafana 26190 (external); Prometheus 26191 (unauthenticated, intranet only recommended); Alertmanager 26192 (localhost, for troubleshooting)
Data	All data lives in the local deploy/data/ directory and is preserved across reinstalls

Out-of-the-box Grafana dashboards: finclaw logs (container log viewing / keyword filtering / download), finclaw container info, Node Exporter Full (host), PostgreSQL / Redis (middleware).

2. Quick Install

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. Verify checksums and load images
cp deploy/.env.example deploy/.env        # 2. Generate the environment config
vi deploy/.env                           # 3. Required: GRAFANA_ADMIN_PASSWORD, ALERT_WEBHOOK_URL
./deploy/scripts/monitor.sh up           # 4. Start
./deploy/scripts/doctor.sh               # 5. Health check (fix any FAIL, then re-run)

After installation, open http://<host-ip>:26190 in a browser; the credentials are in .env, and the UI defaults to Chinese.

GRAFANA_ADMIN_PASSWORD only takes effect when the Grafana data volume is first initialized; change the password via the Grafana UI afterwards.

3. Key Configuration (.env)

Setting	Default	Notes
GRAFANA_ADMIN_PASSWORD	change-me (must change)	Grafana admin password
ALERT_WEBHOOK_URL	required	Unified webhook address alerts are forwarded to (WeCom / Feishu bot, etc.); leaving it empty fails startup
PROM_RETENTION / LOKI_RETENTION	15d / 168h	Metrics / log retention; disk usage is roughly proportional
CHATKIT_HOST	host.docker.internal	Business stack address; if the stack runs on another machine, set its IP and update the host.docker.internal literals in deploy/config/prometheus/targets/chatkit-services.yml and prometheus.yml accordingly
CHATKIT_CONTAINER_REGEX	^chatkit-	Container-name filter regex for log collection (collects only finclaw business containers, excluding the monitoring stack itself)
PG_EXPORTER_* / TSDB_EXPORTER_*	postgres / convstore	Middleware exporter credentials

How changes take effect:

Changed setting	How to apply
Rendered configs such as the alert webhook and LOKI_RETENTION	./deploy/scripts/monitor.sh restart
Compose-level settings such as ports / BIND / CHATKIT_CONTAINER_REGEX	./deploy/scripts/monitor.sh up (rebuilds affected containers automatically)

4. Routine Maintenance

./deploy/scripts/monitor.sh up|down|status|logs   # start/stop and logs
./deploy/scripts/doctor.sh                        # health check: FAIL = monitoring stack itself is broken; WARN = hints such as abnormal business services

• Add or remove probed services: edit deploy/config/prometheus/targets/chatkit-services.yml (file_sd; takes effect within 30 seconds, no restart needed)
• Alert latency: a new group is delivered after group_wait (default 30s); alerts joining an existing group are limited by group_interval (default 5m) and may be delayed by minutes. To deliver faster, tune deploy/config/alertmanager/alertmanager.yml.tmpl
• Upgrade / reinstall: run monitor.sh down, then repeat the install steps; data lives in deploy/data/ - delete the contents of that directory to wipe it completely