BetterDB Monitor

Valkey 应得的监控层。

BetterDB 将 Valkey 丢弃的数据持久化保存——慢日志、命令模式、客户端活动、异常信号——让你能够调试凌晨 3 点发生的事情，而不仅仅是当下正在发生什么。专为 Valkey 8.x 打造，原生支持 COMMANDLOG、CLUSTER SLOT-STATS 以及每线程 I/O 指标。其余功能兼容 Redis 6+。

网站 | Docker Hub | npm | 文档 | 博客

BetterDB 由 BetterDB Inc. 构建，这是一家公益公司，依据 OCV Open Charter 运营。

快速开始（Docker）

docker run -d --name betterdb -p 3001:3001 betterdb/monitor:latest

将浏览器指向 http://localhost:3001。要监控特定实例：

docker run -d \
  --name betterdb \
  -p 3001:3001 \
  -e DB_HOST=your-valkey-host \
  -e DB_PORT=6379 \
  -e DB_PASSWORD=your-password \
  betterdb/monitor:latest

要连接到宿主机上的数据库？ 在容器内部， localhost 指的是容器本身，而不是你的宿主机——因此请使用 host.docker.internal 作为数据库主机。在 Docker Desktop (macOS/Windows) 上开箱即用；在 Linux 上，请在 docker run 命令中 添加 --add-host=host.docker.internal:host-gateway，以便该名称能够解析。 仪表板的一键“连接到本地实例”按钮会自动检测这一点，并为你预填正确的主机。

发布两个镜像变体，均为多架构（linux/amd64、linux/arm64）：

标签	说明
latest、X.Y.Z-no-ai	默认镜像——包含所有监控功能，但不包含实验性本地 LLM AI Helper 所需的依赖项
X.Y.Z	增加实验性 AI Helper（自带 Ollama；默认通过 AI_ENABLED 禁用）

有关持久化存储、自定义端口、许可和隔离网络环境设置，请参阅 Docker 生产部署。

快速开始（Kubernetes / Helm）

helm repo add betterdb https://docs.betterdb.com/charts
helm repo update
helm install betterdb-monitor betterdb/betterdb-monitor \
  --namespace betterdb --create-namespace \
  --set db.host=my-valkey.default.svc.cluster.local \
  --set db.password=yourpassword

然后执行 kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001 并打开 http://localhost:3001，或启用 chart 的 ingress。基于 PostgreSQL 的历史记录、自带 Secrets 以及离线环境授权均在 Kubernetes 指南 和 chart README 中有详细说明。

快速开始（CLI）

无需 Docker 即可运行 BetterDB Monitor：

npx @betterdb/monitor

首次运行时，交互式设置向导会引导您完成数据库连接、存储后端（SQLite、PostgreSQL 或内存）以及服务器设置。配置会保存到 ~/.betterdb/config.json。

npm install -g @betterdb/monitor   # global install
betterdb --setup                   # re-run setup wizard
betterdb --port 8080               # override server port
betterdb --db-host 1.2.3.4         # override database host
betterdb --help                    # all options

需要 Node.js >= 20.0.0 以及一个要监控的 Valkey 或 Redis 实例。若使用 SQLite 存储，还需执行 npm install -g better-sqlite3。

你将获得

洞察一切，留存一切

• 历史分析 - 可查询任意时间范围内的慢日志、命令模式、客户端活动和延迟。这些数据过去在日志轮转后便会消失。
• COMMANDLOG 支持 - Valkey 8.1+ 独有。不仅记录慢请求，还包括大请求和大回复。
• MONITOR 捕获会话 - 按需记录真实流量：实时追踪、过滤、回放、导出为 JSON/CSV，并与连接历史交叉比对。
• 热键追踪 - 按访问频率排列的顶级键，并展示排名随时间的变化。Key Analytics（Pro 版，早期访问免费）通过实时采样增加类型、TTL 和大小分布。
• 集群可见性 - 拓扑图、SLOT-STATS 热力图、每槽 CPU 和键分布。
• 集群自动注册 - 集群连接可自动将每个节点注册为独立的受监控连接，并随集群扩展保持同步。参见 docs/cluster-auto-registration.md。
• CPU 与 I/O 线程指标 - 任何 Redis 工具都无法提供的每线程可见性。
• 客户端分析 - 按客户端名称和模式归因，精确查看哪个服务负责什么。
• ACL 审计追踪 - 追踪谁访问了什么，持久化保存以满足合规和事后调试需求。

理解并行动

