Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

fix(web): add startup help and logging guidance

二丫讲梵4c7f8e8196f5
diff --git a/.github/scripts/start-dbx-web.bat b/.github/scripts/start-dbx-web.bat
index ba3882ffd9..637a40b3f2 100644
--- a/.github/scripts/start-dbx-web.bat
+++ b/.github/scripts/start-dbx-web.bat
@@ -1,6 +1,37 @@
@echo off
setlocal EnableDelayedExpansion
+for %%A in (%*) do (
+ if /I "%%~A"=="-h" goto :help
+ if /I "%%~A"=="--help" goto :help
+ if /I "%%~A"=="/help" goto :help
+)
+goto :main
+
+:help
+echo Usage: start.bat [OPTION]
+echo.
+echo Start the DBX Web browser service.
+echo.
+echo Options:
+echo -h, --help, /help Show this help message and exit.
+echo.
+echo Environment variables:
+echo DBX_PORT Listen port (default: 4224)
+echo DBX_DATA_DIR Data directory (default: package-dir\data)
+echo DBX_PUBLIC_BASE_PATH URL path prefix (default: /)
+echo DBX_PASSWORD Set the Web login password
+echo DBX_DISABLE_PASSWORD Set to 1 to disable login protection
+echo RUST_LOG Configure backend log filtering
+echo RUST_BACKTRACE Set to 1 to include Rust backtraces
+echo.
+echo Examples:
+echo set DBX_PORT=8080 ^&^& start.bat
+echo set RUST_LOG=dbx_web=debug,tower_http=info ^&^& start.bat
+exit /b 0
+
+:main
+
:: 脚本所在目录(等价于 ROOT)
set ROOT=%~dp0
:: 去掉末尾反斜杠
diff --git a/crates/dbx-web/src/main.rs b/crates/dbx-web/src/main.rs
index a67852f9e8..0e7a529fae 100644
--- a/crates/dbx-web/src/main.rs
+++ b/crates/dbx-web/src/main.rs
@@ -39,6 +39,51 @@ use web_mcp::WebMcpRuntime;
const XLSX_CONTENT_TYPE: &str = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
const DATA_GRID_EXTRACTOR_BODY_LIMIT_BYTES: usize = 96 * 1024 * 1024;
+const NON_WINDOWS_HELP_TEXT: &str = r#"Usage: dbx-web [OPTION]
+
+Start the DBX Web browser service.
+
+Options:
+ -h, --help, /help Show this help message and exit.
+
+Environment variables:
+ DBX_PORT Listen port (default: 4224)
+ DBX_DATA_DIR Data directory (default: ~/.dbx-web)
+ DBX_PUBLIC_BASE_PATH URL path prefix (default: /)
+ DBX_PASSWORD Set the Web login password
+ DBX_DISABLE_PASSWORD Set to 1 to disable login protection
+ DBX_STATIC_DIR Serve frontend assets from this directory
+ RUST_LOG Configure backend log filtering
+ RUST_BACKTRACE Set to 1 to include Rust backtraces
+
+Examples:
+ DBX_PORT=8080 dbx-web
+ RUST_LOG=dbx_web=debug,tower_http=info dbx-web
+ RUST_BACKTRACE=1 RUST_LOG=dbx_web=debug dbx-web
+"#;
+const WINDOWS_HELP_TEXT: &str = r#"Usage: dbx-web [OPTION]
+
+Start the DBX Web browser service.
+
+Options:
+ -h, --help, /help Show this help message and exit.
+
+Environment variables:
+ DBX_PORT Listen port (default: 4224)
+ DBX_DATA_DIR Data directory (default: %HOME%\.dbx-web; .\.dbx-web if HOME is unset)
+ DBX_PUBLIC_BASE_PATH URL path prefix (default: /)
+ DBX_PASSWORD Set the Web login password
+ DBX_DISABLE_PASSWORD Set to 1 to disable login protection
+ DBX_STATIC_DIR Serve frontend assets from this directory
+ RUST_LOG Configure backend log filtering
+ RUST_BACKTRACE Set to 1 to include Rust backtraces
+
+Examples:
+ set "DBX_PORT=8080" && dbx-web.exe
+ set "RUST_LOG=dbx_web=debug,tower_http=info" && dbx-web.exe
+ set "RUST_BACKTRACE=1" && set "RUST_LOG=dbx_web=debug" && dbx-web.exe
+"#;
+const HELP_TEXT: &str = if cfg!(windows) { WINDOWS_HELP_TEXT } else { NON_WINDOWS_HELP_TEXT };
#[derive(OpenApi)]
#[openapi(
@@ -56,6 +101,29 @@ async fn openapi_json() -> axum::Json<utoipa::openapi::OpenApi> {
mod data_grid_extractor_openapi_tests {
use super::*;
+ #[test]
+ fn help_flags_are_detected_without_starting_the_server() {
+ for flag in ["-h", "--help", "/help"] {
+ assert!(help_requested(&[flag.to_string()]));
+ }
+ assert!(help_requested(&["extra".to_string(), "--help".to_string()]));
+ assert!(!help_requested(&["--helpful".to_string()]));
+ }
+
+ #[test]
+ fn native_help_matches_the_target_shell() {
+ assert!(WINDOWS_HELP_TEXT.contains(r".\.dbx-web if HOME is unset"));
+ assert!(WINDOWS_HELP_TEXT.contains(r#"set "DBX_PORT=8080" && dbx-web.exe"#));
+ assert!(!WINDOWS_HELP_TEXT.contains("DBX_PORT=8080 dbx-web\n"));
+ if cfg!(windows) {
+ assert!(HELP_TEXT.contains(r#"set "DBX_PORT=8080" && dbx-web.exe"#));
+ assert!(!HELP_TEXT.contains("DBX_PORT=8080 dbx-web\n"));
+ } else {
+ assert!(HELP_TEXT.contains("DBX_PORT=8080 dbx-web\n"));
+ assert!(!HELP_TEXT.contains("dbx-web.exe"));
+ }
+ }
+
#[test]
fn extractor_openapi_contains_the_versioned_request_and_error_responses() {
let document = serde_json::to_value(ApiDoc::openapi()).expect("serialize extractor OpenAPI document");
@@ -175,6 +243,10 @@ where
)
}
+fn help_requested(args: &[String]) -> bool {
+ args.iter().any(|arg| matches!(arg.as_str(), "-h" | "--help" | "/help"))
+}
+
/// Frontend build output compiled into the binary by the `embed-static` feature.
/// The folder is relative to this crate's manifest (crates/dbx-web) and points
/// at the workspace root `dist` directory produced by the frontend build.
@@ -385,6 +457,12 @@ fn add_mq_routes(router: Router<Arc<WebState>>) -> Router<Arc<WebState>> {
}
fn main() {
+ let args: Vec<String> = std::env::args().skip(1).collect();
+ if help_requested(&args) {
+ print!("{HELP_TEXT}");
+ return;
+ }
+
let runtime = dbx_core::scheduled_backup::worker_runtime().expect("Failed to build tokio runtime");
runtime.block_on(serve());
}
diff --git a/docs/content/docs/web-api.cn.mdx b/docs/content/docs/web-api.cn.mdx
index c5ec3f26ab..8d9fbeacc8 100644
--- a/docs/content/docs/web-api.cn.mdx
+++ b/docs/content/docs/web-api.cn.mdx
@@ -92,6 +92,18 @@ Cookie: dbx_session=...
| `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` 会启用范围更广、噪声更大的过滤器。日志写入进程输出,需要保存诊断文件时可自行重定向输出。
## 请求约定
diff --git a/docs/content/docs/web-api.mdx b/docs/content/docs/web-api.mdx
index 2ead497cca..12ae788c62 100644
--- a/docs/content/docs/web-api.mdx
+++ b/docs/content/docs/web-api.mdx
@@ -92,6 +92,18 @@ Cookie: dbx_session=...
| `DBX_MAX_UPLOAD_MB` | Override the general request and uploaded-file limit; default 1024 MB. Multipart routes reserve fixed protocol overhead (set at least `4096` for a 4 GiB file) |
| `DBX_AGENT_DIR` | Override the Web Agent/driver directory; defaults to `agents` under the data directory |
| `DBX_STATIC_DIR` | Override the Web static asset directory |
+| `RUST_LOG` | Configure Rust backend log filtering; the default is `dbx_web=info,tower_http=info` |
+| `RUST_BACKTRACE=1` | Include Rust backtraces when an error reports one |
+
+## Logging and Troubleshooting
+
+DBX Web reads the standard `RUST_LOG` filter when it starts. For a focused diagnostic run, increase the Web and HTTP middleware targets without enabling every dependency:
+
+```bash
+RUST_LOG=dbx_web=debug,tower_http=info ./dbx
+```
+
+Set `RUST_BACKTRACE=1` as well when the error includes a Rust backtrace. If the problem is inside another DBX crate, add its target to the same filter, such as `dbx_core`, `dbx_drivers`, `dbx_sql`, `dbx_plugin_runtime`, `dbx_ai_provider`, or `dbx_platform`. `RUST_LOG=debug` enables a much broader and noisier filter. Logs are written to the process output; redirect that output when you need to save a diagnostic file.
## Request Format
diff --git a/scripts/package-web-static.sh b/scripts/package-web-static.sh
index 548062b7c9..e9b70a85b3 100644
--- a/scripts/package-web-static.sh
+++ b/scripts/package-web-static.sh
@@ -56,6 +56,36 @@ chmod +x "$package_dir/bin/dbx-web-bin"
cat > "$package_dir/dbx" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
+
+for arg in "$@"; do
+ if [[ "$arg" != "-h" && "$arg" != "--help" && "$arg" != "/help" ]]; then
+ continue
+ fi
+ cat <<'HELP'
+Usage: ./dbx [OPTION]
+
+Start the DBX Web browser service.
+
+Options:
+ -h, --help, /help Show this help message and exit.
+
+Environment variables:
+ DBX_PORT Listen port (default: 4224)
+ DBX_DATA_DIR Data directory (default: package-dir/data)
+ DBX_PUBLIC_BASE_PATH URL path prefix (default: /)
+ DBX_PASSWORD Set the Web login password
+ DBX_DISABLE_PASSWORD Set to 1 to disable login protection
+ RUST_LOG Configure backend log filtering
+ RUST_BACKTRACE Set to 1 to include Rust backtraces
+
+Examples:
+ DBX_PORT=8080 ./dbx
+ RUST_LOG=dbx_web=debug,tower_http=info ./dbx
+ RUST_BACKTRACE=1 RUST_LOG=dbx_web=debug ./dbx
+HELP
+ exit 0
+done
+
SOURCE="${BASH_SOURCE[0]}"
while [ -h "$SOURCE" ]; do
DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
@@ -96,9 +126,19 @@ system glibc version (verified down to Ubuntu 14.04).
Useful environment variables:
DBX_PORT=4224
- DBX_DATA_DIR=./data
+ DBX_DATA_DIR=/path/to/data
+ DBX_PUBLIC_BASE_PATH=/dbx
DBX_PASSWORD=your-password
DBX_DISABLE_PASSWORD=1
+ RUST_LOG=dbx_web=debug,tower_http=info
+ RUST_BACKTRACE=1
+
+Show the available options without starting the server:
+ ./dbx --help
+ ./dbx /help
+
+For troubleshooting, start DBX with a targeted debug filter:
+ RUST_LOG=dbx_web=debug,tower_http=info ./dbx
EOF
tar -C "$output_dir" -czf "$tarball" "$package_name"