内存存储

*此内容使用人工智能(Beta)翻译,可能包含错误。若要查看英文页面,请点按 此处。

MemoryStoreService 是一个高吞吐量和低延迟的数据服务,提供快速的内存数据存储,所有服务器在实时会话中均可访问。内存存储 适合频繁和短暂的数据,这些数据变化迅速且不需要持久化,因为它们访问更快,并在达到最大生命周期时消失。对于需要在会话之间持久化的数据,请使用 数据存储。

数据结构

内存存储有三种原始数据结构,供服务器共享以快速处理,而不是直接访问原始数据:排序映射、队列 和 哈希映射。每种数据结构适合某些用例:

  • 基于技能的匹配 - 在服务器之间的共享 队列 中保存用户信息,例如技能水平,并使用大厅服务器定期进行匹配。
  • 跨服务器交易和拍卖 - 启用不同服务器之间的通用交易,用户可以对实时变化价格的物品进行竞标,使用 排序映射 的键值对。
  • 全球排行榜 - 在共享的 排序映射 中存储和更新用户排名。
  • 共享库存 - 在共享的 哈希映射 中保存库存物品和统计数据,用户可以同时使用库存物品。
  • 持久数据的缓存 - 将您的持久数据同步并复制到可以作为缓存的内存存储 哈希映射 中,从而提高游戏性能。

一般来说,如果您需要根据特定键访问数据,请使用哈希映射。如果您需要数据有序,请使用排序映射。如果您需要以特定顺序处理数据,请使用队列。

限制和配额

为了维护可扩展性和系统性能,内存存储对内存大小、API 请求和数据结构大小有数据使用配额。

内存存储有基于过期时间的驱逐策略,也称为生存时间(TTL)。项目在过期后被驱逐,内存配额被释放以供新条目使用。当您达到内存限制时,增加内存使用的请求将失败,直到您释放内存或增加配额。有关选项,请参见 从内存配额耗尽中恢复。

内存大小配额

内存配额限制游戏可以消耗的总内存量。它不是固定值;而是根据游戏中的用户数量随时间变化,公式为 64 KB + 1.2 KB * [用户数量]。配额适用于游戏级别,而不是服务器级别。

当用户加入游戏时,额外的内存配额会立即可用。当用户离开游戏时,配额不会立即减少。配额在八天的追溯期后重新评估为较低值。

在您的游戏达到内存大小配额后,任何增加内存大小的 API 请求都会失败。减少或不改变内存大小的请求仍然成功。

通过 可观察性 仪表板,您可以实时查看游戏的内存大小配额,使用 内存使用情况 图表。

API 请求限制

请求单位 配额适用于所有 MemoryStoreService API 调用。此配额为每分钟 1000 + 120 * [并发用户数量] 请求单位。

大多数 API 调用只消耗一个请求单位,少数例外:

请求配额也适用于游戏级别,而不是服务器级别。这提供了灵活性,可以在服务器之间分配请求,只要总请求速率不超过配额。如果您超过配额,当服务限制您的请求时,您将收到错误响应。

通过可观察性功能,您可以实时查看游戏的请求单位配额。

数据结构大小限制

对于单个排序映射或队列,适用以下大小和项目计数限制:

  • 最大项目数量:1,000,000
  • 最大总大小(包括排序映射的键):100 MB

每分区限制

除了游戏级别的 请求单位配额 外,内存存储还对每个分区施加请求限制,以保护所有游戏的服务稳定性。这些限制不是分配给您游戏的配额,也不是您游戏可以实现的吞吐量的硬上限。以下值是估算值。它们在 Roblox 后端配置,可能会更改,因此请不要将其视为固定数字。

