# Web API 参考 > DBX Web 与 Docker UI 使用的内部 HTTP API，包括认证、查询、后台任务、上传和下载边界。 Source: https://dbxio.com/cn/docs/web-api Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/web-api. 这套 API 主要服务于 DBX Web 界面，以及 MCP Web 模式等内部工具。它不是单独对外承诺的集成契约，路由和字段可能随版本调整。做脚本或 Agent 集成时，优先使用 [@dbx-app/cli](/cn/docs/cli) 或 [@dbx-app/mcp-server](/cn/docs/mcp) 。 ## 基础地址 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=... ``` 其他常用 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`。