04 运维与本体管理

4.1 本体管理 API（运维 CRUD）

方法	路径	功能
POST	`/api/ontology/reload`	热重载本体（新引擎构造+推理全部成功才原子替换，失败返回 400 旧状态可用）
GET	`/api/ontology/status`	本体状态（baseline_file_hash / dirty / pending_changes / changelog / last_commit / counts）
DELETE	`/api/ontology/individual/{name}`	删除个体 `?persist&cascade`（被引用时保护，cascade 连带清理反向引用）
POST	`/api/ontology/revoke`	撤销任务分配 `{task, agent, persist}`
POST	`/api/ontology/import`	批量导入任务个体（事务：任一校验失败整体拒绝）`{individuals, persist}`
GET	`/api/ontology/edit-model`	当前本体 → 结构化编辑模型 JSON（classes/objectProps/dataProps/individuals）
POST	`/api/ontology/save`	保存编辑模型 `{model, filename, mode: "new"\\|"overwrite"}`；保存后自动重建引擎重推理
GET	`/api/ontology/download?name=`	下载已保存的 OWL 文件（basename 白名单 + `data/uploads/` 限定，防路径穿越）
GET	`/api/ontology`	本体结构（图谱渲染数据）
POST	`/api/ontology/load`	加载本体文件（进入通用模式）

实测 status 返回：dirty=false、pending_changes=0、agents=5、tasks=8；实测 edit-model 返回：classes=25、objectProps=9、dataProps=3、individuals=14。

4.2 运维 CLI（ontologyctl）

scripts/ontologyctl.py 聚合 REST API + git + MCP 探测，统一管理本体服务：

.venv/bin/python scripts/ontologyctl.py status     # 服务 + 本体状态 + MCP 进程/端口（含两端一致性）
.venv/bin/python scripts/ontologyctl.py reload     # API reload + MCP kill -HUP
.venv/bin/python scripts/ontologyctl.py diff       # 未提交变更预览（服务 changelog + git status）
.venv/bin/python scripts/ontologyctl.py commit -m "新增合规任务"   # 本体变更入 git 并打 tag
.venv/bin/python scripts/ontologyctl.py rollback   # 回滚最近本体 tag（可指定 tag）并 reload
.venv/bin/python scripts/ontologyctl.py log        # git log + 服务 changelog + tags

环境变量：DOUBAO_API_BASE（默认 http://127.0.0.1:8000）、ONTOLOGY_GIT_ROOT（git 仓库根，默认项目根）。

4.3 备份

文件级快照备份（不依赖 git）：

bash scripts/backup.sh    # 核心 .owl + extensions/ → backups/<时间戳>/（已被 .gitignore 忽略）

建议配合定时任务（如 cron）定期执行；恢复 = 将 backups/<时间戳>/ 中 .owl 复制回本体目录并 reload。

4.4 服务管理

docker compose up -d api mcp        # 启动
docker compose logs -f api          # 查看日志
docker compose down                 # 停止
curl -s http://127.0.0.1:8000/api/health   # 健康检查

4.5 护栏与门禁配置

Agent 调用护栏（默认关闭，向后逐字节兼容）：编辑 domains/agent_task/guard_config.json 启用：

{"enabled": true, "session_budget": 50, "loop_threshold": 3,
 "cache": {"enabled": true, "ttl_calls": 5}, "audit_tail": 100}

enabled: true 后，通用工具注册管道统一包装；guard_status 可在线查看预算/缓存/审计；
非法配置（如 budget≤0）启动 fail-fast；guard_status 自身不被 wrap（自省不熔断）；
时敏查询可关闭 cache 段。

管线质量门禁：pipeline_gate 的 G3 冒烟断言集在领域包 gates_smoke.json（如默认领域 expected_derived：can_execute ≥1、depends_on ≥2）；G4 形状在 pipeline/shapes/<domain>.ttl。新增/修改领域时按需更新这两处。

4.6 安全边界清单

/api/upload（导入自定义本体）无鉴权：单机演示用途，勿暴露公网；
/api/ontology/download 已做 basename 白名单 + 目录限定（防路径穿越）；
前端工作台可编辑本体并覆盖文件：生产环境需自建鉴权与审计；
MCP 受控语义接口（语义白名单）可限制智能体可见概念范围，公网暴露时建议启用。