每个请求都计入持有项目的 分区 的限制,无论数据结构是什么。您目前可以预计在单个分区的请求速率大约为 30,000 请求单位每分钟 时开始限流,因此请尽量保持在该速率以下。数据结构消耗该限制的多少取决于其项目的分布:

  • 排序映射和队列 各自位于单个分区,因此对这些数据结构的每个请求都计入同一分区限制。
  • 哈希映射 将其项目分散到多个分区,因此跨多个项目键的流量很少接近任何一个分区的限制。

哈希映射对每个项目键还有额外的限制,大约为 5,000 写请求单位每分钟 和 15,000 读请求单位每分钟。此每键限制适用于每个分区限制之上,因此频繁访问的键可能会触及其中一个。每键限制仅适用于单键操作:读取限制适用于 MemoryStoreHashMap:GetAsync(),写入限制适用于 MemoryStoreHashMap:SetAsync() 和 MemoryStoreHashMap:RemoveAsync(),而 MemoryStoreHashMap:UpdateAsync() 同时计入读取和写入限制。MemoryStoreHashMap:ListItemsAsync() 扫描分区而不是单个键,因此仅适用每分区限制。

如果您不需要排序或先进先出功能,哈希映射通常是最佳选择,因为它可以将负载分散到多个分区。

当请求超过分区或每键限制时,服务会限制它们并返回 PartitionRequestsOverLimit 状态代码,您可以通过 可观察性 仪表板进行监控。

如果您预计某个数据结构或项目键会接收高且持续的请求速率,请 分片 以便负载分散到更多分区或键。均匀分配读取和写入到多个项目键,以保持在每键限制内。您还可以通过在服务器上缓存值并在一段时间后重新检查它们、尽可能批量请求以及在收到限流响应时应用 指数退避 来减少请求速率。

从内存配额耗尽中恢复

如果您的游戏收到 TotalMemoryOverLimit 错误,请检查 可观察性仪表板 中的 内存使用情况 图表。要恢复增加内存使用的写入,请删除不需要的项目,等待项目过期,或使用以下选项之一。

使用开放云刷新内存存储

如果您不再需要存储的数据,请使用开放云 刷新内存存储 端点异步清除选定范围内的所有内存存储数据结构。

要刷新内存存储:

  1. 创建 API 密钥,并授予刷新内存存储和获取目标宇宙的刷新操作状态的权限。
  2. 向 https://apis.roblox.com/cloud/v2/universes/{universe_id}/memory-store:flush 发送 POST 请求,并在 x-api-key 头中包含 API 密钥。将 {universe_id} 替换为您游戏的宇宙 ID。将 scope 查询参数设置为 LIVE 以获取生产数据,或设置为 TEST 以获取 Studio 数据。如果省略 scope,则端点使用 LIVE。
  3. 使用 获取内存存储刷新操作 轮询刷新请求返回的操作,直到 done 为 true,并检查是否有 error。轮询时使用相同的范围。返回的 path 已包含 cloud/v2,因此在 https://apis.roblox.com/{path} 轮询时无需添加其他前缀。

Studio 和生产内存存储是 隔离的。刷新一个范围不会清除另一个范围。在清除不需要的数据后,请遵循 最佳实践,例如缩短过期时间和显式删除,以防止内存使用再次达到配额。

使用扩展服务增加容量

如果您的游戏需要保留数据并使用超过默认配额允许的更多存储,请为内存存储启用 扩展服务。扩展服务允许您为超出默认配额的内存存储和请求付费。

要开始,请满足 资格要求,添加帐户详细信息和付款方式,然后在 创作者仪表板 中选择您的游戏。在 扩展服务 下,启用内存存储并为所需资源设置每月预算。有关详细信息,请参见 启用服务 和 服务定价。

如果使用超过您的预算,扩展服务会限制服务。监控使用情况和计费,并继续 删除不需要的数据。

最佳实践

