Headless CMS GraphQL接口权限控制
Headless CMS 的 GraphQL 接口默认可能允许匿名查询，一旦暴露到公网，任何人都能读取或修改数据。
本文用零基础也能跟做的步骤，讲清如何通过 Token 鉴权为 GraphQL 接口加上权限控制，最终实现：未携带有效 Token 的请求被拒绝，不同角色只能访问被授权的字段和操作。
动手前的环境确认
开始配置前，先确认你的 Headless CMS 支持 API Token 或角色权限功能。
常见系统如 Strapi、Directus、Ghost 等都有类似机制，但入口名称不同。
本文以通用配置逻辑为例，具体路径请以你所用系统的官方文档或后台实际显示为准。
你需要准备：
- 一个已部署的 Headless CMS 实例，且 GraphQL 插件已启用。
- 管理员账号，能进入后台设置或角色管理页面。
- 一个用于测试的 API 客户端，如 Postman、curl 或浏览器插件。
- 记录下 GraphQL 端点地址，通常形如
https://your-cms.com/graphql。
生成并管理 API Token
Token 是访问接口的临时钥匙，不要直接使用管理员账号密码调用 GraphQL。
进入后台，找到类似 设置 → API 令牌 或 Settings → API Tokens 的入口。
点击创建令牌，填写名称（如 graphql-readonly），选择令牌类型或权限范围。
如果系统支持，优先选择 只读 或 自定义 权限，避免直接给全权限。
创建完成后，系统会显示一串 Token 字符串，通常只显示一次，请立即复制保存到安全位置。
部分系统还允许设置 Token 有效期，建议根据业务需要设置合理时长，不要永久有效。
为 GraphQL 请求添加 Token 头
Token 生成后，调用 GraphQL 时需要在 HTTP 请求头中携带它。
最常见的格式是：
Authorization: Bearer <你的Token>如果用 curl 测试，命令如下：
curl -X POST https://your-cms.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOi..." \
-d '{"query":"{ articles { title } }"}'如果系统使用自定义头，比如 X-API-Token，则替换为：
X-API-Token: <你的Token>具体头名称请查看你所用 Headless CMS 的 GraphQL 文档。
绑定权限规则到角色或 Token
仅添加 Token 还不够，必须让这个 Token 关联到具体的权限规则。
在后台找到 角色与权限 或 Roles & Permissions 页面。
以 Strapi 为例，进入 设置 → 用户及权限插件 → 角色，选择 Authenticated 或你自定义的角色。
在权限列表中展开 GraphQL 插件，勾选允许的查询和变更操作。
例如只勾选 find 和 findOne，不勾选 create、update、delete。
如果系统支持字段级权限，还可以限制某些敏感字段不可见。
保存后，用之前生成的 Token 重新发起请求。
如果权限配置正确，未授权的操作会返回 Forbidden 或 403 错误。
常见报错与排查方向
401 Unauthorized：Token 未提供、格式错误或已过期。
检查请求头名称和 Token 值是否正确，确认没有多余空格。
403 Forbidden：Token 有效但权限不足。
回到角色权限页面，确认该 Token 对应的角色已勾选所需操作。
Cannot query field 错误：GraphQL 查询字段与 schema 不匹配，或该字段被权限隐藏。
用 GraphQL Playground 查看可用字段。
Token 泄露风险：不要把 Token 写在前端代码或公开仓库中。
前端应通过后端代理调用 GraphQL，由后端保管 Token。
验证权限是否生效
完成配置后，做两组对比测试：
- 不带 Token 请求 GraphQL，应返回 401 或权限错误。
- 带只读 Token 请求变更操作（如 mutation），应返回 403。
- 带只读 Token 请求允许的查询，应正常返回数据。
如果测试结果符合预期，说明 Token 鉴权和权限控制已生效。
建议定期轮换 Token，并移除不再使用的令牌。
几个容易踩的坑
- 混淆认证与授权：Token 解决“你是谁”，权限规则解决“你能做什么”，两者缺一不可。
- GraphQL 端点暴露：即使加了 Token，也建议用 Nginx 或防火墙限制来源 IP，减少攻击面。
- 忽略 introspection 查询：生产环境应关闭 GraphQL 的 introspection 功能，避免 schema 泄露。
- Token 硬编码：永远不要把 Token 提交到 Git 仓库，使用环境变量或密钥管理服务。
按照以上步骤操作后，你的 Headless CMS GraphQL 接口就有了基本的 Token 鉴权和权限控制。
如果遇到系统特有的配置项，优先查阅官方文档，不同版本的界面路径可能有差异。
