企业官网建设流程全解析

• AI 应用
• MCP 服务
• 数据治理
• 知识图谱
• 数据目录
• 数据建模
• 后端
• 前端

Auto Ontology 是一款为 LLM 与 Agent 构建语义图谱推理层的 Python 开源框架，支持自然语言转 SQL、语义目录与可解释查询。本文整理Auto Ontology 部署时最常见的 6 大坑与对应解法，覆盖 Docker Compose 本地栈和 Kubernetes Helm 两种部署方式，帮你快速定位问题、一次跑通 🚀

先说清整体组成，排查问题时知道"谁负责什么"会事半功倍：

两种部署入口：本地用 docker-compose.yml 一键起栈，K8s 用 DEPLOYMENT.md 描述的 Helm chart。下面 6 个坑按"遇到频率"排序。

坑 1：忘记填AUTH_SECRET和APP_URL，所有页面报错

症状：打开页面后一片空白或直接报错，控制台出现 Better Auth 的 "default secret" 相关错误。

原因：前端基于 Better Auth 做会话与 CSRF 管理，AUTH_SECRET和APP_URL都是必填项，缺失时每个页面请求都会失败。相关逻辑见 frontend/auth/auth.ts，secret直接取process.env.AUTH_SECRET。

解法：

cp .env.example .env # 编辑 .env，至少填写： # AUTH_SECRET=myverylongsecret123 # APP_URL=http://localhost:3000

完整变量清单参考 .env.example。APP_URL要填你实际访问的精确地址（含端口和协议），后续坑 5 会再提到它的另一个作用。

坑 2：重启后 UI 正常加载，但左侧导航栏消失

症状：页面能打开、能登录，但界面"缺胳膊少腿"——比如左侧导航面板没了，看起来像挂了，实际是会话失效。

原因：浏览器里存着过期的 session cookie。通常发生在两种场景：你改过AUTH_SECRET，或者数据库被重置过。README 的 Troubleshooting 一节明确列出了这个问题。

解法（30 秒搞定）：

1. 打开浏览器开发者工具，清除localhost:3000的站点数据；
2. 或者直接删掉名为better-auth.session_token的 cookie；
3. 重新登录，界面即恢复正常 ✅

💡 注意：这不是前端构建问题，重新docker compose up -d --build也解决不了，根子在浏览器缓存的旧凭证上。

坑 3：后端接口批量 500（UndefinedTable），目录功能全挂

症状：能登录、能进首页，但一点目录、分析相关功能就报 500，日志里常见UndefinedTable。

原因：后端比数据库迁移先启动，表还没建好就开始接请求。项目里有两套迁移：Alembic 管public模式（catalog + 语义层），Prisma 管frontend模式。docker-compose.yml 中已用auto-ontology-migrate和frontend-migrate两个一次性 Job 做启动门禁，注释里明确写着："否则后端会在 Alembic 之前启动，每个 catalog 调用都会 500"。

解法：

• 始终用docker compose up -d --build启动整个栈，不要单独docker start某个容器；
• 用docker compose ps确认auto-ontology-migrate、frontend-migrate状态是completed；
• 若确实手动拉起了后端，等迁移 Job 完成后再重启后端容器即可；
• Helm 部署则无需担心：chart 里配置了wait-for-catalog-schema初始化容器，Pod 会阻塞到alembic_version与 helm/auto-ontology/values.yaml 中的backend.alembicRevision一致才开始服务。

坑 4：宿主机 5432 端口被占用，Postgres 起不来

症状：docker compose up后 postgres 容器反复重启，报错Bind for 0.0.0.0:5432 failed: port is already allocated。

原因：本机已装有 PostgreSQL 或其他服务占用了 5432。很多人会以为改错地方——其实.env里的POSTGRES_PORT只影响宿主机一侧的映射，容器内部永远走内部网络 5432 端口（见 docker-compose.yml 中POSTGRES_PORT: "5432"的覆写注释）。

解法：只改宿主端口即可，例如：

# .env POSTGRES_PORT=15432

然后docker compose up -d。无需改动任何容器内部配置 ⚙️

坑 5：Helm 安装失败，或登录页 404 / CSRF 校验失败

