Skip to content
导航

查看密钥所属项目中沙箱、存储卷和快照的用量

由控制平面响应的节点 GET /v1/usage (sandboxd/openapi/openapi.json)。如果 from、to、group_by、metadata.<key>、kind、volume_id 和 snapshot_id 都没有给出，返回节点的沙箱列表 (UsageList)，向每个节点询问后汇总。只要给出其中任何一个，就返回一份报告 (UsageReport)，数据来自控制平面按小时记的账，最多比节点晚一个 --usage-seconds，节点不在线时也能查到：prices 是九项价格，每个分组和 totals 都带有只有这本账才有的数量（requests、state_gb_hours、storage_gb_hours、log_bytes、log_gb_hours、egress_eu_bytes、egress_ap_bytes、drive_write_bytes、drive_cold_read_bytes、browser_awake_seconds 和 cache_gb_hours），bucket_seconds 为 3600。按沙箱分组的报告还多一个分组，记录不属于任何单个沙箱的用量（sandbox_id 为 null）：存储卷和快照保存的数据、写入存储卷的数据和从存储卷冷读取的数据、应用处理的请求和打印的日志、应用日志导出发送的数据（kind 为 log_export）、存储卷备份在对象存储中保存的数据（kind 为 backup，计入 state_gb_hours），以及浏览器配置文件保存的数据（kind 为 browser_profiles，计入 storage_gb_hours）。欠费的账户也可以读取。所需权限范围：read。

GET
https://api.glac.ai/v1/usage

授权

  • apiKeyHTTPrequired

查询参数

  • fromoptionalstring

    从这个时间起 (RFC 3339)：开始时间不早于它的小时计入报告。

    format: date-time
  • tooptionalstring

    到这个时间为止：开始时间早于它的小时计入报告。

    format: date-time
  • group_byoptionalstring

    按什么分组，用逗号分隔：sandbox、hour 或 day、metadata.<key>，以及这里特有的 kind、volume（或 drive：云盘也是存储卷，分组中给出 drive_id）、snapshot 和 backup（存储卷的每个备份各成一组，backup_id）。不给出时，报告按沙箱分组；查询某个存储卷时按存储卷分组，查询某个快照时按快照分组，查询某个备份时按备份分组 (backup_id)。也可以用 database（项目的每个数据库一组：其分支的实例和云盘的用量，包括历史；database_id）或 branch（数据库的每个分支一组，database_id 和 branch_id），可以搭配 hour 或 day，也可以单独使用，但不能搭配其他分组 (slice DB7)：不属于任何数据库的用量归入 database_id 为 null 的分组。

  • <key>optionalstring

    在使用当时，元数据中该键为该值时的用量。

  • sandbox_idoptionalstring

    单个沙箱的用量：用 id 或名称指定（已删除的沙箱用 id 指定）。

  • kindoptionalsandbox或volume或drive或snapshot或log_export或backup另有 1 个

    某一类东西的用量或保存量：sandbox、volume（存储卷保存的数据，以及写入和冷读取的数据）、drive（同上，针对云盘：云盘也是存储卷）或 snapshot；log_export，节点发往日志导出目标 (/v1/destinations) 的数据，按每个导出目标 (dst-...) 和应用记账；或者 backup，存储卷备份在对象存储中保存的数据 (/v1/backups)，按每个备份 (bak-...) 记在状态计量项 (state_gb_hours) 上：从 ready_at 起到删除为止（若先过期则到过期为止）的 stored_bytes，每小时计入它被保存的那个小时，直到当前时刻，已开始的那个小时也包括在内（每分钟记账一次；已删除的记到删除时）；或者 browser_profiles，项目的浏览器配置文件在平台存储中保存的数据，按存放它们的存储桶 (bkt-...) 作为存储卷数据记账 (storage_gb_hours)，每小时按存储给出的数值计。其他值返回 400 invalid_field。这是控制平面的参数：独立运行的节点会拒绝它，与 volume_id 和 snapshot_id 一样。

  • volume_idoptionalstring

    单个存储卷的保存量：用 id 或名称指定（已删除的用 id 指定）。sandbox_id、volume_id、drive_id、snapshot_id 和 backup_id 一次只能给一个。

  • drive_idoptionalstring

    单个云盘的保存量、写入量和冷读取量：用 id 或名称指定（已删除的用 id 指定）。云盘也是存储卷：与 volume_id 相同，分组中给出 drive_id。sandbox_id、volume_id、drive_id 和 snapshot_id 一次只能给一个。

  • snapshot_idoptionalstring

    单个快照的保存量：用 id 或名称指定（已删除的用 id 指定）；云盘快照用 id 指定（dsnap-…，slice D7）：它单独保存的数据，记在存储计量项上。

  • backup_idoptionalstring

    存储卷的单个备份在对象存储中的保存量 (/v1/backups)：用 id 指定 (bak-…)，无论其存储卷后来怎样，记在状态计量项 (state_gb_hours) 上。sandbox_id、volume_id、drive_id、snapshot_id 和 backup_id 一次只能给一个；默认按备份分组，除非 group_by 另有指定。这是控制平面的参数：独立运行的节点会拒绝它。

  • limitoptionalinteger

    每页的行数或分组数：1 到 1000，默认 100。

    maximum: 1000 · minimum: 1
  • cursoroptionalstring

    取 next_cursor 为此值的那一页之后的一页。

Returns

200

节点的 UsageList，或者带有控制平面数量的 UsageReport (sandboxd/openapi/openapi.json)。

JSON

