docs: clarify upgrade workflow (#5654)

* docs: clarify upgrade workflow

* docs: fix upgrade section placement

README.md

@@ -62,6 +62,7 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe
     - [Running the Application](#running-the-application)
       - [Deployment Sizing](#deployment-sizing)
       - [Option 1: Docker (Recommended)](#option-1-docker-recommended)
+      - [Upgrading an existing checkout](#upgrading-an-existing-checkout)
       - [Option 2: Local Development](#option-2-local-development)
     - [Advanced](#advanced)
       - [Sandbox Mode](#sandbox-mode)
@@ -404,6 +405,15 @@ DeerFlow still uses `Forwarded` / `X-Forwarded-*` headers to recover the browser
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.
 
+#### Upgrading an existing checkout
+
+Keep `config.yaml`, `.env`, and `extensions_config.json`. Stop the services you
+currently use, run `git pull --ff-only`, then start the same mode again. Do not run
+`make config` or `make docker-init` again for a routine source upgrade. If the new
+version requires configuration changes, run `make config-upgrade` before restarting.
+See [Operations and Troubleshooting](frontend/src/content/en/application/operations-and-troubleshooting.mdx#upgrading-an-existing-checkout)
+for the commands for each mode.
+
 #### Option 2: Local Development
 
 If you prefer running services locally:

README_zh.md

@@ -55,6 +55,7 @@ DeerFlow 新近集成了 BytePlus 自研的智能搜索与抓取工具集——[
     - [运行应用](#运行应用)
       - [部署建议与资源规划](#部署建议与资源规划)
       - [方式一：Docker（推荐）](#方式一docker推荐)
+      - [升级已有的代码仓库](#升级已有的代码仓库)
       - [方式二：本地开发](#方式二本地开发)
     - [进阶配置](#进阶配置)
       - [Sandbox 模式](#sandbox-模式)
@@ -278,6 +279,13 @@ make down   # 停止并移除容器
 
 更完整的 Docker 开发说明见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
+#### 升级已有的代码仓库
+
+保留现有的 `config.yaml`、`.env` 和 `extensions_config.json`。停止当前运行的服务后，
+执行 `git pull --ff-only`，再按原运行方式启动。日常源码升级不需要再次运行 `make config`
+或 `make docker-init`；如果新版本需要变更配置，请在重启前运行 `make config-upgrade`。
+各运行方式的命令见[运维与排障](frontend/src/content/zh/application/operations-and-troubleshooting.mdx#升级已有的代码仓库)。
+
 #### 方式二：本地开发
 
 如果你更希望直接在本地启动各个服务：

frontend/src/content/en/application/operations-and-troubleshooting.mdx

@@ -43,19 +43,23 @@ curl http://localhost:8001/health
 curl http://localhost:2026/api/models
 ```
 
-## Config upgrade
+## Upgrading an existing checkout
 
-When you pull a new version of DeerFlow, the `config_version` in `config.example.yaml` may be higher than your `config.yaml`. To merge new fields without losing your customizations:
+Keep your existing `config.yaml`, `.env`, and `extensions_config.json`; do not
+run `make config` again. Stop the mode you currently use, pull the update, then
+start the same mode again:
 
-```bash
-make config-upgrade
-```
+| Current mode | Stop | Pull and restart |
+| --- | --- | --- |
+| Local development | `make stop` | `git pull --ff-only && make dev` |
+| Local production | `make stop` | `git pull --ff-only && make start` |
+| Docker development | `make docker-stop` | `git pull --ff-only && make docker-start` |
+| Docker production | `make down` | `git pull --ff-only && make up` |
 
-Check the current version in your config:
-
-```bash
-grep config_version config.yaml
-```
+Do not run `make docker-init` after every `git pull`; it is for first-time
+sandbox image setup. If the new version needs configuration fields, run
+`make config-upgrade` before restarting. It preserves existing values and writes
+`config.yaml.bak` before changing the file.
 
 ## Common problems
 

frontend/src/content/zh/application/operations-and-troubleshooting.mdx

@@ -44,15 +44,21 @@ curl http://localhost:8001/health
 curl http://localhost:2026/api/models
 ```
 
-## 配置升级
+## 升级已有的代码仓库
 
-当 `config.yaml` schema 更新时（由 `config_version` 字段标识），运行：
+保留现有的 `config.yaml`、`.env` 和 `extensions_config.json`，不要再次运行
+`make config`。先停止当前使用的运行模式，拉取更新，再用原模式启动：
 
-```bash
-make config-upgrade
-```
+| 当前模式 | 停止命令 | 拉取更新并重启 |
+| --- | --- | --- |
+| 本地开发 | `make stop` | `git pull --ff-only && make dev` |
+| 本地生产 | `make stop` | `git pull --ff-only && make start` |
+| Docker 开发 | `make docker-stop` | `git pull --ff-only && make docker-start` |
+| Docker 生产 | `make down` | `git pull --ff-only && make up` |
 
-这将 `config.example.yaml` 中的新字段合并到你现有的 `config.yaml` 中，而不覆盖你的自定义内容。
+不需要在每次 `git pull` 后运行 `make docker-init`，它只用于首次准备 sandbox 镜像。
+如果新版本需要新增配置字段，请在重启前运行 `make config-upgrade`；该命令会保留已有值，
+并在修改前生成 `config.yaml.bak`。
 
 ## 常见问题