为了保持您的内存使用模式最佳并避免达到 限制,请遵循以下最佳实践:

  • 删除已处理的项目。 使用 MemoryStoreQueue:RemoveAsync() 方法定期清理读取的项目(对于队列)和使用 MemoryStoreSortedMap:RemoveAsync()(对于排序映射)可以释放内存并保持数据结构的最新状态。

  • 在添加数据时将过期时间设置为尽可能短的时间。 尽管 MemoryStoreQueue:AddAsync() 和 MemoryStoreSortedMap:SetAsync() 的默认过期时间为 45 天,但设置尽可能短的时间可以自动清理旧数据,以防止它们填满您的内存使用配额。

    • 不要存储大量数据并设置长过期时间,因为这可能会导致超过内存配额,并可能导致问题,甚至破坏整个游戏。
    • 始终显式删除不需要的项目或设置短的项目过期时间。
    • 通常,您应该使用显式删除来释放内存,并将项目过期作为安全机制,以防止未使用的项目长时间占用内存。
  • 仅在内存中保留必要的值。

    例如,对于拍卖行游戏,您只需维护最高出价。您可以在一个键上使用 MemoryStoreSortedMap:UpdateAsync() 来保持最高出价,而不是在数据结构中保留所有出价。

  • 使用 指数退避 来帮助保持在 API 请求限制以下。

    例如,如果您收到 DataUpdateConflict,您可以在两秒后重试,然后是四秒、八秒等,而不是不断向 MemoryStoreService 发送请求以获取正确的响应。

  • 通过 分片 将大型数据结构拆分为多个较小的数据结构。

    通常在较小的结构中管理数据更容易,而不是将所有内容存储在一个大型数据结构中。这种方法还可以帮助避免使用和速率限制。例如,如果您有一个使用前缀作为键的排序映射,请考虑将每个前缀分离到自己的排序映射中。对于特别受欢迎的游戏,您甚至可以根据用户 ID 的最后几位数字将用户分成多个映射。

  • 在哈希映射中对频繁访问的键进行 分片,使用多个键的副本来分散负载。

  • 压缩存储的值。

    例如,考虑使用 LZW 算法来减少存储值的大小。

  • 注册扩展服务。

    对于超出默认配额的存储或请求使用,请 为内存存储启用扩展服务。

可观察性

可观察性仪表板 提供了监控和故障排除内存存储使用情况的见解和分析。通过实时更新的图表,您可以跟踪游戏的内存使用模式,查看当前分配的配额,监控 API 状态,并识别潜在的性能优化问题。

下表列出了可在可观察性仪表板的 按状态的请求计数 和 按 API x 状态的请求 图表中找到的所有 API 响应状态代码及其描述。有关如何解决这些错误的更多信息,请参见 故障排除。有关错误相关的特定配额或限制,请参见 限制和配额。

状态代码描述
成功成功。
DataStructureMemoryOverLimit超过数据结构级别内存大小限制(100 MB)。
DataUpdateConflict由于并发更新而发生冲突。
AccessDenied无权访问游戏数据。此请求不消耗请求单位或使用配额。
InternalError内部错误。
InvalidRequest请求没有所需的信息或信息格式错误。
DataStructureItemsOverLimit超过数据结构级别项目计数限制(1M)。
NoItemFound在 MemoryStoreQueue:ReadAsync() 或 MemoryStoreSortedMap:UpdateAsync() 中未找到项目。ReadAsync() 每 2 秒轮询一次,并在找到队列中的项目之前返回此状态代码。
DataStructureRequestsOverLimit超过数据结构级别请求单位限制(每分钟 100,000 请求单位)。
PartitionRequestsOverLimit超过 每分区或每键请求单位限制。
TotalRequestsOverLimit超过宇宙级别请求单位限制。
TotalMemoryOverLimit超过宇宙级别内存配额。
ItemValueSizeTooLarge值大小超过限制(32 KB)。

下表列出了客户端状态代码,这些状态代码当前在可观察性仪表板上不可用。

