sql升级方案完结

Author: biliww

.gitignore

@@ -18,7 +18,8 @@ logs/
 .env
 .env.*
 !.env.example
-
+scripts/**/*.env
+./scripts/**/*.env
 # Node.js
 node_modules/
 .nuxt/

docs/部署/09-后端版本升级（SQL+代码）线上最便捷升级方案.md

@@ -1,186 +1,92 @@
-# 后端版本升级（SQL+代码）线上最便捷升级方案
+# SQL 升级方案（两种链路）
 
 ## 文档目标
 
-本文档用于约束 `Yunyu` 在“后端代码 + SQL 同时变更”时的线上升级流程，目标是：
+本文档仅说明 `Yunyu` 的 SQL 升级方案，统一为两种可执行链路：
 
-1. 升级过程可重复执行。
-2. 停机时间最短。
-3. 出问题可快速回滚。
+1. 增量升级链路（Diff + Apply）
+2. 全量同步链路（本地库全量覆盖远程库）
 
-## 一、适用范围
+## 一、方案 A：增量升级链路（推荐生产）
 
-适用于当前仓库的两种后端部署方式：
+### 1. 适用场景
 
-1. 标准镜像：`docker-compose.yml` 中的 `yunyu-server`
-2. Native 镜像：`docker/native-image/docker-compose.yml` 中的 `yunyu-server-native`
+1. 线上已有业务数据，不能被覆盖。
+2. 只希望补齐新表、新字段、新索引和缺失配置键。
+3. 需要可重复执行、可审阅 SQL 差异。
 
-数据库默认是同一个 MySQL 服务：`yunyu-mysql`。
+### 2. 核心特点
 
-## 二、一句话策略（最便捷）
+1. 以 `docs/技术/sql/init.sql` 作为目标基线。
+2. 先拉取远端库 schema 快照，再做差异对比。
+3. 只生成安全边界内 SQL：`CREATE TABLE IF NOT EXISTS`、`ADD COLUMN`、`ADD KEY`、`site_config` 缺失 key 补齐。
+4. 默认先备份数据库再执行差异 SQL。
 
-最便捷升级策略：`先备份数据库 -> 执行向后兼容 SQL -> 拉取新镜像并只重建后端容器 -> 健康检查 -> 观察日志`。
+### 3. 执行命令
 
-说明：
-
-1. 不执行 `docker compose down -v`，避免误伤数据库。
-2. SQL 优先做“向后兼容变更”（新增列/新增表/新增索引），避免代码切换瞬间读写失败。
-3. 镜像必须保留上一版 Tag，确保可快速回滚代码版本。
-
-## 三、发布前清单（必须）
-
-上线前准备以下内容：
-
-1. 本次升级 SQL：建议放到 `docs/技术/sql/upgrade/`（按版本号命名）。
-2. SQL 回滚脚本（可逆变更必须准备）。
-3. 本次发布镜像 Tag（例如 `v2026.04.25-01`）和上一版稳定 Tag。
-4. 升级窗口与负责人（执行人/验证人）。
-
-推荐 SQL 命名：
-
-```text
-V20260425_001__add_post_status.sql
-R20260425_001__rollback_add_post_status.sql
-```
-
-## 四、标准升级流程（生产可执行）
-
-### 步骤 1：数据库备份
-
-优先复用仓库已有脚本：
+准备配置文件（首次）：
 
 ```bash
-bash scripts/mysql/backup-remote-db.sh
+cp scripts/release/schema-diff.env.example scripts/release/schema-diff.env
 ```
 
-说明：
-
-1. 需先准备 `scripts/mysql/mysql-sync.env`。
-2. 备份成功后，记录 SQL 文件路径，作为回滚输入。
-
-### 步骤 2：执行 SQL 升级
-
-推荐在服务器执行（以标准 compose 为例）：
+生成差异 SQL：
 
 ```bash
-docker compose exec -T yunyu-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < docs/技术/sql/upgrade/V20260425_001__add_post_status.sql
+bash scripts/release/schema-diff.sh
 ```
 
-如果是 Native compose：
+执行差异 SQL（自动先备份）：
 
 ```bash
-docker compose -f docker/native-image/docker-compose.yml exec -T yunyu-mysql sh -c 'mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < docs/技术/sql/upgrade/V20260425_001__add_post_status.sql
+bash scripts/release/schema-apply.sh
 ```
 
