两条路径解决的是不同问题。接口密钥解决“程序怎么调”,身份集成解决“人是谁、权限从哪来”。混用两条路径,最后会得到一套既追不到人又管不住权限的接入。
两条路径的分工
对照材料:FastGPT 官方说明。
接口密钥是由平台签发、可设置有效期与使用限制的调用凭据,调用方在请求头里带上它访问接口,适合系统对系统的调用。身份集成走单点登录,专业版起支持,账号由已有系统创建,登录后进入应用,授权仍由应用内的组织架构与资源授权决定。
一条边界要先立住:密钥证明调用方,不证明自然人;单点登录证明自然人,不证明调用方。两者都在的链路,要说明以谁为准。
对照
| 维度 | 接口密钥 | 身份集成 |
|---|---|---|
| 证明对象 | 调用方(系统) | 使用人(自然人) |
| 凭据来源 | 平台内创建,归属团队 | 已有身份系统签发 |
| 回收方式 | 轮换或删除密钥 | 停用账号,并验证已有会话的退出策略 |
| 日志可追溯性 | 追到密钥与团队 | 追到具体人 |
| 适用场景 | 定时任务、批量同步、系统间调用 | 人机对话、审批、需留痕操作 |
按调用方判定
第一问是调用方是人还是程序。程序调用走密钥,人使用走身份集成,两者都不要的接入方式(例如公开分享链接)只适合试用,不适合正式业务。
第二问是操作是否留下业务后果。写单据、改状态、提交审批这类操作,日志要能追到人;只做查询的接口,追到密钥与团队通常足够。两问答完,路径基本确定。
凭据怎么管
密钥的关键落在归属与轮换,技术上并不复杂。三个问题要答:密钥归哪个团队、谁能创建、多久换一次。创建权限受团队默认权限开关影响:开关开启后新团队的全员组会增加创建权限,既有团队不自动补授,交接时要先看这条开关的实际状态。
轮换要有计划,并按计划演练一次。把轮换写进运维手册,注明责任人、周期与验证方式;没有计划的轮换,最后会变成“等出问题再换”,而出问题时往往密钥已经泄露了一段时间。
日志与审计的取舍
身份集成的日志完整度更高:谁在什么时候调用了哪个应用,记录到人。密钥调用的日志边界在调用方:能证明是哪个系统、哪个团队,无法证明操作者是谁。
这个差别在验收阶段会被追问。可行的折中是两层记录:应用日志按人记录,接口调用日志按系统记录,两边用同一个业务单号串起来。串起来之后,追查一次操作可以从业务单号回溯到具体调用,比只有一层日志更可靠。
混合路径的注意事项
最常见的混合是人在页面上操作、后台服务代为执行。这种设计里,页面身份与服务身份都要记录,并明确以谁为准。以服务身份为准的好处是实现简单,坏处是审批类操作的责任落不到人。
另一种混合是多个系统共用一个密钥。这种做法短期省事,长期的问题是配额无法归集、封禁一方影响全部。共用之前先把配额与影响面算清。
判定结论
三条结论可以直接用:人使用走身份集成,程序调用走密钥,涉及审批与写操作的身份必须可追溯到人。三条之外再加一条运维约定:每季度核对一次密钥清单与创建权限开关状态。核对记录本身就是审计材料。
密钥轮换怎么做
轮换分三步:先建新密钥并行使用,确认调用方切换完成,再停用旧密钥。三步之间的观察期不少于一个调用周期,避免定时任务刚好在切换窗口执行。轮换记录写明日期、旧密钥停用时间与验证方式,季度对账时按记录核一次。共用密钥的场景,轮换要提前通知全部调用方,否则会出现一方切换、其他方失败的中间态。
交接时的检查顺序
交接或轮岗时按三步检查:先看密钥清单与创建权限开关状态,再看身份集成的账号同步是否仍在运行,最后随机抽一条日志,看能否从业务单号追到具体调用。所需时间取决于凭据数量与身份系统,漏做一次则可能几个月无人发现权限早已过期。
数据来源
| 主题 | 版本 | 来源 |
|---|---|---|
| 单点登录与 OA 集成、组织架构分权 | 当期商业方案 | FastGPT 商务咨询:授权、部署与支持范围 |
| 团队默认权限开关与 API Key 创建权限 | v4.17.3 | self-host/upgrading/4-17/4173 |