API 文档

面向平台资源使用方：使用 X-API-Key 调用 Management 资源接口，创建与管理 Auth / DB / App 等资源。

运营侧 Admin、Console 账号/API Key/Product 管理、Internal 回调等，见仓库内全量文档 api-reference.md（不在公开站 /docs/ 展示）。

概述

• Base URL:
  • 生产环境: https://easylaunchapi.aimos.cloud
  • 本地开发: http://localhost:8080
• Content-Type: application/json
• 认证: X-API-Key: <api_key>（Console 也可使用 JWT；本文件不描述 JWT / Console 专用接口）
• 通用错误响应格式:

  {
    "error": {
      "code": "ERROR_CODE",
      "message": "human-readable message",
      "details": {}
    }
  }
  

  details 为可选字段。
• Region: 资源使用 region: cn | us
• 资源创建通用参数（auth / postgresql / redis / gitlab / app / job / image / oss / umami / payment / ratelimiter）:
  • region（必填）: cn | us
  • product_id（可选）: UUID；绑定 Product 时须 region 一致，否则 400 REGION_PRODUCT_MISMATCH
  • tier（可选）: shared | dedicated，默认 shared
  • skill-executor 任务创建参数不同（见 Skill Executor 节），不走上述 name/product_id 形态
• 资源列表通用 Query:
  • ?product_id=<uuid> — 仅返回绑定到该 Product 的资源
  • ?ungrouped=true — 仅返回 product_id 为空的资源
• 资源重绑定（大多数资源类型）:
  • PATCH /api/v1/resources/{type}/:id，Body: { "product_id": "<uuid>" | null }
  • 成功通常 204；ratelimiter PATCH 还可改限流配置，成功 200

参数非法时返回 400 INVALID_PARAMETER（例如非法 tier）。

1. 资源 — Auth

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key> 所有资源接口位于 /api/v1/resources 路径下

POST /api/v1/resources/auth

创建 Auth 资源（Logto 应用）。

Body (JSON)

{
  "name": "my-auth-app",
  "region": "cn-hangzhou",
  "tier": "shared",
  "redirect_uris": ["https://example.com/callback"]
}

Response 201

{
  "id": "550e8400-...",
  "type": "auth",
  "name": "my-auth-app",
  "region": "cn-hangzhou",
  "status": "creating",
  "redirect_uris": ["https://example.com/callback"],
  "connection": {
    "endpoint": "https://auth-xxx.easylaunch.dev",
    "app_id": "logto_app_id_xxx",
    "app_secret": "logto_app_secret_xxx"
  },
  "created_at": "2025-01-01T00:00:00Z"
}

GET /api/v1/resources/auth

列出当前用户的所有 Auth 资源。

Response 200

{
  "resources": [ { ... } ]
}

GET /api/v1/resources/auth/:id

获取指定 Auth 资源详情。

参数

Response 200 — 返回 Auth 资源对象

错误

• 404 — RESOURCE_NOT_FOUND

DELETE /api/v1/resources/auth/:id

删除 Auth 资源。

参数

Response 204 No Content

2. 资源 — PostgreSQL

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>

POST /api/v1/resources/postgresql

创建 PostgreSQL 数据库资源。

Body (JSON)

{
  "name": "my-db",
  "region": "cn",
  "tier": "shared",
  "spec": {
    "storage_gb": 50,
    "version": "16"
  }
}

Response 201

{
  "id": "550e8400-...",
  "type": "postgresql",
  "name": "my-db",
  "region": "cn-hangzhou",
  "tier": "dedicated",
  "status": "creating",
  "connection": {
    "host": "xxx.rds.aliyuncs.com",
    "port": 5432,
    "db_name": "mydb_xxx",
    "db_user": "user_xxx",
    "db_password": "generated_password"
  },
  "created_at": "2025-01-01T00:00:00Z"
}

GET /api/v1/resources/postgresql

列出当前用户的所有 PostgreSQL 资源。

Response 200

{
  "resources": [ { ... } ]
}

GET /api/v1/resources/postgresql/:id

获取指定 PostgreSQL 资源详情。

参数

Response 200 — 返回 PostgreSQL 资源对象（含连接信息）

DELETE /api/v1/resources/postgresql/:id

删除 PostgreSQL 资源。

参数

Response 204 No Content

3. 资源 — Redis

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>

POST /api/v1/resources/redis

创建 Redis 资源。

Body (JSON)