-### 步骤 3：升级后端容器（只动后端，不动 MySQL）
-
-标准镜像：
+如果要执行指定 diff 文件：
 
 ```bash
-docker compose pull yunyu-server
-docker compose up -d yunyu-server
+bash scripts/release/schema-apply.sh --plan /绝对路径/你的-diff.sql
 ```
 
-Native 镜像：
-
-```bash
-docker compose -f docker/native-image/docker-compose.yml pull yunyu-server-native
-docker compose -f docker/native-image/docker-compose.yml up -d yunyu-server-native
-```
+## 二、方案 B：全量同步链路（覆盖远程库）
 
-### 步骤 4：上线验证（5 分钟内完成）
+### 1. 适用场景
 
-建议按顺序执行：
+1. 演示环境、测试环境、初始化环境。
+2. 明确要把远程库整体替换为本地库结构与数据。
 
-1. 健康检查：`/actuator/health`
-2. 核心接口抽样（登录、内容列表、详情、后台关键写接口）
-3. 错误日志观察（5~10 分钟）
+### 2. 风险说明
 
-示例：
+1. 该方案会清空远程库后再导入本地库内容。
+2. 远程现有数据会被覆盖，生产环境默认不建议使用。
 
-```bash
-curl http://127.0.0.1:20000/actuator/health
-docker compose logs -f --tail=200 yunyu-server
-```
+### 3. 执行命令
 
-Native 示例：
+准备配置文件（首次）：
 
 ```bash
-curl http://127.0.0.1:20001/actuator/health
-docker compose -f docker/native-image/docker-compose.yml logs -f --tail=200 yunyu-server-native
+cp scripts/db/mysql-sync.env.example scripts/db/mysql-sync.env
 ```
 
-## 五、回滚策略（必须提前演练）
-
-### 1. 代码回滚
-
-原则：优先回滚镜像 Tag，通常 1~3 分钟可恢复。
-
-操作方式：
-
-1. 将 `.env` 中后端镜像变量改回上一版 Tag。
-2. 执行 `docker compose up -d <后端服务名>` 重建容器。
-
-### 2. SQL 回滚
-
-原则：
-
-1. 仅当本次 SQL 与旧代码不兼容时执行。
-2. 优先使用预先准备好的回滚 SQL。
-3. 若无法安全回滚，使用备份恢复：
+执行总流程（备份 -> 覆盖同步 -> 输出回滚提示）：
 
 ```bash
-bash scripts/mysql/restore-remote-db.sh <备份文件路径>
-```
-
-## 六、SQL 变更约束（降低升级风险）
-
-生产升级建议遵循：
-
-1. 避免“同次发布立即删列/改列类型”。
-2. 默认采用“扩展优先、收缩滞后”两阶段模式：
-   阶段 A：新增字段并让新旧代码都可运行。
-   阶段 B：观察稳定后，再删除旧字段或旧逻辑。
-3. 关键 DDL 尽量写成可重复执行（例如 `IF NOT EXISTS`）。
-4. 对大表加索引优先评估执行时长，必要时单独窗口执行。
-
-## 七、已落地的自动升级脚本
-
-当前仓库已新增以下脚本：
+bash scripts/db/run-sync-flow.sh
 
-1. `scripts/deploy/schema-diff.sh`
-   作用：以 `docs/技术/sql/init.sql` 为目标结构，自动生成“新增表/新增字段/新增索引”的差异 SQL。
-2. `scripts/deploy/schema-apply.sh`
-   作用：执行“生成差异 -> 备份远程库 -> 应用差异 SQL -> 记录执行历史”的自动流程。
+bash scripts/db/run-sync-flow.sh --yes
 
-脚本说明文档：
-
-1. `scripts/deploy/README.md`
-
-## 八、推荐执行顺序（可直接照抄）
-
-### 1. 先预览 SQL 差异（人工确认）
-
-```bash
-bash scripts/deploy/schema-diff.sh
+MYSQL_AUTO_CONFIRM_ALL=true bash scripts/db/run-sync-flow.sh
 ```
 
-### 2. 执行数据库结构升级（自动先备份）
+## 三、回滚命令
 
-```bash
-bash scripts/deploy/schema-apply.sh
-```
-
-### 3. 升级 Native 后端镜像
+两种链路都可使用数据库备份恢复：
 
 ```bash
-docker compose -f docker/native-image/docker-compose.yml pull yunyu-server-native
-docker compose -f docker/native-image/docker-compose.yml up -d yunyu-server-native
+bash scripts/db/restore-remote-db.sh /绝对路径/备份文件.sql
 ```
 
