> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJlOTFmOGM0Yy1hMGYxLTQxNDItOTQ2OC02MDcyYjY3MGQ3YWYiLCJleHAiOjE3NzgyODc5NDMsImlhdCI6MTc3ODI4NzY0M30.LAaSIaE0J5y7Tx1Qx-z647kSaKN7BZZVZbaLBNp_Ke0
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 基于角色的访问控制

> 了解如何使用基于角色的访问控制 (RBAC) 限制对文档的访问

<Warning title="团队版和企业版功能">
  基于密码的 RBAC 在[团队版和企业版计划](https://buildwithfern.com/pricing)中可用。基于 JWT 和 OAuth 的 RBAC 需要[企业版计划](https://buildwithfern.com/pricing)。
</Warning>

RBAC 根据用户角色控制对页面、部分和其他导航项目的访问。它与[密码保护](/learn/docs/authentication/setup/password-protection)、[JWT](/learn/docs/authentication/setup/jwt) 和 [OAuth](/learn/docs/authentication/setup/oauth) 身份验证配合使用。

RBAC 对于合作伙伴文档、测试版功能、分层访问和内部内容非常有用。在使用 JWT 或 OAuth 身份验证时，您可以将其与 [API 密钥注入](/learn/docs/authentication/features/api-key-injection)结合使用。配置 RBAC 后，[Ask Fern](/learn/docs/ai-features/ask-fern/overview) 会自动遵守这些权限。默认情况下，受限页面对未授权用户完全隐藏——如果您希望它们可见但被锁定，请在设置期间告知 Fern。

## 设置

<Info>
  RBAC 在 `docs.yml` 中配置，并通过 [Fern CLI](/learn/cli-api-reference/cli-reference/overview) 管理。如果您使用[向导界面](https://dashboard.buildwithfern.com/get-started)设置网站，您需要直接使用 Fern 配置文件而不是通过 Fern Dashboard。
</Info>

要启用 RBAC，首先设置身份验证方法——[密码保护](/learn/docs/authentication/setup/password-protection)、[JWT](/learn/docs/authentication/setup/jwt) 或 [OAuth](/learn/docs/authentication/setup/oauth)——然后在 `docs.yml` 中定义您的角色：

```yml docs.yml
roles:
 - everyone # 每个用户都会被赋予这个角色
 - partners
 - beta-users
 - admins
```

每个用户都会自动获得 `everyone` 角色，包括未经身份验证的访问者。如果用户缺乏所需角色或未经身份验证，Fern 会将他们重定向到您的登录页面。您可以定义的角色数量没有限制，除非您使用[密码保护](/learn/docs/authentication/setup/password-protection)，它最多支持三个角色。

## 限制内容

配置 RBAC 后，在导航中使用 `viewers`，在页面中使用 `<If />` 组件来控制每个角色可以看到的内容。

### 在导航中

您可以为以下导航项目分配 `viewers`：`products`、`versions`、`tabs`、`sections`、`pages`、`api references` 和 `changelogs`。

如果您不指定查看者，内容将对任何*经过身份验证*的用户可见。要使内容公开访问，请明确将查看者设置为 `everyone`。

```yml docs.yml {6-7, 13-15}
navigation:
  - tab: Home
    layout:
      - page: Welcome # 此页面是公开的
        path: pages/welcome.mdx
        viewers:
          - everyone
  - tab: Documentation
    layout:
      - page: Overview # 此页面对所有已登录用户可见
        path: pages/overview.mdx
      - section: Beta Release # 此部分对 beta-users 和 admins 可见
        viewers:
          - beta-users
          - admins
        contents:
          ...
```

查看权限是继承的。例如，如果某个部分只能由 `admins` 查看，那么它的所有页面和嵌套部分也只能由管理员查看。

### 在 MDX 页面中

使用 `<If />` 组件根据用户角色[有条件地渲染内容](/learn/docs/writing-content/components/if)。您可以指定一个或多个角色。内容对具有**任何**指定角色的用户可见：

```mdx
<If roles={["partners", "admins"]}>
  <Callout>
    此内容对合作伙伴和管理员都可见。
  </Callout>
</If>
```

您还可以将 `roles` 与 `products` 和 `versions` 属性结合使用。

## 常见错误

### 角色 "X" 被使用但未在 docs.yml 文件的顶层声明。

[`viewers:`](#in-navigation) 条目或 [`<If roles={[...]}>`](/learn/docs/writing-content/components/if) 引用使用了未在 `docs.yml` 顶层 `roles:` 键下列出的角色。将角色添加到 [`roles`](#setup) 列表中：

```yaml title="docs.yml"
roles:
  - everyone
  - partners
  - beta-users
  - admins
```