以下之一：

  • UsageList
    • data数组，元素为objectrequired
      • sandbox_idstringrequired
        pattern: ^sbx-[0-9a-hjkmnp-tv-z]{16}$
      • namestring | nullrequired

        沙箱的名称；已删除的沙箱为其最后使用的名称。

      • metadata映射，值为stringrequired

        供调用方自用的任意键值对；沙箱列表可以按它们筛选。最多 64 个键，每个键 1 到 64 个字符，值最多 1024 个字符。不要在这里存放机密：元数据以明文保存，沙箱在产生用量期间有过的每组元数据都会随其用量保留十三个月，沙箱删除后也一样（GET /v1/usage 按它们分组和筛选）。

      • cpu_secondsnumberrequired
        minimum: 0
      • memory_gib_secondsnumberrequired

        以 128 MiB 为档位的内存随时间的积分：GiB 乘以秒。

        minimum: 0
      • disk_bytesintegerrequired

        根磁盘当前占用的空间；已删除的沙箱为 0。

        format: int64 · minimum: 0
      • egress_bytesintegerrequired

        发送到互联网的字节数。已删除的沙箱不含其最后一秒，那一秒只计入账户的当月情况。

        format: int64 · minimum: 0
      • created_atstringrequired
        format: date-time
      • deleted_atstring | nullrequired

        存在的沙箱为 null。

        format: date-time
      • productoptionalbrowsers或databases或null

        沙箱以什么产品出售，以控制平面自己的记录为准（从不依据元数据）：浏览器会话为 browsers (POST /v1/browsers)，数据库分支的实例为 databases (POST /v1/databases)，其他沙箱为 null。

    • next_cursorstring | nullrequired

      把它作为 cursor 传入即可获取下一页。最后一页为 null。

    • totalsobjectrequired

      筛选条件选中的所有行的合计，而不只是本页的。

      • cpu_secondsnumberrequired
        minimum: 0
      • memory_gib_secondsnumberrequired
        minimum: 0
      • egress_bytesintegerrequired
        format: int64 · minimum: 0
      • sandboxesintegerrequired
        minimum: 0
    • egressobjectrequired

      账户的当月情况：用来对照额度的数据量，无论由哪些沙箱发送。

      • periodstringrequired

        当前的自然月，按 UTC。

        pattern: ^[0-9]{4}-[0-9]{2}$
      • fromstringrequired

        额度对应的时段：账户所在的付费版周期，或免费版的一天 (UTC)。

        format: date-time
      • tostringrequired
        format: date-time
      • bytesintegerrequired

        该时段内发送的数据量。

        format: int64 · minimum: 0
      • allowance_bytesinteger | nullrequired

        该时段包含的额度；null：发送多少都包含在内。

        format: int64 · minimum: 0
      • overage_bytesinteger | nullrequired

        bytes 超出额度多少；没有额度时为 null。

        format: int64 · minimum: 0
      • overage_usdnumberrequired

        超出额度部分按标价计算的金额：在付费版上由账户余额支付；在免费版上不计价，流量会在达到当天配额时停止。

        minimum: 0
      • regionsobjectrequired

        该时段的流量按区域细分：按流量离开时所在节点的区域：na 北美（以及没有区域的节点），eu 欧洲，ap 亚太。额度先抵扣最贵区域的字节数；每个区域单独计价和取整，overage_usd 是各区域之和。

        • naobjectrequired
          • bytesintegerrequired

            该时段内从该区域节点发送的数据量。

            format: int64 · minimum: 0
          • overage_bytesinteger | nullrequired

            其中超出额度的部分；没有额度时为 null。

            format: int64 · minimum: 0
          • unit_price_usdnumberrequired

            该区域每 GB 的价格。

          • overage_usdnumberrequired

            overage_bytes 按该价格计算的金额，精确到百万分之一。

            minimum: 0
        • euobjectrequired
          • bytesintegerrequired

            该时段内从该区域节点发送的数据量。

            format: int64 · minimum: 0
          • overage_bytesinteger | nullrequired

            其中超出额度的部分；没有额度时为 null。

            format: int64 · minimum: 0
          • unit_price_usdnumberrequired

            该区域每 GB 的价格。

          • overage_usdnumberrequired

            overage_bytes 按该价格计算的金额，精确到百万分之一。

            minimum: 0
        • apobjectrequired
          • bytesintegerrequired

            该时段内从该区域节点发送的数据量。

            format: int64 · minimum: 0
          • overage_bytesinteger | nullrequired

            其中超出额度的部分；没有额度时为 null。

            format: int64 · minimum: 0
          • unit_price_usdnumberrequired

            该区域每 GB 的价格。

          • overage_usdnumberrequired

            overage_bytes 按该价格计算的金额，精确到百万分之一。

            minimum: 0
      • month_bytesintegerrequired

        自然月 period 内发送的数据量：账户自己设的上限与这个数对照。

        format: int64 · minimum: 0
      • stoppedbooleanrequired

        账户发往互联网的流量当前是否已停止。

      • stopped_reasonstring | nullrequired

        allowance_reached：账户已用完额度，且没有余额支付更多；overage_cap_reached：账户本自然月发送的数据量已达到自己设的上限。未停止时为 null。

      • pricesobjectrequired
        • egress_gb_usdnumberrequired

          超出额度后每 GB（10^9 字节）的美元价格。

          minimum: 0
        • egress_eu_gb_usdnumberrequired
        • egress_ap_gb_usdnumberrequired
        • provisionalbooleanrequired
      • project_bytesintegerrequired

        调用方密钥所属项目在本自然月发送的数据量；额度是账户的。

        format: int64 · minimum: 0
      • countedbooleanrequired

        被询问的每个节点是否都在统计流量。

  • UsageReport
    • data数组，元素为objectrequired
      • cpu_secondsnumberrequired

        整数微秒，以秒为单位书写。

        minimum: 0
      • memory_gib_secondsnumberrequired

        以 128 MiB 为档位的内存随时间的积分：档位数乘以毫秒的整数，以 GiB 乘以秒的形式书写（为 0.000125 的整数倍）。

        minimum: 0
      • egress_bytesintegerrequired

        发送到互联网的字节数。

        format: int64 · minimum: 0
      • requestsintegerrequired

        仅经由控制平面（节点不统计）：节点经平台入口接收的、发往沙箱的请求，一个 HTTP 请求、一个 WebSocket、一个 SSH 会话各算一次；平台自己拒绝的不算。应用的请求记在应用本身名下，带有其实例的标签以及请求所经边缘节点的区域：按 metadata.app 或 metadata.region 分组时，它们与实例的用量在同一组，按沙箱分组时，它们在不属于任何沙箱的那一组。control/README.md，「套餐和账单」。

        format: int64 · minimum: 0
      • state_gb_hoursnumberrequired

        仅经由控制平面：沙箱休眠期间保存的自身内存和磁盘，每小时采样一次；以及存储卷备份在对象存储中保存的数据，即对象存储为每个备份保存的字节数 (stored_bytes)，从就绪起到消失为止，记在备份自己的 id 下（kind 为 backup：在沙箱分组中为 0）。单位为 GB·小时（整数字节·小时，以 GB·小时的 10^-9 为单位书写）。

        minimum: 0
      • storage_gb_hoursnumberrequired

        仅经由控制平面：存储卷和快照保存的数据，单位为 GB·小时（整数字节·小时，以 GB·小时的 10^-9 为单位书写）。存储卷按其 used_bytes、快照按其 size_bytes 计，只要它们存在就计，由其节点从创建那一刻统计到删除那一刻。记在存储卷或快照自己的 id 下：在沙箱分组中为 0。

        minimum: 0
      • log_bytesintegerrequired

        仅经由控制平面：应用实例打印且被节点保留的内容，按打印时各行 text 的字节数计。根据各节点对应用日志的统计，记在应用本身名下，计入日志行所在的小时，带有应用自己的标签及其 id (metadata.app)：按 metadata.app 分组时，它与应用实例的用量在同一组，按沙箱分组时，它在不属于任何沙箱的那一组。它不属于任何计量项：日志按 log_gb_hours 计价。

        format: int64 · minimum: 0
      • log_gb_hoursnumberrequired

        仅经由控制平面：应用实例打印且被节点保留的内容，乘以保留的小时数（从打印所在的小时起，到账户套餐的日志保留期结束为止的每个小时），单位为 GB·小时：即日志计量项（GET /v1/billing 的 meters.logs）。与 log_bytes 一样记在应用名下，计入其被保留的各个小时。

        minimum: 0
      • drive_write_bytesintegerrequired

        仅经由控制平面：写入存储卷的数据，按其节点的统计，记在存储卷自己的 id 下（在沙箱分组中为 0）。

        format: int64 · minimum: 0
      • drive_cold_read_bytesintegerrequired

        仅经由控制平面：从对象存储（而不是其节点的磁盘）读取的存储卷数据，记在存储卷自己的 id 下；以及沙箱通过云盘快照的只读挂载 (slice D7) 从对象存储读取的数据，记在各沙箱名下，由其账户支付。

        format: int64 · minimum: 0
      • browser_awake_secondsnumberrequired

        仅经由控制平面：浏览器会话的运行时长，以秒为单位、精确到毫秒，按其节点的统计，记在会话名下，不记在其他沙箱名下。没有计量项为它计价：会话与任何沙箱一样，按 CPU 时间、内存和流量计费。

        minimum: 0
      • cache_gb_hoursnumberrequired

        仅经由控制平面时提供：存储卷在其节点 NVMe 上保存的量（每个存储卷取所设缓存大小 cache_bytes 与其保存的数据量中较小的那个），以 GB·小时计，逐小时统计，以节点的统计为准，记在存储卷自己的 id 名下（沙箱分组中为 0）：即缓存计量项 (volume_cache)。缓存为整个存储卷（默认）的存储卷，按其保存的数据量计。

        minimum: 0
      • egress_eu_bytesintegerrequired

        仅经由控制平面：egress_bytes 中从欧洲节点发出的部分，按 egress_eu_gb_usd 计价。

        format: int64 · minimum: 0
      • egress_ap_bytesintegerrequired

        仅经由控制平面：egress_bytes 中从亚太节点发出的部分，按 egress_ap_gb_usd 计价；其余部分从北美节点或没有区域的节点发出，按 egress_gb_usd 计价。

        format: int64 · minimum: 0
      • startoptionalstring

        按 hour 或 day 分组时：本分组的小时或日 (UTC) 的开始时间。

        format: date-time
      • sandbox_idoptionalstring | null

        按 sandbox 分组时。经由控制平面时，在那个记录不属于任何单个沙箱的用量的分组中为 null：存储卷和快照保存的数据（如果报告同时按存储卷或快照分组，则在每个这样的分组中都为 null）、存储卷备份保存的数据，以及应用处理的请求，后者记在应用名下，不记在其任何实例名下。

        pattern: ^sbx-[0-9a-hjkmnp-tv-z]{16}$
      • volume_idoptionalstring | null

        仅经由控制平面，按 volume 分组时：本分组对应的存储卷，或托管应用某个安装的存储桶（ibk-，按存储卷数据计费）。在不属于任何存储卷的分组中为 null。

        pattern: ^(vol|ibk)-[0-9a-hjkmnp-tv-z]{16}$
      • drive_idoptionalstring | null

        仅经由控制平面，按 drive（或 drive_id、kind=drive）分组时：本分组对应的云盘。在不属于任何云盘的分组中为 null。

        pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$
      • snapshot_idoptionalstring | null

        仅经由控制平面，按 snapshot 分组时：本分组对应的快照。在不属于任何快照的分组中为 null。

        pattern: ^snap-[0-9a-hjkmnp-tv-z]{16}$
      • backup_idoptionalstring | null

        仅经由控制平面，按 backup（或 backup_id）分组时：本分组对应的存储卷备份。在不属于任何备份的分组中为 null。其 name 为 null：备份没有名称。

        pattern: ^bak-[0-9a-z]+$
      • kindoptionalstring

        仅经由控制平面，按 kind 分组时（查询针对云盘时，以 drive 代替 volume）：本分组对应的那一类东西。log_export：应用日志导出发往其导出目标的数据，属于发往互联网的流量 (egress_bytes)，别无其他。backup：存储卷备份在对象存储中保存的数据，记在状态计量项 (state_gb_hours) 上，别无其他。browser_profiles：项目的浏览器配置文件保存的数据，按存储卷数据计 (storage_gb_hours)，别无其他。volume：存储卷保存的数据 (storage_gb_hours)，以及写入和冷读取的数据（drive_write_bytes、drive_cold_read_bytes）。

      • nameoptionalstring | null

        按 sandbox 分组时：沙箱现在的名称；已删除的沙箱为其最后使用的名称。经由控制平面按 volume 或 snapshot 分组时，对存储卷或快照也一样。

      • productoptionalbrowsers或databases或null

        沙箱以什么产品出售，以控制平面自己的记录为准（从不依据元数据）：浏览器会话为 browsers (POST /v1/browsers)，数据库分支的实例为 databases (POST /v1/databases)，其他沙箱为 null。仅经由控制平面，按 sandbox 分组时。

      • database_idoptionalstring | null

        仅经由控制平面，按 sandbox 或 volume (drive) 分组时：本分组的东西所属的数据库 (slice DB7)：即其某个分支的实例，或某个分支的云盘，以数据库自己的记录为准（从不依据元数据）。其他东西以及不对应任何东西的分组为 null。按 database 或 branch 分组时：本分组的数据库；在不属于任何数据库的用量分组中为 null。

        pattern: ^db-[0-9a-hjkmnp-tv-z]{16}$
      • branch_idoptionalstring | null

        有 database_id 时：该东西所属的数据库分支（根分支 main，或数据库自己的某个分支）。database_id 为 null 时也为 null。按 branch 分组时：本分组的分支。

        pattern: ^br-[0-9a-hjkmnp-tv-z]{16}$
      • metadataoptional映射，值为string | null

        按 metadata.<key> 分组时：每个分组所依据的键，以及本分组的沙箱在产生这些用量时该键的值。null：它们没有这个键。

    • next_cursorstring | nullrequired

      把它作为 cursor 传入即可获取下一页。最后一页为 null。

    • totalsobjectrequired

      调用选中的所有分组的合计，而不只是本页的，以及它们涉及多少个沙箱（被记入请求的应用不算在内）。合计取自生成本页的那一刻。如果时间范围包含当前时刻，用量仍在不断记账：后面一页的合计会领先于前面一页，分多页收集的各分组加起来会小于最后一页的合计。时间范围已结束时，每一页的合计都相同。

      • cpu_secondsnumberrequired
        minimum: 0
      • memory_gib_secondsnumberrequired
        minimum: 0
      • egress_bytesintegerrequired
        format: int64 · minimum: 0
      • requestsintegerrequired

        只有经由控制平面时才有，与分组中一样。

        format: int64 · minimum: 0
      • state_gb_hoursnumberrequired

        只有经由控制平面时才有，与分组中一样。

        minimum: 0
      • storage_gb_hoursnumberrequired

        只有经由控制平面时才有，与分组中一样。

        minimum: 0
      • log_bytesintegerrequired

        只有经由控制平面时才有，与分组中一样。

        format: int64 · minimum: 0
      • log_gb_hoursnumberrequired

        只有经由控制平面时才有，与分组中一样。

        minimum: 0
      • drive_write_bytesintegerrequired

        只有经由控制平面时才有，与分组中一样。

        format: int64 · minimum: 0
      • drive_cold_read_bytesintegerrequired

        只有经由控制平面时才有，与分组中一样。

        format: int64 · minimum: 0
      • browser_awake_secondsnumberrequired

        只有经由控制平面时才有，与分组中一样。

        minimum: 0
      • cache_gb_hoursnumberrequired

        只有经由控制平面时才有，与分组中一样。

        minimum: 0
      • egress_eu_bytesintegerrequired

        只有经由控制平面时才有，与分组中一样：egress_bytes 中从欧洲节点发出的部分。

        format: int64 · minimum: 0
      • egress_ap_bytesintegerrequired

        只有经由控制平面时才有，与分组中一样：egress_bytes 中从亚太节点发出的部分。

        format: int64 · minimum: 0
      • sandboxesintegerrequired

        分组涉及多少个沙箱。存储卷和快照不计入这里。

        minimum: 0
    • fromstring | nullrequired

      实际采用的时间范围起点：开始时间不早于所请求的 from 的第一个小时。null：没有请求起点。

      format: date-time
    • tostring | nullrequired

      实际采用的时间范围终点：开始时间不早于所请求的 to 的第一个小时；在它之前的小时都在范围内。null：没有请求终点。

      format: date-time
    • group_by数组，元素为stringrequired

      分组依据，按键的顺序：hour 或 day、sandbox，然后是各个 metadata.<key>。经由控制平面时，volume、snapshot 和 kind 排在 sandbox 之后。

    • bucket_secondsintegerrequired

      账目的粒度：3600 秒，即一小时。（为测试而以 --usage-bucket-seconds 启动的节点粒度更短。）

      minimum: 1
    • metadata_atstringrequired

      分组和筛选依据的是哪一组元数据。time_of_use：沙箱在产生该行用量时所带的元数据。

    • metadata_approximatebooleanrequired

      如果范围内的某些用量（针对所请求的沙箱，无论按元数据如何筛选）可能记在与使用时不同的元数据下，则为 true；metadata_approximate_reasons 说明原因。数量在任何情况下都是准确的；归到哪个分组则不一定准确，按元数据筛选可能会漏掉其中一部分。

    • metadata_approximate_reasons数组，元素为stringrequired

      当 metadata_approximate 为 true 时说明原因：范围内适用的每个原因各出现一次；为 false 时为空。changed_often：某个沙箱的元数据在一小时内变化超过 60 次。前 60 次变化各自结束账目中的一行；之后，该小时的行沿用最新的元数据继续记账。其余原因属于控制平面，它把许多节点的账目保存在同一个存储中。sets_in_an_hour：一个沙箱在一小时内最多有 61 组元数据下的行，在更多组元数据下的用量不记在任何元数据下。values_of_a_key：某个元数据键在一个自然月内的不同取值，超过了账目为一个项目接收的上限 (1,000)。超出的取值会把它的键从这组元数据中去掉，用量记在这组的其余键下：标有团队和任务 id 的沙箱，会记在其团队下。按该键查询时，这类用量不属于任何值；按其他任何键查询时，它都在应在的位置。keys_in_a_month：当月新增的元数据组已经用了 256 个不同的键名；新组中再出现的键会被去掉，其他键和所有数量保持不变。已有的组仍然准确。set_too_large：JSON 文本超过 4,096 字节的元数据组不会保留，在它下面的用量不记在任何元数据下。sets_in_a_month：项目在一个自然月内新增的元数据组超过了账目的接收上限 (10,000)；更多新组下的用量在下个月之前不记在任何元数据下。账目中已有的组不会重复计数，也不占用某个键的取值名额。sets_in_all：项目保留的元数据组已达账目为单个项目保留的总上限（130,000：一组元数据在最后一次使用后保留十三个月）；更多新组下的用量不记在任何元数据下，直到项目不再使用的组被清除。booked_on_arrival：沙箱的节点给出了用量读数，却没有给出对应的小时和元数据（在记下它们之前就断开了的节点，或早期版本的节点）：用量记在读数到达的那个小时，使用沙箱在此前或此后的元数据。unspecified：该小时由一个不保留原因的版本标记。

    • pricesobjectrequired

      数量所乘的价格：账户当月的价格，每个计量项一个（流量则每个区域一个）。

      • cpu_ms_million_usdnumberrequired

        每百万 CPU 毫秒的 CPU 时间：即繁忙 vCPU 的毫秒数（$0.01，相当于每 vCPU·小时 $0.036）。

      • memory_gib_hour_usdnumberrequired

        运行时或暂停在内存中（暂停层级）占用内存的每 GiB·小时价格。

      • requests_million_usdnumberrequired

        每百万次请求：发往应用的请求，以及经由预览 URL 发往沙箱的请求。

      • volume_data_gb_month_usdnumberrequired

        每 GB·月的存储卷数据：存储卷中的数据、快照保存的数据、休眠沙箱保存的自身内存和磁盘，以及存储卷备份在对象存储中保存的数据 (--price-volume-data-gb-month)。写入或读取存储卷不计价。

      • volume_cache_gb_month_usdnumberrequired

        每 GB·月的存储卷 NVMe 缓存：其节点在自己磁盘上为它保存的数据，取存储卷所设缓存大小（默认为全部）与其数据量中较小的那个 (--price-volume-cache-gb-month)。这样完全缓存的存储卷，每 GB·月的费用为此价格与 volume_data_gb_month_usd 之和。

      • egress_gb_usdnumberrequired

        从北美节点或没有区域的节点发送到互联网的每 GB（10^9 字节）流量：流量按其离开时所在节点的区域计价：na 北美（以及没有区域的节点），eu 欧洲，ap 亚太。

      • egress_eu_gb_usdnumberrequired

        从欧洲节点发送到互联网的每 GB 流量。

      • egress_ap_gb_usdnumberrequired

        从亚太节点发送到互联网的每 GB 流量。

      • logs_gb_month_usdnumberrequired

        应用打印且被节点保留的内容的每 GB·月价格：每一行保留的输出的 text，按打印时计，乘以其保留的小时数 (--price-logs-gb-month)。

      • provisionalbooleanrequired
    • planstring | nullrequired

      项目所属账户当前的套餐 (Billing.plan)。