状态代码描述
InternalError内部错误。
UnpublishedPlace您必须发布此地点才能使用 MemoryStoreService。
InvalidClientAccessMemoryStoreService 必须从服务器调用。
InvalidExpirationTime字段 'expiration' 时间必须在 0 到 3,888,000 之间。
InvalidRequest无法将值转换为 json。
InvalidRequest无法将 sortKey 转换为有效的数字或字符串。
TransformCallbackFailed调用转换回调函数失败。
RequestThrottled最近的 MemoryStores 请求触及一个或多个限制。
UpdateConflict超过最大重试次数。

故障排除

下表列出了每个响应状态代码的推荐解决方案:

错误故障排除选项
DataStructureRequestsOverLimit / PartitionRequestsOverLimit
  • 通过将信息保存到另一个变量并在一定时间间隔(例如 30 秒)后重新检查来添加本地缓存。
  • 使用 按状态的请求计数 图表验证您收到的 成功 响应是否多于 未找到项目。限制您以失败请求触及 MemoryStoreService 的次数。
  • 在请求之间实施短暂延迟。
  • 遵循 最佳实践,包括:
    • 如果您收到大量 DataStructureRequestsOverLimit/PartitionRequestsOverLimit 响应,请对数据结构进行分片。
    • 如果您在哈希映射调用中收到大量 PartitionRequestsOverLimit 响应,请对哈希映射键进行分片。
    • 如果您看到 PartitionRequestsOverLimit 响应,请减少或批量调用特定数据结构或哈希映射键。
    • 实施指数退避以找到合理的请求发送速率。
TotalRequestsOverLimit
DataStructureItemsOverLimit
DataStructureMemoryOverLimit
TotalMemoryOverLimit
DataUpdateConflict
  • 在请求之间实施短暂延迟,以避免多个请求同时更新同一键。
  • 对于排序映射,使用 MemoryStoreSortedMap:UpdateAsync() 方法上的回调函数,在一定次数的尝试后中止请求,如以下代码示例所示:
  • 请求中止示例
    local MemoryStoreService = game:GetService("MemoryStoreService")
    local map = MemoryStoreService:GetSortedMap("AuctionItems")
    function placeBid(itemKey, bidAmount)
    map:UpdateAsync(itemKey, function(item)
    item = item or { highestBid = 0 }
    if item.highestBid < bidAmount then
    item.highestBid = bidAmount
    return item
    end
    print("item is "..item.highestBid)
    return nil
    end, 1000)
    end
    placeBid("MyItem", 50)
    placeBid("MyItem", 40)
    print("done")
  • 调查您是否有效地调用 MemoryStoreService 以避免冲突。理想情况下,您不应该过多发送请求。
  • 在读取后定期使用 MemoryStoreQueue:RemoveAsync() 方法(对于队列)和 MemoryStoreSortedMap:RemoveAsync()(对于排序映射)删除项目。
内部错误
无效请求
  • 确保在请求中包含正确和有效的参数。无效参数的示例包括:
    • 空字符串
    • 超过长度限制的字符串
项目值大小过大
  • 将项目值分片或拆分为多个键。
    • 要组织分组键,请通过向键添加 prefix 进行字母排序。
  • 对存储的值进行编码或压缩。

在 Studio 中测试和调试

MemoryStoreService 中的数据在 Studio 和生产之间是隔离的,因此在 Studio 中更改数据不会影响生产行为。这意味着您从 Studio 的 API 调用不会访问生产数据,允许您在投入生产之前安全地测试内存存储和新功能。

Studio 测试具有与生产相同的 限制和配额。对于基于用户数量计算的配额,结果配额可能非常小,因为您是 Studio 测试的唯一用户。在 Studio 测试时,您可能还会注意到与生产使用相比,延迟略高且错误率上升,因为执行了一些额外检查以验证访问和权限。

有关如何在实时游戏或在 Studio 中测试时调试内存存储的信息,请使用 开发者控制台。

©2026 Roblox Corporation、Roblox、Roblox 标志及 Powering Imagination 是我们在美国及其他国家或地区的注册与未注册商标。