monitor v0.41.0
针对 Valkey 和 Redis 数据库的实时监控和慢日志分析，支持异常检测、ACL 审计和 Prometheus 指标导出。
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）```bash
docker run -d --name betterdb -p 3001:3001 betterdb/monitor:latest
将浏览器指向 `http://localhost:3001`。要监控特定实例：```bash
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 助手的依赖项 |
X.Y.Z | 添加实验性 AI 助手（自带 Ollama；默认通过 AI_ENABLED 禁用） |
有关持久化存储、自定义端口、许可及离线环境部署，请参阅 Docker 生产部署。
快速开始（Kubernetes / Helm）```bash
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 指南](https://docs.betterdb.com/kubernetes) 和 [chart README](https://github.com/betterdb-inc/monitor/blob/master/charts/betterdb-monitor/README.md) 中涵盖。
## 快速开始（CLI）
无需 Docker 即可运行 BetterDB Monitor：```bash
npx @betterdb/monitor
首次运行时，交互式设置向导会引导你完成数据库连接、存储后端（SQLite、PostgreSQL 或内存模式）以及服务器设置的配置。配置将保存到 ~/.betterdb/config.json。```bash
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 和键分布。
- **CPU 与 I/O 线程指标** - 任何 Redis 工具都无法提供的每线程可见性。
- **客户端分析** - 精确查看哪个服务负责什么，按客户端名称和模式归因。
- **ACL 审计追踪** - 跟踪谁访问了什么，持久化保存以用于合规和事后调试。
### 理解并采取行动
- **异常检测**（Pro 版，早期访问免费）- 自动基线学习，附带关联事件和通俗易懂的诊断说明。20+ 检测器，无需手动设置阈值。
- **容量预测** - 预测内存、每秒操作数、CPU 和碎片率达到上限的时间。
- **Webhooks** - 带 HMAC 签名的告警投递，支持重试和完整投递日志。
- **实时迁移** - 通过三阶段分析、执行和验证工作流在 Redis 和 Valkey 之间迁移。
### 为 AI 时代而生
- **向量搜索可观测性** - 针对 [valkey-search](https://github.com/valkey-io/valkey-search) 和 RediSearch 的 FT.SEARCH 每秒操作数和延迟，以及按索引的健康状态。参见 [docs/vector-ai](https://github.com/betterdb-inc/monitor/blob/master/docs/vector-ai/README.md)。
- **推理延迟** - 每个索引的 p50/p95/p99，附带 SLA 违约告警（Pro 版，早期访问免费）。
- **语义缓存智能**（Pro 版，早期访问免费）- 命中率健康状态、相似度阈值建议，以及批准/拒绝提案工作流。包含代理内存可观测性。
- **AI 追踪** - 来自 AI 应用的 OTLP span 瀑布图，与每个请求底层的实时 Valkey 状态相关联。参见 [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md)。
### 接入一切
- **MCP 服务器** - 通过 [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp) 为 Claude Code、Cursor 或任何 MCP 客户端提供 60 个工具。
- **Prometheus 端点** - 100+ 个 `betterdb_*` 指标。参见 [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md)。
- **OpenTelemetry** - 接收 OTLP 追踪，并将指标和事件镜像到任何 OTLP 后端。参见 [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md)。
- **REST API** - UI 中的一切操作都是 API 调用，通过 OpenAPI 文档化。
## 以你的方式访问数据
| 接口 | 详情 |
|-----------|---------|
| Web UI | `http://localhost:3001` |
| MCP 服务器 | `npx @betterdb/mcp`（stdio）- 在设置 → MCP 令牌下创建令牌 |
| 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](https://github.com/betterdb-inc/monitor/blob/master/docs/providers)，而 [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) 通过出站 WebSocket 连接仅限 VPC 的实例。
## Docker 生产部署
Docker 镜像包含监控应用（后端 + 前端）。它需要：
1. 一个用于监控的 Valkey/Redis 实例
2. 一个用于数据持久化的 PostgreSQL 实例（或使用内存存储）
### 使用 PostgreSQL 存储运行```bash
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 映射：```bash
docker run -d
--name betterdb-monitor
-p 8080:8080
-e PORT=8080
-e DB_HOST=your-valkey-host
betterdb/monitor
### 使用主机网络运行（访问 localhost 服务）
如果你的 Valkey 和 PostgreSQL 运行在同一台主机上：```bash
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
环境变量
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
DB_HOST | 是 | localhost | 要监控的 Valkey/Redis 主机 |
DB_PORT | 否 | 6379 | Valkey/Redis 端口 |
DB_PASSWORD | 否 | - | Valkey/Redis 密码 |
DB_USERNAME | 否 | default | Valkey/Redis ACL 用户名 |
DB_TYPE | 否 | auto | 数据库类型：auto、valkey 或 redis |
STORAGE_TYPE | 否 | memory | 存储后端：memory 或 postgres |
STORAGE_URL | 条件必填 | - | PostgreSQL 连接 URL（当 STORAGE_TYPE=postgres 时必填） |
PORT | 否 | 3001 | 应用 HTTP 端口 |
NODE_ENV | 否 | production | Node 环境 |
ANOMALY_DETECTION_ENABLED | 否 | true | 启用异常检测 |
ANOMALY_PROMETHEUS_INTERVAL_MS | 否 | 30000 | Prometheus 摘要更新间隔（毫秒） |
BETTERDB_LICENSE_KEY | 否 | - | 在线许可证密钥（Pro/Enterprise），通过网络验证 |
BETTERDB_OFFLINE_LICENSE_FILE | 否 | - | 已签名离线许可证 .jwt 文件的路径，适用于隔离网络主机（见下文） |
BETTERDB_OFFLINE_LICENSE | 否 | - | 以内联 JWT 字符串形式提供的离线许可证令牌 |
BETTERDB_DATA_DIR | 否 | /app/data | 用于持久化许可证状态的目录（请挂载可写卷） |
ENCRYPTION_KEY | 否 | - | 用于对存储的连接密码和 SSH 隧道机密进行信封加密的密钥（至少 16 个字符）。未设置时，机密将以明文存储 |
BETTERDB_SSH_KEY_DIR | 否 | - | 服务端 SSH 私钥必须存放的目录。启用 SSH 隧道 的“服务器文件路径”密钥来源；连接的密钥路径必须解析到该目录内。未设置则禁用基于文件的密钥（内联粘贴的密钥仍可使用） |
BETTERDB_TELEMETRY | 否 | true | 设为 false 可禁用匿名遥测 |
完整参考（包括 AI、Webhook 调优和健康门限）：docs/configuration.md。有关 OTLP 追踪摄取及指标/事件导出，请参阅 docs/opentelemetry.md。
SSH 隧道
连接可以通过 SSH 堡垒/跳板主机访问数据库，而非直接连接——这对于位于私有子网、ElastiCache 或 MemoryDB 中的 Valkey/Redis 非常有用。添加连接时，启用 通过 SSH 隧道连接，并提供 SSH 主机、端口和用户名。支持单跳。
认证方式为密码或私钥。私钥来自以下两种来源之一：
- 粘贴密钥（内联）：PEM 密钥内容随连接一起提交。仅当设置了
ENCRYPTION_KEY时，它才会在静态存储时加密（信封加密）；未设置该密钥时，它将与连接密码一样以明文存储。适用于所有环境，包括托管/云部署。 - 服务器文件路径：密钥已存在于监控服务器的文件系统上，并通过路径引用。这需要将
BETTERDB_SSH_KEY_DIR环境变量设置为存放允许密钥的目录，且引用的路径必须解析到该目录内，这样 API 永远不会被诱导去读取任意文件。保持BETTERDB_SSH_KEY_DIR未设置可禁用此选项。
可选地，在连接上固定 SSH 服务器的主机密钥指纹（SHA256:...）；设置后，除非服务器提供匹配的密钥，否则隧道将被拒绝，从而防止针对堡垒路径的中间人攻击。留空则不验证服务器身份（会记录警告日志）。
隧道通过 127.0.0.1 转发到数据库；启用 TLS 时，证书仍会针对真实数据库主机名进行验证。请设置 ENCRYPTION_KEY，以便 SSH 密码、密钥口令和内联密钥在静态存储时加密。
已知限制——集群/Sentinel 拓扑： 只有您配置的连接会通过隧道。集群和 Sentinel 监控会使用这些节点通告的地址（CLUSTER NODES / Sentinel）向其他节点扇出，而这些逐节点连接是直接建立的，不经过隧道。如果其他节点只能通过堡垒机访问（例如私有子网中的 ElastiCache/MemoryDB），则逐节点视图将不可用。请将 SSH 隧道用于单节点/主节点监控，或将监控器部署在可直接访问集群节点的位置。
许可证与隔离网络支持
BetterDB Monitor 通过以下两种方式之一解锁 Pro/Enterprise 功能，具体取决于 主机是否具有互联网访问权限：
- 在线许可证密钥 - 设置
BETTERDB_LICENSE_KEY。监控器会向betterdb.com验证该密钥，并缓存一个本地验证的签名令牌，因此您的 服务层级可在短暂中断和重启期间持续工作。 - 离线/隔离网络许可证令牌 - 适用于完全没有互联网访问权限的主机 （见下文）。
隔离网络许可证的工作原理
每项授权都是一个签名的 RS256 JWT。监控器会在本地使用镜像中内置的 公钥对其进行验证——它永远不需要联系许可证服务器来信任令牌。因此，隔离网络 主机可以在零连接的情况下运行付费服务层级：
- 在可联网的机器上，登录
betterdb.com/account/licenses 并
下载您的离线许可证令牌（
.jwt，Pro/Enterprise）。它不包含任何 机密信息，也无法被篡改——任何修改都会破坏签名。 - 以您喜欢的方式将其传输到隔离网络主机（USB、配置管理、 Docker/Kubernetes 机密挂载）。
- 通过
BETTERDB_OFFLINE_LICENSE_FILE（路径）、BETTERDB_OFFLINE_LICENSE（内联字符串）提供它，或在 UI 中粘贴到 设置 → 许可证 → “隔离网络 环境？激活离线许可证。”
当配置了离线令牌且未设置 BETTERDB_LICENSE_KEY 时，监控器
不会发出任何出站请求——许可证检查、遥测和更新
通知全部被禁用。它将运行所授予的服务层级，直到令牌过期（永久
许可证每年重新下载一次），然后回退到 Community 版。```bash
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` 而失败。
有关完整流程、验证优先级和密钥轮换手册，请参阅
**[离线与气隙许可证](https://github.com/betterdb-inc/monitor/blob/master/docs/offline-licenses.md)** 和
**[配置参考](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md#license-configuration)**。
### Docker 镜像详情
- **基础镜像**：`node:20-alpine`
- **压缩大小**：约 360MB（`latest` / `-no-ai`）/ 约 640MB（带实验性 AI Helper 本地 LLM 依赖的版本化镜像）
- **平台**：`linux/amd64`、`linux/arm64`
- **包含内容**：后端 API + 前端静态文件（由 Fastify 提供）
- **排除内容**：SQLite 支持（使用 PostgreSQL 或 Memory 存储）
### 容器操作```bash
docker logs -f betterdb-monitor # follow logs
docker stop betterdb-monitor # stop
docker rm betterdb-monitor # remove
存储后端
BetterDB Monitor 将审计跟踪、分析、捕获和异常数据持久化到以下四种后端之一：
| 后端 | 使用场景 | 备注 |
|---|---|---|
memory | 测试、临时环境 | Docker 中的默认选项；重启后所有数据丢失 |
postgres | 生产环境 | STORAGE_TYPE=postgres + STORAGE_URL=postgresql://user:pass@host:port/db |
turso | 生产环境 / 无服务器 SQLite | STORAGE_TYPE=turso + STORAGE_URL=libsql://... + STORAGE_AUTH_TOKEN；可在 Docker 中运行 |
sqlite | 本地开发 / CLI | 原生模块已从 latest Docker 镜像中移除；STORAGE_SQLITE_FILEPATH 为可选配置 |
Prometheus 指标
指标以 Prometheus 文本格式在 GET /api/prometheus/metrics 端点暴露：ACL 审计、客户端连接、slowlog/commandlog 模式、内存、吞吐量、键空间、复制、集群槽位统计以及 Node.js 运行时指标——全部以 betterdb_ 为前缀。```yaml
scrape_configs:
- job_name: 'betterdb-monitor'
metrics_path: '/api/prometheus/metrics'
static_configs:
- targets: ['your-monitor-host:3001']
完整指标参考：[docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md) 和 [docs/prometheus-integration.md](https://github.com/betterdb-inc/monitor/blob/master/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/。
| 软件包 | 语言 | 注册表 |
|---|---|---|
@betterdb/monitor | TypeScript | npm |
@betterdb/mcp | TypeScript | npm |
@betterdb/agent | TypeScript | npm |
@betterdb/semantic-cache | TypeScript | npm |
betterdb-semantic-cache | Python | PyPI |
@betterdb/agent-cache | TypeScript | npm |
betterdb-agent-cache | Python | PyPI |
cache-benchmark | Python | 用于基准测试语义缓存的回放工具 |
技术栈
- 后端：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。```bash 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`。```bash
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 镜像构建：```bash 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](https://github.com/betterdb-inc/monitor/blob/master/LICENSE) 许可。