400

unknown_parameter；invalid_field：时间无效，范围的结束早于开始，group_by 或 kind 无效，sandbox_id、volume_id 和 snapshot_id 给出了两个。
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    随 already_moving 返回：该沙箱正在进行的迁移。

  • upgrade_idoptionalstring

    随 upgrade_in_progress（该键尚未结束的升级）、upgrade_started（已开始的升级）和 rollback_gone（回退被拒绝的那次升级）返回：即那次升级。

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    随 move_over、move_going_back 和 move_taken_over 返回 (POST /internal/moves/{id}/cancel)：迁移的当前状态。

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • epochintegerrequired

      迁移开始时表中记录的沙箱纪元：旧节点在这个纪元释放它，新节点在纪元加一时接管它，旧节点在纪元加二时收回它，从对象存储接管则在纪元加三时。

      minimum: 1
    • stepstringrequired

      迁移的进展：releasing（正在请旧节点释放它；表中记录它在旧节点上）、taking_over（正在请新节点接管它；表中记录它在新节点上）、reclaiming（新节点拒绝了它，正在请旧节点收回）、restoring（旧节点没有保留它的任何东西，正从对象存储接管）、done（已在新节点上）、failed（留在原处，或回到了原处，或停在某个时间无法消除的故障或运营方的取消发生时所在的位置：error 说明原因）。

    • whystringrequired

      发起迁移的原因：运营方的迁移、撤离或恢复。

    • wakebooleanrequired

      新节点是否唤醒它：按调用的指定，或按迁移开始时它的状态（是否在运行）。

    • from_storebooleanrequired

      新节点只从对象存储接管它。

    • releaseobject | nullrequired

      旧节点释放时的响应（sandboxd/openapi/openapi.json，releaseSandbox），不含释放所用的密钥；响应之前为 null。

    • takeoverobject | nullrequired

      结束迁移的那次接管的响应（节点文档中的 takeoverSandbox）：磁盘和内存来自哪里 (source)、各用了多长时间 (ms)、memory；之前为 null。

    • errorrequired

      失败的迁移：失败原因（如果被带回旧节点，则为新节点的拒绝原因）；已完成的迁移：null；进行中的迁移：如果当前步骤要再次请求，则为该步骤上次得到的答复。

      以下之一：

      • object
      • null
    • attemptsintegerrequired

      当前步骤已请求了多少次，仍没有得到确定的答复。

      minimum: 0
    • next_attempt_atstring | nullrequired

      该步骤何时再次请求；不在等待时为 null。

      format: date-time
    • batchstring | nullrequired

      它所属的撤离 (evc-…) 或恢复 (rcv-…)。

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    随 lease_held 返回：节点最后获得的租约最晚可以持有到何时，再加上让节点察觉租约到期所需的时间（在此之前 recoverNode 会被拒绝）。

    format: date-time
  • activeoptionalobject | null

    随 standby 返回：备用副本最后一次读取租约时的活动副本；没有副本持有租约时为 null。

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null（节点的 SecretHosts）。

  • problemsoptional数组，元素为object

    随 invalid_definition 返回：定义中的每个问题，各附其位置和内容。

    • atstringrequired

      在定义中的位置，用点分隔的路径 (services.web.port)；针对整个定义时为空。

    • messagestringrequired
  • reportoptionalobject

    随 compose_refused 返回：导入的报告，说明拒绝了什么、为什么以及要改什么。

    • objectcompose_importrequired
    • namestring | nullrequired

      模型的 name：即每个服务的标签 compose.project。null：模型没有名称。

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profiles数组，元素为stringrequired
    • treatmentsobjectrequired

      报告中每种处理方式各有多少项。

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • items数组，元素为objectrequired

      模型的顶层元素：name，以及每个卷、网络、config、secret 和扩展。

      • atstringrequired

        在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

      • treatmentdone或adapted或ignored或refusedrequired

        done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

      • whystringrequired
      • changestring | nullrequired

        被拒绝的项：要改什么。其他情况为 null。

    • services数组，元素为objectrequired

      导入所采纳的服务，按模型中的顺序。

      • namestringrequired

        服务的名称，也是其应用的名称。

      • app_idstring | nullrequired

        其应用。null：试运行，且项目中没有该服务。

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

        导入对其应用做了（试运行时为将会做）什么：创建、写入变化的部分，或什么都不做。

      • kindservice或jobrequired

        job：模型中有服务等待它完成，它会在每次需要它的部署中运行到结束。

      • statefulbooleanrequired

        它挂载自己的存储卷：只有一个实例，由该实例持有存储卷。

      • versionbooleanrequired

        导入的部署是否为它创建版本：即解析引用后其版本的构成与当前版本不同。

      • items数组，元素为objectrequired
        • atstringrequired

          在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

        • treatmentdone或adapted或ignored或refusedrequired

          done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

        • whystringrequired
        • changestring | nullrequired

          被拒绝的项：要改什么。其他情况为 null。

      • appobjectrequired

        导入写入的服务应用字段：其版本的构成，以及立即生效的设置。

        • imagestring | nullrequired

          应用下一个版本的构成，连同其后的七个字段：即其最新版本的构成，加上此后的修改。null：应用没有镜像，也没有版本。

        • image_pull_secretstring | nullrequired

          保存镜像仓库凭据的机密的名称。任何响应都不包含其值。null：没有。

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

          放在镜像 ENTRYPOINT 之后、取代其 CMD 的内容。null：使用镜像的 CMD，或者整个 start_command。

          以下之一：

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          判断实例已启动的方式，版本的模板会在实例启动后保存：三者必须恰好给出一个。前两种从实例外部检查，所以服务必须监听所有地址 (0.0.0.0)。

          • httpoptionalstring

            一个以 / 开头的路径：在应用端口上对它发起 GET，返回 200 到 399 之间的状态码。

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

            在实例中执行成功的一条命令。由实例的 shell 运行：参数列表会被写成一行交给它。

            以下之一：

            • string
            • array<string>
        • env映射，值为stringrequired
        • secrets映射，值为stringrequired

          机密的名称。任何响应都不包含值。

        • sizeobjectrequired

          单个实例最多能使用的资源。按实际用量计费。

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            偶数个 MiB（即节点为虚拟机加载内存所用的 2 MiB 页的整数倍），以字节表示。其他任何大小都返回 400 invalid_field（param 为 size.memory_bytes）：没有节点会创建这种大小的实例，正如没有节点会创建这种大小的沙箱（节点的 SandboxLimitsCreate.memory_bytes）。

            minimum: 134217728
        • volumes数组，元素为objectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • kindstringrequired
        • files数组，元素为objectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          以下之一：

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regions数组，元素为stringrequired

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

            无论有没有请求，应用在一个区域内保持运行的实例数：即下限。该区域服务该应用的节点按分摊 max_instances 的方式分摊它（两个节点、下限为 2：各一个；下限为 1：一个，在最先尝试的节点上；下限为 5：三个和两个），不在线的节点由其他节点补足。节点在收到通知时就创建自己那部分，而不是等到第一个请求，也不会因为空闲而停止或删除这些实例；它们按运行中的实例计量。0（未设置时的值）：没有下限。调低后，超出部分的实例从那一刻起视为空闲，并像空闲实例一样被停止和删除。最多为 max_instances（如果给出），且不超过账户套餐允许应用在一个区域请求的数量（caps.app_instances.limit：5、50 和 500）：超出会被拒绝，返回 403 plan_cap_reached。

            minimum: 0
          • max_instancesinteger | nullrequired

            应用在一个区域内最多有多少个实例：由该区域服务该应用的节点分摊。最多为账户套餐允许应用请求的数量（caps.app_instances.limit：免费版 5，付费版 500）：超出会被拒绝，返回 403 plan_cap_reached；在允许的套餐上请求的数值会保留，但受当前套餐数值的限制。null：未指定数量的应用使用套餐的数值（caps.app_instances.default：免费版 2，付费版 50），如果 min_instances 更大则用它。告诉节点的数值，不超过账户除其他运行中资源外还能容纳的运行量，也不少于应用当前运行的实例数。

            minimum: 1
          • concurrencyinteger | nullrequired

            单个实例同时处理的上限：边缘节点发给它的请求，加上它在项目网络上打开的连接（经由其服务的地址，节点会按连接把它们分给各个实例；或者直接连到它自己的地址）。达到上限的实例即为已满，更多的请求会创建新实例。null（未设置时的值）：没有上限。此时节点会在现有实例的 CPU 或内存接近其规格时增加实例，应用不必猜一个数字；一次只处理一个请求的服务应设为 1。

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            实例在没有请求时最多等待多久就停止，单位为毫秒。在这个上限以内，节点根据应用自己的流量选择等待时间：在应用最近一段时间里两次请求之间的间隔上，比较多运行一秒空闲与停止再恢复所花的 CPU 时间，选出成本最低的等待时间；这样，请求间隔比停止成本还短的应用会一直运行，请求间隔很长的应用则在最后一个响应结束后立即停止（0：总是立即停止）。null（未设置时的值）：平台的上限，三秒。设置过 100（2026年10月28日之前的默认值）的应用，从那天起视为 null。持续停止的实例会在 delete_after_ms 后被其节点删除，下一个需要实例的请求会得到一个新实例；min_instances 保持运行的实例既不会停止也不会删除。

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            在实例因空闲而停止之前多久，向连接到其客户机 /run/sbx/awake 的程序发送一行 sleep N，单位为毫秒：程序可以借此写出手头的数据、关闭连接，或者发起保持，从而推迟停止。无论它们是否响应，停止都会在这段时间之后到来；没有程序连接时，不会推迟。键控实例也会收到通知。0 或 null：不通知（默认）。

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            实例中的程序发起的保持，在空闲时间到期后最多还能让实例运行多久，单位为毫秒：程序连接 /run/sbx/awake，如果某个请求在响应之后还有后续工作，就在响应它之前发送 +，工作完成后发送 -（或关闭连接，或退出）；最后一个保持解除 sleep_after_ms 之后，实例停止。超过这个时间，无论有什么保持，实例都会停止；如果 sleep_notice_ms 要求通知，会先向已连接的程序发送 sleep N cap。保持期间实例在运行，并按运行计量。0：不理会保持。null：30000（默认）。

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            实例空闲多久后被删除，与停止使用同一个起算点：下一个需要实例的请求会得到一个新实例，即版本模板的克隆，不含被删除的实例在内存和磁盘中积累的东西（需要长久保存的数据请放在存储卷或数据库中）。一秒到一小时，一小时是平台的时间，也是上限：超出会被拒绝 (400 invalid_field)，需要保持预热的实例应计入 min_instances。null（未设置时的值）：节点的一小时 (--app-delete-after-seconds)。修改对应用现有的实例和之后创建的实例同样有效：每个节点至少每秒按应用当前的时间检查一次每个实例。不适用于应用的键控实例，键控实例用 keys.delete_after_idle_ms。

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            已停止的实例在保存内存并真正休眠之前保持暂停多久，单位为毫秒：暂停时，下一个请求在一两毫秒内得到响应，内存照常计量；休眠时，唤醒要多几毫秒，只计量它保存的数据。节点会把它限制在节点让任何实例保持暂停的最长时间内（十分钟）；宿主机内存不足、其他虚拟机需要占用槽位，或者有人请求休眠，都会让它更早休眠。null（默认）：节点的最长时间。数据库的 suspend_after_seconds 就是其应用的这一设置。

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            每天的某个 UTC 时刻 (HH:MM)，在此时唤醒应用中处于休眠状态的键控实例和有状态服务的实例，让它们完成等待唤醒才能做的工作（比如数据库维护）；节点根据应用请求创建和删除的实例只会被请求唤醒。唤醒本身不算活动：唤醒后运行的东西才算，运行完毕后实例会再次休眠。此外，无论这里怎么设置，有状态服务的实例都会为其 PostgreSQL 服务器 pg_cron 任务的下一次运行而被唤醒。null（默认）：不唤醒。数据库的 wake_daily_at 就是其应用的这一设置。

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          以下之一：

          • object
          • null
        • egressobject | nullrequired

          与沙箱相同的出站规则（default、allow、deny、http、inject），没有时为 null；按调用给出的原样保存（PATCH 会像节点那样按键逐个合并）。规则立即生效，不产生新版本：服务该应用的节点会把它们应用到其组内的每个实例上，包括现有的实例（运行中的实例对其已有连接也生效）和之后创建的实例；键控实例不受这些规则约束。控制平面只检查它们是不是由这些键组成、不超过 256 KiB 的对象：规则的内容由节点在应用时检查，节点读不懂其规则的实例，所有出站流量都会被拒绝（节点日志会说明原因）。

          • defaultoptionalallow或deny或null
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            任何连接都到达不了的端口，TCP 或 UDP，无论连往哪里，也无论规则的其他部分怎么说。浏览器会话的规则总是包含 25、465、587 以及矿池监听的端口（3333、4444、5555、7777、14444、45700）：无论其规则如何修改，控制平面都会把它们加上。

        • metadata映射，值为stringrequired
        • logsobjectrequired

          应用日志包含哪些内容，每一项为给出的值或默认值 (AppLogSettings)。

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          是否在其默认域名 (url) 上响应。

        • depends_on数组，元素为objectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliases数组，元素为stringrequired
          • endpoint_modestringrequired
        • drivesoptional数组，元素为object

          其实例挂载的云盘 (AppCreate.drives)：没有指定时为空列表 []。

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptional数组，元素为object

          每个键的实例自有的云盘 (AppCreate.key_drives)：没有给出时为空列表 []。

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • runtimeoptional

          运行时设置 (AppCreate.runtime)。null：没有。

          以下之一：

          • Runtime
            • ulimits映射，值为RuntimeLimitGivenrequired
            • sysctls映射，值为stringrequired
            • tmpfs数组，元素为objectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • servers数组，元素为stringrequired
              • search数组，元素为stringrequired
              • options数组，元素为stringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          应用请求的链路追踪包含哪些内容，每一项为给出的值或默认值 (AppTraceSettings)：sample_rate 为 0 时不产生任何 span。

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumes数组，元素为objectrequired

      服务挂载的项目存储卷。

      • modelstring | nullrequired

        它在模型中的名称。null：为有状态服务挂载但未命名卷的路径创建的。

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

        有多个服务挂载它，或者某个服务有多个实例：每个服务的每个实例同时挂载它。

      • statusto_make或made或there或externalrequired

        to_make：导入会创建它（试运行时对将要创建的存储卷这样说明）；made：本次导入创建了它；there：之前的导入创建了它，或者已有同名的存储卷；external：模型把它标为 external，而项目中已有它。

      • used_by数组，元素为stringrequired
    • secrets数组，元素为objectrequired

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

        保存它的项目机密：即模型中的名称，其中机密名称不允许的每个字符都写成下划线。

      • therebooleanrequired

        项目中是否已有它。导入（非试运行）时如果它还不存在，会被拒绝，返回 404 secret_not_found。

      • used_by数组，元素为stringrequired
    • left_out数组，元素为objectrequired

      属于未启用 profile 的服务，导入不会处理它们。

      • namestringrequired
      • profiles数组，元素为stringrequired
    • absent数组，元素为stringrequired

      项目中有而模型中没有的服务：保持原样。

    • deploystring | nullrequired

      导入触发的部署 (GET /v1/deploys/{id})。null：试运行，或者没有服务需要新版本。

      pattern: ^dpl-
  • accountsoptional数组，元素为object

    随 sole_owner 返回：该用户是唯一所有者的那些账户。

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