-### 4. 健康检查与日志观察
+## 四、选择建议
 
-```bash
-curl http://127.0.0.1:20001/actuator/health
-docker compose -f docker/native-image/docker-compose.yml logs -f --tail=200 yunyu-server-native
-```
+1. 生产环境优先用方案 A（增量升级链路）。
+2. 非生产覆盖式同步才用方案 B（全量同步链路）。

scripts/README.md

@@ -0,0 +1,18 @@
+# 脚本目录说明
+
+本目录已按职责统一为两类：
+
+1. `db/`：数据库备份、恢复、同步脚本。
+2. `release/`：发布、差异 SQL、升级与回滚脚本。
+
+## 兼容说明
+
+为避免历史命令失效，保留了两个兼容软链接：
+
+1. `mysql -> db`
+2. `deploy -> release`
+
+建议后续统一使用新路径：
+
+1. `scripts/db/...`
+2. `scripts/release/...`

scripts/mysql/.gitignore scripts/db/.gitignorescripts/mysql/.gitignore renamed to scripts/db/.gitignore

@@ -16,7 +16,7 @@
 1. 复制配置文件：
 
 ```bash
-cp scripts/mysql/mysql-sync.env.example scripts/mysql/mysql-sync.env
+cp scripts/db/mysql-sync.env.example scripts/db/mysql-sync.env
 ```
 
 2. 填写本地和远程数据库连接信息。
@@ -46,7 +46,7 @@ MYSQL_CLIENT_IMAGE=mysql:8
 docker images | grep mysql
 ```
 
-然后把已有镜像名写到 `scripts/mysql/mysql-sync.env` 中。
+然后把已有镜像名写到 `scripts/db/mysql-sync.env` 中。
 
 ## 连接说明
 
@@ -70,25 +70,31 @@ LOCAL_DB_PORT=3306
 ### 1. 备份远程数据库
 
 ```bash
-bash scripts/mysql/backup-remote-db.sh
+bash scripts/db/backup-remote-db.sh
 ```
 
 默认会把备份文件生成到：
 
 ```bash
-scripts/mysql/backups/
+scripts/db/backups/
 ```
 
 如果你想自定义备份目录，可以在执行时指定：
 
 ```bash
-MYSQL_BACKUP_DIR=/自定义目录 bash scripts/mysql/backup-remote-db.sh
+MYSQL_BACKUP_DIR=/自定义目录 bash scripts/db/backup-remote-db.sh
 ```
 
 ### 2. 删除远程数据库全部表
 
 ```bash
-bash scripts/mysql/reset-remote-db.sh
+bash scripts/db/reset-remote-db.sh
+```
+
+如果你希望跳过手工确认，可使用：
+
+```bash
+bash scripts/db/reset-remote-db.sh --yes
 ```
 
 执行前会要求你输入确认文本，例如：
@@ -100,7 +106,7 @@ DELETE yunyu
 ### 3. 从备份文件恢复远程数据库
 
 ```bash
-bash scripts/mysql/restore-remote-db.sh scripts/mysql/backups/你的备份文件.sql
+bash scripts/db/restore-remote-db.sh scripts/db/backups/你的备份文件.sql
 ```
 
 执行前会要求你输入确认文本，例如：
@@ -112,7 +118,13 @@ RESTORE yunyu
 ### 4. 把本地数据库全量同步到远程
 
 ```bash
-bash scripts/mysql/sync-local-to-remote.sh
+bash scripts/db/sync-local-to-remote.sh
+```
+
+如果你希望跳过手工确认，可使用：
+
+```bash
+bash scripts/db/sync-local-to-remote.sh --yes
 ```
 
 执行前会要求你输入确认文本，例如：
@@ -130,7 +142,19 @@ SYNC yunyu TO yunyu
 ### 5. 使用总入口脚本执行完整同步流程
 
 ```bash
-bash scripts/mysql/run-sync-flow.sh
+bash scripts/db/run-sync-flow.sh
+```
+
+如果你希望整条链路自动确认（包含内部同步与清库确认），可使用：
+
+```bash
+bash scripts/db/run-sync-flow.sh --yes
+```
+
+或环境变量方式：
+
+```bash
+MYSQL_AUTO_CONFIRM_ALL=true bash scripts/db/run-sync-flow.sh
 ```
 
 执行过程会输出完整日志，包括：