feat: 补充备份还原文档

Author: Fit111

docs/faq/installation.md

@@ -90,3 +90,8 @@
     POSTGRES_USER=root
     POSTGRES_PASSWORD=Password123@pg
     ```
+
+## 5 如何备份和还原 SQLBot？
+
+!!! Abstract ""
+    SQLBot 没有独立的备份命令。内置 PostgreSQL 建议停服后打包运行目录中的 `data`、`conf` 和 `.env`；外置 PostgreSQL 请使用 `pg_dump`，并同时备份 Excel、图片等文件目录。完整步骤见 [备份还原](../installation/backup.md)。

docs/installation/backup.md

@@ -0,0 +1,110 @@
+!!! Abstract ""
+    SQLBot 的 `sctl` **不提供** backup / restore 命令。升级、迁移前请手动备份；还原须在 **相同版本** 上进行。
+
+    先确认当前是内置库还是外置库：
+
+    ```bash
+    grep SQLBOT_EXTERNAL_DB /opt/sqlbot/.env
+    grep POSTGRES_SERVER /opt/sqlbot/conf/sqlbot.conf
+    ```
+
+    - `SQLBOT_EXTERNAL_DB=false` 且 `POSTGRES_SERVER=localhost`：内置库（默认）
+    - `SQLBOT_EXTERNAL_DB=true`，或 `POSTGRES_SERVER` 指向其他主机：外置库（含多数 1Panel 场景）
+
+## 1 需要备份什么
+
+!!! Abstract ""
+    默认安装目录为 `/opt/sqlbot`。docker 一键运行时，路径相对执行目录下的 `./data`。
+
+    | 内容 | 路径 / 对象 | 说明 |
+    | ---- | ----------- | ---- |
+    | 元数据库 | 内置：`data/postgresql`<br>外置：外部 PostgreSQL 的 `sqlbot` 库 | 用户、工作空间、数据源、问数记录、术语、SQL 示例等 |
+    | 业务文件 | `data/sqlbot/excel`、`data/sqlbot/file`、`data/sqlbot/images` | 与库中记录对应；日志 `logs` 可不备份 |
+    | 配置 | `.env`、`conf/sqlbot.conf`、`docker-compose.yml` | 须与数据库成套还原；尤其保留原 `SECRET_KEY` |
+
+    !!! Warning ""
+        外置库时，宿主机 `data/postgresql` **不是** 业务数据，请备份外部 PostgreSQL。外置库需支持向量扩展（pgvector）。
+
+## 2 备份
+
+### 2.1 内置库（推荐）
+
+!!! Abstract ""
+    停服后打包运行数据与配置，一致性最好：
+
+    ```bash
+    sctl stop
+
+    tar -zcvf /opt/sqlbot-backup-$(date +%F).tar.gz \
+      --exclude='sqlbot/data/sqlbot/logs' \
+      -C /opt sqlbot/data sqlbot/conf sqlbot/.env sqlbot/docker-compose.yml
+
+    sctl start
+    ```
+
+    无 `sctl` 时（docker 一键运行）先执行 `docker stop sqlbot`，再打包当前目录下的 `./data`，最后 `docker start sqlbot`。
+
+### 2.2 外置库
+
+!!! Abstract ""
+    （1）备份外部库（连接信息以 `conf/sqlbot.conf` 为准）：
+
+    ```bash
+    export PGPASSWORD='YourPassword'
+    pg_dump -h <DB_HOST> -p 5432 -U root -d sqlbot -Fc -f ./sqlbot-$(date +%F).dump
+    ```
+
+    本机无客户端时：
+
+    ```bash
+    docker run --rm -e PGPASSWORD='YourPassword' \
+      -v $(pwd):/backup pgvector/pgvector:pg17 \
+      pg_dump -h <DB_HOST> -p 5432 -U root -d sqlbot -Fc -f /backup/sqlbot.dump
+    ```
+
+    （2）再打包业务文件与配置：
+
+    ```bash
+    tar -zcvf ./sqlbot-files-$(date +%F).tar.gz \
+      --exclude='sqlbot/data/sqlbot/logs' \
+      -C /opt sqlbot/data/sqlbot sqlbot/conf sqlbot/.env sqlbot/docker-compose.yml
+    ```
+
+    1Panel 也可使用其 PostgreSQL 备份能力，并备份应用持久化目录中的 excel / file / images 及环境变量。
+
+## 3 还原
+
+!!! Abstract ""
+    还原前：目标环境已安装相同版本；先备份目标侧现有数据；内置库与外置库不要交叉覆盖。
+
+### 3.1 内置库
+
+!!! Abstract ""
+    ```bash
+    sctl stop
+    mv /opt/sqlbot /opt/sqlbot-$(date +%F)-bak
+    # 先安装相同版本后，再覆盖数据与配置
+    tar -zxvf /opt/sqlbot-backup-YYYY-MM-DD.tar.gz -C /opt
+    sctl start
+    ```
+
+
+### 3.2 外置库
+
+!!! Abstract ""
+    ```bash
+    export PGPASSWORD='YourPassword'
+    psql -h <DB_HOST> -p 5432 -U root -d postgres -c "CREATE DATABASE sqlbot;"
+    psql -h <DB_HOST> -p 5432 -U root -d sqlbot -c "CREATE EXTENSION IF NOT EXISTS vector;"
+    pg_restore -h <DB_HOST> -p 5432 -U root -d sqlbot --clean --if-exists ./sqlbot-YYYY-MM-DD.dump
+    ```
+
+    再解压文件备份到运行目录，确认 `POSTGRES_*`、`SECRET_KEY` 与备份一致后执行 `sctl restart`。
+
+## 4 还原后检查
+
+!!! Abstract ""
+    - `sctl status` 或 `docker ps` 正常，可用原管理员账号登录
+    - 抽查数据源、Excel、历史问数、术语 / SQL 示例
+    - 迁移后若 MCP 无图，按 [数据迁移](migration.md) 修改 `SERVER_IMAGE_HOST`
+    - 升级场景请先完成本文备份，再执行 [离线升级](offline_upgrade.md)

docs/installation/migration.md

@@ -1,5 +1,5 @@
 !!! Abstract ""
-	SQLBot 的迁移工作建议在同版本的情况下进行。如源服务器上的 SQLBot 版本是 v1.4.0，则目标服务器上请先安装好 v1.4.0 版本的 SQLBot。
+	SQLBot 的迁移工作建议在同版本的情况下进行。如源服务器上的 SQLBot 版本是 v1.4.0，则目标服务器上请先安装好 v1.4.0 版本的 SQLBot。迁移前请先按 [备份还原](backup.md) 做好备份。若使用外置数据库，除复制运行目录外，还需单独迁移 PostgreSQL 中的 `sqlbot` 库。
 
 ## 停止服务
 

docs/installation/offline_upgrade.md

@@ -15,4 +15,4 @@
 	sctl status
 	```
 
-	**注意：升级前做好数据库的备份工作是一个良好的习惯。**
+	**注意：升级前请先做好备份，可参考 [备份还原](backup.md)。**

mkdocs.yml

@@ -1,5 +1,6 @@
 site_name: 'SQLBot 文档'
 site_url: 'https://sqlbot.cn/docs'
+use_directory_urls: false
 site_description: 'SQLBot 是基于大模型和 RAG 的智能问数系统'
 site_author: '飞致云'
 repo_name: 'SQLBot'
@@ -51,6 +52,7 @@ nav:
         - Windows 下安装: installation/windows_installation.md
         - 命令行工具: installation/cli.md
         - 源码运行: installation/source_run.md
+        - 备份还原: installation/backup.md
         - 数据迁移: installation/migration.md
     - 功能手册:
         - 数据源: