zeaslity/ProjectAGiPrompt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

超大量更新

Browse Source
This commit is contained in:
zeaslity
2026-04-29 09:46:36 +08:00
parent ed945abdf1
commit e7c301023c
349 changed files with 83923 additions and 560 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
24-版本升级标准流程/1-数据库表结构同步-prompt.md Normal file
View File

@@ -0,0 +1,95 @@
你是一名精通MySQL数据库的专家，可以作为专业的DBA进行分析。现在有如下的业务流程需要满足
### 项目升级流程
1. 特战队-项目运行数据库及表结构导出 可能无法直连
2. 特战队-创建临时MySQL，导入上述的表结构 可以直连
3. 研发人员-基于临时MySQL 进行数据库版本升级，升级到最新的数据库结构
1. 研发人员需要提供增量升级的脚本
2. 研发人员需要提供执行成功的证明
3. 特战队-基于研发人员提供的增量升级脚本，在项目运行数据库上执行
### 统一导入导出工具
1. 由于研发人员对于mysql二进制客户端不熟练，需要提供一个统一的导入导出工具
2. 项目无法直连，无法使用Navicat DatGrip等工具
3. 80%的项目可以直连
4. 研发人员通常使用Navicat DatGrip等工具进行数据库操作
5. 工具需要适配windows linux等环境，降级为支持linux即可
6. 工具需要支持不同的CPU架构 x86 arm64
6. 工具需要支持linux的不同发行版
请你基于上面的需求，给出一个可行的方案 请不要废话，直接给出简洁 专业 精炼的答案
导入导出工具可以自己做，底层别自己造协议轮子；增量升级 SQL 必须由研发维护 migration；比对功能可做辅助校验，但不应成为升级方案的核心。
db-tool 应具备的命令能力
建议统一成这种风格：
db-tool export-structure
db-tool import-structure
db-tool run-upgrade
db-tool verify-upgrade
db-tool diff-schema
db-tool pack
1. export-structure
用途：导出结构基线
例如：
db-tool export-structure \
--host 127.0.0.1 \
--port 3306 \
--user root \
--schema app_db \
--out ./export
输出：
schema.sql
routines.sql
manifest.json
log
2. import-structure
用途：向临时库导入结构
db-tool import-structure \
--host 127.0.0.1 \
--port 3306 \
--user root \
--schema app_db_tmp \
--input ./export
3. run-upgrade
用途：执行升级包
db-tool run-upgrade \
--host 127.0.0.1 \
--port 3306 \
--user root \
--schema app_db_tmp \
--package ./upgrade-package
4. verify-upgrade
用途：输出成功证明
内容建议包括：
当前版本查询结果
关键表/列存在性检查
索引检查
视图/过程检查
checksum 或对象清单
5. diff-schema
用途：比对升级前后结构差异
建议底层调用：
mysqldump --no-data
再做文本标准化 diff
6. pack
将交付物打包，便于特战队传递使用

91
24-版本升级标准流程/2-增量升级流程图.md Normal file
View File