{
  "name": "my-redis",
  "region": "cn-hangzhou",
  "tier": "shared",
  "spec": {
    "memory_mb": 1024
  }
}

Response 201

{
  "id": "550e8400-...",
  "type": "redis",
  "name": "my-redis",
  "region": "cn-hangzhou",
  "tier": "shared",
  "status": "creating",
  "connection": {
    "host": "xxx.redis.aliyuncs.com",
    "port": 6379,
    "key_prefix": "user_xxx",
    "password": "generated_password"
  },
  "created_at": "2025-01-01T00:00:00Z"
}

GET /api/v1/resources/redis

列出当前用户的所有 Redis 资源。

Response 200

{
  "resources": [ { ... } ]
}

GET /api/v1/resources/redis/:id

获取指定 Redis 资源详情。

Response 200 — 返回 Redis 资源对象（含连接信息）

DELETE /api/v1/resources/redis/:id

删除 Redis 资源。

Response 204 No Content

4. 资源 — GitLab

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>

POST /api/v1/resources/gitlab

创建 GitLab 项目资源。

Body (JSON)

{
  "name": "my-project",
  "region": "cn-hangzhou",
  "tier": "shared"
}

Response 201

{
  "id": "550e8400-...",
  "type": "gitlab",
  "name": "my-project",
  "region": "cn-hangzhou",
  "status": "creating",
  "project_name": "my-project",
  "project_url": "https://gitlab.example.com/user/my-project",
  "access_token": "glpat-xxx",
  "created_at": "2025-01-01T00:00:00Z"
}

access_token 仅在创建和 GET 单个资源时返回，List 不返回。

GET /api/v1/resources/gitlab

列出当前用户的所有 GitLab 资源（不含 access_token）。

Response 200

