限额与配额
这是什么 / 何时用
平台对项目/账号施加两类上限:
Quota Limit(配额):存量上限,四字段——
databaseStorageLimit(数据库存储,bytes)、storageLimit(对象存储,bytes)、databasesPerProject(项目数据库个数)、tablesPerProject(表个数)。默认 200MB =209715200bytes ×2、5、100。0表示不限量(仅当继承的上级 ceiling 也允许时生效);省略字段表示不变。RateLimit(限频):单位时间请求次数上限,与 Quota 共享 全局 → 账号 ceiling → 项目 override 的三层 ceiling 模型。字段必须为正整数(没有"0=不限"语义)。项目级字段与默认值(period 默认 60 秒):
accountDefault=300000、projectDefault=30000、apiKeyDefault=600、projectUserDefault=60、consoleDefault=60、anonymousDefault=60;另有全局 guardprojectCreateRate=300(项目创建频控,不是项目级 override)。
前置
项目级 Quota 读写使用 Console 上下文(
X-Appwrite-Project: console)和有效的 Console Session/JWT;URL 中的projectId才是目标业务项目。对应 scope 为projects.read/projects.write(RESTGET/PATCH /projects/:projectId/quota-limits)。账号级走Account.getQuotaLimits/updateQuotaLimits/deleteQuotaLimits(REST/account/quota-limits);凭据须绑定当前用户,推荐本页的 Console Session/JWT 路径。需要账号 Key 自动化时,按下方“账号级配额”同时装载账号 Key 与所属用户 ID,不能沿用业务项目 Key。项目级
/limits还要求平台管理员、账号 owner 或项目所属团队 owner;普通业务项目 API Key 不能代替 Console 身份。限频 + 配额一次读写使用 RESTGET/PATCH /projects/:projectId/limits;账号级/account/limits(PATCH body 为{ overrides: { …10 个字段 } })。内部管理面(账号 ceiling / 项目覆盖):
GET/PUT /_internal/admin/limits/accounts/:accountId、GET/PUT /_internal/admin/limits/projects/:projectId——仅实例管理自动化使用,不是应用集成面。
示例中的 APPBASE_ENDPOINT 包含 /v1;APPBASE_SESSION_COOKIE 是登录后获得的完整 Cookie(名称和值),从本机受控环境装载。也可将 Cookie 换为 X-Appwrite-JWT 短期用户 JWT,勿同时混用业务项目 Key。
使用骨架
读当前配额:Console SDK(Node.js / Java)或 REST 读取
GET /projects/:projectId/quota-limits,返回quota/sources/accountLimit/globalLimit——sources说明每个字段值来自项目覆盖、账号 ceiling 还是全局默认。更新项目配额:Console SDK(Node.js / Java)或 REST 调用
PATCH /projects/:projectId/quota-limits——部分更新,未传字段不变;0表示不限(需上级 ceiling 允许)。账号级配额:
account.getQuotaLimits()/updateQuotaLimits(...)/deleteQuotaLimits(...)(删除覆盖回退继承值);listLimitsProjects()只在部分 SDK 暴露,具体见 SDK 差异。限频调优:
PATCH /projects/:projectId/limits,body 为扁平的 5 个限频字段 + 4 个配额字段;响应含rateLimit/quota/accountLimit/overrides。Console SDK 无该接口的 typed 封装时用client.call('patch', ...),或用 REST。
关键参数与返回
字段名陷阱:设置时用
databaseStorageLimit;项目响应里只有历史兼容字段authDatabasesStorageLimit;GET /v1/projects/:projectId不返回storageLimit——有效值一律以 quota/limits 响应为准,不要读project.storageLimit。Quota
0= 不限量;RateLimit 无此语义(必须正整数)。数量类超限在创建时报错:
database_limit_exceeded、table_limit_exceeded。
错误与边界
database_storage_limit_exceeded/storage_limit_exceeded:HTTP 413——写入/上传前先读配额或在业务侧预算。限频触发:HTTP 429——按响应重试指引退避;不要用多把 Key 叠加绕过(ceiling 在账号层收敛)。
更新配额是覆盖语义:先 GET 确认
sources,避免把继承值误写成项目覆盖。
SDK 类别差异
Server SDK(server-sdk/nodejs.md):Node.js
Projects没有项目级 quota 或/limits方法;Account支持账号级 quota 和listLimitsProjects()。Console SDK(console-sdk/nodejs.md):Node.js
Projects.getQuotaLimits/updateQuotaLimits可读写项目 quota;Account有账号级 quota 读写,但没有listLimitsProjects();/limits接口无 typed 封装时用client.call。Client SDK(client-sdk/web.md):
Account支持当前账号级 quota 和listLimitsProjects();不提供项目级 quota 或/limits管理。Java Console SDK 的
Projects也提供项目 quota 方法;Java Server、Python、Go 及 Web SDK 没有项目级 typed 方法时使用 REST。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换调用方式;项目配额与限频卡片共享选择,账号配额卡片单独选择凭据路径。
项目配额(Quota)读写
项目级 Quota 四字段读写:读返回 quota / sources / accountLimit / globalLimit,写为部分更新(未传字段不变)。Node.js Console SDK 与 Java Console SDK 提供项目 quota 方法;Server SDK、Python / Go Console SDK 与 Web SDK 没有项目级 typed 方法,使用 REST。
- Node.js(Server)
- Console(Node)
- REST(curl)
// agentbase-node-sdk@2.10.0 的 Projects 没有项目级 getQuotaLimits / updateQuotaLimits。
// 项目 quota 请使用下方 Console SDK 页签或 REST;Server SDK 的 Account 仅管理账号级 quota。import { Client, Projects } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 须包含 /v1
.setProject('console')
.setCookie(process.env.APPBASE_SESSION_COOKIE!); // Console Session,不使用项目 API Key
const projects = new Projects(client);
const quota = await projects.getQuotaLimits({ projectId: '<projectId>' });
await projects.updateQuotaLimits({ projectId: '<projectId>', tablesPerProject: 120 });# 读项目配额:返回 quota / sources / accountLimit / globalLimit
curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/quota-limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE"
# 部分更新(未传字段不变;0=不限量)
curl -sS -X PATCH "$APPBASE_ENDPOINT/projects/<projectId>/quota-limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE" \
-H 'Content-Type: application/json' \
-d '{"tablesPerProject":120}'
# 账号级:GET/PATCH /account/quota-limits(删除覆盖回退继承值用 DELETE)账号级配额(Account Quota)
账号级读写 /account/quota-limits,以请求中的用户身份确定账号,不能仅凭 SDK 类型推断权限。Web Client 可使用当前用户 Session;管理平台账号时,使用 Console 上下文及该账号的 Session/JWT。
服务端自动化仅在目标环境已为平台账号签发并确认有效的 Account API Key 时使用此路径;Key 须具有 account scope,同时提供 X-Appwrite-Project: console、X-Appwrite-Key 和 Key 所属用户的 X-Appwrite-User。普通项目 Key 的 scope 集不包含 account,不能用项目 ID 代替用户 ID,也不能只调用 setKey 而省略用户头。账号 Key 与 Session/JWT 分开使用,不在同一 Client 中混装;凭据仅从受控环境装载,不写入文档、仓库或日志。本页不假定目标部署开放账号 Key 签发;没有已确认有效的账号 Key 时,使用 Console Session/JWT。
updateQuotaLimits 部分更新四字段,deleteQuotaLimits 删除覆盖回退继承值。Client Web、Server Node、Server/Console Java 还提供 listLimitsProjects;Console Node 有 quota 读写但没有该列表方法,Server Python/Go 也提供各自语言的账号级 quota API。生成方法存在不代表普通项目 Key 可调用,上述账号级能力也不等于项目级 quota 支持。
Client SDK 的读取示例见 client-sdk/web.md 与 JavaScript 示例;本页 Console 和 REST 页签展示账号管理路径。
- Console(Node)
- Node.js(账号 Key)
- REST(curl)
// 账号级走 Console Session/JWT(非项目 API Key)
await sdk.forConsole.account.getQuotaLimits();
await sdk.forConsole.account.updateQuotaLimits({ tablesPerProject: 120 }); // 四 quota 字段部分更新
await sdk.forConsole.account.deleteQuotaLimits(); // 删除覆盖,回退继承值
// Console Node SDK 不提供 listLimitsProjects()import { Account, Client } from 'agentbase-node-sdk';
// 新建独立 Client;账号 Key 须有 account scope,用户 ID 须为该 Key 的所属用户。
const accountClient = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 包含 /v1
.setProject('console')
.setKey(process.env.APPBASE_ACCOUNT_API_KEY!)
.addHeader('X-Appwrite-User', process.env.APPBASE_ACCOUNT_USER_ID!);
const account = new Account(accountClient);
const quota = await account.getQuotaLimits();curl -sS "$APPBASE_ENDPOINT/account/quota-limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE"
# 部分更新(未传字段不变):PATCH /account/quota-limits
curl -sS -X PATCH "$APPBASE_ENDPOINT/account/quota-limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE" \
-H 'Content-Type: application/json' \
-d '{"tablesPerProject":120}'
# DELETE /account/quota-limits:删除覆盖,回退继承值限频调优(综合 /limits:限频 + 配额)
/limits 一次读写 5 个限频字段 + 4 个配额字段;限频字段必须为正整数(没有 0=不限 语义),响应含 rateLimit / quota / accountLimit / overrides。Web Client 只提供账号级 quota,不提供项目级 quota 或 rate-limit 管理;项目级 /limits 的 typed 方法仅在 console-java Projects(getLimits(projectId) / updateLimits(projectId, 5 个限频字段 + 4 个配额字段) / deleteLimits(projectId, keys));server-java / server-python / server-go 的 Projects 均无,统一走 REST(Console 无 typed 封装时用 client.call,见卡内);账号级 /account/limits 在已提供该功能的 Server/Console SDK Account 中有 typed 方法。
- Node.js(Server)
- Console(Node)
- REST(curl)
// agentbase-node-sdk@2.10.0 的 Projects 没有 getLimits / updateLimits。
// 项目限频使用下方 Console 页签或 REST;Account 的同名方法是账号级接口。// Console SDK 无 typed getLimits/updateLimits:用 client.call 直调 REST
client.setProject('console');
const limitsUri = new URL(`${client.config.endpoint}/projects/${projectId}/limits`);
const limits = await client.call('get', limitsUri, {}, {});
await client.call('patch', limitsUri, { 'content-type': 'application/json' }, {
projectDefault: 30000, apiKeyDefault: 600, projectUserDefault: 60,
consoleDefault: 60, anonymousDefault: 60,
databaseStorageLimit: 209715200, storageLimit: 209715200,
databasesPerProject: 5, tablesPerProject: 100
});# 综合读写:PATCH body 为扁平的 5 个限频字段 + 4 个配额字段
curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE"
curl -sS -X PATCH "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE" \
-H 'Content-Type: application/json' \
-d '{"projectDefault":30000,"apiKeyDefault":1200,"projectUserDefault":60,"consoleDefault":60,"anonymousDefault":60,"databaseStorageLimit":209715200,"storageLimit":209715200,"databasesPerProject":5,"tablesPerProject":100}'
# 账号 ceiling:PATCH /account/limits,body 为 {"overrides":{…10 个字段}};不是项目级 override示例指引
JavaScript(Web 读写账号配额、Console Node 读写项目配额):examples/javascript.md