Go 后台初始化 MySQL 脚本失败怎么办？先查 DDL 还是生成配置

Go 后台初始化 MySQL 脚本失败时，不要先改业务代码，也不要马上怀疑 GoFrame。先把 DDL、初始化数据和代码生成配置拆开验。第一步看表能不能稳定创建，默认值、唯一索引、字符集、时间字段是否符合 MySQL 语义；第二步看生成器配置有没有把字段类型、必填、搜索、权限码同步错；第三步才看 CRUD、菜单和 RBAC 是否被写到同一套后台入口里。这个顺序能避免一个很常见的误判：SQL 脚本没跑完，却在接口层反复查 500。

本文的主查询是：Go 后台管理系统初始化 MySQL 脚本失败，应该先查 DDL 还是查代码生成配置？我按真实排查顺序写，不把它写成框架功能介绍。

先固定错误现场

初始化失败最怕只截一行"执行失败"。那一行通常不够。至少要留三类信息：失败的 SQL、数据库版本、迁移脚本执行到哪一步。比如脚本里同时建用户表、菜单表、权限表和业务表，前面的表已经创建，后面的初始化数据没插进去，后续页面就会表现成"菜单空了""按钮没权限""接口 403"。这不是三个问题，而是同一段初始化没有完整提交。

我会先让脚本输出批次号和最后一条成功 SQL：

bash 复制代码

mysql --version
mysql -uroot -p app < deploy/sql/mysql/init.sql 2> init-error.log
sed -n '1,80p' init-error.log

如果日志里是 Invalid default value、Specified key was too long、Duplicate key name，先查 DDL。若表已经建完，报错出现在 insert into admin_menu、insert into admin_permission，再查初始化数据和权限码。不要混在一起改。

DDL 先验哪些地方

MySQL 初始化脚本里最容易出错的不是字段名，而是数据库语义。SQLite、PostgreSQL、MySQL 对空值、唯一索引、时间默认值和布尔字段的处理都不一样。一个后台管理系统如果同时支持 MySQL 和 PostgreSQL，就不能只修一套脚本。

我一般先跑这几条查询：

sql 复制代码

select version();

select table_name, column_name, column_type, is_nullable, column_default
from information_schema.columns
where table_schema = database()
  and table_name in ('admin_user', 'admin_menu', 'admin_permission')
order by table_name, ordinal_position;

select table_name, index_name, non_unique, group_concat(column_name order by seq_in_index) as cols
from information_schema.statistics
where table_schema = database()
group by table_name, index_name, non_unique
order by table_name, index_name;

这里重点看四件事。手机号、邮箱这类可选字段如果写空字符串，再加唯一索引，后面第二条空手机号数据就会冲突。created_at、updated_at 如果默认值写法不兼容当前 MySQL 版本，脚本会在建表阶段直接断掉。权限码如果建了唯一索引，初始化数据里重复插入同一个 code，会让菜单和接口权限只成功一半。布尔字段如果在 Go 里按 bool 用，SQL 里却给了字符串默认值，后续生成器也会跟着错。

再查代码生成配置

DDL 能跑过，不等于生成出来的 CRUD 能上线。生成器关心的是字段语义：字段是不是必填、能不能搜索、是否要出现在列表、导入导出是否允许、远程下拉从哪里取值。数据库只知道列，业务不知道这些语义就会在页面和接口之间分叉。

一个简单的 review 表可以这样列：

检查项	看 SQL	看生成配置	不一致后果
必填字段	`is_nullable = 'NO'`	required / validate	页面不填也能提交，接口再报错
搜索字段	index / where 条件	search flag	页面有搜索框但接口慢或无效
权限码	menu / permission code	action 配置	菜单看得到，按钮或接口 403
远程下拉	外键或业务字段	remote-table	页面显示 id，编辑时回显失败

XYGo Admin 这类 GoFrame v2 + Vue3 后台项目，RBAC、CRUD 生成器和前端页面是连在一起的，所以初始化脚本不能只保证"表存在"。本文只把它当作一个可查看的源码样本，不代表所有项目都要按同一套目录组织。当天核验的证据包括 server/internal/logic/gencodes/generate.go 和 server/internal/logic/gencodes/sync_fields.go，它们分别对应生成流程和字段同步语义。

MySQL 和 PostgreSQL 不要只修一边

如果项目支持两套数据库，初始化脚本修复后要做对照。不要只在 MySQL 里跑通一次，然后把 PostgreSQL 留给用户踩坑。最少做一次字段和索引级别的差异检查。

MySQL 侧可以导出列定义：

sql 复制代码

select table_name, column_name, column_type, is_nullable, column_default
from information_schema.columns
where table_schema = database()
order by table_name, ordinal_position;

PostgreSQL 侧可以查：

sql 复制代码

select table_name, column_name, data_type, is_nullable, column_default
from information_schema.columns
where table_schema = 'public'
order by table_name, ordinal_position;

