diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 91f3ac616..07aad88fb 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -629,6 +629,9 @@ jobs:
           prerelease: ${{ needs.release-info.outputs.prerelease == 'true' }}
           make_latest: ${{ needs.release-info.outputs.prerelease == 'true' && 'false' || 'true' }}
           body: |
+            > [!WARNING]
+            > **Upgrading from 2.x?** 3.x is a clean break: the 2.x database schema and configuration are not migrated, and the one-click self-update cannot cross major versions — do not trigger it from a 2.x admin UI. Deploy 3.x fresh (new `.runtime/` data directory) and re-import or re-authorize provider accounts and client keys. See the [upgrade notes](https://github.com/${{ github.repository }}/blob/main/deploy/README.md#镜像升级与源码构建).
+
             ## 📥 Installation
 
             **Docker:**
diff --git a/README.md b/README.md
index a6c0e94b4..71f77bef7 100644
--- a/README.md
+++ b/README.md
@@ -161,6 +161,12 @@ docker compose -f deploy/compose.yaml up -d
 > `.runtime/` 保存 PostgreSQL、Redis、日志、OpenAI 会话锚点和自更新状态。删除该目录会永久清除
 > 运行状态。
 
+> [!WARNING]
+> 跨大版本（如 2.x → 3.x）不是原地升级：数据库 schema 与配置在大版本之间不迁移，内置
+> 一键自更新也会拒绝跨大版本目标（2.x 界面里的一键更新没有这道门禁，不要用它升 3.x）。
+> 升级到新的大版本需要全新部署（全新 `.runtime/` 数据目录），并重新导入或重新授权
+> Provider 账号与客户端 Key。
+
 Compose 默认只绑定 `127.0.0.1`。公网接入应使用 HTTPS 反向代理，转发 WebSocket
 upgrade 与真实客户端 IP；不要暴露 PostgreSQL 或 Redis。
 
diff --git a/deploy/README.md b/deploy/README.md
index b54850da0..30ed4a1da 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -116,6 +116,13 @@ Provider schema 以明文 JSON 保存于 PostgreSQL。Redis 只保存可重建
 
 ## 镜像升级与源码构建
 
+> [!WARNING]
+> 以下命令只适用于同一大版本内的升级。跨大版本（如 2.x → 3.x）是 clean break：
+> 数据库 schema 与配置在大版本之间不迁移，直接换镜像会导致服务无法启动；内置一键
+> 自更新在 3.x 起拒绝跨大版本目标，而 2.x 界面里的一键更新没有这道门禁，不要用它
+> 升 3.x。跨大版本请全新部署（全新 `.runtime/` 数据目录），并重新导入或重新授权
+> Provider 账号与客户端 Key。
+
 ```bash
 docker compose -f deploy/compose.yaml build codex-proxy-rs
 docker compose -f deploy/compose.yaml up -d