350 lines
8.0 KiB
Plaintext
350 lines
8.0 KiB
Plaintext
---
|
||
title: Web API 参考
|
||
description: DBX Web 与 Docker UI 使用的内部 HTTP API，包括认证、查询、后台任务、上传和下载边界。
|
||
---
|
||
|
||
<Callout type="warn">这套 API 主要服务于 DBX Web 界面，以及 MCP Web 模式等内部工具。它不是单独对外承诺的集成契约，路由和字段可能随版本调整。做脚本或 Agent 集成时，优先使用 [@dbx-app/cli](/cn/docs/cli) 或 [@dbx-app/mcp-server](/cn/docs/mcp)。</Callout>
|
||
|
||
## 基础地址
|
||
|
||
DBX Web 默认监听 `4224` 端口：
|
||
|
||
```text
|
||
http://localhost:4224
|
||
```
|
||
|
||
如果通过反向代理挂在子路径下，需要设置 `DBX_PUBLIC_BASE_PATH`。例如 `/dbx`：
|
||
|
||
```text
|
||
https://example.com/dbx/api/auth/check
|
||
```
|
||
|
||
所有 API 都位于 `/api` 路径下。
|
||
|
||
## 认证
|
||
|
||
受保护的路由需要名为 `dbx_session` 的会话 Cookie。
|
||
|
||
### 检查认证状态
|
||
|
||
```http
|
||
GET /api/auth/check
|
||
```
|
||
|
||
示例响应：
|
||
|
||
```json
|
||
{
|
||
"authenticated": false,
|
||
"required": true,
|
||
"setup_required": false
|
||
}
|
||
```
|
||
|
||
| 字段 | 含义 |
|
||
| --- | --- |
|
||
| `required` | 已启用密码保护 |
|
||
| `setup_required` | 仍需首次设置密码 |
|
||
| `authenticated` | 当前请求已持有有效会话 |
|
||
|
||
### 首次设置密码
|
||
|
||
```http
|
||
POST /api/auth/setup
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"password": "your-password"
|
||
}
|
||
```
|
||
|
||
### 登录
|
||
|
||
```http
|
||
POST /api/auth/login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"password": "your-password"
|
||
}
|
||
```
|
||
|
||
登录成功后，响应会返回 `Set-Cookie: dbx_session=...`。后续请求带上这个 Cookie 即可。
|
||
|
||
连续 5 次登录失败会触发约 60 秒锁定。会话保存在当前 Web 进程内，进程重启后需要重新登录；Cookie 使用 `HttpOnly` 和 `SameSite=Lax`，路径会跟随 `DBX_PUBLIC_BASE_PATH`。
|
||
|
||
### 退出登录
|
||
|
||
```http
|
||
POST /api/auth/logout
|
||
Cookie: dbx_session=...
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 作用 |
|
||
| --- | --- |
|
||
| `DBX_PASSWORD` | 容器启动时设置初始密码 |
|
||
| `DBX_DISABLE_PASSWORD=1` | 完全关闭密码保护 |
|
||
| `DBX_PORT` | 修改监听端口，默认 `4224` |
|
||
| `DBX_DATA_DIR` | 存放 `dbx.db` 的数据目录 |
|
||
| `DBX_PUBLIC_BASE_PATH` | 在子路径下提供服务，例如 `/dbx` |
|
||
| `DBX_MAX_UPLOAD_MB` | 调整通用请求/上传大小上限，默认 1024 MB |
|
||
| `DBX_AGENT_DIR` | 覆盖 Web 端 Agent/驱动目录，默认位于数据目录下的 `agents` |
|
||
| `DBX_STATIC_DIR` | 覆盖 Web 静态文件目录 |
|
||
|
||
## 请求约定
|
||
|
||
- 字段命名由具体 Rust 请求结构决定，既有 `camelCase`，也有连接配置使用的 `snake_case`；不要对整个 API 套用单一命名规则。
|
||
- `GET` 查询参数通常使用 `snake_case`，例如 `connection_id`，但仍应以当前路由实现为准。
|
||
- 出错时通常返回带 `error` 字段的 JSON 和对应 HTTP 状态码。
|
||
- 导出、导入、数据传输、SQL 文件和 AI 等长任务通常使用“启动请求 + SSE 进度 + 取消/下载”组合，不是一个同步响应。
|
||
|
||
只有数据网格提取器当前提供受测试的局部 OpenAPI 文档：`/api/query/data-grid-extractor-openapi.json`。它不覆盖完整 DBX Web API，也不代表其它路由已经版本化。
|
||
|
||
## 连接相关 API
|
||
|
||
### 列出连接
|
||
|
||
```http
|
||
GET /api/connection/list
|
||
Cookie: dbx_session=...
|
||
```
|
||
|
||
返回已保存的连接配置。密码等敏感信息不会直接出现在返回 JSON 中。
|
||
|
||
### 保存连接
|
||
|
||
```http
|
||
POST /api/connection/save
|
||
Content-Type: application/json
|
||
Cookie: dbx_session=...
|
||
|
||
{
|
||
"configs": [
|
||
{
|
||
"name": "local-mysql",
|
||
"db_type": "mysql",
|
||
"host": "127.0.0.1",
|
||
"port": 3306,
|
||
"username": "root",
|
||
"database": "app"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 测试连接
|
||
|
||
```http
|
||
POST /api/connection/test
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"config": {
|
||
"name": "temp",
|
||
"db_type": "mysql",
|
||
"host": "127.0.0.1",
|
||
"port": 3306,
|
||
"username": "root",
|
||
"database": "app"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 建立连接
|
||
|
||
大多数数据类 API 会要求目标连接先处于已连接状态。
|
||
|
||
```http
|
||
POST /api/connection/connect
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"config": {
|
||
"id": "connection-id",
|
||
"name": "local-mysql",
|
||
"db_type": "mysql",
|
||
"host": "127.0.0.1",
|
||
"port": 3306,
|
||
"username": "root",
|
||
"database": "app"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 健康检查
|
||
|
||
```http
|
||
POST /api/connection/check-health
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"connectionId": "connection-id"
|
||
}
|
||
```
|
||
|
||
## Schema API
|
||
|
||
### 列出表
|
||
|
||
```http
|
||
GET /api/schema/tables?connection_id=CONNECTION_ID&database=app&schema=
|
||
Cookie: dbx_session=...
|
||
```
|
||
|
||
### 列出字段
|
||
|
||
```http
|
||
GET /api/schema/columns?connection_id=CONNECTION_ID&database=app&schema=&table=users
|
||
Cookie: dbx_session=...
|
||
```
|
||
|
||
其他常用 Schema 路由包括：
|
||
|
||
- `/api/schema/databases`
|
||
- `/api/schema/schemas`
|
||
- `/api/schema/indexes`
|
||
- `/api/schema/foreign-keys`
|
||
- `/api/schema/ddl`
|
||
|
||
## SQL 查询 API
|
||
|
||
### 执行单条语句
|
||
|
||
```http
|
||
POST /api/query/execute
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"connectionId": "connection-id",
|
||
"database": "app",
|
||
"sql": "select id, name from users limit 10"
|
||
}
|
||
```
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"columns": ["id", "name"],
|
||
"rows": [[1, "Ada"], [2, "Lin"]]
|
||
}
|
||
```
|
||
|
||
相关路由：
|
||
|
||
| 路由 | 作用 |
|
||
| --- | --- |
|
||
| `/api/query/execute-multi` | 一次请求执行多个结果集 |
|
||
| `/api/query/execute-batch` | 执行语句列表 |
|
||
| `/api/query/cancel` | 取消正在执行的查询 |
|
||
| `/api/query/build-table-select-sql` | 生成表浏览 SQL |
|
||
|
||
## Redis API
|
||
|
||
Redis 浏览和命令执行使用独立路由。
|
||
|
||
```http
|
||
POST /api/redis/execute-command
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"connectionId": "redis-id",
|
||
"db": 0,
|
||
"command": "GET mykey"
|
||
}
|
||
```
|
||
|
||
其他常见 Redis 路由：
|
||
|
||
- `/api/redis/scan-keys`
|
||
- `/api/redis/get-value`
|
||
- `/api/redis/set-string`
|
||
- `/api/redis/delete-key`
|
||
|
||
## MongoDB API
|
||
|
||
MongoDB 路由都是 `POST` 请求，使用 JSON 请求体。
|
||
|
||
### 列出集合
|
||
|
||
```http
|
||
POST /api/mongo/list-collections
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"connectionId": "mongo-id",
|
||
"database": "app"
|
||
}
|
||
```
|
||
|
||
### 查询文档
|
||
|
||
```http
|
||
POST /api/mongo/find-documents
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"connectionId": "mongo-id",
|
||
"database": "app",
|
||
"collection": "users",
|
||
"skip": 0,
|
||
"limit": 20,
|
||
"filter": "{}"
|
||
}
|
||
```
|
||
|
||
其他 MongoDB 路由还包括 `aggregate-documents`、`insert-documents`、`update-documents`、`delete-documents` 等。
|
||
|
||
## MCP 与 CLI 集成
|
||
|
||
做自动化时，通常比直接调 Web API 更好维护：
|
||
|
||
- MCP：[@dbx-app/mcp-server](/cn/docs/mcp)
|
||
- CLI：[@dbx-app/cli](/cn/docs/cli)
|
||
|
||
如果 MCP 连接的是已部署的 Web 实例，可设置：
|
||
|
||
```json
|
||
{
|
||
"env": {
|
||
"DBX_WEB_URL": "http://localhost:4224",
|
||
"DBX_WEB_PASSWORD": "your-password"
|
||
}
|
||
}
|
||
```
|
||
|
||
MCP Server 会自动处理登录和会话 Cookie。
|
||
|
||
CLI 同样支持 `DBX_WEB_URL` 和 `DBX_WEB_PASSWORD`。两者都复用 Web 后端的连接、驱动、只读保护、生产保护和数据库权限，比复制内部路由字段更容易随 DBX 升级。
|
||
|
||
## 写入、安全和文件边界
|
||
|
||
- API 认证只证明请求来自已登录会话，不会替代数据库权限
|
||
- 查询、导入和传输路径会继续检查连接只读保护；生产保护和 SQL 风险策略在对应核心路径中执行
|
||
- 浏览器上传的表导入和 SQL 文件会写入服务器临时目录，不是浏览器电脑的原始路径
|
||
- Web 导出先生成服务器临时文件，再通过下载路由返回并清理
|
||
- 反向代理应保留 Cookie、SSE 流和较长请求超时，并限制公网暴露范围
|
||
|
||
## 示例脚本
|
||
|
||
仓库内示例：
|
||
|
||
- [examples/web-api/automation.sh](https://github.com/t8y2/dbx/tree/main/examples/web-api/automation.sh)
|
||
- [examples/docker/docker-compose.yml](https://github.com/t8y2/dbx/tree/main/examples/docker/docker-compose.yml)
|
||
- [examples/cli/basic-workflow.sh](https://github.com/t8y2/dbx/tree/main/examples/cli/basic-workflow.sh)
|
||
|
||
## 其他路由分组
|
||
|
||
Web 后端还为界面提供了更多路由，例如：
|
||
|
||
- `/api/export/*`：导出与下载
|
||
- `/api/import/*`：表导入
|
||
- `/api/transfer/*`：数据传输任务
|
||
- `/api/ai/*`：内置 AI 助手
|
||
- `/api/agents/*`、`/api/jdbc/*`：驱动管理
|
||
- `/api/history/*`、`/api/saved-sql/*`：编辑器状态
|
||
|
||
完整路由列表见仓库中的 `crates/dbx-web/src/main.rs`。
|