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

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

有关持久化存储、自定义端口、许可和离线（air-gapped）部署，请参阅 Docker 生产部署。

快速开始（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，并与连接历史交叉比对。
• 热键追踪 - 按访问频率统计热门键，并展示排名随时间的变化。键分析（Pro，抢先体验期免费）通过实时采样增加类型、TTL 和大小分布。
• 集群可见性 - 拓扑图、SLOT-STATS 热力图、每槽位 CPU 和键分布。
• CPU 和 I/O 线程指标 - 任何 Redis 工具都无法提供的每线程可见性。
• 客户端分析 - 按客户端名称和模式归因，精确查看哪个服务负责什么。
• ACL 审计追踪 - 追踪谁访问了什么，持久化保存，用于合规和事后排查。

理解并采取行动

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

为 AI 时代而生

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

接入一切

• MCP 服务器 - 通过 @betterdb/mcp 为 Claude Code、Cursor 或任何 MCP 客户端提供 60 个工具。
• Prometheus 端点 - 100+ 个 betterdb_* 指标。参见 docs/prometheus-metrics.md。
• OpenTelemetry - 将指标和事件镜像到任何 OTLP 后端。
• REST API - UI 中的所有功能都是 API 调用，通过 OpenAPI 记录文档。

按你的方式访问数据

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

支持的数据库

后端使用基于线上兼容 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

环境变量

完整参考，包括 AI、OTLP 导出、webhook 调优和健康门限阈值： docs/configuration.md。

许可与离线（Air-Gapped）支持

BetterDB Monitor 根据主机是否有互联网访问权限，通过以下两种方式之一解锁 Pro/Enterprise 功能：

• 在线许可证密钥 - 设置 BETTERDB_LICENSE_KEY。监控器会向 betterdb.com 验证该密钥，并缓存一个本地验证的签名令牌，因此你的服务等级在短暂中断和重启期间仍能正常工作。
• 离线/隔离环境许可证令牌 - 适用于完全没有互联网访问的主机（见下文）。

离线许可证的工作原理

每项授权都是一个有符号的 RS256 JWT。监控器使用镜像中内置的公钥在本地验证它——无需连接许可证服务器即可信任令牌。因此，离线主机可以在零连接的情况下运行付费版本：

1. 在联网的机器上，登录 betterdb.com/account/licenses 并 下载你的离线许可证令牌（.jwt，Pro/Enterprise）。它不包含任何机密信息，也 无法被篡改——任何修改都会破坏签名。
2. 以你喜欢的方式将其传输到离线主机（U 盘、配置管理、 Docker/Kubernetes 密钥挂载）。
3. 通过 BETTERDB_OFFLINE_LICENSE_FILE（路径）、BETTERDB_OFFLINE_LICENSE （内联字符串）提供，或粘贴到 UI 的 设置 → 许可证 → “离线环境？ 激活离线许可证。” 中。

当配置了离线令牌且未设置 BETTERDB_LICENSE_KEY 时，监控器会发出零出站请求——许可证检查、遥测和更新探测全部禁用。它会以授予的服务等级运行，直到令牌过期（永久许可证每年重新下载），然后回退到 Community 版。

# fully offline - no network required
docker volume create betterdb-data
docker run --rm -v betterdb-data:/d alpine chown 1001:1001 /d   # volume writable by UID 1001 (one-time)

docker run -d --name betterdb-monitor -p 3001:3001 \
  -e DB_HOST=your-valkey-host -e DB_PORT=6379 -e DB_PASSWORD=your-password \
  -v /path/to/betterdb-license.jwt:/run/secrets/betterdb-license.jwt:ro \
  -e BETTERDB_OFFLINE_LICENSE_FILE=/run/secrets/betterdb-license.jwt \
  -v betterdb-data:/app/data \
  betterdb/monitor

使用 GET /api/license/status 验证 → source: offline-token、mode: offline、airGapped: true。

持久化： 在 /app/data 挂载可写卷，以便离线许可证和在线中断宽限令牌在重启后仍然有效。容器以 UID 1001 运行，因此新创建的卷必须 chown 给它（如上所示）——否则持久化会失败并报错 EACCES … license.jwt。

有关完整流程、验证优先级和密钥轮换运行手册，请参阅 离线与隔离环境许可证 和 配置参考。

Docker 镜像详情

• 基础镜像：node:20-alpine
• 压缩后大小：约 360MB（latest / -no-ai）/ 约 640MB（带实验性 AI Helper 本地 LLM 依赖的版本化镜像）
• 平台：linux/amd64、linux/arm64
• 包含：后端 API + 前端静态文件（由 Fastify 提供）
• 不包含：SQLite 支持（请使用 PostgreSQL 或内存存储）

容器操作

docker logs -f betterdb-monitor        # follow logs
docker stop betterdb-monitor           # stop
docker rm betterdb-monitor             # remove

存储后端

BetterDB Monitor 将审计追踪、分析、捕获和异常数据持久化到以下三种后端之一：

Prometheus 指标

指标以 Prometheus 文本格式在 GET /api/prometheus/metrics 暴露：ACL 审计、客户端连接、慢日志/命令日志模式、内存、吞吐量、键空间、复制、集群槽位统计和 Node.js 运行时指标——均以 betterdb_ 为前缀。

scrape_configs:
  - job_name: 'betterdb-monitor'
    metrics_path: '/api/prometheus/metrics'
    static_configs:
      - targets: ['your-monitor-host:3001']

完整指标参考： docs/prometheus-metrics.md 和 docs/prometheus-integration.md。

开发

项目结构

betterdb-monitor/
├── apps/
│   ├── api/                 # NestJS backend (Fastify)
│   └── web/                 # React frontend (Vite)
├── packages/                # Published packages (see below)
├── docs/                    # Documentation site (Jekyll)
├── docker-compose.yml       # Local Valkey (port 6380) and Redis (port 6382) for testing
└── package.json             # Workspace root

软件包

该 monorepo 发布了多个独立软件包。完整列表请参见 packages/。

技术栈

• 后端：NestJS 搭配 Fastify 适配器，使用 iovalkey 进行 Valkey/Redis 连接，TypeScript 严格模式。端口 3001。
• 前端：React + TypeScript、Vite、TailwindCSS、Recharts。开发服务器位于端口 5173。
• Monorepo：pnpm workspaces + Turborepo。

本地设置

前置要求：Node.js >= 20.0.0、pnpm >= 9.0.0、Docker。

pnpm install
cp .env.example .env
pnpm docker:dev        # local Valkey (6380) and Redis (6382)
pnpm dev               # web on :5173, api on :3001

要连接 Redis 而不是 Valkey，请在 .env 中设置 DB_PORT=6382。

pnpm dev:api           # API only
pnpm dev:web           # frontend only
pnpm docker:dev:down   # stop local databases
pnpm build             # production build
pnpm test              # API tests

Docker 镜像构建：

pnpm docker:build      # local build
pnpm docker:publish    # multi-arch build & push (requires buildx)

添加新功能

1. 在 apps/api/src/ 中添加新端点
2. 在 apps/web/src/api/ 中添加相应的 API 调用
3. 在 packages/shared/src/types/ 中添加共享类型

代码风格

• TypeScript 严格模式、显式返回类型、不使用 any
• 已配置 ESLint + Prettier

许可证

• docs/ 下的内容采用 CC BY-SA 4.0 许可。
• proprietary/ 下的内容受商业许可保护（参见 proprietary/LICENSE）。这些功能在抢先体验期间免费。
• 其余所有内容均为 MIT 许可。