doc:v0.8.0 docs i18n

2026-07-17 01:58:47 +00:00 · 2026-03-23 00:00:35 +08:00
parent 3c34f50134
commit 3b0be9d740
8 changed files with 812 additions and 57 deletions
--- a/docs/docs/getting-started/cli-quickstart.md
+++ b/docs/docs/getting-started/cli-quickstart.md
@@ -26,7 +26,7 @@ The default installation includes the **core framework** (CLI, FastAPI, SQLAlche
 **OpenAI-compatible LLM support** (also works with Kimi, Qwen, MiniMax, Z.AI),
 **DashScope / Tongyi** support, **RAG document parsing**, and **ChromaDB** vector store.

-Need additional providers or data sources? See [Optional Modules](#optional-modules).
+Need additional providers or data sources? See [Optional Modules](#7-optional-modules).
 :::

 After installation the `dbgpt` command is available in your terminal.
--- a/docs/docs/installation/index.md
+++ b/docs/docs/installation/index.md
@@ -0,0 +1,56 @@
+---
+sidebar_position: 0
+title: Install
+summary: "Choose the fastest way to install DB-GPT: quick install, CLI install, or source install"
+read_when:
+  - You want to decide which installation path fits your environment
+  - You want the shortest route to a working DB-GPT setup
+---
+
+# Install
+
+DB-GPT offers three recommended installation paths. Pick the one that matches how you want to run and manage the project.
+
+## Choose an installation path
+
+| Method | Best for | What you get |
+|---|---|---|
+| [Quick Install](/docs/installation/quick-install) | Fastest first run on macOS / Linux | One-line installer, generated profile config, ready-to-start webserver |
+| [CLI Install](/docs/getting-started/cli-quickstart) | Users who prefer installing from PyPI | `dbgpt` CLI, interactive setup wizard, profile management |
+| [Source Install](/docs/getting-started/deploy/source-code) | Developers and custom deployments | Full repo checkout, editable configs, maximum flexibility |
+
+## Recommended path
+
+For most users, start with **Quick Install**. It gives you the fastest path from zero to a running DB-GPT web UI.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh | bash
+```
+
+After installation, start the generated profile config:
+
+```bash
+cd ~/.dbgpt/DB-GPT && uv run dbgpt start webserver --config ~/.dbgpt/configs/<profile>.toml
+```
+
+Then open [http://localhost:5670](http://localhost:5670).
+
+## When to choose each method
+
+### Quick Install
+
+Choose this if you want the simplest install flow and do not need to manage the repository manually.
+
+### CLI Install
+
+Choose this if you want to install DB-GPT directly from PyPI and use the `dbgpt` command to set up profiles interactively.
+
+### Source Install
+
+Choose this if you want full access to the repository for development, debugging, or custom integrations.
+
+## Next steps
+
+- [Quick Install](/docs/installation/quick-install)
+- [CLI Install](/docs/getting-started/cli-quickstart)
+- [Source Install](/docs/getting-started/deploy/source-code)
--- a/docs/docs/installation/quick-install.md
+++ b/docs/docs/installation/quick-install.md
@@ -0,0 +1,127 @@
+---
+sidebar_position: 1
+title: Quick Install
+summary: "The fastest way to install DB-GPT with the installer script from the README"
+read_when:
+  - You want the shortest path to a working DB-GPT web UI
+  - You prefer the installer script over a manual source setup
+---
+
+import CommandCopyCard from "@site/src/components/mdx/CommandCopyCard";
+
+# Quick Install
+
+The fastest way to get DB-GPT running. The installer script prepares a local DB-GPT workspace, generates a provider profile, and gives you a ready-to-run webserver command.
+
+## Recommended: installer script
+
+Use the installer script if you want the shortest path from zero to a working DB-GPT web UI.
+
+<CommandCopyCard command={`curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh | bash`} />
+
+## System requirements
+
+This quick-install flow is designed for:
+
+- **macOS** or **Linux**
+- a shell environment that can run `bash`
+- network access to download dependencies
+- an API key if you plan to use a hosted model provider immediately
+
+:::tip Best fit
+Choose this path if you want to try DB-GPT quickly without managing the repository structure yourself.
+:::
+
+## Install with a provider profile
+
+If you already know which provider you want, pass the profile and API key directly during installation.
+
+### OpenAI-compatible profile
+
+<CommandCopyCard command={`curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
+  | OPENAI_API_KEY=sk-xxx bash -s -- --profile openai`} />
+
+### Kimi 2.5 via Moonshot API
+
+<CommandCopyCard command={`curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
+  | MOONSHOT_API_KEY=sk-xxx bash -s -- --profile kimi`} />
+
+### MiniMax via an OpenAI-compatible API
+
+<CommandCopyCard command={`curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
+  | MINIMAX_API_KEY=sk-xxx bash -s -- --profile minimax`} />
+
+## Reuse an existing local checkout
+
+Already have a local DB-GPT repository? Reuse it instead of cloning into `~/.dbgpt/DB-GPT`.
+
+### Reuse local repo with OpenAI
+
+<CommandCopyCard command={`OPENAI_API_KEY=sk-xxx \
+  bash scripts/install/install.sh --profile openai --repo-dir "$(pwd)" --yes`} />
+
+### Reuse local repo with Kimi
+
+<CommandCopyCard command={`MOONSHOT_API_KEY=sk-xxx \
+  bash scripts/install/install.sh --profile kimi --repo-dir "$(pwd)" --yes`} />
+
+### Reuse local repo with MiniMax
+
+<CommandCopyCard command={`MINIMAX_API_KEY=sk-xxx \
+  bash scripts/install/install.sh --profile minimax --repo-dir "$(pwd)" --yes`} />
+
+## What the installer prepares
+
+The installer script sets up the common runtime layout for you:
+
+- a DB-GPT checkout under `~/.dbgpt/DB-GPT` unless `--repo-dir` is used
+- generated provider configs under `~/.dbgpt/configs/`
+- the DB-GPT home directory under `~/.dbgpt/`
+- a ready-to-run webserver command using the generated profile
+
+## Start DB-GPT after installation
+
+After installation completes, start the webserver with the generated profile config:
+
+<CommandCopyCard command={`cd ~/.dbgpt/DB-GPT && uv run dbgpt start webserver --config ~/.dbgpt/configs/<profile>.toml`} />
+
+Then open [http://localhost:5670](http://localhost:5670).
+
+## Verify the install
+
+Your install is working if:
+
+- the webserver starts without configuration errors
+- the Web UI opens at `http://localhost:5670`
+- you can start a chat in the browser
+
+## Review the script first
+
+If you prefer to inspect the installer before running it:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh -o install.sh
+less install.sh
+bash install.sh --profile openai
+```
+
+## Alternative install methods
+
+If the installer script is not the right fit for your environment:
+
+- use [CLI Install](/docs/getting-started/cli-quickstart) for a PyPI-based install with the `dbgpt` command
+- use [Source Install](/docs/getting-started/deploy/source-code) for development, debugging, and customization
+
+## Troubleshooting
+
+### The installer script does not match my shell or platform
+
+Use [CLI Install](/docs/getting-started/cli-quickstart) or [Source Install](/docs/getting-started/deploy/source-code) instead.
+
+### I want more control over dependencies and configuration
+
+Use [Source Install](/docs/getting-started/deploy/source-code). It exposes the full repository layout and `uv sync` workflow.
+
+### The install completed, but DB-GPT does not start cleanly
+
+Check the generated config under `~/.dbgpt/configs/`, then see [Installation Issues](/docs/getting-started/troubleshooting/installation).
--- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
+++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current.json
@@ -15,6 +15,18 @@
    "message": "安装部署",
    "description": "The label for category Installation in sidebar docsSidebar"
  },
+  "sidebar.docsSidebar.doc.Quick Install": {
+    "message": "快速安装",
+    "description": "The label for the doc item Quick Install in sidebar docsSidebar, linking to the doc installation/quick-install"
+  },
+  "sidebar.docsSidebar.doc.CLI Install": {
+    "message": "CLI 安装",
+    "description": "The label for the doc item CLI Install in sidebar docsSidebar, linking to the doc getting-started/cli-quickstart"
+  },
+  "sidebar.docsSidebar.doc.Source Install": {
+    "message": "源码安装",
+    "description": "The label for the doc item Source Install in sidebar docsSidebar, linking to the doc getting-started/deploy/source-code"
+  },
  "sidebar.docsSidebar.category.Model Service Deployment": {
    "message": "模型服务部署",
    "description": "The label for category Model Service Deployment in sidebar docsSidebar"
--- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/cli-quickstart.md
+++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/cli-quickstart.md
@@ -0,0 +1,429 @@
+---
+sidebar_position: 1
+title: CLI 安装
+summary: "通过 PyPI 安装 DB-GPT，并用单条命令启动它，无需源码 checkout"
+read_when:
+  - 你想直接从 PyPI 安装 DB-GPT
+  - 你希望通过 `dbgpt` CLI 完成交互式配置
+---
+
+# CLI 安装
+
+通过 PyPI 安装 DB-GPT，并使用单条命令启动它 —— 无需检出源码仓库。
+
+:::tip 前置条件
+- Python **3.10** 或更高版本
+- 推荐使用 [uv](https://docs.astral.sh/uv/getting-started/installation/) 包管理器，也支持 pip
+:::
+
+## 1. 安装
+
+```bash
+# 推荐：使用 uv
+uv pip install dbgpt-app
+
+# 或者使用 pip
+pip install dbgpt-app
+```
+
+:::info 默认包含内容
+默认安装会包含 **核心框架**（CLI、FastAPI、SQLAlchemy、Agent）、**OpenAI 兼容 LLM 支持**（也适用于 Kimi、Qwen、MiniMax、Z.AI）、**DashScope / Tongyi** 支持、**RAG 文档解析** 和 **ChromaDB** 向量存储。
+
+如果你需要更多 provider 或数据源，可参考 [可选模块](#7-可选模块)。
+:::
+
+安装完成后，终端中就可以直接使用 `dbgpt` 命令。
+
+## 2. 启动 DB-GPT
+
+```bash
+dbgpt start
+```
+
+首次运行时，DB-GPT 会自动启动一个 **交互式配置向导**，帮助你：
+
+1. 选择 LLM provider（OpenAI、Kimi、Qwen、MiniMax、Z.AI 或自定义 endpoint）
+2. 输入 API Key（或改用环境变量）
+3. 确认模型名称和 API Base URL
+
+完成后，系统会把 TOML 配置写入 `~/.dbgpt/configs/<profile>.toml`，并自动启动 webserver。然后打开浏览器访问 `http://localhost:5670`。
+
+### 启动后的样子
+
+```
+    ____  ____        ____ ____ _____
+   |  _ \| __ )      / ___|  _ \_   _|
+   | | | |  _ \ ____| |  _| |_) || |
+   | |_| | |_) |____| |_| |  __/ | |
+   |____/|____/      \____|_|    |_|
+
+   🚀 DB-GPT Quick Start
+
+   +- - - - - - - - - - - - - - - - - - - - - - - -+
+   :  Profile:   openai                              :
+   :  Config:    /Users/you/.dbgpt/configs/openai.toml:
+   :  Workspace: /Users/you/.dbgpt/workspace          :
+   +- - - - - - - - - - - - - - - - - - - - - - - -+
+```
+
+---
+
+## 3. 命令参考
+
+### 总览
+
+```
+dbgpt [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --log-level TEXT   Log level (default: warn)
+  --version          Show version and exit
+  --help             Show help message
+
+Commands:
+  start     Start the DB-GPT server
+  stop      Stop a running server
+  setup     Configure LLM provider (interactive wizard or CI mode)
+  profile   Manage configuration profiles
+  knowledge Knowledge base operations
+  model     Manage model serving
+  db        Database management and migration
+  ...
+```
+
+---
+
+### `dbgpt start`
+
+启动 DB-GPT web server。直接运行 `dbgpt start` 等价于 `dbgpt start web`。
+
+#### 子命令
+
+| 子命令 | 说明 |
+|---|---|
+| `web`（或 `webserver`） | 启动 web server（默认） |
+| `none` | 仅 API 模式 —— *未来版本计划支持* |
+| `controller` | 启动模型 controller |
+| `worker` | 启动模型 worker |
+| `apiserver` | 启动 API server |
+
+#### `dbgpt start web` 参数
+
+| 参数 | Short | 类型 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `--config` | `-c` | PATH | *auto* | TOML 配置文件路径。若未提供，则使用当前 active profile，或自动启动配置向导。 |
+| `--profile` | `-p` | TEXT | *active* | Provider profile 名称（`openai`、`kimi`、`qwen`、`minimax`、`glm`、`custom`）。会覆盖当前 active profile。 |
+| `--yes` | `-y` | FLAG | false | 非交互模式：跳过向导，直接使用默认值 / 环境变量，适合 CI/CD。 |
+| `--api-key` | | TEXT | *env* | 指定 provider 的 API key，也可通过对应环境变量提供。 |
+| `--daemon` | `-d` | FLAG | false | 后台守护进程方式运行。可通过 `dbgpt stop webserver` 停止。 |
+
+#### 示例
+
+```bash
+# 首次运行，使用交互式向导
+dbgpt start
+
+# 使用现有 profile
+dbgpt start web --profile openai
+
+# 非交互方式并显式传入 API key
+dbgpt start web --profile kimi --api-key sk-xxx --yes
+
+# 使用指定配置文件
+dbgpt start web --config /path/to/my-config.toml
+
+# 以 daemon 方式运行
+dbgpt start web --daemon
+```
+
+#### 配置解析优先级
+
+启动 web server 时，配置文件的解析顺序如下：
+
+1. **`--config` 参数** —— 如果提供，直接使用这个文件
+2. **`--profile` 参数** —— 查找 `~/.dbgpt/configs/<profile>.toml`
+3. **Active profile** —— 从 `~/.dbgpt/config.toml` 中读取
+4. **配置向导** —— 如果还没有配置，则自动启动交互式向导
+
+---
+
+### `dbgpt stop`
+
+停止正在运行的 DB-GPT 服务进程。
+
+```bash
+# 停止 web server
+dbgpt stop webserver
+
+# 停止指定端口上的 web server
+dbgpt stop webserver --port 5670
+
+# 停止所有服务
+dbgpt stop all
+```
+
+---
+
+### `dbgpt setup`
+
+交互式配置 LLM provider，或用于非交互 / CI 模式配置。这个命令会把 TOML 配置写入 `~/.dbgpt/configs/<profile>.toml`，并将它标记为 active profile。
+
+#### 参数
+
+| 参数 | Short | 类型 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `--profile` | `-p` | TEXT | *interactive* | 要配置的 provider profile。若省略，则显示交互菜单。 |
+| `--yes` | `-y` | FLAG | false | 非交互模式：跳过向导并使用默认值。 |
+| `--api-key` | | TEXT | *env* | API key，也会读取 `DBGPT_API_KEY` 环境变量。 |
+| `--show` | | FLAG | false | 显示当前 active profile 和配置路径后退出。 |
+
+#### 示例
+
+```bash
+# 交互式向导
+dbgpt setup
+
+# 非交互：使用 OpenAI + 环境变量
+export OPENAI_API_KEY=sk-xxx
+dbgpt setup --profile openai --yes
+
+# 非交互：显式传入 key
+dbgpt setup --profile kimi --api-key sk-xxx
+
+# 查看当前配置
+dbgpt setup --show
+```
+
+---
+
+### `dbgpt profile`
+
+管理多个配置 profile。每个 profile 都是 `~/.dbgpt/configs/` 下的一个 TOML 文件。
+
+#### 子命令
+
+| 子命令 | 说明 |
+|---|---|
+| `list` | 列出所有 profile，active 的会用 `*` 标记 |
+| `show <name>` | 显示某个 profile 的 TOML 内容 |
+| `create <name>` | 使用配置向导创建（或重新配置）一个 profile |
+| `switch <name>` | 将某个 profile 设为当前默认 |
+| `delete <name>` | 删除某个 profile 配置文件 |
+
+#### 示例
+
+```bash
+# 列出所有 profile
+dbgpt profile list
+#   openai     ← no asterisk
+# * kimi       ← active
+
+# 查看 profile 内容
+dbgpt profile show openai
+
+# 创建新 profile
+dbgpt profile create qwen
+
+# 切换 active profile
+dbgpt profile switch openai
+
+# 删除 profile
+dbgpt profile delete minimax
+dbgpt profile delete minimax --yes  # 跳过确认
+```
+
+---
+
+## 4. 支持的 Providers
+
+配置向导和 `--profile` 参数支持以下 provider：
+
+| Profile 名称 | 显示名称 | LLM 模型 | Embedding 模型 | API Key 环境变量 |
+|---|---|---|---|---|
+| `openai` | OpenAI | gpt-4o | text-embedding-3-small | `OPENAI_API_KEY` |
+| `kimi` | Kimi | kimi-k2 | text-embedding-v3 | `MOONSHOT_API_KEY`（embedding 同时需要 `DASHSCOPE_API_KEY`） |
+| `qwen` | Qwen | qwen-plus | text-embedding-v3 | `DASHSCOPE_API_KEY` |
+| `minimax` | MiniMax | abab6.5s-chat | embo-01 | `MINIMAX_API_KEY` |
+| `glm` | Z.AI | glm-4-plus | embedding-3 | `ZHIPUAI_API_KEY` |
+| `custom` | Custom | gpt-4o | text-embedding-3-small | `OPENAI_API_KEY` |
+
+:::info
+**Custom** profile 可以连接任意 OpenAI 兼容 API endpoint。在向导中你会被要求输入 API Base URL。
+:::
+
+---
+
+## 5. 目录结构
+
+首次运行后，DB-GPT 会在用户目录下创建如下结构：
+
+```
+~/.dbgpt/
+├── config.toml              # 记录当前 active profile 名称
+├── configs/
+│   ├── openai.toml          # OpenAI profile
+│   ├── kimi.toml            # Kimi profile
+│   └── ...                  # 每个 profile 对应一个文件
+└── workspace/
+    └── pilot/               # 运行时工作区（数据库、数据文件等）
+        ├── meta_data/
+        │   └── dbgpt.db     # SQLite 元数据库
+        └── data/            # 向量数据存储
+```
+
+### 环境变量
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| `DBGPT_HOME` | `~/.dbgpt` | 覆盖 DB-GPT home 目录 |
+| `OPENAI_API_KEY` | — | OpenAI API key（也用于 `openai` 和 `custom` profile） |
+| `MOONSHOT_API_KEY` | — | Kimi / Moonshot API key |
+| `DASHSCOPE_API_KEY` | — | Qwen / DashScope API key（也用于 Kimi embedding） |
+| `MINIMAX_API_KEY` | — | MiniMax API key |
+| `ZHIPUAI_API_KEY` | — | Z.AI / Zhipu API key |
+| `DBGPT_API_KEY` | — | 通用 API key（`--api-key` 的 fallback） |
+| `DBGPT_LANG` | `en` | UI 语言（`en` 或 `zh`） |
+
+---
+
+## 6. 常见工作流
+
+### 首次安装
+
+```bash
+pip install dbgpt-app
+dbgpt start
+# Follow the wizard → choose provider → enter API key → server starts
+```
+
+### 在不同 provider 间切换
+
+```bash
+# 创建一个 Kimi profile
+dbgpt profile create kimi
+
+# 切换到它
+dbgpt profile switch kimi
+
+# 使用新 profile 启动
+dbgpt start
+```
+
+### CI/CD 部署
+
+```bash
+export OPENAI_API_KEY=sk-xxx
+dbgpt setup --profile openai --yes
+dbgpt start web --daemon
+```
+
+### 自定义 endpoint（例如 Azure OpenAI、local vLLM）
+
+```bash
+dbgpt setup --profile custom
+# Wizard will ask for:
+#   - API base URL (e.g. http://localhost:8000/v1)
+#   - API key
+#   - Model names
+```
+
+---
+
+## 7. 可选模块
+
+默认 `pip install dbgpt-app` 会包含核心框架。你也可以通过 extras 为 LLM provider、vector store、data source 等增加能力。
+
+### LLM Providers
+
+| Extra | Provider | 关键包 |
+|-------|----------|-------------|
+| `proxy_openai` | OpenAI、Kimi、Qwen、MiniMax、Z.AI 以及任意 OpenAI-compatible API | `openai`, `tiktoken` |
+| `proxy_ollama` | Ollama（本地模型） | `ollama` |
+| `proxy_zhipuai` | Zhipu AI（GLM） | `openai` |
+| `proxy_tongyi` | Tongyi Qianwen | `openai`, `dashscope` |
+| `proxy_qianfan` | 百度千帆 | `qianfan` |
+| `proxy_anthropic` | Anthropic Claude | `anthropic` |
+
+### Vector Stores
+
+| Extra | 存储 | 关键包 |
+|-------|---------|-------------|
+| `storage_chromadb` | ChromaDB | `chromadb`, `onnxruntime` |
+| `storage_milvus` | Milvus | `pymilvus` |
+| `storage_weaviate` | Weaviate | `weaviate-client` |
+| `storage_elasticsearch` | Elasticsearch | `elasticsearch` |
+| `storage_obvector` | OBVector | `pyobvector` |
+
+### Knowledge & RAG
+
+| Extra | 增加能力 | 关键包 |
+|-------|-------------|-------------|
+| `rag` | 文档解析（PDF、DOCX、PPTX、Markdown、HTML） | `spacy`, `pypdf`, `python-docx`, `python-pptx` |
+| `graph_rag` | 基于 TuGraph / Neo4j 的 Graph RAG | `networkx`, `neo4j` |
+
+### Data Sources
+
+| Extra | 数据库 | 关键包 |
+|-------|----------|-------------|
+| `datasource_mysql` | MySQL | `mysqlclient` |
+| `datasource_postgres` | PostgreSQL | `psycopg2-binary` |
+| `datasource_clickhouse` | ClickHouse | `clickhouse-connect` |
+| `datasource_oracle` | Oracle | `oracledb` |
+| `datasource_mssql` | SQL Server | `pymssql` |
+| `datasource_spark` | Apache Spark | `pyspark` |
+| `datasource_hive` | Hive | `pyhive` |
+| `datasource_vertica` | Vertica | `vertica-python` |
+
+### 组合多个 extras 的示例
+
+```bash
+# OpenAI + ChromaDB + RAG + MySQL
+pip install "dbgpt-app[proxy_openai,storage_chromadb,rag,datasource_mysql]"
+```
+
+:::tip 最小安装
+如果你只需要核心框架而不需要任何 LLM 或存储支持：
+```bash
+pip install dbgpt-app
+```
+这会提供 CLI、FastAPI server 和 agent framework，但要真正使用它，至少还需要安装一个 LLM provider extra。
+:::
+
+---
+
+## 8. 故障排查
+
+### 端口已被占用
+
+```bash
+# 停止已有 web server
+dbgpt stop webserver --port 5670
+
+# 或改配置文件换端口
+# [service.web]
+# port = 5671
+```
+
+### 提示 “No config file found”
+
+这说明当前还没有配置任何 profile，请运行：
+
+```bash
+dbgpt setup
+```
+
+### 更换 API Key
+
+重新对同一个 profile 运行 setup 向导即可覆盖原配置：
+
+```bash
+dbgpt setup --profile openai
+# 或者直接编辑 ~/.dbgpt/configs/openai.toml
+```
+
+### 查看当前配置
+
+```bash
+dbgpt setup --show
+dbgpt profile show openai
+```
--- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/installation/index.md
+++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/installation/index.md
@@ -0,0 +1,56 @@
+---
+sidebar_position: 0
+title: 安装
+summary: "选择最适合你的 DB-GPT 安装方式：快速安装、CLI 安装或源码安装"
+read_when:
+  - 你想判断哪种安装路径最适合当前环境
+  - 你希望以最短路径完成可用的 DB-GPT 安装
+---
+
+# 安装
+
+DB-GPT 提供三种推荐安装方式。你可以根据自己的使用方式和环境选择最合适的路径。
+
+## 选择安装方式
+
+| 方式 | 适合人群 | 你会得到什么 |
+|---|---|---|
+| [快速安装](/docs/installation/quick-install) | 希望在 macOS / Linux 上最快完成首次启动的用户 | 一行安装脚本、自动生成的 provider 配置、可直接启动的 webserver |
+| [CLI 安装](/docs/getting-started/cli-quickstart) | 希望通过 PyPI 安装并使用命令行的用户 | `dbgpt` CLI、交互式向导、profile 管理能力 |
+| [源码安装](/docs/getting-started/deploy/source-code) | 开发者或需要自定义部署的用户 | 完整仓库、可编辑配置、最大灵活性 |
+
+## 推荐路径
+
+对于大多数用户，建议先使用 **快速安装**。这是从零开始到跑通 DB-GPT Web UI 的最快路径。
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh | bash
+```
+
+安装完成后，使用生成好的 profile 配置启动：
+
+```bash
+cd ~/.dbgpt/DB-GPT && uv run dbgpt start webserver --config ~/.dbgpt/configs/<profile>.toml
+```
+
+然后打开 [http://localhost:5670](http://localhost:5670)。
+
+## 什么时候选择哪种方式
+
+### 快速安装
+
+如果你想以最少步骤完成安装，并且不打算手动管理仓库结构，选择这种方式。
+
+### CLI 安装
+
+如果你想直接通过 PyPI 安装 DB-GPT，并用 `dbgpt` 命令交互式配置 provider profile，选择这种方式。
+
+### 源码安装
+
+如果你需要完整仓库用于开发、调试或自定义集成，选择这种方式。
+
+## 下一步
+
+- [快速安装](/docs/installation/quick-install)
+- [CLI 安装](/docs/getting-started/cli-quickstart)
+- [源码安装](/docs/getting-started/deploy/source-code)
--- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/installation/quick-install.md
+++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/installation/quick-install.md
@@ -0,0 +1,127 @@
+---
+sidebar_position: 1
+title: 快速安装
+summary: "使用 README 中的安装脚本，以最快方式安装 DB-GPT"
+read_when:
+  - 你希望以最短路径跑通 DB-GPT Web UI
+  - 你希望优先使用安装脚本而不是手动源码部署
+---
+
+import CommandCopyCard from "@site/src/components/mdx/CommandCopyCard";
+
+# 快速安装
+
+这是让 DB-GPT 跑起来的最快方式。安装脚本会帮你准备本地 DB-GPT 工作目录、生成 provider profile，并给出可直接运行的 webserver 启动命令。
+
+## 推荐：安装脚本
+
+如果你想从零开始，以最短路径获得一个可用的 DB-GPT Web UI，推荐直接使用安装脚本。
+
+<CommandCopyCard command={`curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh | bash`} />
+
+## 系统要求
+
+这个快速安装流程主要面向以下环境：
+
+- **macOS** 或 **Linux**
+- 可运行 `bash` 的 shell 环境
+- 可以联网下载依赖
+- 如果你要直接使用托管模型 provider，需要提前准备好 API Key
+
+:::tip 适用场景
+如果你想快速体验 DB-GPT，而不是手动管理仓库结构和依赖细节，这条路径最合适。
+:::
+
+## 使用 provider profile 安装
+
+如果你已经明确要使用哪个 provider，可以在安装时直接传入 profile 和 API Key。
+
+### OpenAI 兼容 profile
+
+<CommandCopyCard command={`curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
+  | OPENAI_API_KEY=sk-xxx bash -s -- --profile openai`} />
+
+### 通过 Moonshot API 使用 Kimi 2.5
+
+<CommandCopyCard command={`curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
+  | MOONSHOT_API_KEY=sk-xxx bash -s -- --profile kimi`} />
+
+### 通过 OpenAI 兼容接口使用 MiniMax
+
+<CommandCopyCard command={`curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
+  | MINIMAX_API_KEY=sk-xxx bash -s -- --profile minimax`} />
+
+## 复用已有本地仓库
+
+如果你已经有一个本地 DB-GPT 仓库，可以直接复用，而不是重新克隆到 `~/.dbgpt/DB-GPT`。
+
+### 使用本地仓库 + OpenAI
+
+<CommandCopyCard command={`OPENAI_API_KEY=sk-xxx \
+  bash scripts/install/install.sh --profile openai --repo-dir "$(pwd)" --yes`} />
+
+### 使用本地仓库 + Kimi
+
+<CommandCopyCard command={`MOONSHOT_API_KEY=sk-xxx \
+  bash scripts/install/install.sh --profile kimi --repo-dir "$(pwd)" --yes`} />
+
+### 使用本地仓库 + MiniMax
+
+<CommandCopyCard command={`MINIMAX_API_KEY=sk-xxx \
+  bash scripts/install/install.sh --profile minimax --repo-dir "$(pwd)" --yes`} />
+
+## 安装脚本会准备什么
+
+安装脚本会帮你准备一套通用运行布局：
+
+- 在 `~/.dbgpt/DB-GPT` 下放置一个 DB-GPT checkout（如果没有使用 `--repo-dir`）
+- 在 `~/.dbgpt/configs/` 下生成 provider 配置文件
+- 在 `~/.dbgpt/` 下准备 DB-GPT home 目录
+- 给出一个基于生成 profile 的 webserver 启动命令
+
+## 安装完成后启动 DB-GPT
+
+安装完成后，使用生成的 profile 配置启动 webserver：
+
+<CommandCopyCard command={`cd ~/.dbgpt/DB-GPT && uv run dbgpt start webserver --config ~/.dbgpt/configs/<profile>.toml`} />
+
+然后打开 [http://localhost:5670](http://localhost:5670)。
+
+## 验证安装是否成功
+
+如果满足以下条件，就说明安装成功：
+
+- webserver 启动时没有配置错误
+- Web UI 能在 `http://localhost:5670` 打开
+- 你可以在浏览器中发起聊天
+
+## 先查看安装脚本
+
+如果你希望先审查脚本内容，再决定是否执行：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh -o install.sh
+less install.sh
+bash install.sh --profile openai
+```
+
+## 其他安装方式
+
+如果安装脚本不适合你的环境：
+
+- 使用 [CLI 安装](/docs/getting-started/cli-quickstart)，通过 PyPI 安装并使用 `dbgpt` 命令
+- 使用 [源码安装](/docs/getting-started/deploy/source-code)，用于开发、调试和自定义部署
+
+## 故障排查
+
+### 安装脚本不适合我的 shell 或平台
+
+请改用 [CLI 安装](/docs/getting-started/cli-quickstart) 或 [源码安装](/docs/getting-started/deploy/source-code)。
+
+### 我想更细粒度地控制依赖和配置
+
+请使用 [源码安装](/docs/getting-started/deploy/source-code)。它会暴露完整仓库结构和 `uv sync` 安装流程。
+
+### 安装完成了，但 DB-GPT 启动不正常
+
+先检查 `~/.dbgpt/configs/` 下生成的配置文件，然后参考 [安装问题排查](/docs/getting-started/troubleshooting/installation)。
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -521,63 +521,11 @@ const sidebars = {
      label: "Installation",
      collapsed: false,
      collapsible: false,
-      link: {
-        type: "generated-index",
-        description: "DB-GPT supports source code, Docker, and cluster deployment modes.",
-        slug: "installation",
-      },
+      link: { type: "doc", id: "installation/index" },
      items: [
-        { type: "doc", id: "installation/sourcecode" },
-        { type: "doc", id: "installation/docker" },
-        { type: "doc", id: "installation/docker_compose" },
-        { type: "doc", id: "installation/docker-build-guide" },
-        {
-          type: "category",
-          label: "Model Service Deployment",
-          items: [
-            { type: "doc", id: "installation/model_service/stand_alone" },
-            { type: "doc", id: "installation/model_service/cluster" },
-            { type: "doc", id: "installation/model_service/cluster_ha" },
-          ],
-        },
-        {
-          type: "category",
-          label: "Other Integrations",
-          collapsed: true,
-          collapsible: true,
-          items: [
-            { type: "doc", id: "installation/integrations" },
-            {
-              type: "category",
-              label: "Datasource Integrations",
-              items: [
-                { type: "doc", id: "installation/integrations/mysql_install" },
-                { type: "doc", id: "installation/integrations/sqlite_install" },
-                { type: "doc", id: "installation/integrations/clickhouse_install" },
-                { type: "doc", id: "installation/integrations/postgres_install" },
-                { type: "doc", id: "installation/integrations/duckdb_install" },
-                { type: "doc", id: "installation/integrations/hive_install" },
-                { type: "doc", id: "installation/integrations/mssql_install" },
-                { type: "doc", id: "installation/integrations/oracle_install" },
-                { type: "doc", id: "installation/integrations/oceanbase_install" },
-                { type: "doc", id: "installation/integrations/gaussdb_install" },
-                { type: "doc", id: "installation/integrations/doris_install" },
-                { type: "doc", id: "installation/integrations/starrocks_install" },
-                { type: "doc", id: "installation/integrations/vertica_install" },
-              ],
-            },
-            {
-              type: "category",
-              label: "RAG Integrations",
-              items: [
-                { type: "doc", id: "installation/integrations/graph_rag_install" },
-                { type: "doc", id: "installation/integrations/oceanbase_rag_install" },
-                { type: "doc", id: "installation/integrations/bm25_rag_install" },
-                { type: "doc", id: "installation/integrations/milvus_rag_install" },
-              ],
-            },
-          ],
-        },
+        { type: "doc", id: "installation/quick-install", label: "Quick Install" },
+        { type: "doc", id: "getting-started/cli-quickstart", label: "CLI Install" },
+        { type: "doc", id: "getting-started/deploy/source-code", label: "Source Install" },
      ],
    },
  ],