Troubleshooting
故障排除概览
快速诊断清单、如何读取 Nebutra 错误信息、如何提高日志详细程度，以及如何获取帮助。
快速诊断清单
在深入排查具体错误之前，请先完成以下清单。大多数问题都可以通过其中一个步骤解决。
pnpm infra:up这会通过 Docker Compose 启动 PostgreSQL 16、Redis 7 和 ClickHouse 24。若这些服务未运行，数据库连接错误和队列故障是预期行为。
pnpm install克隆仓库或拉取新提交后，请务必重新安装依赖。添加或删除包后，工作区符号链接可能会失效。
确保 .env.local 存在且所有必填变量已设置。请参见环境变量参考文档。应用启动时会打印缺失的必填变量名称。
pnpm db:generate在更改 packages/platform/db/prisma/schema.prisma 后请运行此命令。过时的 Prisma 客户端会导致 TypeScript 类型错误和运行时查询失败。
rm -rf apps/web/.next apps/landing/.next
pnpm devTurbopack 和 Webpack 都维护磁盘缓存。过时的缓存条目可能导致模块解析错误，在干净重启后消失。
pnpm lint:fixBiome 会自动修复大多数 lint 错误。如果构建在 lint 步骤失败，此命令可以解决。
如何读取 Nebutra 错误信息
Nebutra 使用遵循统一格式的结构化错误信息：
Error: [package] 问题的简短描述
at functionName (file.ts:line)
Context:
variable: value
tenantId: org_xxx[package] 前缀告诉您是哪个包抛出了错误。常见前缀：
| 前缀 | 包 | 含义 |
|---|---|---|
[config] | @nebutra/config | 缺失或无效的环境变量 |
[tenant] | @nebutra/tenant | 租户上下文未初始化 |
[queue] | @nebutra/queue | 消息队列连接或处理器错误 |
[search] | @nebutra/search | 搜索提供商连接错误 |
[vault] | @nebutra/vault | 加密密钥配置错误 |
提高日志详细程度
设置 LOG_LEVEL 环境变量以查看更多详情：
LOG_LEVEL=debug有效级别（从最少到最详细）：error → warn → info → debug。
开发环境默认级别为 info，生产环境为 warn。调试输出包括：
- API 网关的所有出站 HTTP 请求
- 队列任务的入队和出队事件
- 租户上下文解析步骤
- 配置验证详情
在生产环境中请勿使用 LOG_LEVEL=debug。调试输出包含内部请求详情，不应出现在生产日志中。
获取帮助
如何提交高质量的 Bug 报告
一份有效的 Bug 报告应包含以下内容：
- 完整的错误信息 — 复制完整的堆栈跟踪，而非转述。
- 复现步骤 — 触发错误的最小操作序列。
- 环境信息 — Node.js 版本、pnpm 版本、操作系统，以及出问题的应用（
web、api-gateway等）。 - 预期行为与实际行为。
- 已尝试的方法 — 来自上述清单的步骤。
# 快速收集环境信息
node --version && pnpm --version && uname -a相关文档
How is this guide?
在 GitHub 上编辑此页面
最后更新于