• 异常检测（Pro 版，早期访问免费）- 自动基线学习，关联事件并提供通俗易懂的诊断。20+ 检测器，无需手动设置阈值。
• 容量预测 - 预测内存、每秒操作数、CPU 和碎片率达到上限的时间。
• Webhook - 采用 HMAC 签名的告警投递，支持重试和完整的投递日志。
• 实时迁移 - 在 Redis 和 Valkey 之间迁移，采用三阶段分析、执行和验证工作流。

为 AI 时代打造

• 向量搜索可观测性 - FT.SEARCH 每秒操作数和延迟，以及 valkey-search 和 RediSearch 的每索引健康状态。参见 docs/vector-ai。
• 推理延迟 - 每索引的 p50/p95/p99，并支持 SLA 违约告警（Pro 版，早期访问免费）。
• 语义缓存智能（Pro 版，早期访问免费）- 命中率健康度、相似度阈值建议，以及批准/拒绝提案工作流。包含 Agent 记忆可观测性。
• AI 追踪 - 来自 AI 应用的 OTLP span 瀑布图，与每个请求底层的实时 Valkey 状态相关联。参见 docs/opentelemetry.md。

可接入一切

• MCP 服务器 - 通过 @betterdb/mcp 为 Claude Code、Cursor 或任何 MCP 客户端提供 60 个工具。
• Prometheus 端点 - 100+ 个 betterdb_* 指标。参见 docs/prometheus-metrics.md。
• OpenTelemetry - 摄取 OTLP 追踪，并将指标和事件镜像到任何 OTLP 后端。参见 docs/opentelemetry.md。
• REST API - UI 中的一切皆为 API 调用，通过 OpenAPI 文档化。

按你的方式访问数据

接口	详情
Web UI	http://localhost:3001
MCP 服务器	npx @betterdb/mcp（stdio）- 在 Settings → MCP Tokens 下创建令牌（云端必需，自托管可选）
Prometheus	http://localhost:3001/api/prometheus/metrics
REST API (OpenAPI)	http://localhost:3001/docs
健康检查	http://localhost:3001/api/health

注意：在生产构建（Docker、CLI）中，API 路由以 /api 前缀提供服务。在本地开发（pnpm dev）中则没有前缀 - 例如 http://localhost:3001/health。

支持的数据库

数据库	最低版本	支持的功能
Valkey	8.0+	所有功能，包括 COMMANDLOG（8.1+）和 CLUSTER SLOT-STATS
Redis	6+	除 Valkey 独有的 COMMANDLOG 和 CLUSTER SLOT-STATS 外的所有功能

后端在兼容线协议的 iovalkey 客户端之上使用统一适配器，并从 INFO 响应中自动检测 Valkey 与 Redis（DB_TYPE=auto）。COMMANDLOG 和 SLOT-STATS 等能力按版本检测，当功能不可用时 UI 会优雅降级。

托管服务同样支持 - AWS ElastiCache、MemoryDB、Redis Cloud 和 Upstash 的指南位于 docs/providers，而 @betterdb/agent 可通过出站 WebSocket 访问仅限 VPC 的实例。

Docker 生产部署

Docker 镜像包含监控应用（后端 + 前端）。它需要：

1. 一个要监控的 Valkey/Redis 实例
2. 一个用于数据持久化的 PostgreSQL 实例（或使用内存存储）

使用 PostgreSQL 存储运行

docker run -d \
  --name betterdb-monitor \
  -p 3001:3001 \
  -e DB_HOST=your-valkey-host \
  -e DB_PORT=6379 \
  -e DB_PASSWORD=your-password \
  -e STORAGE_TYPE=postgres \
  -e STORAGE_URL=postgresql://user:pass@postgres-host:5432/dbname \
  betterdb/monitor

在自定义端口上运行

设置 PORT 环境变量并匹配 -p 映射：

docker run -d \
  --name betterdb-monitor \
  -p 8080:8080 \
  -e PORT=8080 \
  -e DB_HOST=your-valkey-host \
  betterdb/monitor

使用主机网络运行（访问 localhost 服务）

如果你的 Valkey 和 PostgreSQL 运行在同一台主机上：

docker run -d \
  --name betterdb-monitor \
  --network host \
  -e DB_HOST=localhost \
  -e DB_PORT=6380 \
  -e DB_PASSWORD=devpassword \
  -e STORAGE_TYPE=postgres \
  -e STORAGE_URL=postgresql://dev:devpass@localhost:5432/postgres \
  betterdb/monitor

环境变量