07 常见问题

启动与部署

Q：端口被占用怎么办？ A：lsof -nP -iTCP:8000 查看占用进程；或改端口：uvicorn api.main:app --port 8001（MCP 同理 --port 9001），并用环境变量 DOUBAO_API_BASE 指向新 API 地址。

Q：--local 报 No module named 'owlrl'？ A：内嵌引擎依赖 owlrl/rdflib，请用项目虚拟环境：.venv/bin/python scripts/query.py ...（HTTP 通道仅需标准库，系统 python3 可跑）。

Q：Docker 方式与手动方式能混用吗？ A：不建议同时启动两个 API（端口冲突）。二选一，停止另一套。

功能与边界

Q：领域推理返回"当前为通用模式"？ A：服务已加载过自定义本体（data/uploads/），领域推理 R1–R4 仅默认本体可用。重启服务恢复默认本体；自定义本体下图谱/物化/SPARQL/通用查询不受影响。

Q：在线编辑覆盖本体后，复杂公理丢了？ A：编辑模型仅覆盖类/属性/个体子集，restriction、属性链等复杂公理不进入编辑模型；「覆盖当前本体」重建 OWL 文件后此类公理不保留。如需保留原文件请用「另存为新本体」。

Q：为什么对象断言可以指向未声明实体？ A：校验规则刻意宽松（开放世界假设）——id 仅要求非空且无 IRI 危险字符，中文/下划线短名合法，对象断言可指向未声明实体。

Q：MCP 的 query_sparql 突然不可用了？ A：启用语义白名单（access_policy.json）后策略激活，query_sparql 被禁用（只暴露白名单内概念）；关闭策略或使用 run_predefined_query。

Q：调用护栏（tool_guard）怎么启用？ A：默认关闭（无配置时行为与旧版逐字节一致）。编辑 domains/agent_task/guard_config.json 将 enabled 置 true 后重启 MCP 服务；guard_status 可在线查看预算/缓存/审计。

Q：pipeline_gate 的输入是什么格式？ A：建模草稿 Turtle（TBox，可选 ABox 参数）；可先用 guide_tbox_draft 生成草稿再过闸。gates 参数支持单闸调试（如 ['G3']），空列表全部 skipped。

Q：新增领域时门禁/护栏文件也要建吗？ A：建议提供 gates_smoke.json（G3 冒烟断言，不建则 G3 skipped）与 guard_config.json（护栏，不建则护栏关闭）；G4 形状放在 pipeline/shapes/<domain>.ttl。

安全

Q：能把服务直接部署到公网吗？ A：不能。/api/upload 无鉴权、无输入隔离，可接收任意 .owl 写入 data/uploads/；需公网部署请自行加鉴权、上传校验与审计（并建议启用 MCP 语义白名单）。

Q：/api/ontology/download 安全吗？ A：已做 basename 白名单 + data/uploads/ 目录限定，防路径穿越；不要自行放宽该限制。