feat(部署): Ubuntu/Debian 原生一键部署（DataLink 外置）

.env.example

@@ -1,6 +1,9 @@
 API_HOST=127.0.0.1
 API_PORT=8787
+WEB_HOST=0.0.0.0
+WEB_PORT=3000
 
+# LLM_* values are optional server-side defaults. Models can also be created in the Web UI after deploy.
 LLM_PROVIDER=openai-compatible
 LLM_MODEL=qwen-plus
 LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

.github/workflows/ci.yml

@@ -97,6 +97,37 @@ jobs:
       - name: Run built-in DTC Growth regression
         run: node --test scripts/test-builtin-dtc-growth-datasource.mjs
 
+  native-deploy-smoke:
+    name: Native Deploy Smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run deployment unit tests
+        run: npm run test:deploy
+
+      - name: Run native deployment smoke
+        run: npm run smoke:native-deploy
+
+      - name: Upload redacted deployment logs
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: native-deploy-logs
+          path: storage/logs/
+          if-no-files-found: ignore
+
   docs:
     name: Docs
     runs-on: ubuntu-latest

README.md

@@ -71,14 +71,40 @@ See the [v0.2.0 release notes](docs/en/releases/v0.2.0.md) for the complete capa
 
 ## 🚀 Formal deploy
 
-Default path is the **formal** stack: `password` auth + `build` / `start` (do **not** run `npm run dev`). No business database required — built-in demo data sources, including the DTC Growth Review case, work out of the box.
+Formal mode has two paths (do **not** run `npm run dev`). Docker / Compose is not provided in this release.
 
-Two formal environments share the **same startup commands**:
+### Recommended: Ubuntu / Debian one-click
 
-| Environment | Use for | Email | Public URL |
-| --- | --- | --- | --- |
-| **Formal test** | Local / private acceptance | `AUTH_EMAIL_DELIVERY=test` (links in API console) | `http://127.0.0.1:3000` |
-| **Real production** | Public service | `AUTH_EMAIL_DELIVERY=smtp` | Public HTTPS + reverse proxy |
+`./deploy.sh` generates configuration, installs dependencies, builds (Web, API, and TUI), and starts Web + API as a detached background process — closing the terminal does not stop the stack. The TUI is built and ready but is a foreground client: start it in another terminal with `./deploy.sh tui` (or `npm run start:tui`); it does **not** stay running with the stack. Semantic Data Link is an **external** component (not started by deploy) — connect it later via MCP in the Web UI if needed. No model key is required during deploy — create and enable a model profile in the Web UI after login. Does **not** support native Windows / macOS.
+
+```bash
+git clone https://github.com/datagallery-lab/datafoundry.git
+cd datafoundry
+./deploy.sh
+```
+
+If a complete `.env` already exists, interactive deploy skips the configuration questions. To change ports or the public URL (secrets are preserved; `.env` is backed up first):
+
+```bash
+./deploy.sh deploy --reconfigure
+```
+
+Common management commands:
+
+```bash
+./deploy.sh status
+./deploy.sh start
+./deploy.sh stop
+./deploy.sh logs
+./deploy.sh doctor
+./deploy.sh tui      # optional: foreground TUI client (API must already be up)
+```
+
+Open `http://127.0.0.1:3000/login`, register or sign in, create an OpenAI-compatible model profile, then go to `/data-tasks`. For remote hosts set `AUTH_PUBLIC_BASE_URL`. Re-running `./deploy.sh deploy` uses a maintenance window (stop the managed process group before install/build).
+
+### Windows / macOS / other: manual npm
+
+On native Windows, macOS, or other non-Ubuntu/Debian hosts, use manual npm. Install and run in the same environment; on Windows, do not share `node_modules` between Windows and WSL.
 
 ```bash
 git clone https://github.com/datagallery-lab/datafoundry.git
@@ -116,8 +142,7 @@ Build and start:
 ```bash
 npm run build
 npm run build:web
-npm run start:api    # :8787  — /healthz liveness, /ready readiness
-npm run start:web    # :3000  — password mode via same-origin BFF
+npm run start        # Web :3000 + API :8787
 ```
 
 Open `http://127.0.0.1:3000/login`, register or sign in, go to `/data-tasks`, and ask:
@@ -130,7 +155,8 @@ You will see the full chain: schema inspection → read-only SQL → SQL audit 
 
 For real production, also configure SMTP and a reverse proxy: [`deploy/nginx.datafoundry.conf.example`](deploy/nginx.datafoundry.conf.example) (gzip/brotli static assets; keep `/api/copilotkit` uncompressed and unbuffered for SSE).
 
-> Full steps and the two-environment matrix: [Quick Start](docs/en/quick-start.md). Contributor hot-reload (`npm run dev`) is appendix-only. Connect your own PostgreSQL / MySQL / CSV and more: [Data Sources guide](docs/en/guides/data-sources.md).
+> Full steps, the two-environment matrix, and optional external Data Link notes: [Quick Start](docs/en/quick-start.md). Contributor hot-reload (`npm run dev`) is appendix-only. Connect your own PostgreSQL / MySQL / CSV and more: [Data Sources guide](docs/en/guides/data-sources.md).
+
 
 ## 🆚 How It Differs From Coding Agents And SQL Chatbots
 

README_zh.md

