AI 和 MCP 控制
PetroBench 中的 AI、MCP 和 API 访问默认关闭，仅在您的组织提出请求时启用。介绍如何启用、谁可以连接、令牌和 Webhook 如何工作，以及如何关闭访问。
本页介绍您的组织如何控制 PetroBench 中的 AI、MCP 和 API 访问。
要点
- 默认关闭：AI 功能、MCP、REST API 和 Webhook 在您的组织提出请求之前一直保持关闭。
- 非必需：油井管理和有杆泵举升模拟是确定性的工程计算。关闭 AI 时它们的工作方式完全相同。
- 与个人或部门绑定：每个连接都由一位具名用户或管理员创建，只能看到其所有者可见的内容，并且可以随时撤销。
- 不训练模型：PetroBench 不使用客户数据训练 AI 模型。
默认关闭
| 功能 | 默认 | 启用方式 |
|---|---|---|
| MCP 服务器（连接 Claude、ChatGPT、Cursor 或其他 MCP 客户端） | 关闭 | 应您的请求按组织启用 |
| REST API 和服务令牌 | 关闭 | 应您的请求按组织启用 |
| Webhook | 关闭 | 应您的请求按组织启用 |
| PetroBench 应用内的 AI 功能 | 关闭 | 应您的请求按组织启用 |
如果您的安全策略要求保持 AI 关闭，则无需任何操作。这就是默认状态，除非您的组织提出请求，否则不会有任何变化。
API、MCP 和 Webhook 访问取决于您的计划。您的订单表列出了包含的内容。
连接方式
为您的组织启用访问本身并不会连接任何东西。每个连接都需要您组织中的某个人执行明确的操作，并且每个连接都与一位用户或一个部门绑定。
| 方式 | 创建者 | 代表身份 | 典型用途 |
|---|---|---|---|
| 个人 API 令牌 | 任何用户，为自己创建 | 该用户 | 个人运行的脚本和 MCP 客户端 |
| 已连接应用 (OAuth) | 任何用户，通过批准同意屏幕 | 该用户 | Claude、ChatGPT、Cursor 和其他 MCP 客户端 |
| 服务令牌 | 部门管理员和 HQ 管理员 | 部门的服务账户 | 共享集成，例如数据管道或监控作业 |
令牌或已连接应用能看到的内容永远不会超过其所有者在 Web 应用中能看到的内容。它遵循相同的角色、部门和组织边界。
个人 API 令牌
用户在 Settings > API Tokens 下创建个人令牌。
- 范围：用户选择令牌可以执行的操作，例如读取油井、写入油井、读取模拟或运行模拟。只提供用户角色和计划允许的范围。
- 有效期：令牌在 7、30、90 或 365 天后过期。不存在没有有效期的令牌。
- IP 允许列表：在包含此功能的计划中，可以将令牌限制在一组 IP 地址内。
- 上次使用：每个令牌都会显示上次使用的时间。
- 撤销：用户可以随时撤销令牌。令牌从下一个请求起停止工作。
已连接应用 (OAuth)
Claude 和 ChatGPT 等 MCP 客户端通过带 PKCE 的标准 OAuth 2.1 登录进行连接。用户登录 PetroBench 后会看到一个同意屏幕，其中列出该应用请求的权限。默认的 MCP 范围为只读：读取油井、模拟和设备。
- 读取范围始终开启。写入范围（例如写入油井或运行模拟）默认不勾选。用户需要逐项有意勾选。
- 同意屏幕只提供用户角色和计划允许的范围。服务器在签发令牌时会再次检查。
- 审计日志会记录用户授予的范围。
- 通过 OAuth 永远无法代表其他用户执行操作。
- 如需更改范围，请断开应用并重新连接。
- 只有经批准的客户端域可以接收登录重定向。
- 用户可以在 Settings > Connected Apps 下查看所有已连接应用。
- Disconnect 会一次性撤销该应用的所有访问令牌和刷新令牌。
服务令牌
服务令牌用于不应依赖某一个人账户的集成。它们属于部门，而不属于用户。
- 谁可以创建：部门管理员和 HQ 管理员，在 API & Integrations > API Console > Service Tokens 下创建。
- 权限：在创建时选择。服务令牌只能获得该部门已获许可的权限。
- 有效期：30、90 或 365 天。管理员会在令牌过期前 30 天和 7 天收到提醒邮件。
- IP 允许列表：服务令牌可以限制为已知 IP 地址。来自未知地址的请求会暂停该令牌，直到管理员恢复它。
- 限制：每个部门最多五个有效的服务令牌。
- 轮换和撤销：轮换会签发一个名称、权限和 IP 列表都相同的新密钥，并撤销旧密钥。撤销会使令牌从下一个请求起停止工作。
- 席位：服务账户不计入用户席位。
- 审计跟踪：调用系统可以指明其代表的人员。如果该人员是您组织中的活跃用户，PetroBench 会在审计日志中记录该人员；否则记录部门的服务账户。
Webhook 通知
当 PetroBench 中发生某些事件时，Webhook 会向您的系统发送 HTTPS 请求，因此您无需轮询 API。
- 谁可以管理：部门管理员和 HQ 管理员，在 API & Integrations > API Console > Webhooks 下管理。
- 事件：模拟完成或失败；油井创建、更新、归档或设备变更；报告和导出就绪；导入完成；用户被邀请或移除；API 令牌创建、撤销或暂停。完整列表见 Webhook 参考文档。
- 签名：每次投递都带有
X-PetroBench-Signature标头（基于时间戳和请求体的 HMAC-SHA256 签名）以及X-PetroBench-Timestamp标头。在信任投递之前请同时验证两者。轮换密钥时，旧密钥会继续有效一天，以便您无停机切换。 - 重试：投递失败后会在约 24 小时内以逐渐增加的间隔重试最多八次。不会跟随重定向。
- 自动停用：连续失败三天的 Webhook 会被停用，并通知管理员。
- 投递日志：每次投递都会连同其请求和响应一起记录，管理员可以从控制台重新发送投递。
速率限制
API 和 MCP 请求按令牌和按部门进行速率限制，并有取决于您计划的月度配额。每个响应都包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 标头，以便客户端在达到限制之前降低请求频率。
关闭访问
- 单个用户：用户在 Settings 下撤销其令牌或断开应用。管理员可以对用户使用 Kill access，这会删除该用户的所有令牌并结束其会话。
- 单个集成：管理员在 API Console 中撤销服务令牌或停用 Webhook。
- 整个组织：联系您的 PetroBench 客户团队以关闭 MCP、API、Webhook 或 AI 功能。访问关闭后，现有令牌和已连接应用将停止工作。
每次令牌变更和已连接应用授权都会记录在审计日志中。
您的数据与模型训练
PetroBench 不使用客户数据训练 AI 模型。启用 AI 功能后，模型提供商仅处理回答请求所需的数据，并受禁止其使用这些数据进行训练的合同约束。
当您通过 MCP 连接自己的 AI 客户端时，该客户端接收的数据受您与该提供商之间的协议约束。详情请参阅隐私政策。