{
  "resources": [
    {
      "id": "550e8400-...",
      "type": "gitlab",
      "name": "my-project",
      "region": "cn-hangzhou",
      "status": "active",
      "project_name": "my-project",
      "project_url": "https://gitlab.example.com/user/my-project",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

GET /api/v1/resources/gitlab/:id

获取指定 GitLab 资源详情（含 access_token）。

Response 200 — 返回 GitLab 资源对象（含 access_token）

GET /api/v1/resources/gitlab/:id/token

获取 GitLab 资源的 access token。

Response 200

{
  "access_token": "glpat-xxx"
}

错误

• 404 — RESOURCE_NOT_FOUND

POST /api/v1/resources/gitlab/:id/rotate-token

轮换 GitLab 资源的 access token。

Response 200

{
  "access_token": "glpat-new-xxx"
}

DELETE /api/v1/resources/gitlab/:id

删除 GitLab 资源。

Response 204 No Content

5. 资源 — App

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>

POST /api/v1/resources/app

创建 App 资源（K8s/Knative 应用占位）。

Body (JSON)

{
  "name": "my-app",
  "region": "cn-hangzhou",
  "tier": "shared"
}

Response 201

{
  "id": "550e8400-...",
  "app_id": "app_a1b2c3d4",
  "type": "app",
  "name": "my-app",
  "region": "cn-hangzhou",
  "tier": "shared",
  "status": "created",
  "image": "",
  "port": 3000,
  "env_vars": [],
  "configmaps": [],
  "domain": "",
  "min_replicas": 0,
  "max_replicas": 2,
  "cpu_request": "100m",
  "cpu_limit": "200m",
  "mem_request": "256Mi",
  "mem_limit": "512Mi",
  "created_at": "2025-01-01T00:00:00Z"
}

GET /api/v1/resources/app

列出当前用户的所有 App 资源。

Response 200

{
  "resources": [ { ... } ]
}

GET /api/v1/resources/app/:id

获取指定 App 资源详情。

Response 200 — 返回 App 资源对象

DELETE /api/v1/resources/app/:id

删除 App 资源。

Response 204 No Content

POST /api/v1/resources/app/:id/deploy

部署 App。

Body (JSON)

{
  "image": "registry.example.com/my-app:v1.0.0",
  "port": 3000,
  "env_vars": [
    { "key": "NODE_ENV", "value": "production" },
    { "key": "DATABASE_URL", "value": "postgres://..." }
  ],
  "configmaps": [
    {
      "name": "app-config",
      "mount_path": "/etc/config",
      "data": {
        "config.yaml": "..."
      }
    }
  ]
}

Response 200

{ "status": "deploying" }

POST /api/v1/resources/app/:id/undeploy

取消部署 App（下线应用）。

Response 200

{ "status": "undeployed" }

GET /api/v1/resources/app/:id/status

查询 App 部署状态。

Response 200

{ "status": "running" }

GET /api/v1/resources/app/:id/logs

获取 App 运行日志。

参数

Response 200

{
  "logs": ["[2025-01-01T00:00:00Z] Server started on port 3000", "..."]
}

6. 资源 — Image

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>

POST /api/v1/resources/image

创建镜像仓库资源，并在 region 对应 registry 上同步 provision repository（easylaunch-app-{name}）。

Provider 前置条件（Image provider，按 region 配置）：

两种类型均需 pipeline_id 及 OSS 构建字段（oss_endpoint、build_bucket、access_key_id、access_key_secret）。CN 使用 Harbor + CN 流水线；US 使用 Docker Hub + US 流水线。

App/Job provider 的 registry 为 registry host（不含 namespace）：CN harbor.aimos.cloud，US docker.io。

Body (JSON)

{
  "name": "my-image",
  "region": "cn-hangzhou",
  "tier": "shared"
}

Response 201

{
  "id": "550e8400-...",
  "type": "image",
  "name": "my-image",
  "region": "cn-hangzhou",
  "tier": "shared",
  "status": "active",
  "provider_id": "660e8400-...",
  "pipeline_run_id": "",
  "build_count": 0,
  "created_at": "2025-01-01T00:00:00Z"
}

首次 create 无 image_url；首次 build 成功后才有。

GET /api/v1/resources/image

列出当前用户的所有 Image 资源。

Response 200

{
  "resources": [ { ... } ]
}

每条资源含 build_count；有成功 build 时还含 latest_tag 与 image_url。

GET /api/v1/resources/image/:id

获取指定 Image 资源详情（含 build_count、latest_tag、最近成功 build 的 image_url）。

Response 200 — 返回 Image 资源对象

GET /api/v1/resources/image/:id/versions

列出镜像 build 版本（tag + 完整 image_url）。

Query: status 可选 — building | active | error

Response 200

{
  "versions": [
    {
      "tag": "20260613-153045",
      "image_url": "harbor.aimos.cloud/easylaunch/easylaunch-app-my-image:20260613-153045",
      "status": "active",
      "pipeline_run_id": "...",
      "created_at": "2026-06-13T15:30:45Z"
    }
  ]
}

DELETE /api/v1/resources/image/:id

删除 Image 资源，并同步删除 registry 上对应的 repository（easylaunch-app-{name}，Harbor 或 Docker Hub，取决于 provider registry_type）。此操作不可撤销；若仍有 App/Job 引用该 image_url，后续拉取可能失败。

Body (JSON)

{
  "confirm_name": "my-image"
}

Errors

Response 204 No Content

POST /api/v1/resources/image/:id/upload-url

获取镜像构建源代码的上传地址（预签名 PUT URL）。

Body (JSON): {}（空对象）

Response 200

{
  "upload_url": "https://bucket.oss-cn-hangzhou.aliyuncs.com/builds/...?Expires=...",
  "oss_key": "builds/<image-id>/<uuid>.zip",
  "oss_url": "https://bucket.oss-cn-hangzhou.aliyuncs.com/builds/<image-id>/<uuid>.zip"
}

客户端将源代码 ZIP 通过 PUT 上传到 upload_url，然后调用 build 接口传入 oss_key。

POST /api/v1/resources/image/:id/build

触发镜像构建。

Body (JSON)

{
  "oss_key": "builds/<image-id>/<uuid>.zip",
  "tag": "v1.0.0"
}

Response 202

{
  "status": "building",
  "tag": "20260613-153045",
  "image_url": "registry.example.com/namespace/my-image:20260613-153045",
  "pipeline_run_id": "..."
}

构建结果通过 Pipeline Callback 通知，或通过 status 接口轮询。

GET /api/v1/resources/image/:id/status

查询镜像构建状态。当资源处于 building 时，会调用云效 Flow API 刷新流水线状态并同步更新资源状态。

Response 200

{
  "status": "building",
  "pipeline_status": "RUNNING"
}

GET /api/v1/resources/image/:id/logs

获取镜像构建日志。日志从云效 Flow 实时拉取，不持久化到数据库。通常在构建失败时使用。

Response 200

{
  "logs": "Step 1/5 : FROM node:20\n..."
}

7. 资源 — Job

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>

Job 为一次性任务：创建后立即在 K8s 中执行。配额按执行次数（max_exec_count）计算。

POST /api/v1/resources/job

创建并执行 Job。

Body (JSON)

{
  "name": "my-job",
  "region": "cn",
  "tier": "shared",
  "spec": {
    "image": "nginx:latest",
    "command": ["/bin/sh"],
    "args": ["-c", "echo hello"],
    "port": 3000,
    "cpu_request": "100m",
    "cpu_limit": "200m",
    "mem_request": "256Mi",
    "mem_limit": "512Mi",
    "active_deadline_seconds": 3600
  }
}

Response 201 — 返回 Job 资源对象（status 初始为 creating）

GET /api/v1/resources/job

列出当前用户的所有 Job 资源。

Response 200

{
  "resources": [ { ... } ]
}

列表与详情查询会自动从 K8s 同步最新状态并写回数据库。

GET /api/v1/resources/job/:id

获取指定 Job 资源详情。

Response 200 — 返回 Job 资源对象（含最新同步的 status）

可能的状态值：creating、pending、running、succeeded、failed、not_found

GET /api/v1/resources/job/:id/status

查询 Job 执行状态（从 K8s 同步并更新数据库）。

Response 200

{ "status": "running" }

GET /api/v1/resources/job/:id/logs

获取 Job 日志。

Query

Response 200

{
  "logs": "...log text..."
}

DELETE /api/v1/resources/job/:id

删除 Job 资源（清理 K8s Job 并软删除记录）。

Response 204 No Content

8. 资源 — OSS

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>

POST /api/v1/resources/oss

创建 OSS 对象存储资源（含 RAM 凭证）。

Body (JSON)

{
  "name": "my-bucket",
  "region": "cn-hangzhou",
  "tier": "dedicated"
}

Response 201

{
  "id": "550e8400-...",
  "type": "oss",
  "name": "my-bucket",
  "bucket_name": "bucket-xxx",
  "region": "cn-hangzhou",
  "tier": "dedicated",
  "status": "creating",
  "acl": "private",
  "endpoint": "oss-cn-hangzhou.aliyuncs.com",
  "access_key_id": "LTAI5t...",
  "access_key_secret": "secret...",
  "created_at": "2025-01-01T00:00:00Z"
}

access_key_id 和 access_key_secret 是 bucket 粒度的 RAM 子账号凭证。

GET /api/v1/resources/oss

列出当前用户的所有 OSS 资源。

Response 200

{
  "resources": [ { ... } ]
}

列表返回完整的连接信息（含凭证）。

GET /api/v1/resources/oss/:id

获取指定 OSS 资源详情。

Response 200 — 返回 OSS 资源对象（含凭证）

DELETE /api/v1/resources/oss/:id

删除 OSS 资源。

Response 204 No Content

PATCH /api/v1/resources/oss/:id/acl

设置 OSS Bucket ACL 权限。

Body (JSON)

{
  "acl": "public-read"
}

Response 200

{
  "status": "ok",
  "acl": "public-read"
}

9. 资源 — Umami

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>
创建走配额检查 QuotaCheck("umami")。目前仅支持 tier=shared。

POST /api/v1/resources/umami

创建 Umami 分析站点。

Body (JSON)

{
  "name": "my-site-analytics",
  "region": "cn",
  "tier": "shared",
  "spec": {
    "domain": "example.com"
  }
}

Response 201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "umami",
  "name": "my-site-analytics",
  "region": "cn",
  "product_id": null,
  "tier": "shared",
  "status": "active",
  "website_id": "umami-website-uuid",
  "domain": "example.com",
  "created_at": "2026-07-14T10:00:00Z"
}

GET /api/v1/resources/umami

列出 Umami 资源。支持 ?product_id= / ?ungrouped=true。

Response 200

{ "resources": [ { "...": "..." } ] }

GET /api/v1/resources/umami/:id

Response 200 — 单条资源对象（同创建响应）。

PATCH /api/v1/resources/umami/:id

重绑定 product_id。Body: { "product_id": "<uuid>" | null } → 204

DELETE /api/v1/resources/umami/:id

Response 204 No Content

GET /api/v1/resources/umami/:id/tracking-code

获取可嵌入的 tracking script。

Response 200

{
  "tracking_code": "<script defer src=\"https://analytics.example.com/script.js\" data-website-id=\"...\"></script>"
}

POST /api/v1/resources/umami/:id/share

获取可分享的看板 URL（无需 Body）。

Response 200

{
  "share_url": "https://analytics.example.com/share/abc123"
}

10. 资源 — Payment

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>
创建走配额检查 QuotaCheck("payment")。

POST /api/v1/resources/payment

创建支付资源配置（渠道 + 环境）。

Body (JSON)

{
  "name": "checkout",
  "region": "cn",
  "tier": "shared",
  "spec": {
    "channel": "stripe",
    "environment": "sandbox"
  }
}

Response 201

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "type": "payment",
  "name": "checkout",
  "region": "cn",
  "product_id": null,
  "tier": "shared",
  "status": "active",
  "channel": "stripe",
  "environment": "sandbox",
  "paddle_client_token": "",
  "created_at": "2026-07-14T10:00:00Z"
}

GET /api/v1/resources/payment

列出支付资源。支持 ?product_id= / ?ungrouped=true。

Response 200

{ "resources": [ { "...": "..." } ] }

GET /api/v1/resources/payment/:id

获取支付资源详情。当 environment == "sandbox" 时，响应可能额外包含 sandbox_credentials（平台沙箱凭证）。

Response 200 — 资源对象（同上，可能带 sandbox_credentials）

PATCH /api/v1/resources/payment/:id

重绑定 product_id → 204

DELETE /api/v1/resources/payment/:id

Response 204 No Content

GET /api/v1/resources/payments/credentials/sandbox

获取平台沙箱支付凭证。

Query

Response 200

{
  "platform_webhook_secret": "...",
  "providers": {
    "stripe": {
      "enabled": true,
      "secret_key": "sk_test_..."
    }
  }
}

GET /api/v1/resources/payments/credentials/production

获取开发者自有的生产支付配置。

注意：ProductionConfig 结构体多数字段无 json tag，Go 默认以 PascalCase 序列化（如 EnabledProviders、AlipayAppID）。加密私钥/密钥字段带 json:"-"，不会在 GET 中返回。

Response 200 — production config 对象（无敏感明文）

PUT /api/v1/resources/payments/credentials/production

更新生产支付配置（部分字段合并更新）。

Body — ProductionConfig 字段子集（含可写的密文字段输入；服务端加密存储）

Response 200

{ "status": "ok" }

11. 资源 — Skill Executor

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>
创建任务走配额检查 QuotaCheck("skill-executor")（按执行次数）。
多数接口使用独立响应信封 { "code": 0, "message": "ok", ... }；错误为 { "code": <int>, "message": "..." }（不是全局 error.code 对象）。

POST /api/v1/resources/skill-executor/upload-url

获取上传 skill zip（或输入文件）的预签名 URL。

Body (JSON)

{
  "region": "cn-hangzhou",
  "tier": "shared",
  "filename": "my-skill.zip"
}

Response 200（无 code 信封，直接返回对象）

{
  "upload_url": "https://bucket.oss-cn-hangzhou.aliyuncs.com/skills/...?signature=...",
  "oss_url": "https://bucket.oss-cn-hangzhou.aliyuncs.com/skills/user-id/file.zip",
  "expires_in": 3600
}

POST /api/v1/resources/skill-executor

创建并调度 FC 任务。

Body (JSON)

{
  "region": "cn-hangzhou",
  "tier": "shared",
  "engine": "claude-code",
  "skill_zip_url": "https://bucket.oss-cn-hangzhou.aliyuncs.com/skills/.../skill.zip",
  "skill_unzip_code": "",
  "model_name": "claude-sonnet-4",
  "inputs": [
    { "type": "str", "name": "prompt", "content": "hello" }
  ],
  "outputs": [
    { "type": "str", "name": "summary", "content": "" }
  ],
  "notify_url": "https://example.com/hooks/skill-done"
}

DataStructure: { "type": "str"|"number"|"bool"|"file", "name": "snake_case", "content": "..." }
file 类型须为用户作用域 OSS URL（skills/{user_id}/ 或 tasks/{user_id}/）。

Response 201

{
  "code": 0,
  "message": "ok",
  "task_id": "770e8400-e29b-41d4-a716-446655440002"
}

GET /api/v1/resources/skill-executor

列出任务。

Query: status、limit（默认 20）、offset（默认 0）

Response 200

{
  "code": 0,
  "message": "ok",
  "tasks": [
    {
      "task_id": "770e8400-...",
      "status": "success",
      "model_name": "claude-sonnet-4",
      "skill_zip_url": "https://...",
      "created_at": "2026-07-14T10:00:00Z",
      "finished_at": "2026-07-14T10:05:00Z"
    }
  ]
}

GET /api/v1/resources/skill-executor/models

列出某区域可用模型。

Query: region（必填）、tier（可选）

Response 200

{
  "code": 0,
  "message": "ok",
  "models": ["claude-sonnet-4", "gpt-4o"]
}

GET /api/v1/resources/skill-executor/:task_id

查询任务状态与结果。

状态: pending | running | success | failed

Response 200（完成）

{
  "code": 0,
  "message": "ok",
  "status": "success",
  "engine": "claude-code",
  "result": [
    { "type": "str", "name": "summary", "content": "done" }
  ],
  "execution_log_url": "https://bucket.oss-.../logs/claude-code.log"
}

running 时额外可能包含 phase、progress_pct、log_tail（约末尾 32KiB）。失败时可能含 error_message。

12. 资源 — Rate Limiter (ratelimiter)

认证: Authorization: Bearer <Logto JWT> 或 X-API-Key: <api_key>
创建走配额检查 QuotaCheck("ratelimiter")。
Postgres 存配置；平台 Redis 存 QPS 桶与并发 lease。
至少启用 qps 或 concurrency 之一。启用并发时必须设置 lease_ttl（1–86400 秒）。qps / concurrency 范围均为 1–10000。

POST /api/v1/resources/ratelimiter

Body (JSON) — 仅 QPS：

{
  "name": "api-gateway",
  "region": "cn",
  "tier": "shared",
  "qps": 10
}

仅并发：

{
  "name": "async-jobs",
  "region": "cn",
  "concurrency": 5,
  "lease_ttl": 600
}

两者同时：

{
  "name": "async-jobs",
  "region": "cn",
  "qps": 10,
  "concurrency": 5,
  "lease_ttl": 600
}

Response 201

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "type": "ratelimiter",
  "name": "async-jobs",
  "region": "cn",
  "product_id": null,
  "tier": "shared",
  "status": "active",
  "qps": 10,
  "concurrency": 5,
  "lease_ttl": 600,
  "created_at": "2026-07-14T10:00:00Z"
}