401

missing_api_key, invalid_api_key, expired_api_key, invalid_token.
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    随 already_moving 返回：该沙箱正在进行的迁移。

  • upgrade_idoptionalstring

    随 upgrade_in_progress（该键尚未结束的升级）、upgrade_started（已开始的升级）和 rollback_gone（回退被拒绝的那次升级）返回：即那次升级。

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    随 move_over、move_going_back 和 move_taken_over 返回 (POST /internal/moves/{id}/cancel)：迁移的当前状态。

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • epochintegerrequired

      迁移开始时表中记录的沙箱纪元：旧节点在这个纪元释放它，新节点在纪元加一时接管它，旧节点在纪元加二时收回它，从对象存储接管则在纪元加三时。

      minimum: 1
    • stepstringrequired

      迁移的进展：releasing（正在请旧节点释放它；表中记录它在旧节点上）、taking_over（正在请新节点接管它；表中记录它在新节点上）、reclaiming（新节点拒绝了它，正在请旧节点收回）、restoring（旧节点没有保留它的任何东西，正从对象存储接管）、done（已在新节点上）、failed（留在原处，或回到了原处，或停在某个时间无法消除的故障或运营方的取消发生时所在的位置：error 说明原因）。

    • whystringrequired

      发起迁移的原因：运营方的迁移、撤离或恢复。

    • wakebooleanrequired

      新节点是否唤醒它：按调用的指定，或按迁移开始时它的状态（是否在运行）。

    • from_storebooleanrequired

      新节点只从对象存储接管它。

    • releaseobject | nullrequired

      旧节点释放时的响应（sandboxd/openapi/openapi.json，releaseSandbox），不含释放所用的密钥；响应之前为 null。

    • takeoverobject | nullrequired

      结束迁移的那次接管的响应（节点文档中的 takeoverSandbox）：磁盘和内存来自哪里 (source)、各用了多长时间 (ms)、memory；之前为 null。

    • errorrequired

      失败的迁移：失败原因（如果被带回旧节点，则为新节点的拒绝原因）；已完成的迁移：null；进行中的迁移：如果当前步骤要再次请求，则为该步骤上次得到的答复。

      以下之一：

      • object
      • null
    • attemptsintegerrequired

      当前步骤已请求了多少次，仍没有得到确定的答复。

      minimum: 0
    • next_attempt_atstring | nullrequired

      该步骤何时再次请求；不在等待时为 null。

      format: date-time
    • batchstring | nullrequired

      它所属的撤离 (evc-…) 或恢复 (rcv-…)。

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    随 lease_held 返回：节点最后获得的租约最晚可以持有到何时，再加上让节点察觉租约到期所需的时间（在此之前 recoverNode 会被拒绝）。

    format: date-time
  • activeoptionalobject | null

    随 standby 返回：备用副本最后一次读取租约时的活动副本；没有副本持有租约时为 null。

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null（节点的 SecretHosts）。

  • problemsoptional数组，元素为object

    随 invalid_definition 返回：定义中的每个问题，各附其位置和内容。

    • atstringrequired

      在定义中的位置，用点分隔的路径 (services.web.port)；针对整个定义时为空。

    • messagestringrequired
  • reportoptionalobject

    随 compose_refused 返回：导入的报告，说明拒绝了什么、为什么以及要改什么。

    • objectcompose_importrequired
    • namestring | nullrequired

      模型的 name：即每个服务的标签 compose.project。null：模型没有名称。

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profiles数组，元素为stringrequired
    • treatmentsobjectrequired

      报告中每种处理方式各有多少项。

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • items数组，元素为objectrequired

      模型的顶层元素：name，以及每个卷、网络、config、secret 和扩展。

      • atstringrequired

        在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

      • treatmentdone或adapted或ignored或refusedrequired

        done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

      • whystringrequired
      • changestring | nullrequired

        被拒绝的项：要改什么。其他情况为 null。

    • services数组，元素为objectrequired

      导入所采纳的服务，按模型中的顺序。

      • namestringrequired

        服务的名称，也是其应用的名称。

      • app_idstring | nullrequired

        其应用。null：试运行，且项目中没有该服务。

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

        导入对其应用做了（试运行时为将会做）什么：创建、写入变化的部分，或什么都不做。

      • kindservice或jobrequired

        job：模型中有服务等待它完成，它会在每次需要它的部署中运行到结束。

      • statefulbooleanrequired

        它挂载自己的存储卷：只有一个实例，由该实例持有存储卷。

      • versionbooleanrequired

        导入的部署是否为它创建版本：即解析引用后其版本的构成与当前版本不同。

      • items数组，元素为objectrequired
        • atstringrequired

          在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

        • treatmentdone或adapted或ignored或refusedrequired

          done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

        • whystringrequired
        • changestring | nullrequired

          被拒绝的项：要改什么。其他情况为 null。

      • appobjectrequired

        导入写入的服务应用字段：其版本的构成，以及立即生效的设置。

        • imagestring | nullrequired

          应用下一个版本的构成，连同其后的七个字段：即其最新版本的构成，加上此后的修改。null：应用没有镜像，也没有版本。

        • image_pull_secretstring | nullrequired

          保存镜像仓库凭据的机密的名称。任何响应都不包含其值。null：没有。

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

          放在镜像 ENTRYPOINT 之后、取代其 CMD 的内容。null：使用镜像的 CMD，或者整个 start_command。

          以下之一：

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          判断实例已启动的方式，版本的模板会在实例启动后保存：三者必须恰好给出一个。前两种从实例外部检查，所以服务必须监听所有地址 (0.0.0.0)。

          • httpoptionalstring

            一个以 / 开头的路径：在应用端口上对它发起 GET，返回 200 到 399 之间的状态码。

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

            在实例中执行成功的一条命令。由实例的 shell 运行：参数列表会被写成一行交给它。

            以下之一：

            • string
            • array<string>
        • env映射，值为stringrequired
        • secrets映射，值为stringrequired

          机密的名称。任何响应都不包含值。

        • sizeobjectrequired

          单个实例最多能使用的资源。按实际用量计费。

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            偶数个 MiB（即节点为虚拟机加载内存所用的 2 MiB 页的整数倍），以字节表示。其他任何大小都返回 400 invalid_field（param 为 size.memory_bytes）：没有节点会创建这种大小的实例，正如没有节点会创建这种大小的沙箱（节点的 SandboxLimitsCreate.memory_bytes）。

            minimum: 134217728
        • volumes数组，元素为objectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • kindstringrequired
        • files数组，元素为objectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          以下之一：

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regions数组，元素为stringrequired

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

            无论有没有请求，应用在一个区域内保持运行的实例数：即下限。该区域服务该应用的节点按分摊 max_instances 的方式分摊它（两个节点、下限为 2：各一个；下限为 1：一个，在最先尝试的节点上；下限为 5：三个和两个），不在线的节点由其他节点补足。节点在收到通知时就创建自己那部分，而不是等到第一个请求，也不会因为空闲而停止或删除这些实例；它们按运行中的实例计量。0（未设置时的值）：没有下限。调低后，超出部分的实例从那一刻起视为空闲，并像空闲实例一样被停止和删除。最多为 max_instances（如果给出），且不超过账户套餐允许应用在一个区域请求的数量（caps.app_instances.limit：5、50 和 500）：超出会被拒绝，返回 403 plan_cap_reached。

            minimum: 0
          • max_instancesinteger | nullrequired

            应用在一个区域内最多有多少个实例：由该区域服务该应用的节点分摊。最多为账户套餐允许应用请求的数量（caps.app_instances.limit：免费版 5，付费版 500）：超出会被拒绝，返回 403 plan_cap_reached；在允许的套餐上请求的数值会保留，但受当前套餐数值的限制。null：未指定数量的应用使用套餐的数值（caps.app_instances.default：免费版 2，付费版 50），如果 min_instances 更大则用它。告诉节点的数值，不超过账户除其他运行中资源外还能容纳的运行量，也不少于应用当前运行的实例数。

            minimum: 1
          • concurrencyinteger | nullrequired

            单个实例同时处理的上限：边缘节点发给它的请求，加上它在项目网络上打开的连接（经由其服务的地址，节点会按连接把它们分给各个实例；或者直接连到它自己的地址）。达到上限的实例即为已满，更多的请求会创建新实例。null（未设置时的值）：没有上限。此时节点会在现有实例的 CPU 或内存接近其规格时增加实例，应用不必猜一个数字；一次只处理一个请求的服务应设为 1。

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            实例在没有请求时最多等待多久就停止，单位为毫秒。在这个上限以内，节点根据应用自己的流量选择等待时间：在应用最近一段时间里两次请求之间的间隔上，比较多运行一秒空闲与停止再恢复所花的 CPU 时间，选出成本最低的等待时间；这样，请求间隔比停止成本还短的应用会一直运行，请求间隔很长的应用则在最后一个响应结束后立即停止（0：总是立即停止）。null（未设置时的值）：平台的上限，三秒。设置过 100（2026年10月28日之前的默认值）的应用，从那天起视为 null。持续停止的实例会在 delete_after_ms 后被其节点删除，下一个需要实例的请求会得到一个新实例；min_instances 保持运行的实例既不会停止也不会删除。

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            在实例因空闲而停止之前多久，向连接到其客户机 /run/sbx/awake 的程序发送一行 sleep N，单位为毫秒：程序可以借此写出手头的数据、关闭连接，或者发起保持，从而推迟停止。无论它们是否响应，停止都会在这段时间之后到来；没有程序连接时，不会推迟。键控实例也会收到通知。0 或 null：不通知（默认）。

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            实例中的程序发起的保持，在空闲时间到期后最多还能让实例运行多久，单位为毫秒：程序连接 /run/sbx/awake，如果某个请求在响应之后还有后续工作，就在响应它之前发送 +，工作完成后发送 -（或关闭连接，或退出）；最后一个保持解除 sleep_after_ms 之后，实例停止。超过这个时间，无论有什么保持，实例都会停止；如果 sleep_notice_ms 要求通知，会先向已连接的程序发送 sleep N cap。保持期间实例在运行，并按运行计量。0：不理会保持。null：30000（默认）。

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            实例空闲多久后被删除，与停止使用同一个起算点：下一个需要实例的请求会得到一个新实例，即版本模板的克隆，不含被删除的实例在内存和磁盘中积累的东西（需要长久保存的数据请放在存储卷或数据库中）。一秒到一小时，一小时是平台的时间，也是上限：超出会被拒绝 (400 invalid_field)，需要保持预热的实例应计入 min_instances。null（未设置时的值）：节点的一小时 (--app-delete-after-seconds)。修改对应用现有的实例和之后创建的实例同样有效：每个节点至少每秒按应用当前的时间检查一次每个实例。不适用于应用的键控实例，键控实例用 keys.delete_after_idle_ms。

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            已停止的实例在保存内存并真正休眠之前保持暂停多久，单位为毫秒：暂停时，下一个请求在一两毫秒内得到响应，内存照常计量；休眠时，唤醒要多几毫秒，只计量它保存的数据。节点会把它限制在节点让任何实例保持暂停的最长时间内（十分钟）；宿主机内存不足、其他虚拟机需要占用槽位，或者有人请求休眠，都会让它更早休眠。null（默认）：节点的最长时间。数据库的 suspend_after_seconds 就是其应用的这一设置。

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            每天的某个 UTC 时刻 (HH:MM)，在此时唤醒应用中处于休眠状态的键控实例和有状态服务的实例，让它们完成等待唤醒才能做的工作（比如数据库维护）；节点根据应用请求创建和删除的实例只会被请求唤醒。唤醒本身不算活动：唤醒后运行的东西才算，运行完毕后实例会再次休眠。此外，无论这里怎么设置，有状态服务的实例都会为其 PostgreSQL 服务器 pg_cron 任务的下一次运行而被唤醒。null（默认）：不唤醒。数据库的 wake_daily_at 就是其应用的这一设置。

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          以下之一：

          • object
          • null
        • egressobject | nullrequired

          与沙箱相同的出站规则（default、allow、deny、http、inject），没有时为 null；按调用给出的原样保存（PATCH 会像节点那样按键逐个合并）。规则立即生效，不产生新版本：服务该应用的节点会把它们应用到其组内的每个实例上，包括现有的实例（运行中的实例对其已有连接也生效）和之后创建的实例；键控实例不受这些规则约束。控制平面只检查它们是不是由这些键组成、不超过 256 KiB 的对象：规则的内容由节点在应用时检查，节点读不懂其规则的实例，所有出站流量都会被拒绝（节点日志会说明原因）。

          • defaultoptionalallow或deny或null
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            任何连接都到达不了的端口，TCP 或 UDP，无论连往哪里，也无论规则的其他部分怎么说。浏览器会话的规则总是包含 25、465、587 以及矿池监听的端口（3333、4444、5555、7777、14444、45700）：无论其规则如何修改，控制平面都会把它们加上。

        • metadata映射，值为stringrequired
        • logsobjectrequired

          应用日志包含哪些内容，每一项为给出的值或默认值 (AppLogSettings)。

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          是否在其默认域名 (url) 上响应。

        • depends_on数组，元素为objectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliases数组，元素为stringrequired
          • endpoint_modestringrequired
        • drivesoptional数组，元素为object

          其实例挂载的云盘 (AppCreate.drives)：没有指定时为空列表 []。

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptional数组，元素为object

          每个键的实例自有的云盘 (AppCreate.key_drives)：没有给出时为空列表 []。

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • runtimeoptional

          运行时设置 (AppCreate.runtime)。null：没有。

          以下之一：

          • Runtime
            • ulimits映射，值为RuntimeLimitGivenrequired
            • sysctls映射，值为stringrequired
            • tmpfs数组，元素为objectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • servers数组，元素为stringrequired
              • search数组，元素为stringrequired
              • options数组，元素为stringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          应用请求的链路追踪包含哪些内容，每一项为给出的值或默认值 (AppTraceSettings)：sample_rate 为 0 时不产生任何 span。

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumes数组，元素为objectrequired

      服务挂载的项目存储卷。

      • modelstring | nullrequired

        它在模型中的名称。null：为有状态服务挂载但未命名卷的路径创建的。

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

        有多个服务挂载它，或者某个服务有多个实例：每个服务的每个实例同时挂载它。

      • statusto_make或made或there或externalrequired

        to_make：导入会创建它（试运行时对将要创建的存储卷这样说明）；made：本次导入创建了它；there：之前的导入创建了它，或者已有同名的存储卷；external：模型把它标为 external，而项目中已有它。

      • used_by数组，元素为stringrequired
    • secrets数组，元素为objectrequired

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

        保存它的项目机密：即模型中的名称，其中机密名称不允许的每个字符都写成下划线。

      • therebooleanrequired

        项目中是否已有它。导入（非试运行）时如果它还不存在，会被拒绝，返回 404 secret_not_found。

      • used_by数组，元素为stringrequired
    • left_out数组，元素为objectrequired

      属于未启用 profile 的服务，导入不会处理它们。

      • namestringrequired
      • profiles数组，元素为stringrequired
    • absent数组，元素为stringrequired

      项目中有而模型中没有的服务：保持原样。

    • deploystring | nullrequired

      导入触发的部署 (GET /v1/deploys/{id})。null：试运行，或者没有服务需要新版本。

      pattern: ^dpl-
  • accountsoptional数组，元素为object

    随 sole_owner 返回：该用户是唯一所有者的那些账户。

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

