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 开放宪章 运营。
快速开始（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 Helper 所需的依赖项 |
X.Y.Z | 添加实验性 AI Helper（自带 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 时代打造
- **向量搜索可观测性** - FT.SEARCH 每秒操作数和延迟，以及 [valkey-search](https://github.com/valkey-io/valkey-search) 和 RediSearch 的每索引健康状态。参见 [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）- 在 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](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 |
DB_TLS | 否 | false | 设置为 true 以通过 TLS 连接到被监控的数据库（Aiven 或 ElastiCache Serverless 等托管服务商要求） |
STORAGE_TYPE | 否 | memory | 存储后端：memory 或 postgres |
STORAGE_URL | 条件必需 | - | PostgreSQL 连接 URL（当 STORAGE_TYPE=postgres 时必需） |
STORAGE_SSL_CA | 否 | - | 用于验证 PostgreSQL 服务器的 CA 证书路径（或受信任的 HTTPS URL）。对于拥有自己 CA 的托管服务商（如 Aiven），在此提供项目 CA 以进行完整链 + 主机名验证。优先于 STORAGE_SSL_NO_VERIFY |
STORAGE_SSL_NO_VERIFY | 否 | false | 通过 TLS 连接到 PostgreSQL 但不验证服务器证书（加密但未认证）。适用于那些提供自己的 CA 并强制 sslmode=require 而你又无法提供 STORAGE_SSL_CA 的托管服务商。生产环境请优先使用 STORAGE_SSL_CA |
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 堡垒机/跳板机访问数据库，而不是直接连接——这对于私有子网中的 Valkey/Redis、ElastiCache 或 MemoryDB 非常有用。添加连接时启用 Connect via SSH tunnel 并提供 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 中的 Settings → License → "Air-gapped environment? Activate an offline license." 下粘贴它。
当配置了离线令牌且未设置 BETTERDB_LICENSE_KEY 时，
监控器会发出零出站请求——许可证检查、遥测和更新
ping 均被禁用。它会运行所授予的层级直到令牌过期（永久
许可证每年重新下载），然后回退到 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 指标
指标通过 GET /api/prometheus/metrics 以 Prometheus 文本格式暴露：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) 许可。