@@ -0,0 +1,91 @@
```mermaid
%%{init: {
"theme": "default",
"themeVariables": {
"fontFamily": "Microsoft YaHei, PingFang SC, Noto Sans SC, SimHei, sans-serif"
}
}}%%
flowchart TD
A["① 特战队：导出现场数据库表结构基线<br/>db-operator export-structure"]
B["② 特战队：创建临时 MySQL，导入结构基线<br/>db-operator import-structure"]
subgraph LOOP["③ 研发人员：升级迭代循环（可能多轮）"]
C1["③-a 重置临时库到基线状态<br/>db-operator reset-database"]
C2["③-b 执行增量升级脚本<br/>db-operator run-upgrade"]
C3["③-c 验证升级结果<br/>db-operator verify-upgrade"]
D{"验证是否通过？"}
C4["③-d 修改 migration 脚本"]
C1 --> C2 --> C3 --> D
D -- 否 --> C4 --> C1
end
E["④ 研发人员：比对升级前后结构差异（可选）<br/>db-operator diff-schema"]
F["⑤ 研发人员：打包全部交付物<br/>db-operator pack"]
G["交付包传递给特战队"]
H["⑥ 特战队：在现场数据库执行增量升级脚本<br/>db-operator run-upgrade"]
I["⑦ 特战队：执行验证并生成现场成功证明<br/>db-operator verify-upgrade"]
A --> B --> C1
D -- 是 --> E --> F --> G --> H --> I
```
```mermaid
%%{init: {
"theme": "default",
"themeVariables": {
"fontFamily": "Microsoft YaHei, PingFang SC, Noto Sans SC, SimHei, sans-serif"
}
}}%%
flowchart TB
%% =========================
%% 时间顺序：自上而下
%% =========================
subgraph T0["阶段一：特战队提供"]
direction TB
A["1. 导出现场数据库表结构基线<br/>命令：db-operator export-structure"]
B["2. 创建临时 MySQL 并导入结构基线<br/>命令：db-operator import-structure"]
A --> B
end
subgraph T1["阶段二：研发人员提供升级SQL"]
direction TB
C1["3.1 重置临时库到基线状态<br/>命令：db-operator reset-database"]
C2["3.2 执行增量升级脚本<br/>命令：db-operator run-upgrade"]
C3["3.3 验证升级结果<br/>命令：db-operator verify-upgrade"]
D{"是否满足转交条件？"}
C4["3.4 修改 migration 脚本"]
E["3.5 比对升级前后结构差异（可选）<br/>命令：db-operator diff-schema"]
F["3.6 打包交付物并移交特战队<br/>命令：db-operator pack"]
C1 --> C2 --> C3 --> D
D -- 否 --> C4 --> C1
D -- 是 --> E --> F
end
subgraph S["研发转交标准"]
direction TB
S1["提供run-upgrade命令执行成功截图"]
S2["提供diff-schema结构差异执行结果截图"]
S1 --> S2
end
subgraph T2["阶段三：特战队执行升级"]
direction TB
G["4. 接收研发交付包"]
H["5. 生产数据库执行升级脚本<br/>命令：db-operator run-upgrade"]
I["6. 验证并生成成功证明<br/>命令：db-operator verify-upgrade"]
G --> H --> I
end
B --> C1
F -- 满足 --> S
S --> G
```

131
24-版本升级标准流程/3-命令总览.md Normal file
View File