403

key_scope：密钥没有调用所需的权限范围（错误信息会指明是哪一个）；needs_api_key：使用的是运营方的密钥或 SSH 网关的密钥；account_held：账户因付款问题被冻结，除 GET /v1/account 外，用它的密钥发起的所有调用都会这样被拒绝，而且在检查权限范围之前就拒绝 (x-error-codes)；installation_key_scope：限定于某个托管应用安装的密钥，用在了与该安装自身无关的调用上。（沙箱令牌会被转给其节点，节点对它没有的调用返回 404 no_such_route。）
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    随 already_moving 返回：该沙箱正在进行的迁移。

  • upgrade_idoptionalstring

    随 upgrade_in_progress（该键尚未结束的升级）、upgrade_started（已开始的升级）和 rollback_gone（回退被拒绝的那次升级）返回：即那次升级。

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    随 move_over、move_going_back 和 move_taken_over 返回 (POST /internal/moves/{id}/cancel)：迁移的当前状态。

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • epochintegerrequired

      迁移开始时表中记录的沙箱纪元：旧节点在这个纪元释放它，新节点在纪元加一时接管它，旧节点在纪元加二时收回它，从对象存储接管则在纪元加三时。

      minimum: 1
    • stepstringrequired

      迁移的进展：releasing（正在请旧节点释放它；表中记录它在旧节点上）、taking_over（正在请新节点接管它；表中记录它在新节点上）、reclaiming（新节点拒绝了它，正在请旧节点收回）、restoring（旧节点没有保留它的任何东西，正从对象存储接管）、done（已在新节点上）、failed（留在原处，或回到了原处，或停在某个时间无法消除的故障或运营方的取消发生时所在的位置：error 说明原因）。

    • whystringrequired

      发起迁移的原因：运营方的迁移、撤离或恢复。

    • wakebooleanrequired

      新节点是否唤醒它：按调用的指定，或按迁移开始时它的状态（是否在运行）。

    • from_storebooleanrequired

      新节点只从对象存储接管它。

    • releaseobject | nullrequired

      旧节点释放时的响应（sandboxd/openapi/openapi.json，releaseSandbox），不含释放所用的密钥；响应之前为 null。

    • takeoverobject | nullrequired

      结束迁移的那次接管的响应（节点文档中的 takeoverSandbox）：磁盘和内存来自哪里 (source)、各用了多长时间 (ms)、memory；之前为 null。

    • errorrequired

      失败的迁移：失败原因（如果被带回旧节点，则为新节点的拒绝原因）；已完成的迁移：null；进行中的迁移：如果当前步骤要再次请求，则为该步骤上次得到的答复。

      以下之一：

      • object
      • null
    • attemptsintegerrequired

      当前步骤已请求了多少次，仍没有得到确定的答复。

      minimum: 0
    • next_attempt_atstring | nullrequired

      该步骤何时再次请求；不在等待时为 null。

      format: date-time
    • batchstring | nullrequired

      它所属的撤离 (evc-…) 或恢复 (rcv-…)。

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    随 lease_held 返回：节点最后获得的租约最晚可以持有到何时，再加上让节点察觉租约到期所需的时间（在此之前 recoverNode 会被拒绝）。

    format: date-time
  • activeoptionalobject | null

    随 standby 返回：备用副本最后一次读取租约时的活动副本；没有副本持有租约时为 null。

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null（节点的 SecretHosts）。

  • problemsoptional数组，元素为object

    随 invalid_definition 返回：定义中的每个问题，各附其位置和内容。

    • atstringrequired

      在定义中的位置，用点分隔的路径 (services.web.port)；针对整个定义时为空。

    • messagestringrequired
  • reportoptionalobject

    随 compose_refused 返回：导入的报告，说明拒绝了什么、为什么以及要改什么。

    • objectcompose_importrequired
    • namestring | nullrequired

      模型的 name：即每个服务的标签 compose.project。null：模型没有名称。

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profiles数组，元素为stringrequired
    • treatmentsobjectrequired

      报告中每种处理方式各有多少项。

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • items数组，元素为objectrequired

      模型的顶层元素：name，以及每个卷、网络、config、secret 和扩展。

      • atstringrequired

        在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

      • treatmentdone或adapted或ignored或refusedrequired

        done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

      • whystringrequired
      • changestring | nullrequired

        被拒绝的项：要改什么。其他情况为 null。

    • services数组，元素为objectrequired

      导入所采纳的服务，按模型中的顺序。

      • namestringrequired

        服务的名称，也是其应用的名称。

      • app_idstring | nullrequired

        其应用。null：试运行，且项目中没有该服务。

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

        导入对其应用做了（试运行时为将会做）什么：创建、写入变化的部分，或什么都不做。

      • kindservice或jobrequired

        job：模型中有服务等待它完成，它会在每次需要它的部署中运行到结束。

      • statefulbooleanrequired

        它挂载自己的存储卷：只有一个实例，由该实例持有存储卷。

      • versionbooleanrequired

        导入的部署是否为它创建版本：即解析引用后其版本的构成与当前版本不同。

      • items数组，元素为objectrequired
        • atstringrequired

          在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

        • treatmentdone或adapted或ignored或refusedrequired

          done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

        • whystringrequired
        • changestring | nullrequired

          被拒绝的项：要改什么。其他情况为 null。

      • appobjectrequired

        导入写入的服务应用字段：其版本的构成，以及立即生效的设置。

        • imagestring | nullrequired

          应用下一个版本的构成，连同其后的七个字段：即其最新版本的构成，加上此后的修改。null：应用没有镜像，也没有版本。

        • image_pull_secretstring | nullrequired

          保存镜像仓库凭据的机密的名称。任何响应都不包含其值。null：没有。

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

          放在镜像 ENTRYPOINT 之后、取代其 CMD 的内容。null：使用镜像的 CMD，或者整个 start_command。

          以下之一：

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          判断实例已启动的方式，版本的模板会在实例启动后保存：三者必须恰好给出一个。前两种从实例外部检查，所以服务必须监听所有地址 (0.0.0.0)。

          • httpoptionalstring

            一个以 / 开头的路径：在应用端口上对它发起 GET，返回 200 到 399 之间的状态码。

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

            在实例中执行成功的一条命令。由实例的 shell 运行：参数列表会被写成一行交给它。

            以下之一：

            • string
            • array<string>
        • env映射，值为stringrequired
        • secrets映射，值为stringrequired

          机密的名称。任何响应都不包含值。

        • sizeobjectrequired

          单个实例最多能使用的资源。按实际用量计费。

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            偶数个 MiB（即节点为虚拟机加载内存所用的 2 MiB 页的整数倍），以字节表示。其他任何大小都返回 400 invalid_field（param 为 size.memory_bytes）：没有节点会创建这种大小的实例，正如没有节点会创建这种大小的沙箱（节点的 SandboxLimitsCreate.memory_bytes）。

            minimum: 134217728
        • volumes数组，元素为objectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • kindstringrequired
        • files数组，元素为objectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          以下之一：

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regions数组，元素为stringrequired

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

            无论有没有请求，应用在一个区域内保持运行的实例数：即下限。该区域服务该应用的节点按分摊 max_instances 的方式分摊它（两个节点、下限为 2：各一个；下限为 1：一个，在最先尝试的节点上；下限为 5：三个和两个），不在线的节点由其他节点补足。节点在收到通知时就创建自己那部分，而不是等到第一个请求，也不会因为空闲而停止或删除这些实例；它们按运行中的实例计量。0（未设置时的值）：没有下限。调低后，超出部分的实例从那一刻起视为空闲，并像空闲实例一样被停止和删除。最多为 max_instances（如果给出），且不超过账户套餐允许应用在一个区域请求的数量（caps.app_instances.limit：5、50 和 500）：超出会被拒绝，返回 403 plan_cap_reached。

            minimum: 0
          • max_instancesinteger | nullrequired

            应用在一个区域内最多有多少个实例：由该区域服务该应用的节点分摊。最多为账户套餐允许应用请求的数量（caps.app_instances.limit：免费版 5，付费版 500）：超出会被拒绝，返回 403 plan_cap_reached；在允许的套餐上请求的数值会保留，但受当前套餐数值的限制。null：未指定数量的应用使用套餐的数值（caps.app_instances.default：免费版 2，付费版 50），如果 min_instances 更大则用它。告诉节点的数值，不超过账户除其他运行中资源外还能容纳的运行量，也不少于应用当前运行的实例数。

            minimum: 1
          • concurrencyinteger | nullrequired

            单个实例同时处理的上限：边缘节点发给它的请求，加上它在项目网络上打开的连接（经由其服务的地址，节点会按连接把它们分给各个实例；或者直接连到它自己的地址）。达到上限的实例即为已满，更多的请求会创建新实例。null（未设置时的值）：没有上限。此时节点会在现有实例的 CPU 或内存接近其规格时增加实例，应用不必猜一个数字；一次只处理一个请求的服务应设为 1。

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            实例在没有请求时最多等待多久就停止，单位为毫秒。在这个上限以内，节点根据应用自己的流量选择等待时间：在应用最近一段时间里两次请求之间的间隔上，比较多运行一秒空闲与停止再恢复所花的 CPU 时间，选出成本最低的等待时间；这样，请求间隔比停止成本还短的应用会一直运行，请求间隔很长的应用则在最后一个响应结束后立即停止（0：总是立即停止）。null（未设置时的值）：平台的上限，三秒。设置过 100（2026年10月28日之前的默认值）的应用，从那天起视为 null。持续停止的实例会在 delete_after_ms 后被其节点删除，下一个需要实例的请求会得到一个新实例；min_instances 保持运行的实例既不会停止也不会删除。

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            在实例因空闲而停止之前多久，向连接到其客户机 /run/sbx/awake 的程序发送一行 sleep N，单位为毫秒：程序可以借此写出手头的数据、关闭连接，或者发起保持，从而推迟停止。无论它们是否响应，停止都会在这段时间之后到来；没有程序连接时，不会推迟。键控实例也会收到通知。0 或 null：不通知（默认）。

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            实例中的程序发起的保持，在空闲时间到期后最多还能让实例运行多久，单位为毫秒：程序连接 /run/sbx/awake，如果某个请求在响应之后还有后续工作，就在响应它之前发送 +，工作完成后发送 -（或关闭连接，或退出）；最后一个保持解除 sleep_after_ms 之后，实例停止。超过这个时间，无论有什么保持，实例都会停止；如果 sleep_notice_ms 要求通知，会先向已连接的程序发送 sleep N cap。保持期间实例在运行，并按运行计量。0：不理会保持。null：30000（默认）。

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            实例空闲多久后被删除，与停止使用同一个起算点：下一个需要实例的请求会得到一个新实例，即版本模板的克隆，不含被删除的实例在内存和磁盘中积累的东西（需要长久保存的数据请放在存储卷或数据库中）。一秒到一小时，一小时是平台的时间，也是上限：超出会被拒绝 (400 invalid_field)，需要保持预热的实例应计入 min_instances。null（未设置时的值）：节点的一小时 (--app-delete-after-seconds)。修改对应用现有的实例和之后创建的实例同样有效：每个节点至少每秒按应用当前的时间检查一次每个实例。不适用于应用的键控实例，键控实例用 keys.delete_after_idle_ms。

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            已停止的实例在保存内存并真正休眠之前保持暂停多久，单位为毫秒：暂停时，下一个请求在一两毫秒内得到响应，内存照常计量；休眠时，唤醒要多几毫秒，只计量它保存的数据。节点会把它限制在节点让任何实例保持暂停的最长时间内（十分钟）；宿主机内存不足、其他虚拟机需要占用槽位，或者有人请求休眠，都会让它更早休眠。null（默认）：节点的最长时间。数据库的 suspend_after_seconds 就是其应用的这一设置。

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            每天的某个 UTC 时刻 (HH:MM)，在此时唤醒应用中处于休眠状态的键控实例和有状态服务的实例，让它们完成等待唤醒才能做的工作（比如数据库维护）；节点根据应用请求创建和删除的实例只会被请求唤醒。唤醒本身不算活动：唤醒后运行的东西才算，运行完毕后实例会再次休眠。此外，无论这里怎么设置，有状态服务的实例都会为其 PostgreSQL 服务器 pg_cron 任务的下一次运行而被唤醒。null（默认）：不唤醒。数据库的 wake_daily_at 就是其应用的这一设置。

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          以下之一：

          • object
          • null
        • egressobject | nullrequired

          与沙箱相同的出站规则（default、allow、deny、http、inject），没有时为 null；按调用给出的原样保存（PATCH 会像节点那样按键逐个合并）。规则立即生效，不产生新版本：服务该应用的节点会把它们应用到其组内的每个实例上，包括现有的实例（运行中的实例对其已有连接也生效）和之后创建的实例；键控实例不受这些规则约束。控制平面只检查它们是不是由这些键组成、不超过 256 KiB 的对象：规则的内容由节点在应用时检查，节点读不懂其规则的实例，所有出站流量都会被拒绝（节点日志会说明原因）。

          • defaultoptionalallow或deny或null
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            任何连接都到达不了的端口，TCP 或 UDP，无论连往哪里，也无论规则的其他部分怎么说。浏览器会话的规则总是包含 25、465、587 以及矿池监听的端口（3333、4444、5555、7777、14444、45700）：无论其规则如何修改，控制平面都会把它们加上。

        • metadata映射，值为stringrequired
        • logsobjectrequired

          应用日志包含哪些内容，每一项为给出的值或默认值 (AppLogSettings)。

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          是否在其默认域名 (url) 上响应。

        • depends_on数组，元素为objectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliases数组，元素为stringrequired
          • endpoint_modestringrequired
        • drivesoptional数组，元素为object

          其实例挂载的云盘 (AppCreate.drives)：没有指定时为空列表 []。

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptional数组，元素为object

          每个键的实例自有的云盘 (AppCreate.key_drives)：没有给出时为空列表 []。

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • runtimeoptional

          运行时设置 (AppCreate.runtime)。null：没有。

          以下之一：

          • Runtime
            • ulimits映射，值为RuntimeLimitGivenrequired
            • sysctls映射，值为stringrequired
            • tmpfs数组，元素为objectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • servers数组，元素为stringrequired
              • search数组，元素为stringrequired
              • options数组，元素为stringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          应用请求的链路追踪包含哪些内容，每一项为给出的值或默认值 (AppTraceSettings)：sample_rate 为 0 时不产生任何 span。

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumes数组，元素为objectrequired

      服务挂载的项目存储卷。

      • modelstring | nullrequired

        它在模型中的名称。null：为有状态服务挂载但未命名卷的路径创建的。

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

        有多个服务挂载它，或者某个服务有多个实例：每个服务的每个实例同时挂载它。

      • statusto_make或made或there或externalrequired

        to_make：导入会创建它（试运行时对将要创建的存储卷这样说明）；made：本次导入创建了它；there：之前的导入创建了它，或者已有同名的存储卷；external：模型把它标为 external，而项目中已有它。

      • used_by数组，元素为stringrequired
    • secrets数组，元素为objectrequired

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

        保存它的项目机密：即模型中的名称，其中机密名称不允许的每个字符都写成下划线。

      • therebooleanrequired

        项目中是否已有它。导入（非试运行）时如果它还不存在，会被拒绝，返回 404 secret_not_found。

      • used_by数组，元素为stringrequired
    • left_out数组，元素为objectrequired

      属于未启用 profile 的服务，导入不会处理它们。

      • namestringrequired
      • profiles数组，元素为stringrequired
    • absent数组，元素为stringrequired

      项目中有而模型中没有的服务：保持原样。

    • deploystring | nullrequired

      导入触发的部署 (GET /v1/deploys/{id})。null：试运行，或者没有服务需要新版本。

      pattern: ^dpl-
  • accountsoptional数组，元素为object

    随 sole_owner 返回：该用户是唯一所有者的那些账户。

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

