排错

从症状入手，再从最小的边界开始检查。

ObjectOS 启动失败

检查：

1. 容器日志。
2. Node 版本与依赖安装。
3. PORT 冲突。
4. 缺失产物。
5. 期望使用认证端点时缺失 OS_AUTH_SECRET。

Docker：

docker compose -f docker/docker-compose.yml logs objectos

产物无法加载

检查：

• OS_ARTIFACT_FILE 指向已挂载的文件;
• 文件在容器内确实存在;
• 文件是合法的 JSON;
• 该产物是编译后的 ObjectStack 产物，而非源元数据;
• 文件权限允许读取。

容器内：

ls -l /artifacts/objectstack.json

登录失败

检查：

• 已配置 OS_AUTH_SECRET;
• 公开 URL 与回调 URL 匹配;
• ObjectOS 能访问 OIDC 发现 URL;
• 受信任来源包含公开域名;
• Cookie 作用域是正确的项目主机名;
• 项目内核已启用认证。

用户看不到记录

检查：

1. 主机名对应的项目是否正确。
2. 用户是否归属于预期的组织。
3. 对象的 read 权限。
4. 行级安全。
5. 共享规则或记录共享。
6. 如果只缺少部分字段，检查字段级安全。

设置不可编辑

设置可能被环境层覆盖锁定。生效顺序如下：

Environment -> Tenant -> User -> Default

如果环境提供了值，运行时的编辑应当被拒绝，而不是静默覆盖。

webhook 或任务不运行

检查：

• 产物的 requires 列表包含所需能力;
• ObjectOS 镜像包含相应的可选服务包;
• 队列/任务服务配置可用;
• 允许出站访问目标地址;
• 在 Console 诊断中能看到投递日志或任务运行。

数据库错误

检查：

• 数据库 URL 与驱动类型;
• 从 ObjectOS 到数据库的网络可达性;
• 凭据与 TLS 选项;
• schema 同步/迁移日志;
• 若使用本地 SQLite，检查存储持久化。