集合访问控制

Collection Access Control（集合访问控制）是用于限制对Collection中文档访问权限的Access Control，同时也控制用户在Admin Panel中与该集合相关的可见内容。

要为集合添加访问控制，请在Collection Config中使用access属性：

import type { CollectionConfig } from 'payload'

export const CollectionWithAccessControl: CollectionConfig = {
  // ...
  access: {
    // highlight-line
    // ...
  },
}

配置选项

访问控制（Access Control）是针对请求操作的具体控制。

要为 Collection 添加访问控制，可以在 Collection Config 中使用 access 属性：

import type { CollectionConfig } from 'payload';

export const CollectionWithAccessControl: CollectionConfig = {
  // ...
  // highlight-start
  access: {
    create: () => {...},
    read: () => {...},
    update: () => {...},
    delete: () => {...},

    // 仅限启用认证的 Collections
    admin: () => {...},
    unlock: () => {...},

    // 仅限启用版本控制的 Collections
    readVersions: () => {...},
  },
  // highlight-end
}

可用的配置选项如下：

函数允许/拒绝访问的时机
create用于 create 操作。详情。
read用于 find 和 findByID 操作。详情。
update用于 update 操作。详情。
delete用于 delete 操作。详情。

如果 Collection 支持认证，则还有以下额外选项：

函数允许/拒绝访问的时机
admin用于限制访问管理面板。详情。
unlock用于限制哪些用户可以访问 unlock 操作。详情。

如果 Collection 支持版本控制，则还有以下额外选项：

函数允许/拒绝访问的时机
readVersions用于控制谁可以读取版本，谁不能。会自动限制管理界面中的版本查看权限。详情。

Create

返回一个布尔值，用于控制是否允许 create 请求。

要为 Collection 添加创建访问控制，可以在 Collection Config 中使用 create 属性：

import type { CollectionConfig } from 'payload'

export const CollectionWithCreateAccess: CollectionConfig = {
  // ...
  access: {
    // highlight-start
    create: ({ req: { user }, data }) => {
      return Boolean(user)
    },
    // highlight-end
  },
}

create 函数接收以下参数：

选项描述
req包含当前认证用户 user 的 Request 对象。
data用于创建文档的传入数据。

读取权限控制

返回一个布尔值，用于允许/拒绝 read 请求的访问权限。

要为 Collection 添加读取权限控制，可以在 Collection 配置 中使用 read 属性：

import type { CollectionConfig } from 'payload'

export const CollectionWithReadAccess: CollectionConfig = {
  // ...
  access: {
    // highlight-start
    read: ({ req: { user } }) => {
      return Boolean(user)
    },
    // highlight-end
  },
}

提示： 可以返回一个 查询条件 来限制只能访问匹配条件的文档。这有助于限制用户只能访问特定文档。了解更多。

随着应用复杂度增加，你可能希望将函数定义在单独的文件中，然后导入到 Collection 配置：

import type { Access } from 'payload'

export const canReadPage: Access = ({ req: { user } }) => {
  // 允许已认证用户
  if (user) {
    return true
  }

  // 通过返回查询条件，访客用户可以读取公开文档
  // 注意：这假设你的 Collection 中有 `isPublic` 复选框字段
  return {
    isPublic: {
      equals: true,
    },
  }
}

read 函数接收以下参数：

选项描述
req包含当前认证用户 user 的 Request 对象。
id请求文档的 id（仅在 findByID 操作中存在）。

更新权限控制

返回一个布尔值，用于允许或拒绝 update 请求的访问权限。

要为 Collection 添加更新访问控制，请在 Collection Config 中使用 update 属性：

import type { CollectionConfig } from 'payload'

export const CollectionWithUpdateAccess: CollectionConfig = {
  // ...
  access: {
    // highlight-start
    update: ({ req: { user } }) => {
      return Boolean(user)
    },
    // highlight-end
  },
}

提示： 返回一个 Query 可以限制只能访问匹配条件的文档。这有助于限制用户对特定文档的访问权限。了解更多详情。

随着应用变得复杂，你可能希望将函数定义在单独的文件中，然后导入到 Collection Config：

import type { Access } from 'payload'

export const canUpdateUser: Access = ({ req: { user }, id }) => {
  // 允许角色为 'admin' 的用户
  if (user.roles && user.roles.some((role) => role === 'admin')) {
    return true
  }

  // 允许其他用户只能更新自己的文档
  return user.id === id
}

update 函数接收以下参数：

选项描述
req包含当前认证用户 user 的 Request 对象。
id请求更新的文档 id。
data用于更新文档的数据。

删除

与 Update 函数类似，返回一个布尔值或 query constraint 来限制哪些用户可以删除哪些文档。

要为 Collection 添加删除访问控制，可以在 Collection Config 中使用 delete 属性：

import type { CollectionConfig } from 'payload'

export const CollectionWithDeleteAccess: CollectionConfig = {
  // ...
  access: {
    // highlight-start
    delete: ({ req: { user } }) => {
      return Boolean(user)
    },
    // highlight-end
  },
}

随着应用变得复杂，你可能希望将函数定义在单独的文件中，然后导入到 Collection Config：

import type { Access } from 'payload'

export const canDeleteCustomer: Access = async ({ req, id }) => {
  if (!id) {
    // 允许 admin UI 显示删除控件，因为没有 `id` 时无法确定
    return true
  }

  // 使用 `id` 查询另一个 Collection
  const result = await req.payload.find({
    collection: 'contracts',
    limit: 0,
    depth: 0,
    where: {
      customer: { equals: id },
    },
  })

  return result.totalDocs === 0
}

delete 函数接收以下参数：

选项描述
reqRequest 对象，带有额外的 user 属性，表示当前登录的用户。
id请求删除的文档 id。

管理权限

如果 Collection 用于访问 Admin Panel，Admin 访问控制函数决定了当前登录用户是否可以访问管理界面。

要为 Collection 添加管理访问控制，可以在 Collection Config 中使用 admin 属性：

import type { CollectionConfig } from 'payload'

export const CollectionWithAdminAccess: CollectionConfig = {
  // ...
  access: {
    // highlight-start
    admin: ({ req: { user } }) => {
      return Boolean(user)
    },
    // highlight-end
  },
}

admin 函数接收以下参数：

选项描述
req包含当前认证用户 user 的 Request 请求对象。

解锁功能

决定哪些用户可以解锁其他因登录尝试失败次数过多而被阻止认证的用户。

要为 Collection 添加解锁访问控制，请在 Collection 配置 中使用 unlock 属性：

import type { CollectionConfig } from 'payload'

export const CollectionWithUnlockAccess: CollectionConfig = {
  // ...
  access: {
    // highlight-start
    unlock: ({ req: { user } }) => {
      return Boolean(user)
    },
    // highlight-end
  },
}

unlock 函数接收以下参数：

选项描述
reqRequest 对象，包含当前已认证的 user 信息。

读取版本

如果 Collection 启用了版本控制，readVersions 访问控制函数将决定当前登录用户是否可以访问文档的版本历史记录。

要为 Collection 添加读取版本访问控制，请在 Collection 配置 中使用 readVersions 属性：

import type { CollectionConfig } from 'payload'

export const CollectionWithVersionsAccess: CollectionConfig = {
  // ...
  access: {
    // highlight-start
    readVersions: ({ req: { user } }) => {
      return Boolean(user)
    },
    // highlight-end
  },
}

readVersions 函数接收以下参数：

选项描述
reqRequest 对象，包含当前已认证的 user 信息。