429

report_in_progress：同一项目的另一份报告在 2 秒后仍在生成。可重试 (retryable)。
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    随 already_moving 返回：该沙箱正在进行的迁移。

  • upgrade_idoptionalstring

    随 upgrade_in_progress（该键尚未结束的升级）、upgrade_started（已开始的升级）和 rollback_gone（回退被拒绝的那次升级）返回：即那次升级。

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    随 move_over、move_going_back 和 move_taken_over 返回 (POST /internal/moves/{id}/cancel)：迁移的当前状态。

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • epochintegerrequired

      迁移开始时表中记录的沙箱纪元：旧节点在这个纪元释放它，新节点在纪元加一时接管它，旧节点在纪元加二时收回它，从对象存储接管则在纪元加三时。

      minimum: 1
    • stepstringrequired

      迁移的进展：releasing（正在请旧节点释放它；表中记录它在旧节点上）、taking_over（正在请新节点接管它；表中记录它在新节点上）、reclaiming（新节点拒绝了它，正在请旧节点收回）、restoring（旧节点没有保留它的任何东西，正从对象存储接管）、done（已在新节点上）、failed（留在原处，或回到了原处，或停在某个时间无法消除的故障或运营方的取消发生时所在的位置：error 说明原因）。

    • whystringrequired

      发起迁移的原因：运营方的迁移、撤离或恢复。

    • wakebooleanrequired

      新节点是否唤醒它：按调用的指定，或按迁移开始时它的状态（是否在运行）。

    • from_storebooleanrequired

      新节点只从对象存储接管它。

    • releaseobject | nullrequired

      旧节点释放时的响应（sandboxd/openapi/openapi.json，releaseSandbox），不含释放所用的密钥；响应之前为 null。

    • takeoverobject | nullrequired

      结束迁移的那次接管的响应（节点文档中的 takeoverSandbox）：磁盘和内存来自哪里 (source)、各用了多长时间 (ms)、memory；之前为 null。

    • errorrequired

      失败的迁移：失败原因（如果被带回旧节点，则为新节点的拒绝原因）；已完成的迁移：null；进行中的迁移：如果当前步骤要再次请求，则为该步骤上次得到的答复。

      以下之一：

      • object
      • null
    • attemptsintegerrequired

      当前步骤已请求了多少次，仍没有得到确定的答复。

      minimum: 0
    • next_attempt_atstring | nullrequired

      该步骤何时再次请求；不在等待时为 null。

      format: date-time
    • batchstring | nullrequired

      它所属的撤离 (evc-…) 或恢复 (rcv-…)。

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    随 lease_held 返回：节点最后获得的租约最晚可以持有到何时，再加上让节点察觉租约到期所需的时间（在此之前 recoverNode 会被拒绝）。

    format: date-time
  • activeoptionalobject | null

    随 standby 返回：备用副本最后一次读取租约时的活动副本；没有副本持有租约时为 null。

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null（节点的 SecretHosts）。

  • problemsoptional数组，元素为object

    随 invalid_definition 返回：定义中的每个问题，各附其位置和内容。

    • atstringrequired

      在定义中的位置，用点分隔的路径 (services.web.port)；针对整个定义时为空。

    • messagestringrequired
  • reportoptionalobject

    随 compose_refused 返回：导入的报告，说明拒绝了什么、为什么以及要改什么。

    • objectcompose_importrequired
    • namestring | nullrequired

      模型的 name：即每个服务的标签 compose.project。null：模型没有名称。

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profiles数组，元素为stringrequired
    • treatmentsobjectrequired

      报告中每种处理方式各有多少项。

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • items数组，元素为objectrequired

      模型的顶层元素：name，以及每个卷、网络、config、secret 和扩展。

      • atstringrequired

        在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

      • treatmentdone或adapted或ignored或refusedrequired

        done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

      • whystringrequired
      • changestring | nullrequired

        被拒绝的项：要改什么。其他情况为 null。

    • services数组，元素为objectrequired

      导入所采纳的服务，按模型中的顺序。

      • namestringrequired

        服务的名称，也是其应用的名称。

      • app_idstring | nullrequired

        其应用。null：试运行，且项目中没有该服务。

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

        导入对其应用做了（试运行时为将会做）什么：创建、写入变化的部分，或什么都不做。

      • kindservice或jobrequired

        job：模型中有服务等待它完成，它会在每次需要它的部署中运行到结束。

      • statefulbooleanrequired

        它挂载自己的存储卷：只有一个实例，由该实例持有存储卷。

      • versionbooleanrequired

        导入的部署是否为它创建版本：即解析引用后其版本的构成与当前版本不同。

      • items数组，元素为objectrequired
        • atstringrequired

          在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

        • treatmentdone或adapted或ignored或refusedrequired

          done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

        • whystringrequired
        • changestring | nullrequired

          被拒绝的项：要改什么。其他情况为 null。

      • appobjectrequired

        导入写入的服务应用字段：其版本的构成，以及立即生效的设置。

        • imagestring | nullrequired

          应用下一个版本的构成，连同其后的七个字段：即其最新版本的构成，加上此后的修改。null：应用没有镜像，也没有版本。

        • image_pull_secretstring | nullrequired

          保存镜像仓库凭据的机密的名称。任何响应都不包含其值。null：没有。

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

          放在镜像 ENTRYPOINT 之后、取代其 CMD 的内容。null：使用镜像的 CMD，或者整个 start_command。

          以下之一：

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          判断实例已启动的方式，版本的模板会在实例启动后保存：三者必须恰好给出一个。前两种从实例外部检查，所以服务必须监听所有地址 (0.0.0.0)。

          • httpoptionalstring

            一个以 / 开头的路径：在应用端口上对它发起 GET，返回 200 到 399 之间的状态码。

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

            在实例中执行成功的一条命令。由实例的 shell 运行：参数列表会被写成一行交给它。

            以下之一：

            • string
            • array<string>
        • env映射，值为stringrequired
        • secrets映射，值为stringrequired

          机密的名称。任何响应都不包含值。

        • sizeobjectrequired

          单个实例最多能使用的资源。按实际用量计费。

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            偶数个 MiB（即节点为虚拟机加载内存所用的 2 MiB 页的整数倍），以字节表示。其他任何大小都返回 400 invalid_field（param 为 size.memory_bytes）：没有节点会创建这种大小的实例，正如没有节点会创建这种大小的沙箱（节点的 SandboxLimitsCreate.memory_bytes）。

            minimum: 134217728
        • volumes数组，元素为objectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • kindstringrequired
        • files数组，元素为objectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          以下之一：

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regions数组，元素为stringrequired

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

            无论有没有请求，应用在一个区域内保持运行的实例数：即下限。该区域服务该应用的节点按分摊 max_instances 的方式分摊它（两个节点、下限为 2：各一个；下限为 1：一个，在最先尝试的节点上；下限为 5：三个和两个），不在线的节点由其他节点补足。节点在收到通知时就创建自己那部分，而不是等到第一个请求，也不会因为空闲而停止或删除这些实例；它们按运行中的实例计量。0（未设置时的值）：没有下限。调低后，超出部分的实例从那一刻起视为空闲，并像空闲实例一样被停止和删除。最多为 max_instances（如果给出），且不超过账户套餐允许应用在一个区域请求的数量（caps.app_instances.limit：5、50 和 500）：超出会被拒绝，返回 403 plan_cap_reached。

            minimum: 0
          • max_instancesinteger | nullrequired

            应用在一个区域内最多有多少个实例：由该区域服务该应用的节点分摊。最多为账户套餐允许应用请求的数量（caps.app_instances.limit：免费版 5，付费版 500）：超出会被拒绝，返回 403 plan_cap_reached；在允许的套餐上请求的数值会保留，但受当前套餐数值的限制。null：未指定数量的应用使用套餐的数值（caps.app_instances.default：免费版 2，付费版 50），如果 min_instances 更大则用它。告诉节点的数值，不超过账户除其他运行中资源外还能容纳的运行量，也不少于应用当前运行的实例数。

            minimum: 1
          • concurrencyinteger | nullrequired

            单个实例同时处理的上限：边缘节点发给它的请求，加上它在项目网络上打开的连接（经由其服务的地址，节点会按连接把它们分给各个实例；或者直接连到它自己的地址）。达到上限的实例即为已满，更多的请求会创建新实例。null（未设置时的值）：没有上限。此时节点会在现有实例的 CPU 或内存接近其规格时增加实例，应用不必猜一个数字；一次只处理一个请求的服务应设为 1。

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            实例在没有请求时最多等待多久就停止，单位为毫秒。在这个上限以内，节点根据应用自己的流量选择等待时间：在应用最近一段时间里两次请求之间的间隔上，比较多运行一秒空闲与停止再恢复所花的 CPU 时间，选出成本最低的等待时间；这样，请求间隔比停止成本还短的应用会一直运行，请求间隔很长的应用则在最后一个响应结束后立即停止（0：总是立即停止）。null（未设置时的值）：平台的上限，三秒。设置过 100（2026年10月28日之前的默认值）的应用，从那天起视为 null。持续停止的实例会在 delete_after_ms 后被其节点删除，下一个需要实例的请求会得到一个新实例；min_instances 保持运行的实例既不会停止也不会删除。

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            在实例因空闲而停止之前多久，向连接到其客户机 /run/sbx/awake 的程序发送一行 sleep N，单位为毫秒：程序可以借此写出手头的数据、关闭连接，或者发起保持，从而推迟停止。无论它们是否响应，停止都会在这段时间之后到来；没有程序连接时，不会推迟。键控实例也会收到通知。0 或 null：不通知（默认）。

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            实例中的程序发起的保持，在空闲时间到期后最多还能让实例运行多久，单位为毫秒：程序连接 /run/sbx/awake，如果某个请求在响应之后还有后续工作，就在响应它之前发送 +，工作完成后发送 -（或关闭连接，或退出）；最后一个保持解除 sleep_after_ms 之后，实例停止。超过这个时间，无论有什么保持，实例都会停止；如果 sleep_notice_ms 要求通知，会先向已连接的程序发送 sleep N cap。保持期间实例在运行，并按运行计量。0：不理会保持。null：30000（默认）。

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            实例空闲多久后被删除，与停止使用同一个起算点：下一个需要实例的请求会得到一个新实例，即版本模板的克隆，不含被删除的实例在内存和磁盘中积累的东西（需要长久保存的数据请放在存储卷或数据库中）。一秒到一小时，一小时是平台的时间，也是上限：超出会被拒绝 (400 invalid_field)，需要保持预热的实例应计入 min_instances。null（未设置时的值）：节点的一小时 (--app-delete-after-seconds)。修改对应用现有的实例和之后创建的实例同样有效：每个节点至少每秒按应用当前的时间检查一次每个实例。不适用于应用的键控实例，键控实例用 keys.delete_after_idle_ms。

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            已停止的实例在保存内存并真正休眠之前保持暂停多久，单位为毫秒：暂停时，下一个请求在一两毫秒内得到响应，内存照常计量；休眠时，唤醒要多几毫秒，只计量它保存的数据。节点会把它限制在节点让任何实例保持暂停的最长时间内（十分钟）；宿主机内存不足、其他虚拟机需要占用槽位，或者有人请求休眠，都会让它更早休眠。null（默认）：节点的最长时间。数据库的 suspend_after_seconds 就是其应用的这一设置。

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            每天的某个 UTC 时刻 (HH:MM)，在此时唤醒应用中处于休眠状态的键控实例和有状态服务的实例，让它们完成等待唤醒才能做的工作（比如数据库维护）；节点根据应用请求创建和删除的实例只会被请求唤醒。唤醒本身不算活动：唤醒后运行的东西才算，运行完毕后实例会再次休眠。此外，无论这里怎么设置，有状态服务的实例都会为其 PostgreSQL 服务器 pg_cron 任务的下一次运行而被唤醒。null（默认）：不唤醒。数据库的 wake_daily_at 就是其应用的这一设置。

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          以下之一：

          • object
          • null
        • egressobject | nullrequired

          与沙箱相同的出站规则（default、allow、deny、http、inject），没有时为 null；按调用给出的原样保存（PATCH 会像节点那样按键逐个合并）。规则立即生效，不产生新版本：服务该应用的节点会把它们应用到其组内的每个实例上，包括现有的实例（运行中的实例对其已有连接也生效）和之后创建的实例；键控实例不受这些规则约束。控制平面只检查它们是不是由这些键组成、不超过 256 KiB 的对象：规则的内容由节点在应用时检查，节点读不懂其规则的实例，所有出站流量都会被拒绝（节点日志会说明原因）。

          • defaultoptionalallow或deny或null
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            任何连接都到达不了的端口，TCP 或 UDP，无论连往哪里，也无论规则的其他部分怎么说。浏览器会话的规则总是包含 25、465、587 以及矿池监听的端口（3333、4444、5555、7777、14444、45700）：无论其规则如何修改，控制平面都会把它们加上。

        • metadata映射，值为stringrequired
        • logsobjectrequired

          应用日志包含哪些内容，每一项为给出的值或默认值 (AppLogSettings)。

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          是否在其默认域名 (url) 上响应。

        • depends_on数组，元素为objectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliases数组，元素为stringrequired
          • endpoint_modestringrequired
        • drivesoptional数组，元素为object

          其实例挂载的云盘 (AppCreate.drives)：没有指定时为空列表 []。

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptional数组，元素为object

          每个键的实例自有的云盘 (AppCreate.key_drives)：没有给出时为空列表 []。

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • runtimeoptional

          运行时设置 (AppCreate.runtime)。null：没有。

          以下之一：

          • Runtime
            • ulimits映射，值为RuntimeLimitGivenrequired
            • sysctls映射，值为stringrequired
            • tmpfs数组，元素为objectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • servers数组，元素为stringrequired
              • search数组，元素为stringrequired
              • options数组，元素为stringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          应用请求的链路追踪包含哪些内容，每一项为给出的值或默认值 (AppTraceSettings)：sample_rate 为 0 时不产生任何 span。

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumes数组，元素为objectrequired

      服务挂载的项目存储卷。

      • modelstring | nullrequired

        它在模型中的名称。null：为有状态服务挂载但未命名卷的路径创建的。

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

        有多个服务挂载它，或者某个服务有多个实例：每个服务的每个实例同时挂载它。

      • statusto_make或made或there或externalrequired

        to_make：导入会创建它（试运行时对将要创建的存储卷这样说明）；made：本次导入创建了它；there：之前的导入创建了它，或者已有同名的存储卷；external：模型把它标为 external，而项目中已有它。

      • used_by数组，元素为stringrequired
    • secrets数组，元素为objectrequired

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

        保存它的项目机密：即模型中的名称，其中机密名称不允许的每个字符都写成下划线。

      • therebooleanrequired

        项目中是否已有它。导入（非试运行）时如果它还不存在，会被拒绝，返回 404 secret_not_found。

      • used_by数组，元素为stringrequired
    • left_out数组，元素为objectrequired

      属于未启用 profile 的服务，导入不会处理它们。

      • namestringrequired
      • profiles数组，元素为stringrequired
    • absent数组，元素为stringrequired

      项目中有而模型中没有的服务：保持原样。

    • deploystring | nullrequired

      导入触发的部署 (GET /v1/deploys/{id})。null：试运行，或者没有服务需要新版本。

      pattern: ^dpl-
  • accountsoptional数组，元素为object

    随 sole_owner 返回：该用户是唯一所有者的那些账户。

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