未配置的维度字段不会出现在响应中。

错误

• 400 INVALID_CONFIG — 例如未提供任何维度，或 concurrency 无 lease_ttl
• 400 TIER_NOT_AVAILABLE
• 422 PROVIDER_UNAVAILABLE

GET /api/v1/resources/ratelimiter

列出限流器。支持 ?product_id= / ?ungrouped=true。

Response 200

{ "resources": [ { "...": "..." } ] }

GET /api/v1/resources/ratelimiter/:id

Response 200 — 单条资源对象。

PATCH /api/v1/resources/ratelimiter/:id

可更新 product_id 以及限流配置。省略字段不变；JSON null 可清除某一维度（须至少保留一个维度）。变更作用于下一次 acquire。

Body (JSON) 示例：

{
  "qps": 20,
  "concurrency": null,
  "product_id": null
}

Response 200 — 更新后的完整资源对象（不是 204）。

DELETE /api/v1/resources/ratelimiter/:id

软删除资源，并清理 Redis 桶与 leases。

Response 204 No Content

POST /api/v1/resources/ratelimiter/:id/acquire

阻塞式获取容量（QPS token 和/或并发 lease）。timeout 内拿不到则超时。

Body (JSON)

{ "timeout": 30 }

Response 200（仅 QPS）

{
  "acquired": true,
  "limiter_id": "880e8400-...",
  "qps": 10
}

Response 200（启用并发）

{
  "acquired": true,
  "limiter_id": "880e8400-...",
  "qps": 10,
  "concurrency": 5,
  "lease_id": "92448953-...",
  "lease_expires_at": "2026-07-14T12:10:00Z"
}

QPS 未配置时响应不含 qps。仅 QPS 时不返回 lease_id。

错误

POST /api/v1/resources/ratelimiter/:id/release

释放并发 lease。不会归还 QPS token。仅 QPS 的 limiter 调用会 400 INVALID_CONFIG。

Body (JSON)

{ "lease_id": "92448953-..." }

Response 200

{ "released": true }

幂等未命中：

{ "released": false, "reason": "lease_not_found" }

13. Webhooks（入站）

认证: 无（由各支付渠道签名 / 平台验签校验）。面向渠道回调，一般不由客户端调用。

附录：通用错误码