@@ -0,0 +1,131 @@
### 4.1 命令总览
```bash
db-operator <command> [connection-flags] [command-flags]
Commands:
export-structure 导出目标数据库的表结构基线（DDL）
import-structure 向目标数据库导入表结构基线
reset-database 重置数据库到基线状态（DROP + CREATE + 重新导入）
run-upgrade 执行增量升级 SQL 脚本
verify-upgrade 验证升级结果，生成成功证明报告
diff-schema 比对两份结构基线的差异
pack 将交付物打包为标准交付包
version 输出工具版本及内置 MySQL 客户端版本
help 帮助信息
Connection Flags（需要连接数据库的命令通用）:
-H, --host 数据库主机地址（默认: 127.0.0.1）
-P, --port 数据库端口（默认: 3306）
-u, --user 数据库用户名（默认: root）
-p, --password 数据库密码（若未指定则交互式提示输入）
--charset 字符集（默认: utf8mb4）
Global Flags:
-v, --verbose 启用详细输出
--dry-run 仅预览操作，不实际执行
--yes 跳过确认提示，直接执行
--mysql-bin 指定 MySQL 客户端二进制所在目录（默认使用内置客户端）
```
> **无状态设计（ADR-6）**：工具不使用配置文件、不维护任何本地状态。每次调用通过 CLI 参数传入连接信息，仅连接单个数据库实例。密码也可通过环境变量 `DB_OPERATOR_PASSWORD` 传入以避免命令行暴露。
> **Docker 模式下的路径约定**：容器中所有文件 I/O 路径均相对于 `/data` 工作目录。用户通过 `-v` 挂载宿主目录到 `/data`，容器内的路径引用即对应宿主目录下的相对路径。详见 §6。
### 4.2 命令详细规格
#### 4.2.1 `export-structure` — 导出结构基线
| 属性 | 说明 |
|--------------|----------------------------------------------------------------------|
| **用途** | 连接目标 MySQL，导出全部/指定数据库的表结构（不含数据） |
| **底层调用** | `mysqldump --no-data --routines --triggers --events` |
| **输出** | `<output-dir>/<database>_structure_<timestamp>.sql` |
| **关键参数** | `--databases`：指定数据库列表（逗号分隔），不指定则导出全部 |
| | `--output-dir`：输出目录（默认: `./export/`） |
#### 4.2.2 `import-structure` — 导入结构基线
| 属性 | 说明 |
|--------------|----------------------------------------------------------------------|
| **用途** | 将 `export-structure` 产出的 SQL 文件导入到目标 MySQL |
| **底层调用** | `mysql < structure.sql` |
| **输入** | 一个或多个 `.sql` 文件路径 |
| **关键参数** | `--input`：SQL 文件路径（必填，支持 glob 模式如 `./export/*.sql`） |
| | `--create-db`：若数据库不存在则自动创建（默认: `true`） |
#### 4.2.3 `reset-database` — 重置数据库到基线状态
| 属性 | 说明 |
|--------------|----------------------------------------------------------------------|
| **用途** | 将目标数据库销毁并从基线 SQL 文件重新创建，恢复到 `import-structure` 的初始状态 |
| **适用场景** | 研发人员调试 migration 脚本时多次重试，每次需要干净的起点 |
| **执行逻辑** | 1. `DROP DATABASE IF EXISTS <database>` |
| | 2. `CREATE DATABASE <database> DEFAULT CHARSET=<charset>` |
| | 3. `mysql <database> < baseline.sql`（重新导入基线结构） |
| **关键参数** | `--database`：目标数据库名（必填） |
| | `--baseline`：基线 SQL 文件路径（必填，即 `export-structure` 的产物） |
| **安全约束** | 执行前输出 **"即将销毁数据库 xxx，是否继续？[y/N]"** 确认提示 |
| | 使用 `--yes` 可跳过确认（适用于脚本化场景） |
| | `--dry-run` 模式下仅输出将要执行的操作，不实际执行 |
> ⚠️ **风险警告**：此命令会**彻底销毁**目标数据库的所有数据与结构。仅应在临时库/开发环境使用，**严禁在生产环境执行**。
#### 4.2.4 `run-upgrade` — 执行增量升级脚本
| 属性 | 说明 |
|--------------|----------------------------------------------------------------------|
| **用途** | 按顺序执行研发维护的增量 migration SQL 脚本 |
| **底层调用** | `mysql < migration.sql`（按文件名自然排序依次执行） |
| **输入** | migration 脚本目录 |
| **关键参数** | `--migration-dir`：脚本目录（默认: `./migrations/`） |
| | `--database`：目标数据库名（必填） |
| | `--from`：起始版本号（可选，按文件名前缀过滤） |
| | `--to`：结束版本号（可选） |
| **执行逻辑** | 1. 扫描目录中所有 `.sql` 文件，按文件名自然排序 |
| | 2. 若指定 `--from`/`--to`，过滤文件名范围 |
| | 3. 逐个执行，任一脚本失败立即中止，输出失败脚本名及错误信息 |
| | 4. 执行结果写入日志文件 |
#### 4.2.5 `verify-upgrade` — 验证升级结果
| 属性 | 说明 |
|--------------|----------------------------------------------------------------------|
| **用途** | 升级后重新导出结构，与预期结构进行比对，生成验证报告 |
| **输出** | `<output-dir>/verify_report_<timestamp>.json` |
| **报告内容** | 执行时间、执行环境（OS/Arch）、数据库版本、各脚本执行状态、 |
| | 升级前后表数量对比、结构差异摘要 |
| **关键参数** | `--baseline`：升级前的结构文件（用于对比） |
| | `--database`：目标数据库名（必填） |
| | `--output-dir`：报告输出目录（默认: `./reports/`） |
#### 4.2.6 `diff-schema` — 结构差异比对
| 属性 | 说明 |
|--------------|----------------------------------------------------------------------|
| **用途** | 比对两份结构 SQL 文件的差异，输出人可读的差异报告 |
| **定位** | **仅做校验辅助，不生成可执行的 DDL SQL**（遵循 ADR-4） |
| **输入** | 两份 `.sql` 结构文件 |
| **输出** | 终端输出差异摘要 + 可选写入文件 |
| **关键参数** | `--source`：源结构文件（升级前） |
| | `--target`：目标结构文件（升级后） |
| | `--output`：差异报告输出文件（可选） |
| **比对维度** | 表级别：新增表、删除表、表名变更 |
| | 列级别：新增列、删除列、类型变更、默认值变更 |
| | 索引级别：新增索引、删除索引、索引列变更 |
| | 约束级别：外键、唯一约束变更 |
> **注意**：`diff-schema` 是纯文件比对，**不需要连接数据库**，因此不需要 Connection Flags。
#### 4.2.7 `pack` — 打包交付物
| 属性 | 说明 |
|--------------|----------------------------------------------------------------------|
| **用途** | 将升级脚本、结构快照、验证报告等交付物打包为标准交付包 |
| **输出** | `<output-dir>/db-upgrade-pack_<project>_<version>_<timestamp>.tar.gz` |
| **关键参数** | `--project`：项目名称（必填） |
| | `--version`：本次升级版本号（必填） |
| | `--include-dirs`：需要打包的目录列表（默认包含 export/、migrations/、reports/） |
| | `--output-dir`：输出目录（默认: `./dist/`） |
> **注意**：`pack` 是纯文件操作，**不需要连接数据库**，因此不需要 Connection Flags。

