402 lines
13 KiB
Plaintext
402 lines
13 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；multipart 路由会额外预留固定的协议开销（如需上传 4 GiB 文件，请设为至少 `4096`） |
|
||
| `DBX_AGENT_DIR` | 覆盖 Web 端 Agent/驱动目录，默认位于数据目录下的 `agents` |
|
||
| `DBX_STATIC_DIR` | 覆盖 Web 静态文件目录 |
|
||
| `RUST_LOG` | 配置 Rust 后端日志过滤；默认值为 `dbx_web=info,tower_http=info` |
|
||
| `RUST_BACKTRACE=1` | 错误包含 Rust 回溯时输出 backtrace |
|
||
|
||
## 日志与问题排查
|
||
|
||
DBX Web 启动时读取标准 `RUST_LOG` 过滤器。排查问题时，可以只提高 Web 和 HTTP 中间件的日志级别，避免打开所有依赖的日志：
|
||
|
||
```bash
|
||
RUST_LOG=dbx_web=debug,tower_http=info ./dbx
|
||
```
|
||
|
||
如果错误需要 Rust 回溯，同时设置 `RUST_BACKTRACE=1`。如果问题位于其他 DBX crate，可以在同一个过滤器中加入 `dbx_core`、`dbx_drivers`、`dbx_sql`、`dbx_plugin_runtime`、`dbx_ai_provider` 或 `dbx_platform`。`RUST_LOG=debug` 会启用范围更广、噪声更大的过滤器。日志写入进程输出，需要保存诊断文件时可自行重定向输出。
|
||
|
||
## 请求约定
|
||
|
||
- 字段命名由具体 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 中。
|
||
|
||
### 保存连接
|
||
|
||
连接按 `id` 增量写入：请求中未出现的连接保持不变，因此多个客户端共用同一个服务端时不会互相删除
|
||
对方的连接；删除连接通过可选的 `removedIds` 显式声明。
|
||
|
||
```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"
|
||
}
|
||
],
|
||
"removedIds": ["connection-to-delete"]
|
||
}
|
||
```
|
||
|
||
### 测试连接
|
||
|
||
```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=...
|
||
```
|
||
|
||
### 读取 Oracle 系触发器
|
||
|
||
不需要先知道所属表，可按触发器类型发现对象。精确适配器先筛选，再分页：
|
||
|
||
```http
|
||
GET /api/schema/objects?connection_id=CONNECTION_ID&database=demo&schema=APP&object_types=TRIGGER&filter=audit&limit=100&offset=0&identity_mode=exact
|
||
```
|
||
|
||
所属对象入口使用真实 parent owner/name；返回的触发器 owner 可以不同：
|
||
|
||
```http
|
||
GET /api/schema/triggers?connection_id=CONNECTION_ID&database=demo&schema=DATA&table=ORDERS&identity_mode=exact
|
||
```
|
||
|
||
完整定义使用触发器自身的 owner/name。此路由的 `table` 参数是源码对象名，不是父表：
|
||
|
||
```http
|
||
GET /api/schema/object-source?connection_id=CONNECTION_ID&database=demo&schema=APP&table=AUDIT_ORDERS&object_type=TRIGGER&identity_mode=exact
|
||
```
|
||
|
||
三项接口均接受可选 `identity_mode=exact` 和 `catalog`。省略模式时保持旧读取合同；精确模式保留原始 owner/name，空格、引号等字符应 URL 编码，不应 trim 或转换大小写。`catalog` 透传给实际 provider，不替代 `schema`。
|
||
|
||
对象和源码响应可包含 `trigger.oracle_metadata`，所属对象列表各项直接包含 `oracle_metadata`。版本 1 提供已核实的 engine、原始身份、作用域、独立 parent、字符串 object ID 及逐字段 `reads` 状态。`enabled` 是启用状态，`valid` 是独立读取的对象有效性；Schema/Database 作用域不填假父表。
|
||
|
||
exact 源码查询成功且零行时，返回 `reads.identity.state="empty"`，保留已核实的引擎和原始目标。这只表示当前可见范围内无匹配对象，不推断全库不存在；查询失败和旧 provider 缺契约不能产生该证明。新建仍使用不带 REPLACE 的 CREATE。
|
||
|
||
源码元数据另含来源、格式、完整性及带行列的编译错误。缺失或 null 错误列表表示未知，不是成功读到零错误。不完整或失败的读取不能作为替换基线；保留草稿，补齐字典访问或更新 provider 后重读。旧 Agent/插件仍可按旧模式使用，但缺少新元数据时不能证明 exact 身份。`DBMS_METADATA` 可能附带同目标的状态语句；导出原文和单定义保存内容分别处理。
|
||
|
||
其他常用 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 |
|
||
|
||
### 准备 Oracle 系触发器的单个定义
|
||
|
||
`POST /api/query/prepare-oracle-trigger-sql` 的请求体为 `{ "input": ... }`。input 包含 `databaseType`（`oracle`、`oceanbase-oracle` 或 `dameng`）、原始 `owner`/`name`、`source` 和 `purpose`（`inspect`、`create` 或 `replace`）。返回单个规范化 `definition`、解析后的 `header`，以及独立的内联/导出启用状态。`comparisonSource` 仅用于读回比较：规范化已确认的声明包装，保留头部其余内容、正文、注释及字符串换行；执行时使用 `definition`。该接口只准备 SQL；核对当前对象、权限和并发变化后，沿正常查询接口执行。
|
||
|
||
创建和替换还需传入已核实的 `binding`：`scope` 为 `TABLE`、`VIEW`、`SCHEMA`、`DATABASE` 或 `TIMER`；适用时带真实 parent `owner`/`name`，Oracle 容器作用域另带已核实的 `pluggable`。省略的 ON 限定只从该绑定补全。替换还需传入期望保全的 `enabled`。新建生成不带 OR REPLACE 的 CREATE；Oracle/已验证 OB 将状态保全在定义内，DM 返回的 `requiresStateRestore` 表示需要另行预览和核实原生状态步骤。`allowExportAppendix` 仅用于查看可信元数据导出；写入用途拒绝该选项及额外 SQL。
|
||
|
||
`structuredEditable` 表示完整定义的头部能否由时机、事件和正文表单无损表达。值为 false 或缺失时，结构修改须使用完整源码入口；只有 `TRIGGER_BODY` 不能证明可以安全重建定义。
|
||
|
||
## 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`。
|