两边不要求文本完全相同，但语义要一致。比如自增主键、时间默认值、空字符串和 NULL、JSON 字段、唯一索引条件，都要按数据库自己的写法落地。Release v1.4.6 里记录过 PostgreSQL 脚本修复和数据库迁移升级命令 go run tools.go update；而 2026-08-06 的提交 c7e5c90eecaa01bec29133e0e1159f3d607e0ccb message 是"修复mysql初始脚本"。这两个事实放在一起看，说明跨库初始化脚本应该单独进入发布检查，而不是附带测一下页面能不能打开。

升级脚本跑完后怎么验

脚本执行成功只说明数据库接受了这些语句。后台系统还要验菜单、权限、接口和业务表是否对得上。我会把验收拆成几条 SQL 和几条接口命令。

sql 复制代码

-- 菜单和权限码是否重复
select permission_code, count(*) c
from admin_permission
group by permission_code
having c > 1;

-- 菜单是否存在没有权限码的按钮动作
select m.id, m.name, m.path, p.permission_code
from admin_menu m
left join admin_permission p on p.menu_id = m.id
where m.type in ('button', 'api') and p.id is null;

-- 初始化账号、角色、菜单关系是否为空
select count(*) as admin_user_count from admin_user;
select count(*) as role_menu_count from admin_role_menu;

接口侧不要只测 200。登录失败、无 token、无权限、管理员权限四种状态都要测。示例命令可以这样写：

bash 复制代码

curl -i localhost:8000/admin/user/list
curl -i -H 'Authorization: Bearer bad-token' localhost:8000/admin/user/list
curl -i -H 'Authorization: Bearer $LOW_PRIV_TOKEN' localhost:8000/admin/user/list
curl -i -H 'Authorization: Bearer $ADMIN_TOKEN' localhost:8000/admin/user/list

如果前三条和第四条都返回 200，权限中间件没有生效；如果第四条 403，初始化权限数据没有对上。server/internal/middleware/admin_permission.go 是这类检查的源码证据之一，但排查时仍然要从 SQL 和 HTTP 响应读回结果。

适用边界

这套方法适合三类问题：初始化 SQL 报错、升级脚本跑完但菜单或权限异常、代码生成器同步字段后页面和接口不一致。它不适合把所有部署失败都归因于初始化脚本。Nginx 502、数据库连不上、Redis 密码错、前端静态资源路径错，应该走部署链路排查。

也不要把生成器当成免 review 工具。生成器能减少重复文件，但它不知道业务里的唯一约束、租户边界和权限粒度是否合理。尤其是 AI 或 Agent 参与改表时，DDL、生成配置和接口验收要放在同一个 checklist 里，否则很容易出现"页面生成了，线上一跑初始化脚本先炸"的尴尬状态。

发布前最好加一条脚本级门禁

人工 review 容易漏，因为表结构、菜单和生成配置分别散在不同目录里。更稳的是把这些检查做成一条本地命令，失败就不允许打包。脚本可以先连空库跑初始化，再把 information_schema 的结果保存成 JSON，最后检查权限码和菜单动作是否一一对应。这样做有个好处：下次有人改了 SQL 或生成模板，不需要记住这篇文章，只要门禁报错就会回到同一套证据。

可以从很小的脚本开始：

bash 复制代码

set -e
mysql -uroot -p app < deploy/sql/mysql/init.sql
mysql -uroot -p app -e "select count(*) from admin_menu"
mysql -uroot -p app -e "select count(*) from admin_permission"
go test ./server/internal/logic/gencodes/...

这段命令不保证业务正确，但能拦住低级错误：脚本建不起来、权限基础数据为空、生成器包编译失败。后面再补跨库对照和接口验收，成本会低很多。团队里如果有人只改了前端页面或生成模板，也能通过这条门禁尽早发现数据库没有同步。它的价值不是把所有问题自动修好，而是把失败点固定在提交前，而不是等部署后再靠日志猜。

一个可复制的发布前检查清单

bash 复制代码

# 1. 空库跑初始化
mysql -uroot -p app < deploy/sql/mysql/init.sql

# 2. 跑升级命令或迁移脚本
go run tools.go update

# 3. 查字段、索引、权限码
mysql -uroot -p app < deploy/sql/check-init.sql

# 4. 跑最小接口验收
curl -i localhost:8000/admin/user/list
curl -i -H 'Authorization: Bearer $ADMIN_TOKEN' localhost:8000/admin/menu/list

如果要看本文提到的真实源码样本，可以从 GitHub 仓库进入，重点看上面列出的生成器、字段同步和权限中间件路径。核验时点是 2026-09-06 09:00 CST：仓库为 public，最新正式 GitHub Release API 仍是 v1.4.6，最新提交显示 v1.4.9 对象存储增强与 CDN 预览。动态 Star、Issue 和后续提交不要按本文固定值引用，发布前应重新查一遍。

初始化脚本这类问题看起来小，其实很适合做发布门禁。它不需要复杂平台，也不需要猜用户环境。空库建表、跨库对照、权限 SQL、四条 curl，把这几步跑完，很多"后台初始化失败"的问题会在上线前暴露出来。