管理与治理集成

钩子

以 Markdown 格式查看

钩子用于接收外部系统事件，并触发已批准的自动化或智能体流程。它适合事件驱动集成，不适合作为未认证的通用执行入口。该入口通常只在企业版且部署已启用钩子能力后可见。

管理边界

项目建议
入口为不同业务系统创建独立 hook，避免共享一个高权限入口。
认证使用签名、令牌或来源限制校验请求。
范围只触发明确配置的工作流或操作。
审计记录事件 ID、来源、命中规则、执行结果和失败原因。

核心概念

概念含义治理决策
Hook pointAIvis 流程中允许调用自定义逻辑的固定阶段。将每个点视为稳定合同：先理解它何时运行、接收哪些数据，以及是否可以修改或阻断流程。
Hook将某个 hook point 连接到 HTTPS endpoint 的配置。每个 hook point 和环境使用一个用途明确的 endpoint，避免用宽泛转发隐藏 owner 和故障影响。
Endpoint接收 JSON 请求并返回预期响应的自有服务。只允许批准网络访问，校验认证，并尽快返回结果。
Fail strategyendpoint 不可达、超时或返回无效响应时，AIvis 继续采取的行为。继续执行会违反策略时使用 hard fail；hook 只做通知或观测且主流程可安全继续时使用 soft fail。

常见 Hook Points

Hook point运行时机可执行动作默认取向
Document ingestion文档验证后、索引开始前。透传内容、改写 sections，或在进入索引前拒绝文档。策略执行、分类、脱敏和来源 allowlist 优先使用 hard fail。
Document push文档成功索引后。将已索引内容通知或复制到审计日志、数据仓库或下游归档系统。除非下游目标是强制合规流程，否则优先使用 soft fail。
Query processing用户提交查询后、进入检索或模型调用前。透传查询、改写查询，或通过用户可见消息拒绝查询。访问策略、数据防泄漏或受监管主题控制优先使用 hard fail。

具体 payload 和响应格式属于各 hook point 的合同。不要因为它们都使用 HTTP POST，就假设不同 hook point 接受相同字段。

配置前检查

  • 明确事件来源、事件类型和允许触发的动作。
  • 为每个 hook 设置签名校验和重放保护。
  • 规划失败重试、幂等和告警策略。
  • 判断哪个 hook point 可以影响主流程，哪个只用于观测或通知。
  • 在连接 endpoint 前确定 fail strategy 和 timeout。
  • 准备能返回合法 JSON 与 2xx 状态码的 endpoint。
  • 将 endpoint API key 存入受管 Secret Store，并跟随所属服务轮换。

连接 Hook

  1. 打开 AIvis 管理区域，进入 hooks 页面。
  2. 选择要连接的 hook point。
  3. 填写包含系统、环境和用途的显示名称。
  4. 输入 HTTPS endpoint URL。生产数据不要使用公开测试 endpoint。
  5. 配置认证、timeout 和 fail strategy。
  6. 只有在 endpoint 通过连接测试后才保存 hook。
字段是否必填建议
Display name是使用 pii-redaction-prod 或 audit-export-staging 这类名称，让日志可读。
Endpoint URL是使用 HTTPS，并路由到负责该 hook 行为的团队拥有的服务。
API key可选配置后，endpoint 必须在处理 payload 前校验传入的 Authorization: Bearer <key> header。
Timeout可选设置为足够短，避免影响用户可见延迟和 worker 吞吐。
Fail strategy可选阻断类控制选择 hard fail；遥测或 best-effort 通知选择 soft fail。

管理 Hooks

操作适用时机变更后检查
启用或停用需要在不删除配置的情况下启动或暂停执行。用受控事件确认预期流程行为。
编辑endpoint URL、API key、timeout、名称或 fail strategy 发生变化。重新执行成功、拒绝、超时和无效响应测试。
查看日志hook 降级、失败或产生非预期决策。用事件 ID 和失败原因对齐 AIvis 与 endpoint 所属服务日志。
删除集成已经退役或被替换。移除 endpoint secret，并更新所属团队 Runbook。

健康状态与失败处理

注册后持续监控 hook 健康状态。健康 endpoint 表示当前可达且近期没有执行失败；降级 endpoint 可能仍然可达，但应视为活跃的可靠性或策略风险；连接丢失表示 AIvis 无法访问 endpoint，并会按配置的 fail strategy 处理。

对于 hard-fail hooks，要测试 hook 拒绝、超时或返回无效 JSON 时用户或索引流程看到的结果。对于 soft-fail hooks，要确认主流程继续执行，同时失败仍能在日志和告警中被发现。

验证

  • 使用合法事件验证触发路径。
  • 使用无签名、错误签名和重复事件验证拒绝路径。
  • 在查询历史中确认事件处理结果可追踪。
  • 测试超时行为和无效 JSON 响应。
  • 确认 hard-fail hooks 会阻断预期动作，soft-fail hooks 会安全继续。
  • 确认 endpoint 不记录原始 secret、完整凭证或不必要的用户内容。
  • 确认 request ID、event ID 和 rejection reason 能在 AIvis 日志与 endpoint 日志之间关联。

生产检查清单

  • 每个 hook 只有一个 owner、一个环境和一个明确 hook point。
  • Endpoint 通过 HTTPS、认证和网络控制限制访问。
  • Endpoint 对重试和重复事件保持幂等。
  • 阻断类 hooks 的用户可见或运维可见失败消息说明下一步，不泄漏策略内部细节。
  • Hook 决策可审计，包括透传、改写、拒绝、超时和 endpoint failure。