fix(web): add startup help and logging guidance

.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
 :: 去掉末尾反斜杠

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());
 }

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` 会启用范围更广、噪声更大的过滤器。日志写入进程输出，需要保存诊断文件时可自行重定向输出。
 
 ## 请求约定
 

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
 

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"