症状 A：helm install直接报错退出，装不上。

原因：Helm 部署必须提供adminEmail和adminPassword——项目禁用了自助注册，这两个值是用来创建第一个管理员账号的，缺一个安装就失败（见 DEPLOYMENT.md）。

解法：把敏感值放进 values 文件再安装，官方推荐用编辑器写文件（避免进 shell 历史）：

# auto-ontology-secrets.yaml defaultModelsApiKey: <API-KEY> postgresPassword: <POSTGRES-PASSWORD> adminEmail: <ADMIN-EMAIL> adminPassword: <ADMIN-PASSWORD>

chmod 600 auto-ontology-secrets.yaml helm install auto-ontology nvidia/auto-ontology -f auto-ontology-secrets.yaml

症状 B：装上了，但登录请求 404 或提示 CSRF 校验失败。

原因：appUrl与你实际访问的地址不一致。Better Auth 会把会话、CSRF、OIDC 回调都绑定到appUrl，差一个斜杠都会出问题（values.yaml 中appUrl的注释原话："必须与你实际浏览的 URL 完全一致，否则认证请求会 404 或 CSRF 失败"）。

解法：本地用kubectl port-forward svc/frontend 3000:3000访问就保持默认的http://localhost:3000；走 Ingress/NodePort/HTTPS 时，把appUrl设成那个精确的公网 origin，例如https://auto-ontology.example.com，然后helm upgrade生效。

坑 6：模型调用报 503 / 限流，或者问什么都不出答案

症状：聊天框转圈很久，最终报 HTTP 503 或 429；或者摄取（ingest）阶段卡住、检索质量差。

原因分三种，逐条排查：

1. API Key 不对或没填：默认模型跑在 NVIDIA API catalog 上，需要一个nvapi-开头的 key，填到DEFAULT_MODELS_API_KEY（模板见 .env.example）。key 前缀决定端点：nvapi-对应 integrate 端点，sk-对应 inference 端点。

2. 并发打爆端点：LLM 嵌套调用（表 × 术语的扇出）容易超过端点的单 worker 请求上限，表现为 503。客户端对 503/429 有自动重试与退避（见 auto_ontology/utils/llm_invoke.py），但并发上限需要你自己收紧：

   # .env，降低同时在飞的 LLM 请求数（默认 6） LLM_MAX_INFLIGHT=3

3. Embedding 模型不一致：EMBED_MODEL在摄取时和查询时必须一致，不一致不会报错，但语义检索会"静默变差"——这是最隐蔽的一种。改模型后需要重新跑摄取。

解法清单：

• 确认DEFAULT_MODELS_API_KEY是有效的nvapi-key；
• 503 频发时调低LLM_MAX_INFLIGHT；
• 核对摄取与查询两侧EMBED_MODEL相同；
• 需要自定义模型时，每个角色是一组三元变量<PREFIX>_ENDPOINT / _API_KEY / _MODEL，未设置的字段会回退到DEFAULT_MODELS_*，只覆盖不同的字段即可。

附赠：3 个容易忽略的小提醒

• Vault 配置不完整 = 明文存储：VAULT_ADDR、VAULT_NAMESPACE、VAULT_ROLE_ID、VAULT_SECRET_ID四个变量缺一不可，只配一半会被忽略并告警，连接串凭证明文落在 Postgres 的目录行上（机制说明见 README.md 的 Connections Management 一节）。
• CONNECTION_STRINGS只是兜底：只有 UI 里没有任何连接时，环境变量里的连接串才会生效；UI 里加过连接后它形同虚设。
• MCP 客户端连不上：OAuth token 与AUTO_ONTOLOGY_MCP_PUBLIC_URL绑定了 audience，客户端连接地址必须与该值完全一致（含/mcp后缀），细节见 docs/mcp.md。

排错速查表

按这份清单从坑 1 依次排查，绝大多数 Auto Ontology 部署问题都能在 10 分钟内定位 🎯 部署完成后，打开http://localhost:3000，用管理员账号登录，即可开始连接数据源、体验自然语言查询。

• AI 应用
• MCP 服务
• 数据治理
• 知识图谱
• 数据目录
• 数据建模
• 后端
• 前端