把应用交给外部使用时,先要回答一个问题:调用方是人在用,还是程序在调。分享链接以链接本身为凭据,API Key 以密钥为凭据,两者的身份校验、回收方式与配额归属都不同。
两种凭据的形态
分享链接把访问入口封装成一个地址,可以附加身份验证要求,使用者打开页面即可对话。API Key 是一段长期有效的密钥,调用方在请求头里带上它访问接口,适合系统对系统的集成。前者的边界在浏览器,后者的边界在服务端。两类凭据留下的记录也不同:链接方式的访问记录带页面会话,密钥方式的调用记录带应用与密钥标识。做用量分析时先确认数据来自哪一侧,两边直接相加会把同一次使用算两遍。
选择矩阵
| 方案 | 适用条件 | 核对点 |
|---|---|---|
| 分享链接 | 人通过浏览器使用、不希望分发密钥 | 是否开启身份验证,链接是否会被转发到范围之外 |
| API Key | 程序调用、需要按调用方区分与统计 | 密钥归属哪个团队、谁能创建、如何轮换 |
| 两者并存 | 内部试用走链接、正式集成走密钥 | 两套入口的配额是否同一份、日志是否可合并 |
配额是按团队计的,两个入口产生的调用都记在同一份额度里。把链接接入面做大了,接口侧的余量会跟着变小,压测时要把两边合起来估。
回收与人员流动
链接的回收靠失效,密钥的回收靠轮换或删除,两者的操作人不同。密钥创建权限受团队默认权限开关影响:DEFAULT_TEAM_BASIC_PERMISSIONS_ENABLED 默认关闭,开启后新团队的全员组会增加创建 API Key 的权限,既有团队不自动补授。这条设置的副作用是新人能建密钥而老人不能,交接时容易误判为权限故障。
人员离职时的顺序是:先失效链接或轮换密钥,再停用账号。反过来做,账号停用了但链接仍可访问,看起来“已经关掉”,实际没有。
切换代价
从链接切到密钥,需要补的是服务端调用逻辑与错误处理;从密钥切到链接,需要补的是身份验证与页面侧的会话管理。两种方式都能用同一个应用,切换不涉及重建应用,但配额曲线会重新起算,切换前后各留一段观察期再对比。
顺带一条与页面有关的约束:4.17.0 起增加 CSRF 防御,嵌入第三方页面时先验证提交是否被拦;这一条对链接方式影响更直接。
落地时把两个入口分开记:链接按使用人记录,密钥按调用方记录。分开记之后,配额吃紧时能直接看出是哪一侧涨的;合在一起记,只看到总数,判断不了原因。
数据来源
| Source | Version | Document |
|---|---|---|
| FastGPT | v4.17.3 | self-host/upgrading/4-17/4173 |
| FastGPT | v4.17.0 | self-host/upgrading/4-17/4170 |