503

report_too_long：生成报告用了超过 5 秒；请分成更短的时段查询再相加，或者按整个自然月查询。可重试 (retryable)。
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

    随 already_moving 返回：该沙箱正在进行的迁移。

  • upgrade_idoptionalstring

    随 upgrade_in_progress（该键尚未结束的升级）、upgrade_started（已开始的升级）和 rollback_gone（回退被拒绝的那次升级）返回：即那次升级。

    pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
  • moveoptionalobject

    随 move_over、move_going_back 和 move_taken_over 返回 (POST /internal/moves/{id}/cancel)：迁移的当前状态。

    • objectstringrequired
    • idstringrequired
      pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
    • sandbox_idstringrequired
    • project_idstringrequired
    • fromobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

        节点名称；之后已从记录中消失的节点为 null。

    • epochintegerrequired

      迁移开始时表中记录的沙箱纪元：旧节点在这个纪元释放它，新节点在纪元加一时接管它，旧节点在纪元加二时收回它，从对象存储接管则在纪元加三时。

      minimum: 1
    • stepstringrequired

      迁移的进展：releasing（正在请旧节点释放它；表中记录它在旧节点上）、taking_over（正在请新节点接管它；表中记录它在新节点上）、reclaiming（新节点拒绝了它，正在请旧节点收回）、restoring（旧节点没有保留它的任何东西，正从对象存储接管）、done（已在新节点上）、failed（留在原处，或回到了原处，或停在某个时间无法消除的故障或运营方的取消发生时所在的位置：error 说明原因）。

    • whystringrequired

      发起迁移的原因：运营方的迁移、撤离或恢复。

    • wakebooleanrequired

      新节点是否唤醒它：按调用的指定，或按迁移开始时它的状态（是否在运行）。

    • from_storebooleanrequired

      新节点只从对象存储接管它。

    • releaseobject | nullrequired

      旧节点释放时的响应（sandboxd/openapi/openapi.json，releaseSandbox），不含释放所用的密钥；响应之前为 null。

    • takeoverobject | nullrequired

      结束迁移的那次接管的响应（节点文档中的 takeoverSandbox）：磁盘和内存来自哪里 (source)、各用了多长时间 (ms)、memory；之前为 null。

    • errorrequired

      失败的迁移：失败原因（如果被带回旧节点，则为新节点的拒绝原因）；已完成的迁移：null；进行中的迁移：如果当前步骤要再次请求，则为该步骤上次得到的答复。

      以下之一：

      • object
      • null
    • attemptsintegerrequired

      当前步骤已请求了多少次，仍没有得到确定的答复。

      minimum: 0
    • next_attempt_atstring | nullrequired

      该步骤何时再次请求；不在等待时为 null。

      format: date-time
    • batchstring | nullrequired

      它所属的撤离 (evc-…) 或恢复 (rcv-…)。

    • created_atstringrequired
      format: date-time
    • updated_atstringrequired
      format: date-time
    • ended_atstring | nullrequired
      format: date-time
  • lease_untiloptionalstring

    随 lease_held 返回：节点最后获得的租约最晚可以持有到何时，再加上让节点察觉租约到期所需的时间（在此之前 recoverNode 会被拒绝）。

    format: date-time
  • activeoptionalobject | null

    随 standby 返回：备用副本最后一次读取租约时的活动副本；没有副本持有租约时为 null。

    • namestringrequired
    • urlstringrequired
    • termintegerrequired
      minimum: 1
  • allowed_hostsoptionalarray | null

    随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null（节点的 SecretHosts）。

  • problemsoptional数组，元素为object

    随 invalid_definition 返回：定义中的每个问题，各附其位置和内容。

    • atstringrequired

      在定义中的位置，用点分隔的路径 (services.web.port)；针对整个定义时为空。

    • messagestringrequired
  • reportoptionalobject

    随 compose_refused 返回：导入的报告，说明拒绝了什么、为什么以及要改什么。

    • objectcompose_importrequired
    • namestring | nullrequired

      模型的 name：即每个服务的标签 compose.project。null：模型没有名称。

    • dry_runbooleanrequired
    • strictbooleanrequired
    • profiles数组，元素为stringrequired
    • treatmentsobjectrequired

      报告中每种处理方式各有多少项。

      • doneintegerrequired
        minimum: 0
      • adaptedintegerrequired
        minimum: 0
      • ignoredintegerrequired
        minimum: 0
      • refusedintegerrequired
        minimum: 0
    • items数组，元素为objectrequired

      模型的顶层元素：name，以及每个卷、网络、config、secret 和扩展。

      • atstringrequired

        在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

      • treatmentdone或adapted或ignored或refusedrequired

        done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

      • whystringrequired
      • changestring | nullrequired

        被拒绝的项：要改什么。其他情况为 null。

    • services数组，元素为objectrequired

      导入所采纳的服务，按模型中的顺序。

      • namestringrequired

        服务的名称，也是其应用的名称。

      • app_idstring | nullrequired

        其应用。null：试运行，且项目中没有该服务。

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

        导入对其应用做了（试运行时为将会做）什么：创建、写入变化的部分，或什么都不做。

      • kindservice或jobrequired

        job：模型中有服务等待它完成，它会在每次需要它的部署中运行到结束。

      • statefulbooleanrequired

        它挂载自己的存储卷：只有一个实例，由该实例持有存储卷。

      • versionbooleanrequired

        导入的部署是否为它创建版本：即解析引用后其版本的构成与当前版本不同。

      • items数组，元素为objectrequired
        • atstringrequired

          在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。

        • treatmentdone或adapted或ignored或refusedrequired

          done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。

        • whystringrequired
        • changestring | nullrequired

          被拒绝的项：要改什么。其他情况为 null。

      • appobjectrequired

        导入写入的服务应用字段：其版本的构成，以及立即生效的设置。

        • imagestring | nullrequired

          应用下一个版本的构成，连同其后的七个字段：即其最新版本的构成，加上此后的修改。null：应用没有镜像，也没有版本。

        • image_pull_secretstring | nullrequired

          保存镜像仓库凭据的机密的名称。任何响应都不包含其值。null：没有。

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

          放在镜像 ENTRYPOINT 之后、取代其 CMD 的内容。null：使用镜像的 CMD，或者整个 start_command。

          以下之一：

          • array<string>
          • null
        • portinteger | nullrequired
        • readyobjectrequired

          判断实例已启动的方式，版本的模板会在实例启动后保存：三者必须恰好给出一个。前两种从实例外部检查，所以服务必须监听所有地址 (0.0.0.0)。

          • httpoptionalstring

            一个以 / 开头的路径：在应用端口上对它发起 GET，返回 200 到 399 之间的状态码。

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

            在实例中执行成功的一条命令。由实例的 shell 运行：参数列表会被写成一行交给它。

            以下之一：

            • string
            • array<string>
        • env映射，值为stringrequired
        • secrets映射，值为stringrequired

          机密的名称。任何响应都不包含值。

        • sizeobjectrequired

          单个实例最多能使用的资源。按实际用量计费。

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

            偶数个 MiB（即节点为虚拟机加载内存所用的 2 MiB 页的整数倍），以字节表示。其他任何大小都返回 400 invalid_field（param 为 size.memory_bytes）：没有节点会创建这种大小的实例，正如没有节点会创建这种大小的沙箱（节点的 SandboxLimitsCreate.memory_bytes）。

            minimum: 134217728
        • volumes数组，元素为objectrequired
          • volumestringrequired
          • pathstringrequired
          • read_onlybooleanrequired
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • kindstringrequired
        • files数组，元素为objectrequired
          • pathstringrequired
          • modeintegerrequired
          • uidintegerrequired
          • gidintegerrequired
          • contentoptionalstring
          • secretoptionalstring
        • userstring | nullrequired
        • working_dirstring | nullrequired
        • stoprequired

          以下之一：

          • ServiceStop
            • signalstring | nullrequired
            • grace_msinteger | nullrequired
          • null
        • hostnamestring | nullrequired
        • regions数组，元素为stringrequired

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

            无论有没有请求，应用在一个区域内保持运行的实例数：即下限。该区域服务该应用的节点按分摊 max_instances 的方式分摊它（两个节点、下限为 2：各一个；下限为 1：一个，在最先尝试的节点上；下限为 5：三个和两个），不在线的节点由其他节点补足。节点在收到通知时就创建自己那部分，而不是等到第一个请求，也不会因为空闲而停止或删除这些实例；它们按运行中的实例计量。0（未设置时的值）：没有下限。调低后，超出部分的实例从那一刻起视为空闲，并像空闲实例一样被停止和删除。最多为 max_instances（如果给出），且不超过账户套餐允许应用在一个区域请求的数量（caps.app_instances.limit：5、50 和 500）：超出会被拒绝，返回 403 plan_cap_reached。

            minimum: 0
          • max_instancesinteger | nullrequired

            应用在一个区域内最多有多少个实例：由该区域服务该应用的节点分摊。最多为账户套餐允许应用请求的数量（caps.app_instances.limit：免费版 5，付费版 500）：超出会被拒绝，返回 403 plan_cap_reached；在允许的套餐上请求的数值会保留，但受当前套餐数值的限制。null：未指定数量的应用使用套餐的数值（caps.app_instances.default：免费版 2，付费版 50），如果 min_instances 更大则用它。告诉节点的数值，不超过账户除其他运行中资源外还能容纳的运行量，也不少于应用当前运行的实例数。

            minimum: 1
          • concurrencyinteger | nullrequired

            单个实例同时处理的上限：边缘节点发给它的请求，加上它在项目网络上打开的连接（经由其服务的地址，节点会按连接把它们分给各个实例；或者直接连到它自己的地址）。达到上限的实例即为已满，更多的请求会创建新实例。null（未设置时的值）：没有上限。此时节点会在现有实例的 CPU 或内存接近其规格时增加实例，应用不必猜一个数字；一次只处理一个请求的服务应设为 1。

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

            实例在没有请求时最多等待多久就停止，单位为毫秒。在这个上限以内，节点根据应用自己的流量选择等待时间：在应用最近一段时间里两次请求之间的间隔上，比较多运行一秒空闲与停止再恢复所花的 CPU 时间，选出成本最低的等待时间；这样，请求间隔比停止成本还短的应用会一直运行，请求间隔很长的应用则在最后一个响应结束后立即停止（0：总是立即停止）。null（未设置时的值）：平台的上限，三秒。设置过 100（2026年10月28日之前的默认值）的应用，从那天起视为 null。持续停止的实例会在 delete_after_ms 后被其节点删除，下一个需要实例的请求会得到一个新实例；min_instances 保持运行的实例既不会停止也不会删除。

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

            在实例因空闲而停止之前多久，向连接到其客户机 /run/sbx/awake 的程序发送一行 sleep N，单位为毫秒：程序可以借此写出手头的数据、关闭连接，或者发起保持，从而推迟停止。无论它们是否响应，停止都会在这段时间之后到来；没有程序连接时，不会推迟。键控实例也会收到通知。0 或 null：不通知（默认）。

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

            实例中的程序发起的保持，在空闲时间到期后最多还能让实例运行多久，单位为毫秒：程序连接 /run/sbx/awake，如果某个请求在响应之后还有后续工作，就在响应它之前发送 +，工作完成后发送 -（或关闭连接，或退出）；最后一个保持解除 sleep_after_ms 之后，实例停止。超过这个时间，无论有什么保持，实例都会停止；如果 sleep_notice_ms 要求通知，会先向已连接的程序发送 sleep N cap。保持期间实例在运行，并按运行计量。0：不理会保持。null：30000（默认）。

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

            实例空闲多久后被删除，与停止使用同一个起算点：下一个需要实例的请求会得到一个新实例，即版本模板的克隆，不含被删除的实例在内存和磁盘中积累的东西（需要长久保存的数据请放在存储卷或数据库中）。一秒到一小时，一小时是平台的时间，也是上限：超出会被拒绝 (400 invalid_field)，需要保持预热的实例应计入 min_instances。null（未设置时的值）：节点的一小时 (--app-delete-after-seconds)。修改对应用现有的实例和之后创建的实例同样有效：每个节点至少每秒按应用当前的时间检查一次每个实例。不适用于应用的键控实例，键控实例用 keys.delete_after_idle_ms。

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

            已停止的实例在保存内存并真正休眠之前保持暂停多久，单位为毫秒：暂停时，下一个请求在一两毫秒内得到响应，内存照常计量；休眠时，唤醒要多几毫秒，只计量它保存的数据。节点会把它限制在节点让任何实例保持暂停的最长时间内（十分钟）；宿主机内存不足、其他虚拟机需要占用槽位，或者有人请求休眠，都会让它更早休眠。null（默认）：节点的最长时间。数据库的 suspend_after_seconds 就是其应用的这一设置。

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

            每天的某个 UTC 时刻 (HH:MM)，在此时唤醒应用中处于休眠状态的键控实例和有状态服务的实例，让它们完成等待唤醒才能做的工作（比如数据库维护）；节点根据应用请求创建和删除的实例只会被请求唤醒。唤醒本身不算活动：唤醒后运行的东西才算，运行完毕后实例会再次休眠。此外，无论这里怎么设置，有状态服务的实例都会为其 PostgreSQL 服务器 pg_cron 任务的下一次运行而被唤醒。null（默认）：不唤醒。数据库的 wake_daily_at 就是其应用的这一设置。

            pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
        • keysrequired

          以下之一：

          • object
          • null
        • egressobject | nullrequired

          与沙箱相同的出站规则（default、allow、deny、http、inject），没有时为 null；按调用给出的原样保存（PATCH 会像节点那样按键逐个合并）。规则立即生效，不产生新版本：服务该应用的节点会把它们应用到其组内的每个实例上，包括现有的实例（运行中的实例对其已有连接也生效）和之后创建的实例；键控实例不受这些规则约束。控制平面只检查它们是不是由这些键组成、不超过 256 KiB 的对象：规则的内容由节点在应用时检查，节点读不懂其规则的实例，所有出站流量都会被拒绝（节点日志会说明原因）。

          • defaultoptionalallow或deny或null
          • allowoptionalarray | null
          • denyoptionalarray | null
          • httpoptionalarray | null
          • injectoptionalarray | null
          • deny_portsoptionalarray | null

            任何连接都到达不了的端口，TCP 或 UDP，无论连往哪里，也无论规则的其他部分怎么说。浏览器会话的规则总是包含 25、465、587 以及矿池监听的端口（3333、4444、5555、7777、14444、45700）：无论其规则如何修改，控制平面都会把它们加上。

        • metadata映射，值为stringrequired
        • logsobjectrequired

          应用日志包含哪些内容，每一项为给出的值或默认值 (AppLogSettings)。

          • outputbooleanrequired
          • keepbooleanrequired
          • requestsobjectrequired
            • sample_ratenumberrequired
              maximum: 1 · minimum: 0
            • keep_errorsbooleanrequired
        • publicbooleanrequired

          是否在其默认域名 (url) 上响应。

        • depends_on数组，元素为objectrequired
          • servicestringrequired
          • conditionstringrequired
        • networkobjectrequired
          • aliases数组，元素为stringrequired
          • endpoint_modestringrequired
        • drivesoptional数组，元素为object

          其实例挂载的云盘 (AppCreate.drives)：没有指定时为空列表 []。

          • drivestringrequired
          • pathstringrequired
          • modestringrequired
        • key_drivesoptional数组，元素为object

          每个键的实例自有的云盘 (AppCreate.key_drives)：没有给出时为空列表 []。

          • namestringrequired
          • pathstringrequired
          • size_bytesinteger | nullrequired
            format: int64
          • nocopyoptionalunknown

            只有给出为 true 时才会出现。

        • runtimeoptional

          运行时设置 (AppCreate.runtime)。null：没有。

          以下之一：

          • Runtime
            • ulimits映射，值为RuntimeLimitGivenrequired
            • sysctls映射，值为stringrequired
            • tmpfs数组，元素为objectrequired
              • pathstringrequired
              • size_bytesinteger | nullrequired
              • modeintegerrequired
            • dnsobjectrequired
              • servers数组，元素为stringrequired
              • search数组，元素为stringrequired
              • options数组，元素为stringrequired
            • shm_size_bytesinteger | nullrequired
          • null
        • tracesoptionalobject

          应用请求的链路追踪包含哪些内容，每一项为给出的值或默认值 (AppTraceSettings)：sample_rate 为 0 时不产生任何 span。

          • sample_ratenumberrequired
            maximum: 1 · minimum: 0
          • trust_incomingbooleanrequired
    • volumes数组，元素为objectrequired

      服务挂载的项目存储卷。

      • modelstring | nullrequired

        它在模型中的名称。null：为有状态服务挂载但未命名卷的路径创建的。

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

        有多个服务挂载它，或者某个服务有多个实例：每个服务的每个实例同时挂载它。

      • statusto_make或made或there或externalrequired

        to_make：导入会创建它（试运行时对将要创建的存储卷这样说明）；made：本次导入创建了它；there：之前的导入创建了它，或者已有同名的存储卷；external：模型把它标为 external，而项目中已有它。

      • used_by数组，元素为stringrequired
    • secrets数组，元素为objectrequired

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

        保存它的项目机密：即模型中的名称，其中机密名称不允许的每个字符都写成下划线。

      • therebooleanrequired

        项目中是否已有它。导入（非试运行）时如果它还不存在，会被拒绝，返回 404 secret_not_found。

      • used_by数组，元素为stringrequired
    • left_out数组，元素为objectrequired

      属于未启用 profile 的服务，导入不会处理它们。

      • namestringrequired
      • profiles数组，元素为stringrequired
    • absent数组，元素为stringrequired

      项目中有而模型中没有的服务：保持原样。

    • deploystring | nullrequired

      导入触发的部署 (GET /v1/deploys/{id})。null：试运行，或者没有服务需要新版本。

      pattern: ^dpl-
  • accountsoptional数组，元素为object

    随 sole_owner 返回：该用户是唯一所有者的那些账户。

    • idstringrequired
      pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
    • namestringrequired

输入以搜索……

↑↓ 切换↵ 选择Esc 关闭