@@ -71,14 +71,40 @@ DataFoundry 0.2 在首个可用版本上，进一步补齐了有状态、可追
 
 ## 🚀 正式态跑通
 
-默认按**正式态**部署：`password` 认证 + `build` / `start`（不要跑 `npm run dev`）。不需要准备业务数据库，包含 DTC 增长经营复盘在内的内置 demo 数据源开箱即用。
+正式态有两条路径（都不要跑 `npm run dev`）。本版本不提供 Docker / Compose。
 
-正式态分两种环境，**启动命令相同**：
+### 推荐：Ubuntu / Debian 一键部署
 
-| 环境 | 用途 | 邮箱 | 公网地址 |
-| --- | --- | --- | --- |
-| **正式测试** | 本机 / 内网验收 | `AUTH_EMAIL_DELIVERY=test`（链接打控制台） | `http://127.0.0.1:3000` |
-| **真实生产** | 对外服务 | `AUTH_EMAIL_DELIVERY=smtp` | 公网 HTTPS + 反代 |
+`./deploy.sh` 自动生成配置、安装依赖、构建（含 Web、API 与 TUI），并以 detached 后台进程启动 Web + API——关闭终端一般不会停止服务。TUI 会在部署时构建就绪，但它是前台交互客户端：请另开终端执行 `./deploy.sh tui`（或 `npm run start:tui`），**不会**随 stack 后台常驻。语义 Data Link 为**外置**组件（deploy 不会安装或启动）——如需使用，稍后在 Web 的 MCP 配置中连接外部服务即可。部署时不要求填写模型 Key——登录后在 Web 中创建并启用模型即可。**不支持**原生 Windows / macOS。
+
+```bash
+git clone https://github.com/datagallery-lab/datafoundry.git
+cd datafoundry
+./deploy.sh
+```
+
+若已有完整 `.env`，交互部署会跳过配置问答。要改端口或公开访问地址时（会保留密钥并先备份 `.env`）：
+
+```bash
+./deploy.sh deploy --reconfigure
+```
+
+常用管理命令：
+
+```bash
+./deploy.sh status
+./deploy.sh start
+./deploy.sh stop
+./deploy.sh logs
+./deploy.sh doctor
+./deploy.sh tui      # 可选：前台启动 TUI（需 API 已在运行）
+```
+
+打开 `http://127.0.0.1:3000/login` 注册登录，在模型配置中创建 OpenAI-compatible Profile，然后进入 `/data-tasks`。远程部署请设置 `AUTH_PUBLIC_BASE_URL`；重复执行 `./deploy.sh deploy` 会进入维护窗口（先停止旧进程再安装/构建）。
+
+### Windows / macOS / 其他：手动 npm
+
+原生 Windows、macOS 或其他非 Ubuntu/Debian 环境请用手动 npm。请在同一环境内安装和运行；Windows 用户不要在 Windows 和 WSL 之间共用 `node_modules`。
 
 ```bash
 git clone https://github.com/datagallery-lab/datafoundry.git
@@ -116,8 +142,7 @@ API_PROXY_TARGET=http://127.0.0.1:8787
 ```bash
 npm run build
 npm run build:web
-npm run start:api    # :8787  — /healthz 存活，/ready 就绪
-npm run start:web    # :3000  — password 模式走同源 BFF
+npm run start        # Web :3000 + API :8787
 ```
 
 打开 `http://127.0.0.1:3000/login` 注册登录后进入 `/data-tasks`，提问：

apps/web/.env.example

@@ -1,5 +1,9 @@
 # DataFoundry Web — formal deploy defaults (password + same-origin BFF).
 #
+# Native one-click deploy (`./deploy.sh`) generates `apps/web/.env.local` for you.
+# It uses same-origin BFF variables (empty NEXT_PUBLIC_* URLs) and sets
+# API_PROXY_TARGET from the selected API host/port.
+#
 # Keep in sync with root `.env` → DATAFOUNDRY_AUTH_MODE.
 # NEXT_PUBLIC_* values are baked in at `npm run build:web`.
 #

deploy.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+ROOT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/deploy/bootstrap.sh
+source "${ROOT_DIR}/scripts/deploy/bootstrap.sh"
+
+main() {
+  check_supported_system
+  ensure_node_22 "$@"
+  exec node "$ROOT_DIR/scripts/deploy/cli.mjs" "$@"
+}
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  main "$@"
+fi

docs/en/index.md

@@ -30,7 +30,7 @@ Review a realistic growth spike with schema inspection, read-only SQL, and trace
 ## Recommended path
 
 1. Read [Product overview](overview.md) to confirm the problem space and capability boundaries.
-2. Follow [Quick start](quick-start.md) to configure a model API key and run the built-in DTC Growth Review.
+2. Follow [Quick start](quick-start.md): on Ubuntu / Debian prefer `./deploy.sh`; on Windows / macOS and other hosts use manual npm (`npm install` → configure → `build` / `start`). Then create a model profile in the Web UI and run the built-in DTC Growth Review.
 3. Read [Capabilities](capabilities.md) to see coverage across Web, TUI, and backend API.
 4. Choose [Web workbench guide](guides/web-workbench.md) or [TUI guide](guides/tui.md) based on your entry point.
 5. When you need your own data, read [Data sources guide](guides/data-sources.md).