核心概念
在开始开发和开放接口前，先理解平台中的几个核心对象。它们共同决定了「谁能看到什么、接口在哪里运行、调用方如何获得权限」。
对象关系
项目（Project）
项目是最高层级的业务与数据隔离单元。接口、数据源、分组、环境、规则、订阅、AI 会话都按项目隔离。
- 登录后必须选择或创建项目，后续请求由前端自动携带
X-Project-Id。 - 项目拥有唯一 接口前缀，用于拼接开放接口地址；比较时忽略大小写与首尾斜杠。
- 项目成员分为管理员与成员；管理员可维护成员、删除项目内资源。
- 跨项目访问数据源需要通过「数据源授权」；被授权方只能使用数据，不能查看连接账号与密码。
详见 项目空间。
用户、角色与菜单
平台采用「用户 - 角色 - 菜单」的 RBAC 模型：
- 菜单权限：决定登录后能看到哪些导航与页面，以及角色可访问的接口地址规则。
- 数据权限：在菜单权限之上，用户只能看到自己创建的数据，以及被协作授权访问的分组与数据源。
- 超级管理员： 默认拥有全部菜单，不受角色菜单限制；重置密码等敏感操作仅超级管理员可执行。
- 用户未分配角色不能登录（
41003）；角色未关联任何菜单也不能登录（41004）。
详见 权限模型。
数据源（Data Source）
数据源描述一个数据库连接，包括类型、地址、账号、密码、连接池参数与启用状态。平台通过数据源驱动 SPI 统一接入异构数据库。
- 保存前必须测试连接。
- 密码加密存储，前端不回显明文。
- 元数据按「库 → 表 → 字段」三级展开。
- 数据查询页只允许
SELECT、SHOW、DESC、DESCRIBE、EXPLAIN开头的只读语句。
API（接口）
一个 API 由基本信息、请求参数、返回参数、执行配置与数据插件组成。
| 维度 | 取值 | 说明 |
|---|---|---|
| 执行类型 | SQL 脚本 / 单表 / 代理 / 编排 | 决定由哪个执行器处理 |
| 请求方式 | GET / POST / PUT / PATCH / DELETE | 部分类型与数据源下会收窄可选范围 |
| 权限级别 | 公开 / 私有 | 公开且已发布到生产环境的接口才进入 API Hub |
| 认证方式 | 无认证 / 简单认证 / 签名认证 | 决定网关的鉴权策略 |
| 发布协议 | REST / MCP | MCP 仅简单认证时可勾选 |
| 操作类型 | 查询 / 插入 / 修改 / 删除 | 脚本接口不显示该项 |
| 状态 | 开发中 / 已发布 / 已下线 | 已下线接口不能调用 |
接口地址由「环境前缀 + 项目前缀 + 接口路径」构成；同一环境下「请求方式 + 路径」必须唯一。
环境（Environment）
环境是接口与策略数据的隔离维度。
- 系统内置
dev开发环境，受保护不可删除。 - 每个项目默认初始化
dev与生产环境；生产环境只能有一个且必须启用。 - 环境包含：环境编码、名称、接口前缀、访问地址、绑定服务名、MCP 前缀、是否生产环境、访问权限。
- 接口列表、流控规则、缓存规则、IP 规则、告警规则均按当前所选环境展示与保存。
- 环境下已有接口时不允许删除。
详见 环境与发布。
版本与发布快照
同一个接口可以有多个版本，不同版本的接口地址不能相同。发布到某个环境时，平台会生成该环境的 发布快照，记录接口在该环境的完整定义。
- 开发中的修改不会自动影响已发布快照。
- 已上线接口编辑前必须先下线。
- 支持版本升级、跨环境同步、Bundle 导入导出与离线文档导出。
- 网关与执行端读取的是快照对应的运行时配置，而不是编辑中的草稿。
详见 版本、同步与迁移。
调用凭证（Credential / App）
调用凭证是开放接口的调用身份，包含 AppCode、AppKey、AppSecret、作用域、IP 白名单与 MCP 开关。
| 作用域 | 可访问范围 |
|---|---|
| 项目级 | 当前项目内符合授权条件 的接口 |
| 接口级 | 仅被明确授权的接口 |
- 简单认证：只传
X-AppKey。 - 签名认证：传
X-AppKey、X-Timestamp、X-Nonce、X-Sign，可选X-Algorithm。 - 凭证被禁用后，所有调用返回
40019。 - 凭证启用 MCP 后，可作为 MCP Server 使用。
详见 调用凭证。
订阅（Subscription）
对于需要控制的接口，调用方需要提交订阅申请并经审批。
| 状态 | 含义 |
|---|---|
pending | 待审批，可撤回 |
active | 生效中，受有效期与日调用量约束 |
rejected | 已拒绝，可重新申请 |
frozen | 已冻结，调用返回 40021 |
expired | 已过期，可续订 |
unsubscribed | 已退订 |
同一凭证对同一接口只能存在一条有效订阅。日调用量通过 Redis Lua 原子预留，超限返回 HTTP 429 + 40023；下游失败会回退额度。
详见 订阅与审批。
治理规则（Rules）
网关治理规则按环境隔离，并关联到接口：
| 规则 | 作用 | 超限响应 |
|---|---|---|
| 流量控制 | 限制 QPS | 429 + 40429 |
| 熔断降级 | 慢调用比例、异常比例、异常数 | 503 + 40503 |
| 接口缓存 | Redis 缓存 JSON 查询结果 | 命中加 Api-Cache: true |
| IP 规则 | 接口级黑/白名单 | 40012 |
| 告警规则 | 按日志指标触发通知 | 生成告警记录 |
- 规则需要关联 API 后才生效；一个接口同一类规则只能关联一个。
- 接口存在多版本时，规则只对当前最新版本生效。
- 已关联 API 的规则不能直接删除，需先解除关联。
运行时配置与 Trace
管理端保存配置后，会写入 MySQL 并同步到 Redis 运行时中枢，通过 Pub/Sub 增量通知网关与执行服务。
- 网关按「请求方式 + 路径」匹配动态路由。
- 每次请求可携带
X-Trace-Id；不传时由平台生成，并在返回体traceId中回传。 - 接口日志记录请求、响应、耗时、状态与来源（
rest/mcp）。 - 配置变更实时生效，无需重启服务；定时对账保证 Redis 与 MySQL 最终一致。
AI 与会话
- 智能助理：以对话方式规划并调用平台工具，支持问数、查日志、开发接口等操作。
- 问数工具：对指定数据源生成只读 SQL，结果以表格/图表展示，可编辑 SQL 后再次预览。
- 智能体：外部 AI Agent 接入平台管理能力的身份，通过 MCP 使用平台工具。
- 会话与 AI 日志按用户和项目隔离，写操作需要人工确认。
术语速查
| 术语 | 含义 |
|---|---|
| API Hub | 对外展示公开、生产环境、已上线接口的门户 |
| 发布快照 | 接口在某个环境的只读发布版本 |
| 运行时配置 | Redis 中供网关与执行端读取的配置 |
| 工具时间线 | 智能助理展示每次工具调用过程的条目 |
| MCP Tool | 通过 MCP 协议暴露给 AI 客户端的可调用工具 |
| 配额预留 | 调用前原子扣减当日订阅额度，失败回退 |
| 受信代理 | 只有来自受信网段的转发头才被采信，用于识别真实客户端 IP |