LibreDB Studio
面向云原生团队的现代化、AI 驱动的开源 SQL IDE。
快速开始 •
在线体验 •
安装选项 •
部署你自己的实例
## 快速开始
一行命令即可运行完整的 SQL IDE —— 无需克隆，无需构建：
```
# Docker（推荐）
docker run -d -p 3000:3000 ghcr.io/libredb/libredb-studio:latest
# 或使用 Node.js 20.9+（无 Docker）
npx @libredb/studio
```
然后打开 **http://localhost:3000** —— 首次运行时，管理员密码会输出到日志中（零配置）。
## 在线体验
| 测试 | URL | 凭证 |
|------|-----|-------------|
| **公开测试** | [app.libredb.org](https://app.libredb.org) | SSO |
测试实例通过[预设连接](#seed-connections-pre-configured-databases)提供了一个预配置的 PostgreSQL 数据库。无需任何设置！
## 概述
**LibreDB Studio** 是一个轻量级、高性能且安全的基于 Web 的 SQL 编辑器，旨在弥合重量级桌面应用程序（如 DataGrip/DBeaver）与简易 CLI 工具之间的差距。它秉承“移动优先，始终专业”的理念，赋能工程团队在任何地方管理数据库——从 4K 显示器到移动屏幕。
### 为什么选择 LibreDB Studio？
- **零安装**：在浏览器或私有网络中运行专业的 SQL IDE。
- **多平台**：在 **Web**、**移动端** 和 **Windows**（原生 zip、winget、Chocolatey）上提供原生般的体验。
- **AI 原生**：提供多模型支持（Gemini、OpenAI 或本地 LLM）以实现 NL2SQL。
- **DevOps 就绪**：针对 Kubernetes 编排和 Docker 环境进行了优化。
- **企业级**：内置 RBAC、SSO (OIDC)、查询审计和实时健康监控。
Connect to PostgreSQL, MySQL, Oracle, SQL Server, MongoDB, Redis, or SQLite with SSL/TLS and SSH Tunnel support.
[](https://deepwiki.com/libredb/libredb-studio)
## 核心功能
### 专业 SQL IDE
- **Monaco 引擎**：由与 VS Code 相同的核心提供支持。
- **智能自动补全**：提供感知 schema 的表、列和 SQL 关键字建议。
- **多标签工作区**：以独立的执行状态处理并行任务。
- **可视化 EXPLAIN**：通过图形化执行计划来识别性能瓶颈。
- **交互式 ER 图**：包含真实外键边、基数标签、MiniMap 导航、表搜索/过滤、紧凑模式以及 PNG/SVG 导出的可视化 schema 图。由 ELK.js 提供自动分层布局。
- **Schema Diff 与迁移**：并排比较 schema 快照或跨连接 schema。带有颜色标记的 diff 视图（新增/删除/修改），可为 PostgreSQL、MySQL、SQLite、Oracle 和 SQL Server 自动生成迁移 SQL。
- **快照时间轴**：schema 快照的可视化横向时间轴。点击任意两点即可立即比较并追踪 schema 随时间的演变。
Visual schema explorer with interactive ER diagrams powered by ReactFlow.
### 多模型 AI Copilot
- **通用 LLM 支持**：默认为 Gemini 2.5 Flash，但也支持 OpenAI、Claude 或**本地 LLM**（Ollama/LM Studio）。
- **NL2SQL**：利用感知 schema 的上下文，从自然语言生成复杂查询。
- **查询安全分析**：在执行前，利用 AI 评估破坏性查询（DELETE、DROP、TRUNCATE）的风险。
- **AI 查询解释器**：将 EXPLAIN 计划翻译成通俗易懂的语言，并提供优化建议。
- **AI 查询自动驾驶**：自动分析慢查询，并提供可操作的索引和重写建议。
- **Schema 感知**：AI 能理解你特定的数据库结构，实现精准无误。
- **即插即用**：开箱即用，无需复杂的配置。
Ask questions in plain English and get executable SQL queries instantly.
### 专业数据管理
- **通用数据网格**：虚拟化渲染（TanStack），支持数百万行数据。
- **内联编辑**：双击可直接在网格中更新值。
- **列过滤**：对查询结果进行逐列文本过滤，实现即时数据探索。
- **交互式数据透视表**：客户端透视，提供 5 种聚合函数（COUNT、SUM、AVG、MIN、MAX）并支持生成 SQL。
- **专家级导出工具**：即时导出 CSV 和 JSON 用于生成报告。
### 高级数据可视化
- **8 种图表类型**：由 Recharts 提供支持的柱状图、折线图、饼图、面积图、散点图、直方图、堆叠柱状图和堆叠面积图。
- **数据聚合**：支持 SUM、AVG、COUNT、MIN、MAX 聚合函数的 Group-by 分组。支持按小时、天、周、月或年进行日期分组。
- **图表持久化**：保存图表配置并立即重新加载。管理已保存图表的库。
- **图表仪表板**：在底部面板中以网格视图展示所有已保存的图表，方便一目了然地查看数据概览。
### 显示脱敏（预览版）
- **客户端显示层**：在浏览器 UI 中掩码敏感值——适用于屏幕共享、演示以及减少屏幕上意外的敏感信息暴露。**非服务器端强制执行**；对于已认证的用户，查询 API 的响应仍包含完整值。
- **列名模式匹配**：10 种内置模式（电子邮件、电话、信用卡、SSN、密码、IP、日期、财务等）通过正则表达式匹配**结果列标题**。在输出名称匹配时生效（例如 `SELECT salary`）。别名（`salary AS x`）和聚合函数（`SUM(salary)`）目前不会被脱敏。
- **可配置规则**：通过管理面板添加、编辑、启用/禁用脱敏模式。支持使用正则表达式的自定义模式。设置按浏览器存储在 localStorage 中。
- **RBAC UI 控制**：普通用户角色无法在 UI 中切换或显示被脱敏的单元格。管理员角色可以切换脱敏状态，并临时显示单个单元格（10秒自动隐藏）。
- **导出与剪贴板**：当 UI 中激活脱敏功能时，CSV、JSON 和 SQL INSERT 导出将使用脱敏后的显示值。这不会阻止通过 API、浏览器开发者工具或管理员显示功能访问原始数据。
- **UI 覆盖范围**：网格、移动端卡片/表格视图、行详情表以及剪贴板复制均会遵循当前激活的显示脱敏规则。
### 分析师与开发者工具
- **AI 数据剖析器**：一键表剖析，提供列统计信息（空值百分比、基数、最小/最大值、样本值）以及 AI 生成的叙述性摘要。
- **ORM 代码生成器**：从实时表 schema 生成 TypeScript 接口、Zod schemas、Prisma 模型、Go 结构体、Python dataclasses 和 Java POJOs。
- **测试数据生成器**：具备感知 schema 能力的假数据生成，包含 30 多种语义列推断（电子邮件、电话、姓名、地址等）。生成 INSERT 语句或 MongoDB insertMany JSON。
- **数据库文档**：从实时 schema 自动生成可搜索的数据字典，提供 AI 驱动的文档说明并支持 Markdown 导出。
One-click column profiling: null %, cardinality, min/max, and sample values for 300K+ rows.
Generate TypeScript interfaces, Prisma models, Go structs, and more from live schemas.
### 身份验证与 SSO
- **双重认证模式**：本地电子邮件/密码登录或 OpenID Connect (OIDC) 单点登录——可通过环境变量切换。
- **供应商无关的 OIDC**：兼容任何符合 OIDC 标准的提供商——Auth0、Keycloak、Okta、Azure AD、Zitadel、Google 等。
- **PKCE 安全性**：使用带有代码交换证明密钥（S256）的授权码流程，确保身份验证安全。
- **自动角色映射**：可配置的基于声明的角色映射，支持嵌套声明的点表示法（例如 `realm_access.roles`）。
- **提供商登出**：登出时会同时清除本地 JWT 会话和身份提供商会话。
### DBA 维护工具包（仅限管理员）
- **实时监控仪表板**：包含 7 个标签页的监控视图：概览、性能、查询、会话、表、存储和连接池视图。
- **时间序列趋势图**：实时指标趋势（连接数、缓存命中率、缓冲池、死锁），带有自动刷新的环形缓冲区历史记录。
- **可配置的自动刷新**：支持 5 秒到 60 秒的轮询间隔，并提供播放/暂停控制。
- **阈值告警**：针对缓存命中率、连接使用率、死锁和缓冲池利用率提供带有颜色编码（健康/警告/严重）的健康指标。
- **连接池统计**：实时显示总数/活跃/空闲/等待的连接池指标，并带有利用率进度条。
- **一键维护**：根据数据库引擎触发 `VACUUM`、`ANALYZE`、`REINDEX`、`UPDATE STATISTICS`、`DBCC CHECKDB` 和 `ALTER INDEX REBUILD`。
- **审计追踪**：记录整个组织内执行的每一次查询的完整历史记录。
## 支持的数据库
| 数据库 | 驱动 | 功能 |
| :--- | :--- | :--- |
| **PostgreSQL** | `pg` | 完整的 SQL IDE、EXPLAIN 计划、事务、查询取消（`pg_cancel_backend`）、SSL/TLS、SSH 隧道 |
| **MySQL** | `mysql2` | 完整的 SQL IDE、EXPLAIN 计划、事务、查询取消（`KILL QUERY`）、SSL/TLS、SSH 隧道 |
| **Oracle** | `oracledb` (Thin 模式) | 完整的 SQL IDE、`FETCH FIRST N ROWS` 分页、`V$` 监控视图、`ANALYZE TABLE`、`ALTER INDEX REBUILD`、事务 |
| **SQL Server** | `mssql` (tedious) | 完整的 SQL IDE、`TOP N` / `OFFSET FETCH` 分页、`sys.dm_*` DMVs、`UPDATE STATISTICS`、`DBCC CHECKDB`、事务、Azure SQL 自动检测 |
| **SQLite** | `bun:sqlite` / `node:sqlite` (运行时自动选择) | 完整的 SQL IDE、基于文件或内存中的数据库（服务器本地文件） |
| **MongoDB** | `mongodb` | JSON 查询编辑器、集合操作（find、aggregate、insert、update、delete） |
| **Redis** | `ioredis` | 命令编辑器、键浏览器、基于 INFO 的监控 |
## 技术栈
| 组件 | 技术 | 目标平台 |
| :--- | :--- | :--- |
| **框架** | Next.js 16 (App Router), React 19 | Web、移动端 |
| **UI 引擎** | Tailwind CSS 4, Radix UI, [shadcn/ui](https://ui.shadcn.com/) | Web、移动端 |
| **主题设置** | CSS Variables + `@theme inline` ([指南](docs/ui/theming.md)) | Web、移动端 |
| **编辑器** | Monaco Editor (VS Code 引擎) | Web |
| **AI** | 多模型（Gemini、OpenAI、Ollama、自定义） | Web、移动端 |
| **身份验证** | JWT (`jose`) + OIDC (`openid-client`)、PKCE、角色映射 | Web、移动端 |
| **数据库** | PostgreSQL、MySQL、Oracle、SQL Server、SQLite、MongoDB、Redis | Web、移动端 |
| **图表** | Recharts（柱状图、折线图、饼图、面积图、散点图、直方图、堆叠图） | Web、移动端 |
| **ER 图 (ERD)** | React Flow、ELK.js（自动布局） | Web |
| **状态/网格** | TanStack Table & Virtual | Web、移动端 |
| **部署** | Docker、Kubernetes | Web |
## 入门指南
### 安装
| 渠道 | 命令 | 说明 |
| :--- | :--- | :--- |
| **Docker** | `docker run -d -p 3000:3000 ghcr.io/libredb/libredb-studio:latest` | 零配置：首次运行时管理员密码会输出到日志中 |
| **Helm (Kubernetes)** | `helm install libredb oci://ghcr.io/libredb/charts/libredb-studio` | 零配置：首次运行的管理员凭证会输出到 pod 日志中 |
| **npx** | `npx @libredb/studio` | Linux/macOS/Windows，Node 20.9+（推荐使用 Node 24 LTS）；下载已发布的服务归档文件 |
| **Homebrew** | `brew trust libredb/tap && brew install libredb/tap/libredb-studio` | 需要运行一次 `brew trust`（Homebrew 6+；若版本未知请运行 `brew update`） |
| **deb / rpm** | `sudo dpkg -i libredb-studio_
_amd64.deb` | 附在每个 GitHub Release 中；包含 systemd 服务 |
| **Snap** | `sudo snap install libredb-studio` | 零配置：首次运行时管理员密码会输出到 `sudo snap logs libredb-studio` —— [Snap Store 列表](https://snapcraft.io/libredb-studio) |
| **winget (Windows)** | `winget install LibreDB.Studio` | 便携版 zip，内置 Node.js 运行时；运行 `libredb-studio` —— 支持 CI 自动化；首个社区发布列表正在审核中（[#114](https://github.com/libredb/libredb-studio/issues/114)） |
| **Chocolatey (Windows)** | `choco install libredb-studio` | 同样的独立 zip —— 支持 CI 推送；首次推送正在等待社区审核（[#114](https://github.com/libredb/libredb-studio/issues/114)） |
| **Portable zip (Windows)** | `.\libredb-studio.exe` | 从 [GitHub Releases](https://github.com/libredb/libredb-studio/releases) 下载；内置 Node 运行时，无需包管理器 |
### 快速开始（Docker）
一行命令即可运行 LibreDB Studio —— 无需克隆，无需安装，无需构建：
```
docker run -d \
--name libredb-studio \
-p 3000:3000 \
-e ADMIN_EMAIL=admin@libredb.org \
-e ADMIN_PASSWORD=LibreDB.2026 \
-e USER_EMAIL=user@libredb.org \
-e USER_PASSWORD=LibreDB.2026 \
-e JWT_SECRET=change-me-to-a-random-32-char-string \
ghcr.io/libredb/libredb-studio:latest
```
打开 [http://localhost:3000](http://localhost:3000) 并使用 `admin@libredb.org` / `LibreDB.2026` 登录。
### 零配置首次运行
在不配置 `JWT_SECRET` / `ADMIN_PASSWORD` 的情况下启动服务器即可直接开箱即用：
缺失的值会在首次启动时生成，存储在 `/auth-bootstrap.json`
（文件模式 0600）中，并且管理员密码会输出一次到服务器日志中。显式
设置的环境变量始终具有最高优先级。设置 `AUTH_BOOTSTRAP=off` 可要求
进行显式配置（推荐用于生产环境部署）。
### Linux 软件包（.deb / .rpm）
适用于 Debian/Ubuntu 和 RHEL/Fedora（amd64 和 arm64）的原生软件包附在每一个
[GitHub release](https://github.com/libredb/libredb-studio/releases) 中。它们打包了独立
服务器以及一个专用的 Node.js 运行时（无需安装其他任何内容），并注册了一个 systemd 服务：
```
# Debian / Ubuntu
sudo dpkg -i libredb-studio__amd64.deb
# RHEL / Fedora / Rocky
sudo rpm -i libredb-studio-.x86_64.rpm
# 启动服务（首次运行会将生成的管理员密码打印到 journal）
sudo systemctl enable --now libredb-studio
journalctl -u libredb-studio
```
配置文件位于 `/etc/libredb-studio/env`（由 unit 加载；请参阅那里安装的带有注释的模板），状态文件（SQLite 存储和生成的凭证）位于 `/var/lib/libredb-studio`。
也可以在不使用 systemd 的情况下直接运行 `libredb-studio` 命令。有关此安装方式及
其他所有渠道的完整详细信息：请参阅 [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md)。
### 前置条件
- [Bun](https://bun.sh/)（推荐）或 Node.js 24+
- 一个用于查询的目标数据库（PostgreSQL、MySQL、Oracle、SQL Server、SQLite、MongoDB 或 Redis）
### 快速开始（本地）
1. **克隆并安装**
git clone https://github.com/libredb/libredb-studio.git
cd libredb-studio
bun install
```
2. **Configure Environment**
Create a `.env.local` file:
```env
# Authentication (email/password)
ADMIN_EMAIL=admin@libredb.org
ADMIN_PASSWORD=your_admin_password
USER_EMAIL=user@libredb.org
USER_PASSWORD=your_user_password
JWT_SECRET=your_32_character_random_string
# Optional: OIDC Single Sign-On (Auth0, Keycloak, Okta, Azure AD, etc.)
# NEXT_PUBLIC_AUTH_PROVIDER=oidc
# OIDC_ISSUER=https://your-provider.com
# OIDC_CLIENT_ID=your_client_id
# OIDC_CLIENT_SECRET=your_client_secret
# LLM Configuration
LLM_PROVIDER=gemini # options: gemini, openai, ollama, custom
LLM_API_KEY=your_api_key
LLM_MODEL=gemini-2.5-flash
LLM_API_URL=http://localhost:11434/v1 # optional for local LLMs (Ollama)
```
```
3. **启动**
bun dev
打开 [http://localhost:3000](http://localhost:3000)
## 开发用数据库
需要用于测试的数据库？我们为所有支持的引擎提供了开箱即用的容器：
```
# 启动所有开发数据库（PostgreSQL、MySQL、MongoDB、SQL Server、Oracle）
docker compose -f database-compose.yml up -d
# 或启动特定数据库
docker compose -f database-compose.yml up -d postgres
docker compose -f database-compose.yml up -d mssql
docker compose -f database-compose.yml up -d oracle
# 启动带有示例电商数据的 PostgreSQL
docker compose -f docker/postgres.yml up -d
# 停止（保留数据）
docker compose -f database-compose.yml down
# 停止并删除所有数据
docker compose -f database-compose.yml down -v
```
### 连接详情
| 数据库 | 主机 | 端口 | 用户名 | 密码 | 数据库/服务 |
|----------|------|------|------|----------|-----------------|
| **PostgreSQL** | localhost | 5432 | postgres | postgres | postgres |
| **MySQL** | localhost | 3306 | root | root | mysql |
| **SQL Server** | localhost | 1433 | sa | Password123! | master |
| **Oracle** | localhost | 1521 | system | Password123! | freepdb1 |
| **MongoDB** | localhost | 27017 | admin | admin | — |
### PostgreSQL 示例数据
`docker/postgres.yml` 设置包含了一个预加载的电子商务 schema：
| 功能 | 描述 |
|---------|-------------|
| **PostgreSQL 18** | 官方镜像，包含 `pg_stat_statements` |
| **pg_stat_statements** | 预先启用，用于查询监控 |
| **示例 Schema** | 电子商务数据库（app schema） |
| **示例数据** | 25 个客户，30 件产品，100 个订单 |
| **视图** | 订单摘要、产品销量、客户 LTV |
示例表：`app.customers`、`app.products`、`app.orders`、`app.order_items`、`app.product_reviews`、`app.categories`、`app.coupons`、`app.audit_log`
## 测试
LibreDB Studio 拥有全面的测试套件，包含跨越 6 个层级的 **3,000 多个单元/集成测试**和 **32 个 E2E 测试**，在 SonarCloud 上测得的**行覆盖率高达 90% 以上**。
### 快速命令
```
# 运行所有测试（unit + API + integration + hooks + components）
bun run test
# 按层运行
bun run test:unit # Pure function tests (1,600+ cases)
bun run test:api # API route handler tests (270+ cases)
bun run test:integration # Database provider tests (340+ cases)
bun run test:hooks # React hook tests (250+ cases)
bun run test:components # Component tests with mock isolation (570+ cases)
# E2E 测试（需要 build）
bun run test:e2e # Playwright browser tests (32 cases)
# 覆盖率报告（lcov）
bun run test:coverage
```
### 测试架构
| 层级 | 目录 | 运行器 | 测试数 | 覆盖范围 |
|-------|-----------|--------|-------|----------------|
| **单元测试** | `tests/unit/` | `bun:test` | ~1,609 | 纯函数：SQL 解析器、连接字符串、数据脱敏、查询限制器、schema diff、错误类、数据库图标、演示查询 |
| **API 测试** | `tests/api/` | `bun:test` | ~279 | 路由处理器：身份验证、查询、事务、维护、AI 接口、中间件 |
| **集成测试** | `tests/integration/` | `bun:test` | ~346 | 数据库提供商：PostgreSQL、MySQL、SQLite、MongoDB、Redis、Oracle、MSSQL|
| **Hooks 测试** | `tests/hooks/` | `bun:test` | ~251 | React hooks：身份验证、连接、标签页、查询执行、事务、内联编辑、AI 聊天、监控 |
| **组件测试** | `tests/components/` | `bun:test` + happy-dom | ~570 | UI 组件：Studio、侧边栏、查询编辑器、结果网格、管理员仪表板、图表、ER 图 |
| **E2E 测试** | `e2e/` | Playwright | ~32 | 完整的浏览器流程：登录、连接、查询执行、标签页、导出、管理后台 |
### 关键细节
- **测试运行器**：`bun:test`（内置，兼容 Jest 的 API），并使用 `happy-dom` 提供 DOM 环境
- **组件隔离**：组件测试通过 `tests/run-components.sh` 在 6 个独立的组中运行，以防止 `mock.module()` 发生交叉污染
- **E2E**：使用 Playwright 和 Chromium，针对生产构建版本运行（`bun run build && bun start`）
- **CI**：GitHub Actions 会运行 lint + 类型检查 + 构建、带覆盖率的单元/集成测试、E2E 测试以及 SonarCloud 分析
- **覆盖率**：`bun test --coverage` 生成 lcov 报告，用于与 SonarCloud 集成
## 一键部署
只需在 DigitalOcean、Koyeb、Render、Railway、CapRover 或 Dokploy 上一键点击，即可部署你自己的 LibreDB Studio 实例：
[](https://app.koyeb.com/deploy?name=libredb-studio&type=docker&image=ghcr.io%2Flibredb%2Flibredb-studio%3Alatest&instance_type=free®ions=fra&instances_min=0&autoscaling_sleep_idle_delay=3900&env%5BADMIN_EMAIL%5D=admin%40libredb.org&env%5BADMIN_PASSWORD%5D=LibreDB.2026&env%5BJWT_SECRET%5D=your_secure_pass%3D&env%5BLLM_API_KEY%5D=your_GEMINI_API_KEY&env%5BLLM_MODEL%5D=gemini-2.5-flash&env%5BLLM_PROVIDER%5D=gemini&env%5BNEXT_PUBLIC_AUTH_PROVIDER%5D=local&env%5BSTORAGE_PROVIDER%5D=local&env%5BUSER_EMAIL%5D=user%40libredb.org&env%5BUSER_PASSWORD%5D=LibreDB.2026&ports=3000%3Bhttp%3B%2F&hc_protocol%5B3000%5D=tcp&hc_grace_period%5B3000%5D=5&hc_interval%5B3000%5D=30&hc_restart_limit%5B3000%5D=3&hc_timeout%5B3000%5D=5&hc_path%5B3000%5D=%2F&hc_method%5B3000%5D=get)
[](https://render.com/deploy?repo=https://github.com/libredb/libredb-studio)
[](https://railway.com/deploy/libredb-studio?referralCode=libredb&utm_medium=integration&utm_source=template&utm_campaign=generic)
[](https://marketplace.digitalocean.com/apps/libredb-studio)
[](https://github.com/caprover/one-click-apps/blob/master/public/v4/apps/libredb-studio.yml)
[](docs/FLY.md)
[](https://templates.dokploy.com)
### 环境变量
| 变量 | 必填 | 描述 |
|----------|----------|-------------|
| `ADMIN_EMAIL` | ❌ | 管理员邮箱（默认：`admin@libredb.org`） |
| `ADMIN_PASSWORD` | ❌ | 管理员密码；除非设置了 `AUTH_BOOTSTRAP=off`，否则在首次运行时自动生成 |
| `USER_EMAIL` | ❌ | 可选的用户账号邮箱（默认：`user@libredb.org`） |
| `USER_PASSWORD` | ❌ | 可选；仅在设置后才会创建低权限用户账号 |
| `JWT_SECRET` | ❌ | JWT 密钥（至少 32 个字符）；除非设置了 `AUTH_BOOTSTRAP=off`，否则在首次运行时自动生成 |
| `AUTH_BOOTSTRAP` | ❌ | 设置为 `off` 可禁用零配置生成（严格模式；推荐用于生产环境） |
| `NEXT_PUBLIC_AUTH_PROVIDER` | ❌ | `local`（默认）或用于 SSO 的 `oidc` |
| `OIDC_ISSUER` | ❌ | OIDC 签发者 URL（当选择 `oidc` 时必填） |
| `OIDC_CLIENT_ID` | ❌ | OIDC 客户端 ID（当选择 `oidc` 时必填） |
| `OIDC_CLIENT_SECRET` | ❌ | OIDC 客户端密钥（当选择 `oidc` 时必填） |
| `OIDC_ADMIN_ROLES` | ❌ | 以逗号分隔的管理员角色值（默认：`admin`） |
| `OIDC_ROLE_CLAIM` | ❌ | 角色的声明路径（例如 `realm_access.roles`） |
| `OIDC_SCOPE` | ❌ | OIDC 范围（默认：`openid profile email`） |
| `LLM_PROVIDER` | ❌ | AI 提供商：`gemini`、`openai`、`ollama` |
| `LLM_API_KEY` | ❌ | 用于 AI 功能的 API key |
| `LLM_MODEL` | ❌ | 模型名称（例如 `gemini-2.5-flash`） |
| `STORAGE_PROVIDER` | ❌ | 存储提供商：`local`（默认）、`sqlite` 或 `postgres` |
| `STORAGE_POSTGRES_URL` | ❌ | PostgreSQL 连接 URL（当 `STORAGE_PROVIDER=postgres` 时必填） |
| `SEED_CONFIG_PATH` | ❌ | 用于预设连接的 YAML 配置文件路径（参见[预设连接](#seed-connections-pre-configured-databases)） |
| `SEED_CACHE_TTL_MS` | ❌ | 预设配置的缓存 TTL（以毫秒为单位，默认：`60000`） |
## 部署
### Koyeb
1. **ork 本仓库**
2. **连接到 Koyeb**：[app.koyeb.com](https://app.koyeb.com) → New → Blueprint
3. **选择你 Fork 的仓库**，Koyeb 将自动识别 `koyeb.yaml`
4. 在 Koyeb 仪表板中**设置环境变量**：
5. **部署！**
### Railway
LibreDB Studio 作为一个一键 [Railway](https://railway.com) 模板提供。
请参阅 [`deploy/railway/`](deploy/railway/) 了解模板定义、安装
说明和发布检查清单。该模板在 Railway 数据卷上
运行预构建的 `ghcr.io/libredb/libredb-studio` 镜像以实现 SQLite 持久化。
注意：Docker 镜像模板需要在每次发布时手动进行版本更新（与 CapRover 相同）。
### CapRover
LibreDB Studio 已发布在官方的 [CapRover 一键应用](https://github.com/caprover/one-click-apps/blob/master/public/v4/apps/libredb-studio.yml) 目录中：
1. **打开你的 CapRover 仪表板** → **Apps → One-Click Apps/Databases**
2. **搜索** **LibreDB Studio**
3. **填写变量**（管理员/用户凭证、`JWT_SECRET`、可选的 AI/存储设置）
4. **部署！**
该应用运行预构建的 `ghcr.io/libredb/libredb-studio` 镜像。与 Railway 一样，Docker 镜像模板需要在每次发布时手动更新版本。
### Kubero
LibreDB Studio 已在官方的
[Kubero 模板目录](https://www.kubero.dev/templates)（一个“适用于 Kubernetes 的 Heroku 替代方案”
自托管平台）中列出。在你的 Kubero 仪表板中，浏览
**Templates**，搜索 **LibreDB Studio**，填写凭证 / `JWT_SECRET`，
然后部署。该模板运行预构建的 `ghcr.io/libredb/libredb-studio` 镜像，
并在位于 `/app/data` 的 5Gi 数据卷上实现 SQLite 持久化。请参阅
[`deploy/kubero/`](deploy/kubero/) 了解安装及安装后的详细信息。与
Railway 和 CapRover 一样，Docker 镜像模板需要在每次发布时手动更新版本。
### Cosmos
LibreDB Studio 已在官方的
[Cosmos servapp 市场](https://github.com/azukaar/cosmos-servapps-official)
中列出（[Cosmos](https://cosmos-cloud.io) 是一个自托管的服务器管理器和安全
反向代理）。在你的 Cosmos 仪表板中，打开 **Marketplace**，搜索
**LibreDB Studio** 并进行安装。Cosmos 会自动生成凭证
和 `JWT_SECRET`，在 `/app/data` 下配置持久化的 SQLite 数据卷，并
将应用置于受 SmartShield 保护的路由之后。请参阅
[`deploy/cosmos/`](deploy/cosmos/) 了解安装及安装后的详细信息。与
Railway、CapRover 和 Kubero 一样，Docker 镜像模板需要在每次发布时手动更新版本。
### Render（推荐用于云端部署）
LibreDB Studio 包含一个用于一键部署的 `render.yaml` 蓝图：
1. **Fork 本仓库**
2. **连接到 Render**：[dashboard.render.com](https://dashboard.render.com) → New → Blueprint
3. **选择你 Fork 的仓库**，Render 将自动识别 `render.yaml`
4. 在 Render 仪表板中**设置环境变量**：
5. **部署！**
### Docker Compose（自托管）
使用开箱即用的 [`docker-compose.example.yml`](docker-compose.example.yml) —— 它会拉取已发布的镜像（`ghcr.io/libredb/libredb-studio:latest`），因此无需进行源码构建。它记录了每一个支持的环境变量（身份验证、OIDC、存储、LLM、预设连接），其中不常用的选项已被注释掉。
```
# 1. 复制现成可用的 compose 文件
cp docker-compose.example.yml docker-compose.yml
# 2. 创建你的 .env（至少设置 JWT_SECRET / ADMIN_PASSWORD / USER_PASSWORD）
cp .env.example .env
# 3. 启动
docker compose up -d # → http://localhost:3000
```
此文件是平台无关的，可与使用普通 `docker-compose.yml` 的 PaaS 工具（Dokploy、Coolify、Portainer 等）配合使用 —— 只需将它们指向该文件，并将私密信息设置为环境变量即可。
### Kubernetes（Helm Chart）
```
helm repo add libredb https://libredb.org/libredb-studio/
helm install libredb libredb/libredb-studio
# 从 pod 日志中获取生成的管理员凭据
kubectl logs deployment/libredb-libredb-studio | grep -A 4 "generated admin credentials"
```
或通过 OCI registry：
```
helm install libredb oci://ghcr.io/libredb/charts/libredb-studio
```
对于生产环境，请提供你自己的密钥，而不是依赖生成的密钥：
```
helm install libredb libredb/libredb-studio \
--set secrets.jwtSecret=$(openssl rand -base64 32) \
--set secrets.adminPassword=MyAdmin123
```
功能包括：PostgreSQL 子 chart、Ingress/TLS、HPA、PDB、NetworkPolicy 和 ExternalSecrets 支持。完整文档请参见 [charts/libredb-studio/README.md](charts/libredb-studio/README.md)。
### 预设连接（预配置数据库）
通过 YAML 配置文件预配置数据库连接，以便用户在登录后能立即看到它们。非常适合管理员为团队分配数据库的 PaaS/SaaS 部署。
**功能特点：**
- 基于角色的访问控制（`admin`、`user`、`*` 通配符）
- 混合模式：`managed: true`（只读，由管理员控制）或 `managed: false`（用户可编辑的副本）
- 通过 `${ENV_VAR}` 语法注入凭证 —— 永远不会存储在配置文件中
- 热更新：配置更改在 60 秒内生效，无需重启
- 兼容 Docker、docker-compose 和 Kubernetes（Helm）
**1. 创建配置文件**（`seed-connections.yaml`）：
```
version: "1"
defaults:
managed: true
environment: production
connections:
- id: "prod-analytics"
name: "Production Analytics"
type: postgres
host: analytics-db.internal
port: 5432
database: analytics
user: "readonly_user"
password: "${ANALYTICS_DB_PASSWORD}"
roles: ["admin"]
color: "#10B981"
- id: "dev-sandbox"
name: "Dev Sandbox"
type: mysql
host: dev-mysql.internal
port: 3306
database: sandbox
user: "dev_user"
password: "${DEV_DB_PASSWORD}"
roles: ["*"]
managed: false
```
**2. 挂载并配置：**
Docker
```
docker run -v ./seed-connections.yaml:/app/config/seed-connections.yaml:ro \
-e SEED_CONFIG_PATH=/app/config/seed-connections.yaml \
-e ANALYTICS_DB_PASSWORD=secret \
-e DEV_DB_PASSWORD=devsecret \
ghcr.io/libredb/libredb-studio:latest
```
Docker Compose
```
services:
app:
image: ghcr.io/libredb/libredb-studio:latest
volumes:
- ./seed-connections.yaml:/app/config/seed-connections.yaml:ro
environment:
SEED_CONFIG_PATH: /app/config/seed-connections.yaml
ANALYTICS_DB_PASSWORD: ${ANALYTICS_DB_PASSWORD}
DEV_DB_PASSWORD: ${DEV_DB_PASSWORD}
```
Kubernetes (Helm)
```
# values.yaml
seedConnections:
enabled: true
config:
version: "1"
connections:
- id: "prod-analytics"
name: "Production Analytics"
type: postgres
host: analytics-db.internal
password: "${ANALYTICS_DB_PASSWORD}"
roles: ["admin"]
# 通过 K8s Secret 设置凭据：
extraEnvFrom:
- secretRef:
name: seed-db-credentials
```
**配置参考：**
| 字段 | 必填 | 描述 |
|-------|----------|-------------|
| `version` | 是 | 必须为 `"1"` |
| `defaults` | 否 | 合并到所有连接中的默认值 |
| `connections[].id` | 是 | 唯一的 slug（`[a-z0-9-]+`，最长 64 个字符） |
| `connections[].name` | 是 | UI 中的显示名称 |
| `connections[].type` | 是 | `postgres`、`mysql`、`sqlite`、`mongodb`、`redis`、`oracle`、`mssql` |
| `connections[].roles` | 是 | `["*"]`（所有人）、`["admin"]`、`["user"]` 或 `["admin", "user"]` |
| `connections[].managed` | 否 | `true` = 只读（默认），`false` = 用户可编辑的副本 |
| `connections[].password` | 否 | 密钥使用 `${ENV_VAR}` 语法 |
| `connections[].environment` | 否 | `production`、`staging`、`development`、`local`、`other` |
| `connections[].group` | 否 | 侧边栏中的分组标签 |
| `connections[].color` | 否 | 徽章的十六进制颜色代码（例如 `#10B981`） |
**环境变量：**
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SEED_CONFIG_PATH` | `/app/config/seed-connections.yaml` | 配置文件的路径 |
| `SEED_CACHE_TTL_MS` | `60000` | 缓存 TTL，以毫秒为单位（热重载间隔） |
## 路线图
- [x] **阶段 1**：Monaco SQL IDE 和多标签页支持。
- [x] **阶段 2**：多模型 AI（Gemini、OpenAI、Ollama、自定义）集成。
- [x] **阶段 3**：专业数据网格和虚拟化。
- [x] **阶段 4**：多数据库支持（PostgreSQL、MySQL、SQLite、MongoDB、Redis）。
- [x] **阶段 5**：交互式 ER 图（可视化 schema 关系图）。
- [x] **阶段 6**：企业级基础设施（连接测试、SSL/TLS、SSH 隧道、事务控制、查询取消）。
- [x] **阶段 7**：AI 智能（NL2SQL、查询安全分析、AI 索引顾问、多轮对话、查询自动驾驶）。
- [x] **阶段 8**：分析师和开发者工具（数据剖析器、代码生成器、测试数据生成器、数据透视表、列过滤、数据库文档）。
- [x] **阶段 9**：显示脱敏 —— 预览版（列名模式匹配、可配置规则、RBAC UI 控制、客户端导出/剪贴板脱敏）。
- [x] **阶段 10**：高级 ER 图（真实外键边、ELK.js 自动布局、MiniMap、PNG/SVG 导出、紧凑模式、表搜索）。
- [x] **阶段 11**：Schema Diff 与迁移（快照时间轴、跨连接 Diff、为 PostgreSQL、MySQL、SQLite、Oracle 和 SQL Server 自动生成迁移 SQL）。
- [x] **阶段 12**：高级图表（散点图、直方图、堆叠图、聚合、日期分组、图表保存/加载、图表仪表板）。
- [x] **阶段 13**：监控增强（时间序列趋势、阈值告警、连接池统计、可配置轮询）。
- [x] **阶段 14**：企业级数据库支持（通过 oracledb Thin 模式支持 Oracle Database，通过 mssql/tedious 支持 Microsoft SQL Server）。
- [x] **阶段 15**：SSO 集成 —— 供应商无关的 OIDC 身份验证（Auth0、Keycloak、Okta、Azure AD、Zitadel），具备 PKCE、角色映射和提供商登出功能。
- [ ] **阶段 16**：DBA 和监控（锁依赖图、Vacuum 调度程序、Prometheus 导出）。
- [ ] **阶段 17**：企业级协作（用户身份、共享工作区、SAML 2.0）。
- [ ] **阶段 18**：服务器端强制数据脱敏（SQL 输出血缘、部署全局策略、fail-closed API 脱敏、别名/聚合覆盖）。
## 社区与质量
| 资源 | 描述 |
|----------|-------------|
| [DeepWiki](https://deepwiki.com/libredb/libredb-studio) | AI 驱动的文档 —— 始终与代码库保持同步 |
| [SonarCloud](https://sonarcloud.io/project/overview?id=libredb_libredb-studio) | 代码质量、安全性分析和技术债务追踪 |
| [API 文档](docs/API_DOCS.md) | 完整的 REST API 参考 |
| [OIDC SSO](docs/OIDC.md) | SSO 设置（Auth0、Keycloak、Okta、Azure AD、Zitadel、Google）+ 子系统内部原理与安全模型 |
| [主题指南](docs/ui/theming.md) | CSS 主题设置、深色模式和样式自定义 |
| [登录页面](docs/ui/login-page.md) | 登录页面布局、OIDC/本地模式以及设计系统 |
| [编辑器文档](docs/editor/) | SQL 编辑器内部原理 —— 自动补全、性能、查询优化 |
| [架构](docs/ARCHITECTURE.md) | 系统架构和设计模式 |
## 支持
libredb-studio 是免费且开源的。如果它对你或你的团队有所帮助，请考虑
[赞助本项目](https://github.com/sponsors/libredb) —— 你的支持
将用于日常维护、Bug 修复、开发新的数据库提供商以及
开源版本的持续开发。
[](https://github.com/sponsors/libredb)
## 赞助商
_成为 libredb-studio 的第一位赞助商吧！_
## 贡献
我们欢迎社区的贡献！无论是修复 Bug、开发新功能还是改进文档：
1. Fork 本项目。
2. 创建你的功能分支（`git checkout -b feature/AmazingFeature`）。
3. 提交你的更改（`git commit -m 'Add some AmazingFeature'`）。
4. 推送到该分支（`git push origin feature/AmazingFeature`）。
5. 发起一个 Pull Request。
## 许可证
基于 MIT 许可证分发。了解更多信息，请参阅 `LICENSE`。
专为 DBA 和开发者打造。