--- canonical: https://koalavps.com/zh/api/ language: zh generated: 2026-10-21T13:34:54.966Z --- [首页](https://koalavps.com/zh/) / [探索](https://koalavps.com/zh/resources/) / 可以用代码描述的基础设施 可以用代码描述的基础设施 # 更从容的控制平面。 为服务器生命周期任务、账户权限和计费规划集成。KoalaVPS API 已在集成路线图中；生产环境的 API 访问和 SDK 下载尚不可用。 [找到你的 VPS](https://koalavps.com/zh/vps/) ## 本文档内容 [清晰的资源模型](https://koalavps.com/zh/api/#section-1)[职责有限的凭据](https://koalavps.com/zh/api/#section-2)[重试必须安全](https://koalavps.com/zh/api/#section-3)[集成前检查兼容性](https://koalavps.com/zh/api/#section-4)[API 路线图](https://koalavps.com/zh/api/#section-5)[身份验证和账户路由](https://koalavps.com/zh/api/#section-6)[目录和账单路由](https://koalavps.com/zh/api/#section-7)[服务器与访问路由](https://koalavps.com/zh/api/#section-8)[事件与公开信息](https://koalavps.com/zh/api/#section-9)[授权和流量限制](https://koalavps.com/zh/api/#section-10)[SDK 和协议版本](https://koalavps.com/zh/api/#section-11)[API 资源，按职责分组](https://koalavps.com/zh/api/#section-12)[服务器请求应保持精简](https://koalavps.com/zh/api/#section-13)[权限范围和密钥限制是约定的一部分](https://koalavps.com/zh/api/#section-14)[同时发布速率限制和重试行为](https://koalavps.com/zh/api/#section-15)[Webhook 是可能多次到达的消息](https://koalavps.com/zh/api/#section-16)[审计而不将日志变成秘密存储](https://koalavps.com/zh/api/#section-17)[仅在产物存在时才发布](https://koalavps.com/zh/api/#section-18)[问题与解答](https://koalavps.com/zh/api/#page-faq)[知识库](https://koalavps.com/zh/resources/) ## 清晰的资源模型 集成应使用明确的服务器标识符、区域、镜像、方案和操作。创建和重装请求应返回一个可检查至完成的操作。HTTP 请求成功并不等同于机器已就绪。 ## 职责有限的凭据 API 令牌应可独立撤销，并限制在所需的最小资源和操作范围内。将它们存储在密钥管理器或受保护的环境中。绝不要仅仅为了避免编写小型后端而将令牌发送到浏览器。 ## 重试必须安全 操作被接受后可能发生网络超时。对创建和支付敏感请求使用幂等键，检查操作状态并遵守速率限制。重试应消除不确定性，而不是创建额外计费服务器。 ## 集成前检查兼容性 在构建集成之前，请检查已发布的 API 版本、身份验证模型、错误格式、分页、速率限制和令牌范围。仅使用来自已验证发布链接的已发布 KoalaVPS SDK 包。 ## API 路线图 API 路线图涵盖目录发现、身份验证、账户状态、加密计费、服务器生命周期、公共 SSH 密钥和 webhook。以下路由描述接口契约；生产访问尚不可用。 ## 身份验证和账户路由 API 合约将登录会话与 API 密钥分开。请对照为你的集成发布的版本，检查响应模式、错误、令牌有效期和受支持的恢复操作。 - POST /v1/auth/register - POST /v1/auth/login - POST /v1/auth/login/totp - POST /v1/auth/token/refresh - POST /v1/auth/recover - GET /v1/auth/sessions - DELETE /v1/auth/sessions/{token_id} - POST /v1/auth/totp/setup - POST /v1/auth/totp/enable - POST /v1/auth/totp/disable - POST /v1/auth/password - POST /v1/auth/api-keys - GET /v1/auth/api-keys - DELETE /v1/auth/api-keys/{key_id} - GET /v1/account - PATCH /v1/account - GET /v1/account/usage - GET /v1/account/audit-log ## 目录和账单路由 目录浏览不应需要付款。创建支付需要受限的计费权限、清晰的发票状态和幂等处理。确认必须在服务激活前完成。 - GET /v1/catalog - GET /v1/catalog/vps - GET /v1/catalog/dedicated - GET /v1/catalog/regions - GET /v1/catalog/images - GET /v1/catalog/{code} - GET /v1/billing/coins ## 服务器与访问路由 生命周期需要针对取消和重装操作进行明确确认。私有 SSH 密钥应保存在客户端；服务端只需要其公钥对应部分。 - POST /v1/servers - GET /v1/servers - GET /v1/servers/{order_number} - PATCH /v1/servers/{order_number} - DELETE /v1/servers/{order_number} - POST /v1/ssh-keys - GET /v1/ssh-keys - GET /v1/ssh-keys/{id} - DELETE /v1/ssh-keys/{id} ## 事件与公开信息 Webhook 需要可验证的签名、有界重试和重放防护。公开信任端点应返回真实的带日期证据，而不是合成保证。 - POST /v1/webhooks - GET /v1/webhooks - DELETE /v1/webhooks/{id} - POST /v1/webhooks/{id}/test - GET /v1/transparency/canary - GET /v1/transparency/peering - GET /v1/transparency/status - GET /v1/agents/directory - POST /v1/agents/directory ## 授权和流量限制 候选范围模型为读取、服务器、计费和完全权限，每个账户最多十个活动密钥。API 合同提议 API 密钥每分钟 120 次、每小时 3,000 次的请求预算，公共流量为每分钟 30 次。请查阅已发布的 API 文档中的 HTTP 429、Retry-After 和执行窗口；这些路线图预算不构成生产容量承诺。 - POST /v1/oauth/register - POST /v1/oauth/token - POST /v1/oauth/revoke - GET /v1/oauth/introspect ## SDK 和协议版本 集成路线图包括 REST、托管的 MCP 端点、带版本号的 stdio 包、SDKs 和 CLI。安装客户端前，请检查发布可用性、受支持的运行时、校验和以及 API 兼容性。生产下载尚不可用。 ## API 资源，按职责分组 预期的 API 将账户访问、目录读取、账单、服务器生命周期、SSH 密钥和回调分开。只读调用不应创建订单，账单凭据不应自动授权账户安全变更。这描述的是集成契约。本网站不提供生产环境开通端点和已发布的 SDK。 - 账户：会话、使用情况与安全审计事件 - 目录：套餐、区域和可用镜像 - 服务器：创建、查看、变更与取消 - SSH 密钥：注册公开材料并撤销过时密钥 - Webhook：注册、检查、测试和移除签名回调 ## 服务器请求应保持精简 选择标准套餐标识符、区域、操作系统镜像和主机名。预期主机名限制为 64 个字符。在线服务可以私下生成管理员密钥，或接受已登记的 SSH 公钥。标准套餐请求不意味着可任意添加磁盘、GPU、网卡和 IP。拒绝不支持的字段，而不是为猜测的升级静默收费。 ``` { "plan": "KV-D3", "region": "hel", "image": "ubuntu-24", "hostname": "private-node-01" } // Example request schema; validate against a released API before integration. ``` ## 权限范围和密钥限制是约定的一部分 拟议的权限组为读取、服务器、账单和完整账户管理。密钥应在创建时显示一次，私下存储，并可独立于用户密码撤销。拟定的账户上限为十个活跃密钥。在发布实现前，请验证每项操作都会拒绝缺少所需范围的密钥。 ## 同时发布速率限制和重试行为 建议的限制为：API 密钥每分钟 120 次请求、每小时 3,000 次请求；未认证的公开目录请求每分钟 30 次请求。这些是计划中的策略值，并非实测的 API 容量。实际实现需要一致的 429 响应、Retry-After 指引以及有上限的客户端退避。创建和支付请求还需要稳定的幂等键。 ## Webhook 是可能多次到达的消息 回调接收方应基于原始请求体验证签名，拒绝超出允许时间窗口的时间戳，并记录已处理的事件标识符。在确认前先持久化事件，然后以幂等方式应用变更。保持投递尝试和手动重放路径可见。回调是对某次操作的观察，而非执行载荷中无关指令的许可。 ## 审计而不将日志变成秘密存储 在账户安全需要时，记录操作者标识符、操作类型、受影响的资源、结果和时间。默认避免记录密码、持有者令牌、私钥或完整的支付和应用请求正文。明确保留期限、访问权限和客户可见历史。安全审计追踪与检查客户应用内容的权利是两回事。 ## 仅在产物存在时才发布 公开的 API 发布应包含带版本的 OpenAPI 文档、认证说明、错误示例和弃用流程。未来的 CLI、Python 包、TypeScript 客户端或 MCP 服务器需要实际的发布版本、校验和以及持续维护的文档。KoalaVPS 开通包或生产管理端点不会通过本站发布。 ## 多一点清晰。 我今天可以调用生产环境的 API 吗？ 生产环境 API 访问尚不可用。本页描述集成路线图以及在使用已发布端点前需检查的要求。 只读 API 密钥能订购服务器吗？ 拟议的权限边界禁止此操作。服务器创建请求需要相应的服务器权限和有效的计费决定。 公布的 API 限额目前是否执行？ 它们描述的是计划中的约定。此处未连接生产开通 API，因此这些策略限制不能作为实测服务容量的证据。 服务器创建响应是否意味着服务器已就绪？ 否。实时请求应标识一个操作，其开通状态可在完成后检查。 继续探索 ## 继续阅读。 [产品 ### 为你的代理提供可靠栖息地。 在您掌控的基础设施上运行调度器、浏览器工作进程、队列和自动化流程。让每个代理都处于明确的权限边界内。…](https://koalavps.com/zh/agentic-vps/)[指南 ### 带有明确停止按钮的自动化。 良好的自动化系统具有明确的任务、可见的状态和对不确定性的可预测响应。…](https://koalavps.com/zh/automation-safety/)[产品 ### 小体积。大自由。 一台属于您自己的虚拟服务器：您的代码、您的服务、您的数据。选择服务器配置，挑选操作系统，按您的方式构建。…](https://koalavps.com/zh/vps/) 配置您的基础设施 ## 掌控一切。 按你的条件部署。 无需身份文件。完整管理员权限。原生加密货币计费。 [选择配置](https://koalavps.com/zh/vps/)