★ FEATURED ARTICLE 1. 团队列表接口为什么值得单独拆出来做fastGPT 的团队管理模块里团队列表 API 是一个看起来简单、实际很容易踩坑的接口。它要解决的核心问题是一个用户可能同时属于多个团队在每个团队里的角色还不一样前端下拉框需要把这些团队全部列出来用户切换后要能查到对应团队下的成员和部门。这个接口一旦写歪表现就是下拉框只显示一个团队、切换后权限错乱、或者返回字段缺斤少两导致前端渲染报错。我这次要落地的场景是基于 Next.js 的 API Route 和 Mongoose 的 populate 查询把团队列表接口跑通同时把模型调用通道统一到 TaoToken 的 Key 上方便本地联调时不用来回切多个平台的密钥。适合正在做 fastGPT 二次开发、需要自己扩展团队管理能力的同学也适合想搞清楚 fastGPT 权限链路是怎么串起来的人。整条链路涉及三块MongoTeamMember 集合的查询、getResourcePermission 拿权限、以及 JWT 的签发与解析。下面按可复制的顺序拆开讲配置骨架和请求示例都会给全。2. TaoToken 前置统一 Key 与本地联调通道在动手写接口之前先把调用通道理顺。fastGPT 本身支持通过环境变量配置 OpenAI 兼容的 base url 和 key这就是接入统一 Key 的入口。TaoToken 提供 OpenAI 兼容的 API 通道官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key然后把它填到 fastGPT 的环境变量里。这里的关键是fastGPT 的.env里ONEAPI_URL和CHAT_API_KEY是配套的如果填了ONEAPI_URLkey 也必须是这个通道的 key否则会走到默认的 OpenAI 地址上去联调时表现为 401 或模型不存在。创建 Key 的入口在控制台的 API Keys 页面地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到 key 之后先别急着写代码用模型对话页面发一条测试消息确认通道是通的地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。这一步能省掉后面大量「到底是接口写错了还是 key 不对」的排查时间。如果你后面还要做长期编码或者 Agent 类的联调可以了解下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合高频调用的场景。3. 可复制配置config.toml 与 settings.json 骨架fastGPT 的配置分两层一层是服务端的.env一层是本地开发工具比如 Cline、CC Switch的配置文件。先把服务端.env里和团队列表接口、模型通道相关的部分列出来。# .env 关键片段 PORT3001 LOG_DEPTH3 DEFAULT_ROOT_PSW245ZXCVqaz DB_MAX_LINK5 # JWT 与权限相关 TOKEN_KEYsadasgvfd FILE_TOKEN_KEYfiletokenkey ROOT_KEYfdafasd # 模型通道优先走 ONEAPI_URLkey 需与之一致 OPENAI_BASE_URLhttps://taotoken.net/api ONEAPI_URLhttps://taotoken.net/api/v1 CHAT_API_KEYsk-你的TaoToken密钥 # Mongo 连接本地开发建议加 directConnectiontrue MONGODB_URImongodb://10.185.92.58:27017/fastgpt?authSourceadmindirectConnectiontrue # 向量库优先级 pg milvus PG_URLpostgresql://user08:245ZXCVqaz10.195.162.55:5432/fastgpt MILVUS_ADDRESShttps://in03-78bd7f60e6e2a7c.api.gcp-us-west1.zillizcloud.com MILVUS_TOKEN你的milvus令牌 SANDBOX_URLhttps://fastgptsandbox.encloudx.com HOME_URL/ LOG_LEVELdebug STORE_LOG_LEVELwarn注意TOKEN_KEY是 JWT 签发和解析共用的密钥团队列表接口里authCert和createJWT都依赖它。本地改过之后之前登录拿到的 cookie 会全部失效需要重新登录。然后是本地开发工具的配置。如果你用 Cline 或 CC Switch 发起调用配置骨架大致如下。这里以 OpenAI 兼容格式为例{ provider: openai-compatible, baseUrl: https://taotoken.net/api/v1, apiKey: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514, temperature: 0.2, maxTokens: 4096 }如果你用的是 CC Switch 管理多套配置可以把它写成命名 profile切换时不用改代码# config.toml [profiles.fastgpt-local] base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken密钥 model claude-sonnet-4-20250514 [profiles.fastgpt-local.headers] Authorization Bearer sk-你的TaoToken密钥 Content-Type application/json提示baseUrl结尾带不带/v1取决于客户端实现。Cline 这类工具通常要求带/v1而直接 curl 调/chat/completions时https://taotoken.net/api/v1/chat/completions是完整路径。4. 团队列表接口实现查询链路与字段拼装团队列表接口的核心逻辑分三步认证拿到 userId、查 MongoTeamMember 并 populate team、对每个成员记录计算权限并拼装返回字段。先看认证部分。authCert会走parseHeaderCert根据请求头里的 cookie 或 token 解析 JWT拿到 userId、teamId、tmbId。团队列表接口用的是authToken: true也就是走 cookie/token 这条路不是 apikey。import { NextAPI } from /service/middleware/entry; import type { NextApiRequest, NextApiResponse } from next; import { authCert } from fastgpt/service/support/permission/auth/common; import { MongoTeamMember } from fastgpt/service/support/user/team/teamMemberSchema; import { getResourcePermission } from fastgpt/service/support/permission/controller; import { PerResourceTypeEnum } from fastgpt/global/support/permission/constant; import { TeamPermission } from fastgpt/global/support/permission/user/controller; import { TeamDefaultPermissionVal } from fastgpt/global/support/permission/user/constant; import { TeamMemberRoleEnum } from fastgpt/global/support/user/team/constant; import { TeamSchema } from fastgpt/global/support/user/team/type; async function handler(req: NextApiRequest, res: NextApiResponse) { try { const { userId } await authCert({ req, authToken: true }); let userInTeams await MongoTeamMember.find({ userId }) .populate{ team: TeamSchema }(team) .lean(); if (!userInTeams.length) { return res.status(404).json({ message: member not exist }); } const aggreTeam await Promise.all( userInTeams.map(async (tmb) await getTeam(tmb)) ); return res.status(200).json(aggreTeam); } catch (error: any) { return res.status(500).json({ message: 服务器内部错误 }); } }这里有个容易忽略的点MongoTeamMember.find({ userId })返回的是数组一个用户在多团队时会有多条记录。populate(team)把 teamId 对应的团队文档填充进来这样后面才能拿到tmb.team.name、tmb.team.avatar这些字段。然后是getTeam函数负责把每条成员记录转成前端需要的结构async function getTeam(tmb: any) { const Per await getResourcePermission({ resourceType: PerResourceTypeEnum.team, teamId: tmb.teamId, tmbId: tmb._id }); return { userId: String(tmb.userId), teamId: String(tmb.teamId), teamAvatar: tmb.team.avatar, teamName: tmb.team.name, memberName: tmb.name, avatar: tmb.avatar, balance: tmb.team.balance, tmbId: String(tmb._id), teamDomain: tmb.team?.teamDomain, role: tmb.role, status: tmb.status, permission: new TeamPermission({ per: Per ?? TeamDefaultPermissionVal, isOwner: tmb.role TeamMemberRoleEnum.owner }), notificationAccount: tmb.team.notificationAccount, lafAccount: tmb.team.lafAccount, openaiAccount: tmb.team.openaiAccount, externalWorkflowVariables: tmb.team.externalWorkflowVariables }; }getResourcePermission会根据 teamId 和 tmbId 去查这个成员在团队里的权限位。如果查不到就用TeamDefaultPermissionVal兜底。isOwner的判断直接看 role 是不是 owner这个字段前端会用来决定是否显示「团队设置」入口。最后导出时用NextAPI包一层它会统一处理错误和响应格式export default NextAPI(handler);5. 切换团队接口与 JWT 解析链路团队列表只是把团队列出来真正切换团队是另一个接口。它的逻辑是用 userId、目标 teamId、以及该团队下的 tmbId 重新签一个 JWT写回 cookie。后续所有接口都从这个 cookie 里解析出当前团队上下文。import type { NextApiRequest, NextApiResponse } from next; import { NextAPI } from /service/middleware/entry; import { MongoTeam } from fastgpt/service/support/user/team/teamSchema; import { createJWT, setCookie } from fastgpt/service/support/permission/controller; import { authCert } from fastgpt/service/support/permission/auth/common; import { MongoTeamMember } from fastgpt/service/support/user/team/teamMemberSchema; async function handler(req: NextApiRequest, res: NextApiResponse) { let { teamId } req.body; const { userId, isRoot } await authCert({ req, authToken: true }); const userTeam await MongoTeamMember.findOne({ userId, teamId }); const tmbId: any userTeam?._id; const token createJWT({ _id: userId, team: { teamId, tmbId }, isRoot }); setCookie(res, token); } export default NextAPI(handler);这里的关键是createJWT的 payload 结构_id是 userIdteam里带 teamId 和 tmbIdisRoot标记是否 root 用户。这个结构和登录时签发的 token 是一致的区别只是 teamId 换成了目标团队。解析侧在parseHeaderCert里。它按优先级依次尝试三种认证方式apikey、token/cookie、rootkey。团队列表和切换团队走的是 token/cookie 这条路async function authCookieToken(cookie?: string, token?: string) { const cookies Cookie.parse(cookie || ); const cookieToken token || cookies[TokenName]; if (!cookieToken) { return Promise.reject(ERROR_ENUM.unAuthorization); } return await authJWT(cookieToken); }authJWT用TOKEN_KEY验签并解出 userId、teamId、tmbId、isRoot。如果验签失败或 token 过期直接抛unAuthorization。这就是为什么改了TOKEN_KEY之后必须重新登录。apikey 那条路走的是parseAuthorization从Authorization: Bearer fastgpt-xxxx-appId里拆出 apikey 和 appId再查authOpenApiKey拿到 teamId 和 tmbId。这条路主要用于外部调用机器人对话接口和团队列表接口不是同一条认证链路。rootkey 那条路最简单直接比对process.env.ROOT_KEY匹配就放行返回isRoot: true。它不参与团队列表的正常流程但排查权限问题时可以用它来确认是不是认证层的问题。6. 验证请求与成功结果核对配置和代码都就位后用 curl 发起一次团队列表请求。前提是你已经通过登录接口拿到了 cookie或者手动构造了一个有效 token。curl -X GET http://localhost:3001/api/support/user/team/list \ -H Cookie: fastgpt_token你的JWT令牌 \ -H Content-Type: application/json成功时返回的是一个数组每个元素对应一个团队。重点核对这几个字段字段含义核对要点teamId团队 ID多个团队时不应重复tmbId成员记录 ID切换团队时用它签 JWTteamName团队名称前端下拉框显示这个role成员角色owner/member 决定权限permission权限对象由 getResourcePermission 计算status成员状态禁用成员不应出现在列表如果返回 404 且 message 是member not exist说明MongoTeamMember.find({ userId })没查到记录检查 userId 是否正确、Mongo 连接是否通。如果返回 500先看服务端日志大概率是populate(team)时 teamId 对应的团队文档不存在导致tmb.team.name取值为 undefined 抛错。切换团队接口的验证curl -X POST http://localhost:3001/api/support/user/team/switch \ -H Cookie: fastgpt_token你的JWT令牌 \ -H Content-Type: application/json \ -d {teamId:目标团队ID}成功时响应头里会带Set-Cookie新的 token 里 teamId 和 tmbId 已经换成目标团队。你可以把新 cookie 再拿去调团队列表接口确认返回的当前团队上下文变了。用 Cline 或 CC Switch 发起调用时把 baseUrl 指向https://taotoken.net/api/v1apiKey 填 TaoToken 的 key模型选一个可用的然后让它帮你发上面这两个请求并解析返回。这样做的价值是模型通道和业务接口的联调可以并行不用等前端页面写完。7. 本篇常见错排查报错一unAuthorization但 cookie 明明带了。先确认TOKEN_KEY没改过或者改过之后重新登录了。其次检查 cookie 的 name 是不是TokenName对应的值fastGPT 默认是fastgpt_token。如果是从浏览器复制的 cookie注意有没有被 URL 编码。报错二团队列表只返回一个团队但用户确实在多个团队里。检查MongoTeamMember集合里该 userId 是不是只有一条记录。多团队场景下每个团队都会有一条独立的 member 记录userId 相同、teamId 不同。如果数据只有一条是数据写入的问题不是接口的问题。报错三Cannot read property name of undefined。这是populate(team)没填充成功。常见原因是 teamId 在 Team 集合里不存在或者 Mongoose 的 ref 配置不对。可以在查询后加一行console.log(userInTeams)确认 team 字段是不是 null。报错四切换团队后其他接口还是返回旧团队的数据。检查setCookie有没有真正写回响应头。有些反向代理会过滤Set-Cookie本地开发时如果用了 nginx 之类的中间层确认它没把 cookie 头吃掉。另外前端发请求时要带credentials: include否则 cookie 不会自动带上。报错五模型调用返回 401 或 model not found。回到.env检查ONEAPI_URL和CHAT_API_KEY是否配套。如果ONEAPI_URL填了 TaoToken 的地址key 也必须是 TaoToken 的 key。两者不匹配时请求会走到默认 OpenAI 地址自然报错。用模型对话页面先确认 key 本身可用再回来查 fastGPT 的配置。8. 把联调动作固定下来团队列表接口本身不复杂复杂的是它背后的认证链路和权限计算。我的做法是每次改完TOKEN_KEY或团队相关 schema先跑一遍「登录 → 团队列表 → 切换团队 → 再查团队列表」这个四步动作确认 cookie 里的 teamId 确实变了、返回字段完整。这套动作固定下来之后后面加成员管理、部门查询接口时可以直接复用同一套认证和权限逻辑不用每次重新排查。模型通道这边把 TaoToken 的 key 配到.env的CHAT_API_KEYbase url 配到ONEAPI_URL本地联调时模型调用和业务接口走同一套环境变量省掉来回切配置的麻烦。需要新建 key 或者查用量时控制台在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到认证或参数问题可以先翻文档再排查代码。
阅读完成 · 觉得有帮助？
