clidey/whodb · 上手攻略
- 仓库：clidey/whodb
- 链接：https://github.com/clidey/whodb
- 分类：skill
- 作者：Tom
- 更新：2026-08-10
这是什么
WhoDB 是一个浏览器端数据库工作空间，支持探索数据库表结构、编辑数据、运行查询、理解 schema 关系图。它用 Docker 一行命令启动、自托管免费（Apache 2.0）、也提供桌面 App 和终端 CLI。对 AI 编程场景，它还内置了 Ollama / OpenAI / Anthropic / LM Studio 的自然语言查询能力——用英文提问，自动生成 SQL 查询。
核心定位：极简化的浏览器端数据库 GUI，适合自托管和轻量协作。
解决什么问题
主流数据库 GUI（TablePlus、DBeaver、DataGrip）的痛点：
| 痛点 | WhoDB 解法 |
|---|---|
| 重量级安装、配置复杂 | Docker 一行启动，浏览器访问 |
| 团队成员需要安装才能看数据 | 共享 URL，浏览器打开即用 |
| 不支持图表/可视化 | 内置 schema 关系图 + 思维导图 |
| 不支持自然语言查询 | 接入 Ollama/OpenAI/Anthropic 等 LLM 用英文问数据 |
| 缺乏协作功能（商业版才有） | WhoDB Platform 商业版提供 SSO / 审计日志 / 共享项目 |
快速安装
最简启动（Docker）
docker run --rm -it -p 8080:8080 clidey/whodb
# 启动后浏览器打开 http://localhost:8080
⚠️ 容器删除后登录会话会失效，详见下文加密密钥配置。
持久化会话（推荐）
# 1. 生成加密密钥
openssl rand -hex 32
# 输出类似：a3f8b2c1d4e5f678...（64字符）
# 2. 持久化启动
docker run -it -p 8080:8080 \
-v whodb-data:/data \
-e WHODB_ENCRYPTION_KEY=上面生成的64字符密钥 \
clidey/whodb
⚠️ 密钥改变会使已有会话失效；通过 HTTPS 反向代理访问时需额外设置 WHODB_SECURE=true。
桌面 App（macOS / Windows / Linux Snap）
# macOS App Store
# https://apps.apple.com/app/whodb/id6754566536
# Windows Microsoft Store
# https://apps.microsoft.com/detail/9pftx5bv4ds6
# Linux Snap
sudo snap install whodb
CLI（macOS / Linux）
# 方式一：官方安装脚本
curl -fsSL https://raw.githubusercontent.com/clidey/whodb/main/cli/install/install.sh | bash
# 方式二：npm
npm install -g @clidey/whodb-cli
# 打开终端 UI
whodb-cli
# 启动 MCP Server（供 AI 工具调用）
whodb-cli mcp serve
核心用法
连接数据库
启动后浏览器访问 http://localhost:8080，在连接界面选择数据库类型，填写连接信息。
WhoDB Community 支持的数据库：
| 分类 | 数据库 |
|---|---|
| PostgreSQL 系 | PostgreSQL、CockroachDB、YugabyteDB、QuestDB |
| MySQL 系 | MySQL、MariaDB、TiDB |
| 文件型 | SQLite、DuckDB |
| 文档型 | MongoDB、FerretDB |
| KV 存储 | Redis、Valkey、Dragonfly |
| 搜索 | Elasticsearch、OpenSearch |
| 列式/分析 | ClickHouse、Memcached |
⚠️ 支持的数据库类型因连接器实现差异而不同，具体功能以连接界面显示为准。
Schema 可视化
连接后自动生成表结构关系图，鼠标悬停表名查看列信息，拖拽节点查看表间外键关系。
数据编辑（电子表格风格）
在数据视图中支持：排序、筛选、分页、内联编辑（双击单元格直接改值）。修改后自动生成 UPDATE 语句，可预览并确认执行。
Scratchpad 查询
内置多单元格查询工作台：每个查询单元格独立运行、结果与查询语句并排显示、自动补全、历史记录。
AI 自然语言查询
无需配置即可体验：
# 在 WhoDB UI 中打开 Chat 面板
# Add Provider → 选择 OpenAI / Anthropic / Gemini → 填入 API Key
# 局部选项（无需配置，Whodb 自动查找）：
# - Ollama：默认 localhost:11434（Docker/WSL 环境自动调整）
# - LM Studio：默认 localhost:1234/v1
在 Chat 面板用英文提问"Who has placed the most orders in the last month?"，WhoDB 自动生成 SQL、执行、返回结果。
环境变量预配置示例（Docker 部署时由管理员设置）：
# 预配置 OpenAI
WHODB_OPENAI_API_KEY=sk-...
WHODB_OPENAI_BASE_URL=https://api.openai.com/v1
# 预配置 Anthropic
WHODB_ANTHROPIC_API_KEY=sk-ant-...
# 预配置 Ollama（修改默认地址）
WHODB_OLLAMA_HOST=192.168.1.100
WHODB_OLLAMA_PORT=11434
# 预配置 OpenAI 兼容服务商
WHODB_AI_GENERIC__BASE_URL=https://your-endpoint.com/v1
WHODB_AI_GENERIC__API_KEY=your-key
MCP Server（CLI 模式，供 AI 工具调用）
# 启动 MCP Server
whodb-cli mcp serve
# AI 工具（如 Claude Code / Codex）可通过 MCP 协议调用数据库查询
⚠️ MCP Server 连接信息（端口、认证方式）以 whodb-cli mcp serve 启动输出为准，原文未提供默认端口号，建议运行时确认。
数据导入导出
支持 CSV 导入、查询结果导出（CSV/JSON）、Mock 数据生成（供开发和测试使用）。
典型适用场景
- 本地数据库快速探索：不需要安装重型客户端，Dockcer 启动后浏览器看数据
- 团队数据共享：生成链接分享数据库视图，队友无需安装任何软件
- Schema 文档生成：用关系图 + 截图快速记录数据库结构
- AI Agent 数据查询：用 MCP Server 让 AI 工具通过自然语言查询数据库
- 开发/测试环境：Mock 数据生成功能快速造测试数据集
- 多数据库类型切换：同时管理 PostgreSQL + MongoDB + Redis，无需切换工具
坑与注意
- Docker 容器删除后会话失效：不使用持久化卷时，容器重建后所有连接配置和登录会话丢失。使用
-v whodb-data:/data持久化卷 + 加密密钥是生产环境推荐做法。 - 数据库支持不均等：PostgreSQL 功能最完整；ClickHouse、Memcached 等支持的功能较少，具体以 UI 连接界面显示为准。
- AI 查询依赖外部 LLM：本地 Ollama 需要提前安装并启动；云端 API Key 费用由用户自行承担。
- WhoDB Community ≠ WhoDB Platform：前者是 Apache 2.0 开源版；后者是商业版，提供 SSO、审计日志、共享项目等企业功能。
- Ollama / LM Studio 自动检测：默认检测 localhost:11434 和 localhost:1234/v1，如果服务在其他地址需要显式设置
WHODB_OLLAMA_HOST等环境变量。 - MCP Server 默认端口未公开文档：建议运行
whodb-cli mcp serve后查看输出获取实际端口，不建议假设固定端口。 - HTTPS 反向代理：生产环境通过 Nginx/Caddy 等代理时需设置
WHODB_SECURE=true，否则浏览器可能拒绝发送 Cookie。
与同类对比
| 工具 | 部署方式 | 数据库覆盖 | AI 查询 | 许可证 | 适合场景 |
|---|---|---|---|---|---|
| WhoDB | Docker / App / CLI | 12+ 种 | ✅ Ollama / OpenAI / Anthropic | Apache 2.0 | 轻量自托管、团队共享 |
| TablePlus | 桌面 App | 主流数据库 | ❌ | 商业 | 个人单数据库深度操作 |
| DBeaver | 桌面 App | 几乎全覆盖 | ⚠️ 插件支持 | CE/商业 | 企业、多数据库管理 |
| phpMyAdmin | Web (PHP) | MySQL/MariaDB | ❌ | GPL | LAMP 环境已有 PHP |
| Adminer | 单 PHP 文件 | MySQL/PG/SQLite | ❌ | Apache 2.0 | 极简单文件需求 |
| SQLite Browser | 桌面 App | SQLite | ❌ | MPL 2.0 | SQLite 专项 |
| Supabase | 云服务 | PostgreSQL | ✅ 内置 | 商业 | 需要云端托管 |
如果你需要免费、轻量、浏览器访问、多数据库支持，WhoDB 是 Docker 环境下的最优选择；如果你需要企业级协作和审计，WhoDB Platform 商业版或 DBeaver 商业版更合适。
一句话推荐结论
需要一个一行命令启动、浏览器打开就能探索数据库的工具？WhoDB Community 用 Docker
8080:8080装完即用，支持 12+ 种数据库加 AI 自然语言查询，开发团队共享数据视图零配置，Apache 2.0 免费自托管。
README 获取于 2026-08-10；未 clone 或运行代码；MCP Server 默认端口以实际运行输出为准；AI benchmark 数字原文未提供。