79
24-版本升级标准流程/4-执行流程.md Normal file
View File

@@ -0,0 +1,79 @@
以下示例展示 Docker 运行方式下各命令的完整用法。假设宿主机当前工作目录为升级项目目录。
```bash
# -------------------------------------------------------
# 定义镜像别名（可选，减少输入量）
# -------------------------------------------------------
alias db-operator='docker run --rm -it \
--network host \
--user $(id -u):$(id -g) \
-v $(pwd):/data \
-e DB_OPERATOR_PASSWORD \
harbor.wdd.io:8033/rmdc/db-operator:v1.2.0'
# 执行数据库密码输入
export DB_OPERATOR_PASSWORD=XXXXXX
# -------------------------------------------------------
# ① 导出现场数据库结构基线（多个库按顺序分别导出）
# -------------------------------------------------------
db-operator export-structure \
-H 192.168.1.100 -P 3306 -u root \
--databases mydb_core,mydb_order \
--output-dir ./export/
# 导出结果示例（文件名带 001/002 序号前缀，与 --databases 顺序一致）：
# ./export/001_mydb_core_structure_<timestamp>.sql
# ./export/002_mydb_order_structure_<timestamp>.sql
# -------------------------------------------------------
# ② 导入结构基线到临时 MySQL（目录模式）
# -------------------------------------------------------
db-operator import-structure \
-H 127.0.0.1 -P 3306 -u root \
--input ./export/
# 目录模式会按文件名自然序执行（001 -> 002 -> ...）
# -------------------------------------------------------
# ②-补充：单文件导入（仍保留）
# -------------------------------------------------------
db-operator import-structure \
-H 127.0.0.1 -P 3306 -u root \
--input ./export/001_mydb_core_structure_<timestamp>.sql
# -------------------------------------------------------
# ③-a 重置数据库（--database 必须与 baseline SQL 内数据库名一致）
# -------------------------------------------------------
db-operator reset-database \
-H 127.0.0.1 -P 3306 -u root -d mydb_core \
--baseline ./export/001_mydb_core_structure_<timestamp>.sql \
--yes
# -------------------------------------------------------
# ③-b 执行增量升级
# -------------------------------------------------------
db-operator run-upgrade \
-H 127.0.0.1 -P 3306 -u root -d mydb_core \
--migration-dir ./migrations/
# -------------------------------------------------------
# ③-c 验证升级
# -------------------------------------------------------
db-operator verify-upgrade \
-H 127.0.0.1 -P 3306 -u root -d mydb_core \
--baseline ./export/001_mydb_core_structure_<timestamp>.sql
# -------------------------------------------------------
# ④ 比对差异（纯文件操作，无需 --network host）
# -------------------------------------------------------
db-operator diff-schema \
--source ./export/001_mydb_core_structure_before.sql \
--target ./export/001_mydb_core_structure_after.sql
# -------------------------------------------------------
# ⑤ 打包交付物
# -------------------------------------------------------
db-operator pack \
--project myproject --version 2.3.1
```