数据库发布与版本基线

统一版本

当前核心配置、核心插件契约、管理端、用户端、新闻插件、电商插件、OpenAPI 说明、SQL 目录及数据库当前版本统一为 0.0.1，配置和清单不使用 v 前缀。接口 URL 保持 /admin/...、/api/...，不新增版本路径。

本次是一次性基线归并。后续核心与插件各自按语义版本严格递增；每个插件的 core_version 必须精确匹配宿主插件契约版本。旧 Git 提交、标签和安装审计日志保留真实历史，不改写为新发布。

发布目录

text

server_api/sql/
├── 0.0.1/
│   ├── full.sql
│   ├── incremental.sql
│   └── release.json
└── plugins/
    └── news/
        └── 0.0.1/
            ├── full.sql
            └── incremental.sql

插件源码包/database/
└── 0.0.1/
    ├── full.sql
    └── incremental.sql

每次发版，即使没有数据库变化，也必须交付两个文件。全量是该版本完整表结构与必要初始化数据；增量只包含相对上一版本的变化，无变更时用非空注释文件明确说明。首次 0.0.1 没有前置版本，增量为说明文件，不重复执行全量结构。

全量不能简单拼接历史 ALTER，不能包含真实会员、订单、配置密钥或测试数据。核心全量只含核心表及必要初始化数据；插件独立交付业务表，菜单始终由 plugin.json.menus 交付。

自动生成新版本 SQL

在 server_api 目录使用发布命令增加版本。先编写本版增量工作文件，放在目标发布目录之外；不要手工创建目标版本目录，也不要修改历史发布文件。

# 核心：生成 sql/0.0.2/{full.sql,incremental.sql,release.json}
go run . database release --version 0.0.2 --incremental ../changes/core.sql

# 插件：生成插件仓库 database/0.0.2/{full.sql,incremental.sql}
go run . plugin release ../go_basic_frame_plugin_news \
  --version 0.0.2 --incremental ../changes/news.sql --description "本版数据库变更"

# 即使本版数据库没有变化，也生成两份 SQL
go run . plugin release ../go_basic_frame_plugin_news \
  --version 0.0.2 --no-database-change
go run . database release --version 0.0.2 --no-database-change

示例中的有变更和无变更命令是二选一，不能对同一版本重复执行。版本必须严格高于最新发布版本，已有版本目录不能覆盖。初始版本由现有基线或插件脚手架提供。

生成机制：

校验历史版本链、SHA256、SQL 范围及插件源码声明。
创建随机命名的 gbf_release_* 隔离数据库，导入上一版全量，再执行本版增量。
从隔离库导出最终建表语句和初始化数据，生成新全量；增量工作文件原样归档，无变更时自动写入说明注释。
创建第二个隔离库导入新全量，对比两种路径的结构和初始化数据；不一致则拒绝发布。
生成摘要并校验后写入新版本目录，清理临时库。插件同时同步 plugin.json、后端版本和迁移声明、已有用户端清单及脚手架信息接口的版本，并生成版本文档供审核。

这项自动化生成全量、归档增量；业务变化对应的增量 SQL 仍需开发者编写，工具不会从生产数据库自动推断差异。它不连接配置中的业务库，也不读取真实会员、订单或密钥。导出数据仅来自发布 SQL 重放，因此增量中也只能提交必要初始化数据。

可通过 --config 指定独立构建 MySQL 配置；账号需要创建、使用和删除临时数据库的权限。建议使用独立构建实例。无权限、SQL 执行失败、循环外键或暂不支持的空间字段均会中止生成。正常错误路径会清理临时库，进程被强制终止时需检查残留的 gbf_release_* 数据库。

插件 API 和数据库文档默认继承上一版并标记待审核，更新说明自动生成；也可提前编写目标版本文档。命令不推断接口变化，发行前必须审核文档、测试并执行原打包脚本。单独修改版本号不会触发生成，打包脚本也不会替代发布命令。

核心发布命令只生成数据库版本资产，不修改框架配置、SDK 契约或前端版本；正式核心发版时仍需同步这些版本。插件发布命令修改的是插件源码仓库，不升级已安装插件或其数据库，安装与升级仍执行下述流程。

生成的全量初始化数据可以保留内部主键，以确保种子数据关系一致；开发者编写的插件增量 INSERT 仍必须显式列出字段并省略自增 ID，公开接口的 UID 规则不变。

核心安装与升级

先创建空数据库并配置 config.yaml，版本为 0.0.1：

cd server_api
go run . database validate
go run . database install --config config.yaml

也可以直接向空库导入 sql/0.0.1/full.sql。初始账号为 admin，初始密码为 Admin@123456，安装后立即修改。SQL 不包含现有开发库的账户密文、存储密钥、支付密钥或业务数据。

后续更新配置版本后运行：

go run . database upgrade --config config.yaml

release.json 声明版本、前置版本以及全量、增量文件的 SHA256。命令校验完整版本链、文件目录、摘要与 SQL 操作范围，并以数据库锁串行执行。新安装只运行目标版本全量；升级核对 sys_database_version 历史记录，只执行后续增量，拒绝同版本和降级。

MySQL DDL 无法与版本元数据组成整体事务。发布前必须验证 SQL；执行失败后应检查已执行的结构变更，修复或恢复备份后再继续，不能把未完成迁移手工标记为成功。

插件安装与升级

每个清单迁移项必须声明同版本全量和增量：

json

{
  "version": "0.0.1",
  "file": "database/0.0.1/incremental.sql",
  "checksum": "增量文件SHA256",
  "full_file": "database/0.0.1/full.sql",
  "full_checksum": "全量文件SHA256",
  "description": "统一发布基线"
}

后续版本保留历史文件和迁移项，按版本严格升序排列，最后一项必须与 plugin.json.version 一致。后端 Manifest.Version、Migrations()、清单、文档和打包版本保持一致，已发布 SQL 不允许修改。

go run . plugin validate plugin.zip
go run . plugin install plugin.zip --apply-database
# 停用插件并重启服务后，使用更高版本包：
go run . plugin upgrade plugin-new.zip --apply-database

新安装只执行最新全量，记录其覆盖的迁移摘要；升级先校验已安装清单和历史迁移，再按序执行高于当前版本的增量。SQL 仍只能操作本插件前缀表，拒绝核心表、其他插件表及破坏性语句。安装成功后生成注册文件，安装文档归档到 Wiki，SQL 按版本归档到 sql/plugins/{plugin_id}/{version}。

Remove 后重装时，安装器核对保留的迁移摘要，并通过 MySQL 临时表对照完整结构；结构或历史不一致时拒绝重装，不重放全量覆盖业务数据。

当前开发数据库从旧发布号归并到 0.0.1 时，先完整备份、核对全部插件表结构，再在事务内归并插件版本、清单和迁移记录；不执行全量重建、不删除业务数据。正常升级命令不提供降级豁免。

发布验证

验证全量安装与历史全量加后续增量得到相同结构和必要初始数据。
验证缺文件、摘要不符、清单与代码版本不符、目录不符、重复或逆序版本均被拒绝。
验证旧用户数据在升级前后保持，普通升级拒绝同版本和降级。
同步接口、数据库引用、更新说明和插件发行包；不得覆盖历史发行包。

数据库发布与版本基线 ​

统一版本 ​

发布目录 ​

自动生成新版本 SQL ​

核心安装与升级 ​

插件安装与升级 ​

发布验证 ​