限额与配额
这是什么 / 何时用
平台对项目/账号施加两类上限:
- 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 读写:
projects.read/projects.write(RESTGET/PATCH /projects/:projectId/quota-limits);账号级走Account.getQuotaLimits/updateQuotaLimits/deleteQuotaLimits(REST/account/quota-limits)。 - 项目级
/limits(限频 + 配额一次读写):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——仅实例管理自动化使用,不是应用集成面。
使用骨架
- 读当前配额:
projects.getQuotaLimits({ projectId })(Server / Console SDK 均可),返回quota/sources/accountLimit/globalLimit——sources说明每个字段值来自项目覆盖、账号 ceiling 还是全局默认。 - 更新项目配额:
projects.updateQuotaLimits({ projectId, databaseStorageLimit?, storageLimit?, databasesPerProject?, tablesPerProject? })——部分更新,未传字段不变;0表示不限(需上级 ceiling 允许)。 - 账号级配额:
account.getQuotaLimits()/updateQuotaLimits(...)/deleteQuotaLimits(...)(删除覆盖回退继承值);account.listLimitsProjects()列出有项目级覆盖的项目。 - 限频调优:
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):
projects.getQuotaLimits/updateQuotaLimits;账号级account.getQuotaLimits/getLimits/listLimitsProjects。 - Console SDK(console-sdk/nodejs.md):同名项目 quota 方法;
/limits接口无 typed 封装时用client.call。 - 客户端 SDK(client-sdk/web.md):不暴露配额/限频管理。
- Java Console SDK 无 typed quota/ratelimit 方法:走 JS Console SDK 或 REST。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
项目配额(Quota)读写
项目级 Quota 四字段读写:读返回 quota / sources / accountLimit / globalLimit,写为部分更新(未传字段不变)。Web SDK 不暴露配额/限频管理,无 Web 页签;项目级 quota 的 typed 方法仅在 console-java Projects(getQuotaLimits(projectId) / updateQuotaLimits(projectId, 四个 quota 字段));server-java / server-python / server-go 的 Projects 均无(源码核验),统一走 REST。
- Node.js(Server)
- Console(Node)
- REST(curl)
import { Client, Projects } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 须包含 /v1
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!); // projects.read / projects.write 最小 scope
const projects = new Projects(client);
const quota = await projects.getQuotaLimits({ projectId: '<projectId>' });
// 返回 quota / sources / accountLimit / globalLimit;sources 说明每字段来自项目覆盖、账号 ceiling 还是全局默认
await projects.updateQuotaLimits({ projectId: '<projectId>', tablesPerProject: 120 });
// 部分更新:未传字段不变;0=不限量(需继承的上级 ceiling 允许)
// 账号级:account.getQuotaLimits / updateQuotaLimits / deleteQuotaLimits / listLimitsProjects// Console SDK 同名 projects.getQuotaLimits / updateQuotaLimits;管理接口场景先把 client.setProject() 指向 Console project
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: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"
# 部分更新(未传字段不变;0=不限量)
curl -sS -X PATCH "$APPBASE_ENDPOINT/projects/<projectId>/quota-limits" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"tablesPerProject":120}'
# 账号级:GET/PATCH /account/quota-limits(删除覆盖回退继承值用 DELETE)账号级配额(Account Quota)
账号级读写 /account/quota-limits,走账号凭据(Console Session/JWT,非项目 API Key):updateQuotaLimits 部分更新四字段,deleteQuotaLimits 删除覆盖回退继承值,listLimitsProjects 列出有项目级覆盖的项目。Web SDK 不暴露配额管理;server-java / console-java 的 Account、server-python account、server-go account 均有账号级 typed 方法(getQuotaLimits / updateQuotaLimits / deleteQuotaLimits 与 listLimitsProjects,源码核验)。
- Console(Node)
- 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(); // 删除覆盖,回退继承值
// listLimitsProjects() 列出设置了项目级覆盖的项目curl -sS "$APPBASE_ENDPOINT/account/quota-limits" \
-b "$APPBASE_CONSOLE_COOKIE"
# 部分更新(未传字段不变):PATCH /account/quota-limits
curl -sS -X PATCH "$APPBASE_ENDPOINT/account/quota-limits" \
-b "$APPBASE_CONSOLE_COOKIE" \
-H 'Content-Type: application/json' \
-d '{"tablesPerProject":120}'
# DELETE /account/quota-limits:删除覆盖,回退继承值限频调优(综合 /limits:限频 + 配额)
/limits 一次读写 5 个限频字段 + 4 个配额字段;限频字段必须为正整数(没有 0=不限 语义),响应含 rateLimit / quota / accountLimit / overrides。Web SDK 不暴露配额/限频管理;项目级 /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 在上述三家 Account 均有 getLimits / updateLimits(overrides) / deleteLimits(keys)。
- Node.js(Server)
- Console(Node)
- REST(curl)
// Node Server SDK 扩展封装:getLimits / updateLimits 走综合 /limits 接口
const limits = await projects.getLimits({ projectId: '<projectId>' });
await projects.updateLimits({
projectId: '<projectId>',
projectDefault: 30000, apiKeyDefault: 1200, projectUserDefault: 60,
consoleDefault: 60, anonymousDefault: 60,
databaseStorageLimit: 209715200, storageLimit: 209715200,
databasesPerProject: 5, tablesPerProject: 100
});// 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: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"
curl -sS -X PATCH "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-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(Node 读写项目配额):examples/javascript.md
事实源
skills/ob-agentbase/references/console-sdk.md(quota 四字段与 ceiling 模型节)skills/ob-agentbase/references/server-sdks/nodejs.md(quota/ratelimit 节)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
packages/sdks/server-nodejs/src/services/projects.ts的getQuotaLimits/updateQuotaLimits;account.ts的 limits 方法面)