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

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。