连接器审计日志

所有 MCP、Telegram 和 ChatGPT 工具调用的审计追踪 — 合规、成本追踪和事件调查。

通过 MCP、Telegram 或 ChatGPT 的每个外部连接器工具调用都被记录在连接器审计日志中，用于合规、成本追踪和安全调查。

记录了什么

字段	值	注释
`id`	UUID	唯一审计记录 ID
`workspace_id`	UUID	发起调用的工作区
`user_id`	UUID	触发工具的用户（如果是人类）
`platform`	`mcp` \| `telegram` \| `chatgpt` \| `stdio`	工具通过哪个接口被调用
`tool_name`	string	工具名称（例如 `create_issue`、`list_comments`）
`scopes`	string[]	令牌携带的 OAuth 范围（例如 `["issues:read", "issues:write"]`）
`outcome`	`ok` \| `denied` \| `error`	成功、权限被拒绝或错误
`error_code`	string \| null	如果出错，错误代码（例如 `insufficient_scope`、`malformed_input`）
`input_summary`	string	编辑的输入（从不包括秘密或完整有效负载）
`result_size`	integer	返回的字节
`tokens_in`	integer \| null	输入令牌（如果调用驱动模型）
`tokens_out`	integer \| null	输出令牌（如果调用驱动模型）
`cost_micros`	integer \| null	估计成本（单位：微美元）
`created_at`	timestamp	调用发生时间
`duration_ms`	integer	往返延迟

审计日志查询 API

列出审计条目

GET /api/audit/connectors

查询参数：

参数	类型	描述
`platform`	string	按 `mcp`、`telegram`、`chatgpt`、`stdio` 过滤
`user_id`	UUID	按用户过滤
`tool`	string	按工具名称过滤
`outcome`	string	按 `ok`、`denied`、`error` 过滤
`since`	ISO 8601	开始日期（默认：最近 7 天）
`until`	ISO 8601	结束日期
`limit`	integer	页面大小（默认：100）
`offset`	integer	分页偏移

示例：

curl https://aacworkflow.example.com/api/audit/connectors \
  ?platform=mcp \
  &outcome=error \
  &since=2025-06-01T00:00:00Z \
  &limit=50

{
  "entries": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440001",
      "user_id": "550e8400-e29b-41d4-a716-446655440002",
      "platform": "mcp",
      "tool_name": "update_issue",
      "scopes": ["issues:write", "issues:read"],
      "outcome": "ok",
      "error_code": null,
      "input_summary": "issue_id: AAC-42, status: done",
      "result_size": 2048,
      "tokens_in": 150,
      "tokens_out": 80,
      "cost_micros": 12,
      "created_at": "2025-06-22T15:30:00Z",
      "duration_ms": 245
    }
  ],
  "total": 1247,
  "limit": 50,
  "offset": 0
}

审计日志 UI

工作区管理员可以在 设置 → 审计与合规 → 连接器日志 中查看审计日志。

UI 提供：

时间线视图 — 最近的工具调用，带状态指示器（绿色 = 成功、黄色 = 被拒绝、红色 = 错误）
过滤 — 按平台、工具、结果、用户和日期范围
成本分析 — 一段时间内的令牌成本总和
事件调查 — 深入查看失败或被拒绝的调用以了解原因

示例：调查可疑的错误激增

进入 设置 → 审计与合规 → 连接器日志
按 platform: mcp、outcome: error、since: yesterday 过滤
点击失败的调用查看：
- 调用了哪个工具
- 发生了什么错误
- 谁发起了调用
- 当时的完整令牌范围
与代理执行日志关联以理解上下文

编辑策略

审计日志从不存储：

API 令牌或秘密
完整的请求/响应正文
结果本身披露之外的 PII

input_summary 字段编辑敏感数据：

❌ input_summary: "token=sk-..." — 编辑
✓ input_summary: "issue_id: AAC-42, status: done" — 安全
✓ input_summary: "create issue, title length: 45 chars, 3 labels" — 安全

范围强制实施 + 审计

使用权限不足的范围调用工具时：

调用被拒绝 — 工具永远不会执行
审计记录拒绝 — 结果为 denied，error_code 为 insufficient_scope
无变化 — 调用被记录但不采取行动

拒绝日志示例：

{
  "platform": "mcp",
  "tool_name": "delete_issue",
  "scopes": ["issues:read"],
  "outcome": "denied",
  "error_code": "insufficient_scope",
  "input_summary": "issue_id: AAC-100",
  "created_at": "2025-06-22T16:00:00Z"
}

结果为 outcome: ok 的成功调用证明令牌有正确的范围。被拒绝的调用证明它没有。

成本和使用情况追踪

对于驱动语言模型的调用（例如代理通过 MCP 调用工具），审计日志捕获：

tokens_in — 发送到模型的输入令牌
tokens_out — 接收的输出令牌
cost_micros — 估计成本（定价因模型而异）

管理员可以查询审计日志以：

预测成本 — 求和计费期间的 cost_micros
检测失控代理 — 查找具有异常令牌计数的用户/工作区
优化提示 — 识别具有最高输入令牌开销的工具

成本查询示例：

curl https://aacworkflow.example.com/api/audit/connectors \
  ?since=2025-06-01&until=2025-06-30 \
  | jq '[.entries[] | .cost_micros] | add'
# 返回 6 月份以微美元计的总成本

合规和保留

审计日志默认保留 90 天（每个工作区可配置）
日志不可变 — 不能编辑或删除
日志按工作区索引 — 一个工作区无法查看另一个的审计追踪
删除工作区、用户或令牌不会追溯删除审计条目（历史记录）

安全注意事项

审计日志是 仅限管理员。非管理员无法查看其工作区的审计条目。

审计写入是即发即忘 — 日志失败不会阻止工具执行
审计数据在静止时被加密（与问题数据相同的加密）
审计查询需要工作区管理员角色
审计条目携带 workspace_id，防止跨工作区数据泄露

示例工作流

1. 调查支持工单

"用户说 issue 更新失败。让我检查审计日志。"

curl https://aacworkflow.example.com/api/audit/connectors \
  ?user_id=<user_id> \
  &tool=update_issue \
  &outcome=error \
  &since=2025-06-22T00:00:00Z

你看到调用因 insufficient_scope 失败。用户的令牌只有 issues:read，没有 issues:write。

2. 监控 Telegram 机器人使用

"我们的 Telegram 机器人这周调用了多少工具？"

curl https://aacworkflow.example.com/api/audit/connectors \
  ?platform=telegram \
  &since=2025-06-15T00:00:00Z \
  | jq '.total'

结果：本周通过 Telegram 调用 342 次工具。

3. 计算成本

"我们的 MCP 工具在 6 月花费了多少？"

curl https://aacworkflow.example.com/api/audit/connectors \
  ?platform=mcp \
  &since=2025-06-01 \
  &until=2025-06-30 \
  | jq '[.entries[] | select(.cost_micros != null) | .cost_micros] | add'

结果：45,000 微美元 = $0.045

4. 查找被拒绝的调用

"为什么某些工具调用被拒绝？让我检查。"

curl https://aacworkflow.example.com/api/audit/connectors \
  ?outcome=denied \
  &since=yesterday

结果：12 个调用因 insufficient_scope 被拒绝，1 个因 malformed_input 被拒绝。

本页目录