配置故障排查

配置文件无法加载

现象： dab start 启动失败，提示配置文件解析错误。

常见原因与解决：

原因	解决
JSON 语法错误（逗号多余、引号不匹配）	用 JSON 校验工具检查语法
配置文件路径不正确	确认 dab-config.json 在当前目录，或用 --config 指定路径
文件编码问题	确保文件是 UTF-8 编码（无 BOM）
顶层字段拼写错误	检查 data-source（不是 datasource）、entities（不是 entity）
@env() 引用的变量不存在	确认环境变量已设置，或在 .env 文件中定义

dab validate 阶段 1（Schema）失败

现象： dab validate 在 Schema 阶段报错。

常见错误：

错误	修复
属性名拼写错误（"conn-string"）	改为 "connection-string"
database-type 值非法（"mydb"）	改为 mssql、postgresql、mysql
entities 写成了数组	改为以实体名为键的对象 { "Book": { ... } }
存在 Schema 不认识的额外属性	删除多余字段

dab validate 阶段 2（配置属性）失败

常见错误：

错误	修复
所有终结点都关闭（REST=false, GraphQL=false, MCP=false）	至少启用一个
设置了 JWT issuer 但没有 audience	两者都提供，或都不提供
REST/GraphQL 路径不以 / 开头	添加 / 前缀

dab validate 阶段 3（权限）失败

常见错误：

错误	修复
动作值不合法（如 "drop"）	改为 read、create、update、delete、execute 或 *
存储过程配置了 CRUD 动作	改为 execute 或 *
空动作列表 "actions": []	提供至少一个动作

dab validate 阶段 4（数据库连接）失败

执行 dab validate 时数据库连接失败。参见数据库连接故障排查。

dab validate 阶段 5（实体元数据）失败

常见错误：

错误	修复
视图缺少 key-fields 或 fields[].primary-key	添加主键指定
fields.include 或 fields.exclude 引用了不存在的字段	修正或删除字段名
关系目标实体不存在	确认目标实体名已配置
多对多关系缺少 linking.object	添加联接表名
策略引用的字段无效	确认策略中 @item.xxx 字段存在
缓存 TTL 为负数	设为非负整数或 0

身份验证配置错误

现象： 所有请求返回 401 或 403。

排查步骤：

1. 确认 host.authentication.provider 已正确设置。
2. 如果使用 Custom（JWT），确认同时配置了 jwt.issuer 和 jwt.audience。
3. 解码 JWT 令牌确认 iss 和 aud 与配置一致。
4. 确认 JWT 令牌中包含 roles 声明（声明名固定为 roles，不可配置）。

实体配置了权限但仍然 403

排查步骤：

1. 确认请求的最终角色与 permissions 中的角色名完全一致（区分大小写）。
2. 如果使用 Unauthenticated 提供程序，所有请求都是 anonymous——authenticated 和命名角色永远不会生效。
3. 确认操作名正确——read 不是 get，create 不是 insert。
4. 运行 dab configure --show-effective-permissions 查看每个实体的最终权限。

环境变量未生效

现象： 配置中使用了 @env('VAR_NAME') 但引擎启动时报变量不存在或使用错误的值。

排查步骤：

1. 确认环境变量已在启动前正确设置——echo $VAR_NAME（Linux）或 echo %VAR_NAME%（Windows）。
2. 如果使用 .env 文件，确认文件在 dab-config.json 所在目录，格式为 KEY=VALUE（每行一条）。
3. 语法必须精确——@env('VAR_NAME') 中有单引号，不是 @env(VAR_NAME)。
4. 容器环境中确认 -e VAR_NAME=value 或 --env 参数正确传递。

首次启动无实体暴露

现象： 服务启动成功但访问 /api 找不到任何端点。

原因： dab init 只创建配置骨架，不添加实体。忘记运行 dab add 添加至少一个实体。

解决： 运行 dab add 添加实体后重启服务。

修改配置后未生效

原因： 数据墙DBW 在启动时一次性加载配置，运行时不会自动热加载（日志级别除外）。

解决： 修改 dab-config.json 后重启服务（dab start）。

下一步

• 数据库连接故障排查 — 数据库相关错误。
• REST 故障排查 — REST API 问题。