第 9 章 常见坑与上线自检

第 9 章 常见坑与上线自检

这一章是前面八章的「事故合集」。每条都对应一个真实会卡住启动或导致权限失效的问题，按现象、原因、处理方式组织。

启动阶段

1. panic: reflect: call of reflect.Value.UnsafeAddr on zero Value

原因：SubApp 或 Provider 没有名为 app 的字段。

处理：结构体加上：

type SubAppOrder struct {
	app foundation.Application
}

字段名必须是小写 app，类型实现 foundation.Application。

2. missing type: *repository.XxxRepository

原因：构造函数没加进 Binds()，或加了但写成了调用结果。

处理：

// 正确
return []any{repository.NewOrderRepository}

// 错误
return []any{repository.NewOrderRepository(db)}

3. missing type: redis.LockerFactory / *gorm.DB

原因：Service 依赖了某个 Provider 提供的类型，但 ServiceProviders() 没登记对应 Provider。

处理：补 &redis.RedisServiceProvider{}、&db.DBServiceProvider{} 等。

4. 启动卡在某个阶段

debug 日志最后一条 startup begin 就是卡住的位置。常见是某个 Invoke 里的构造函数在连数据库或 Redis，而地址不可达。

配置阶段

5. 配置文件没生成

原因：当前使用的不是你以为的目录。

处理：看启动日志里的「程序启动目录」「程序所在目录」，确认 conf/ 落在哪里。打包后用 systemd/Docker 时尤其容易错位。

6. 环境变量没生效

原因：前缀或键名转换写错。

处理：database.yaml 用 DATABASE_ 前缀，jwt.yaml 用 JWT_；键里的 .、- 转 _，嵌套用 _ 连接。例如 signing-key → JWT_SIGNING_KEY。

7. 升级框架后旧配置缺字段

框架会补默认键，但只在启动时做。启动一次后检查 conf/ 是否出现新字段；补不进去的键会告警，需要手工处理。

路由与接口

8. 接口 404

原因：

• RegisterRouters() 没执行（ConsoleShell 模式不会注册路由）；
• InitApi 没被调用；
• 路由没注册在 /api/v1 分组；
• 请求方法不匹配；
• 中间件路由表里找不到该路径。

处理：先确认启动模式是 WebShell；再确认 RegisterRouters() 里真的调用了路由初始化；最后核对方法与路径。

9. 接口 401 / 403

原因：

• 401：令牌缺失、过期或解析失败；
• 403：访问级别不满足，或 Casbin 没有对应权限。

处理：先看路由的 AccessLevel，再看 GET /api/v1/users/me/permissions 是否包含该接口的权限标识。权限部分详见配套手册。

10. 改了方法名后权限失效

原因：权限标识由 appName:moduleEn:方法名 生成，重命名 Handler 方法会改变标识。

处理：重新给角色分配菜单，或在设计阶段就固定方法名。

11. 直接写 gin.GET 的路由权限行为异常

原因：绕过 RouterInfoBuilder 的路由不会进入运行时路由表，权限中间件无法识别。

处理：业务路由统一用 Builder 注册；确实需要裸路由时，确认它不需要鉴权或单独处理。

菜单与前端

12. 菜单不显示

原因：

• RegisterMenus() 返回了 nil 节点；
• 根菜单没有 SubApp，被 ?app= 过滤掉；
• 角色没有分配该菜单；
• 前端组件名与菜单 Name 不一致。

处理：检查菜单树、SubApp 标记、角色授权和前端 defineOptions({ name })。

13. 多标签 / keep-alive 异常

原因：Vue 页面组件的 name 与后端菜单 Name 不一致。

处理：两边保持完全一致，包括大小写。

迁移与数据

14. 新表没建

原因：model 没加入 RegisterMigrate()，或加入了但启动时连不上数据库。

处理：检查 RegisterMigrate() 返回值；确认 conf/database.yaml 指向正确数据库。

15. 加了字段但数据库没变

原因：schema hash 没变化（改动没被识别），或 hash 文件被保留。

处理：确认模型标签确实改了；必要时删掉 storage/migrate_hash.txt 中对应行再启动。

16. 每次启动都重新迁移

原因：storage/ 不可写，hash 写不进去。

处理：检查存储目录权限。

依赖与版本

17. go.mod 的 replace 指向错误

本地开发用 replace bit-labs.cn/owl => ../owl，要保证相对路径真实存在。CI 构建时应去掉 replace，改用正式版本。

18. owl 与子应用版本不兼容

升级框架后，至少跑一遍启动、登录、一个核心写接口。接口签名或启动顺序变化通常在启动阶段就会暴露。

上线前自检清单

• [ ] 服务能启动，日志无 panic、无 missing type；
• [ ] conf/ 自动生成或已正确挂载；
• [ ] 数据库迁移成功，hash 文件已写入；
• [ ] 至少一条创建接口、一条查询接口验证通过；
• [ ] 所有 SubApp 都有 app 字段；
• [ ] 所有新增构造函数都在 Binds() 里；
• [ ] 所有需要迁移的模型都在 RegisterMigrate() 里；
• [ ] 路由全部通过 Builder 注册，访问级别符合预期；
• [ ] 菜单 Name 与前端组件 name 一致；
• [ ] 敏感配置未提交，部署环境变量已核对；
• [ ] 用普通用户验证过一次权限，而不是只用超管。

写在最后

Owl 的难点不在单个 API，而在启动顺序和接线完整性。遇到问题时，先判断它发生在哪个阶段（装配、配置、路由、迁移、运行期），再按该阶段的顺序排查，通常几分钟就能定位。

下一本手册进入 owl-admin 的权限子系统，解释登录、访问级别、权限标识和 Casbin 授权如何串起来。