Skip to content
导航

设置账户的通知地址和语言、账单地址和税号,以及发往互联网的流量上限

只修改给出的项,其他不变。email:账户通知的发送地址;null 表示移除地址。如果它是账户已验证的地址,或账户某个成员已验证的地址,会立即视为已验证;否则会向它发送一个验证链接,账户通知会等到链接被打开后再发送(email_verified、POST /v1/auth/account-email/verify);再次设置会再发送一个链接。这类链接每个账户 3 次,之后每十分钟一次(429 rate_limited,在执行调用的任何部分之前返回)。language:通知使用的语言,必须是通知支持的语言之一(en、de、fr;否则返回 400 invalid_field),或者 null,表示使用账单地址所在国家大多数人的首选语言(GET /v1/account 的 language 会说明是哪种以及原因)。欠费的账户也可以修改这两项,以及账单地址和税号,但请求体中只能有这些字段(否则返回 402 account_in_debt):在只面向企业销售的地方,付款需要它们。egress_overage_cap_bytes:账户在一个自然月内最多发送的字节数,在任何套餐上都从当月第一个字节开始计算,无论账户持有多少余额;null 表示取消上限。egress_overage 反映当前状态,不由账户选择:传入它当前的值不会改变任何东西;不在付费版上或没有余额的账户设为 pay 返回 403 needs_balance,在付费版上且有余额的账户设为 stop 返回 400 invalid_field(要在某个字节数处停止流量,应该用上限)。billing_address:账户的付款地,其付款按该地纳税(control/README.md,税):country(两个字母,ISO 3166-1),以及 line1、line2、city、state 和 postal_code 中有的各项(美国需要州和 ZIP 码,加拿大需要省或邮政编码,当地的税按这些确定);null 表示移除。tax_id:企业的税号,按 Stripe 的命名方式,type(eu_vat、gb_vat、au_abn 等)和 value(欧盟增值税号前加上国家的两个字母:DE123456789);null 表示移除。由 Stripe 收款时,两者会先设置到账户在 Stripe 的客户上,Stripe 拒绝的部分会被拒绝 (400 invalid_field),不会设置;Stripe 会向主管机构(VIES、HMRC、ABR)核验税号:在 Stripe 给出结果 (tax_id.updated) 之前为 pending,未通过核验的税号会再从客户上移除。由替代收款方收款时,它会按指示立即核验税号 (PATCH /internal/charges/collector)。税号已通过核验或仍在核验中的账户被视为企业:它可以在只面向企业销售的地方付款 (tax.can_pay),在平台已注册的地方,其付款适用反向征收(不加收税款)。账户自己确认的地址,可以用于那些要求它确认地址的付款(通知 tax_address_confirm)。所需权限范围:admin。

PATCH
https://api.glac.ai/v1/account

授权

  • apiKeyHTTPrequired

请求体JSON必填

  • emailoptionalstring | null

    账户通知的发送地址;null 表示移除地址。

  • languageoptionalen或de或fr或null

    账户通知使用的语言;null 表示取消选择,重新按账单地址决定。

  • egress_overageoptionalstop或pay

    不由账户选择:见 PATCH /v1/account。

  • egress_overage_cap_bytesoptionalinteger | null

    一个自然月内最多发送的字节数;null 表示取消上限。

    format: int64 · minimum: 0
  • billing_addressoptionalobject | null

    账单地址:country,以及其余各项中有的部分,每项为最多 200 个字符的字符串;美国需要 state 和 ZIP 码(postal_code,五位数字或 ZIP+4),加拿大需要省份 (state) 或 postal_code。null 表示移除。

    • countrystringrequired

      ISO 3166-1 alpha-2 代码。

      pattern: ^[A-Za-z]{2}$
    • line1optionalstring | null
      maxLength: 200
    • line2optionalstring | null
      maxLength: 200
    • cityoptionalstring | null
      maxLength: 200
    • stateoptionalstring | null
      maxLength: 200
    • postal_codeoptionalstring | null
      maxLength: 200
  • tax_idoptionalobject | null

    按 Stripe 命名方式给出的税号;null 表示移除。

    • typestringrequired

      eu_vat、gb_vat、au_abn 等(Stripe 的类型)。

      maxLength: 24 · pattern: ^[a-z]{2}_[a-z_]+$
    • valuestringrequired

      按主管机构的写法;空格会被去掉。欧盟增值税号前要加国家的两个字母(DE123456789;希腊为 EL)。

Returns

200

账户的当前状态。

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

    其应用日志所受的限制。

    • line_bytesintegerrequired

      输出行的最大长度,单位为字节:超出的部分会被截掉,该行会注明截掉了多少 (cut_bytes)。除非机器另有说明,否则为 16384。

      minimum: 1
    • lines_per_secondintegerrequired

      单个实例的输出每秒最多保留多少行:超出的行会被丢弃,日志中会有一行说明丢弃了多少 (output.dropped)。500。

      minimum: 1
    • instance_bytesintegerrequired

      机器为现存实例保留多少:其文件达到此大小时,较旧的一半会被删除。4 MiB。

      format: int64 · minimum: 1
    • deleted_instance_bytesintegerrequired

      机器为已删除实例保留多少:其文件末尾的这部分字节。1 MiB。

      format: int64 · minimum: 0
    • deleted_instance_daysnumberrequired

      从实例删除时起保留多少天。7。

      minimum: 0
    • app_bytes_per_nodeintegerrequired

      机器为单个应用总共保留多少:超出时,最早删除的实例剩下的内容最先删除。1 GiB。

      format: int64 · minimum: 1
    • followersintegerrequired

      同一时间最多有多少读取方跟踪账户的应用日志,所有项目的应用合计(GET /v1/apps/{app}/logs 的 follow=true):即其套餐的数值(套餐标志的 log_followers=;按控制平面的默认启动设置,免费版 10,付费版 100)。超出的那个会被拒绝,返回 429 too_many_followers。

      minimum: 1
  • keepsobjectrequired

    密钥所属项目保留的存储卷和云盘(云盘计入存储卷;数据库自己的云盘不计入,键控实例的云盘计入总容量但不计入数量),按创建时所受的限制计算(POST /v1/volumes、POST /v1/drives:403 volume_limit_reached、drive_limit_reached),每项旁附带项目当前的量:套餐的数值,或运营方为该账户设定的数值(可申请提高:POST /v1/limits/requests,volumes 和 volume_bytes)。免费版:3 个,单个最大 10 GiB,合计 15 GiB,创建时不指定大小则为 5 GiB;付费套餐:500 个(软限制),单个最大 1 TiB,不限合计,不指定大小则为节点自己的 64 GiB。

    • volumesobjectrequired
      • limitintegerrequired

        项目最多可以有多少个存储卷和云盘。

        minimum: 0
      • usedintegerrequired

        当前有多少个。

        minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:套餐,或运营方为该账户设定。

    • volume_bytesobjectrequired
      • limitintegerrequired

        单个最大多少,单位为字节。

        format: int64 · minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:套餐,或运营方为该账户设定。

    • volumes_bytesobjectrequired
      • limitinteger | nullrequired

        全部合计最大多少,单位为字节;null:没有限制(付费版,按存储量计费)。

        format: int64 · minimum: 0
      • usedintegerrequired

        项目现有的合计大小。

        format: int64 · minimum: 0
    • unsized_bytesintegerrequired

      创建时不指定 size_bytes 的存储卷或云盘的大小:单个允许的最大值;如果套餐限制了合计,则为合计的平均份额(免费版为 5 GiB:15 GiB 分给 3 个);如果节点自己的大小 (64 GiB) 更小,则用它。

      format: int64 · minimum: 0
  • capsobjectrequired

    账户同时可拥有的数量及其当前各项的用量:CapLimits 中的上限(即 GET /v1/billing 的 caps),每项在 limit 和 source 旁附带 used(control/README.md,同时能有多少)。

    • instancesobjectrequired

      同时运行的沙箱和应用实例。

      • limitintegerrequired

        账户可以拥有的数量。

        minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:其套餐,或运营方为该账户设定。

      • usedintegerrequired

        当前拥有的数量:上次检查的结果,加上此后各调用带来的变化。

        minimum: 0
    • vcpusobjectrequired

      它们的 vCPU 合计。

      • limitintegerrequired

        账户可以拥有的数量。

        minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:其套餐,或运营方为该账户设定。

      • usedintegerrequired

        当前拥有的数量:上次检查的结果,加上此后各调用带来的变化。

        minimum: 0
    • memory_bytesobjectrequired

      它们的内存合计,单位为字节。

      • limitintegerrequired

        账户可以拥有的数量。

        minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:其套餐,或运营方为该账户设定。

      • usedintegerrequired

        当前拥有的数量:上次检查的结果,加上此后各调用带来的变化。

        minimum: 0
    • sleepingobjectrequired

      保留着但不在运行的沙箱。

      • limitintegerrequired

        账户可以拥有的数量。

        minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:其套餐,或运营方为该账户设定。

      • usedintegerrequired

        当前拥有的数量:上次检查的结果,加上此后各调用带来的变化。

        minimum: 0
    • app_instancesobjectrequired
      • limitintegerrequired

        账户可以拥有的数量。

        minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:其套餐,或运营方为该账户设定。

      • usedintegerrequired

        账户某个应用的某个版本当前拥有的最多实例数,包括运行中和休眠中的,涵盖其所有节点(以节点最近的盘点为准)。

        minimum: 0
      • defaultintegerrequired

        What an app has when it asks for no scale.max_instances.

        minimum: 0
    • creates_per_minuteobjectrequired

      最近一分钟内创建的沙箱。

      • limitintegerrequired

        账户可以拥有的数量。

        minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:其套餐,或运营方为该账户设定。

      • usedintegerrequired

        当前拥有的数量:上次检查的结果,加上此后各调用带来的变化。

        minimum: 0
    • creates_per_hour_per_projectobjectrequired

      单个项目最近一小时内创建的沙箱:used 为账户各项目中的最大值。

      • limitintegerrequired

        账户可以拥有的数量。

        minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:其套餐,或运营方为该账户设定。

      • usedintegerrequired

        当前拥有的数量:上次检查的结果,加上此后各调用带来的变化。

        minimum: 0
    • app_creates_per_hourobjectrequired

      最近一小时内创建的应用和应用版本。

      • limitintegerrequired

        账户可以拥有的数量。

        minimum: 0
      • sourcestringrequired

        limit 的数值来自哪里:其套餐,或运营方为该账户设定。

      • usedintegerrequired

        当前拥有的数量:上次检查的结果,加上此后各调用带来的变化。

        minimum: 0
  • namestringrequired
  • projectobjectrequired

    密钥所属的项目。

    • idstringrequired
    • namestringrequired
  • emailstring | nullrequired

    账户通知的发送地址:欠款通知、将因欠款删除的内容等。null:暂时没有地址,通知会等到账户有地址后再发送。只向已验证的地址发送 (email_verified)。

  • email_verifiedbooleanrequired

    email 是否已验证:只向已验证的地址发送。账户设置的地址,如果是账户已验证的地址,或账户某个成员用户已验证的地址,会立即视为已验证;否则会向它发送一个验证链接(verify_account_email,一周内有效),账户通知会等到链接被打开后再发送 (POST /v1/auth/account-email/verify),与没有地址的账户一样,从通知起算的事情(欠款的天数)也一样要等。运营方设置的地址凭其说明即视为已验证;用户验证自己的地址时,也会验证把通知发往该地址的账户的地址。没有地址时为 false。

  • email_undeliverablerequired

    据发件方接收后的反馈,发往 email 的邮件被退回或被投诉:不再向它发送任何通知(通知会等待,与没有地址的账户一样),直到账户重新设置地址(设置同一个地址也可以)。邮件能正常送达时为 null。

    以下之一:

    • object
    • null
  • languageobjectrequired

    账户通知使用的语言,以及由什么决定(control/README.md,通知的语言)。撤回的收件确认和购买确认也使用该语言;该语言没有对应措辞的通知使用英语。

    • codestringrequired

      ISO 639-1:通知支持的语言之一。

    • sourcestringrequired

      account:账户自己选择的(PATCH /v1/account,带上 language)。billing_address:账户没有选择,这是其账单地址所在国家大多数人的首选语言。default:两者都没有决定(没有选择,也没有账单地址,或者其国家的语言不是通知支持的语言):英语。

  • egress_overagestringrequired

    按目前的状况,达到额度时会怎样:在付费版上且有余额的账户为 pay(超出周期包含额度的部分从余额中扣除),其他账户为 stop:免费版账户,无论有多少余额,流量都会在达到当天配额时停止;没有余额的账户也一样。

  • egress_overage_cap_bytesinteger | nullrequired

    账户在一个自然月内最多发送的字节数;null:没有上限。

    format: int64 · minimum: 0
  • egressobjectrequired

    账户的沙箱在所有项目、所有节点上向互联网发送的数据,并与额度对照:即 GET /v1/account 的 egress,GET /v1/usage 列出沙箱时也返回它。它就是节点的 AccountEgress,附带时段、自然月、项目、超出额度部分的金额,以及流量停止的原因。

    • 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

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

  • debtrequired

    账户的欠款,与 GET /v1/billing 的 debt 相同;没有欠款的账户为 null。

    以下之一:

    • Debt
      • objectstringrequired
      • idstringrequired
      • stateowing或deleting或paid或deletedrequired

        owing:账户欠费,其中任何部分都不能使用。deleting:期限已过,账户存储的内容正在删除。账户只会看到这两种状态的欠款。paid:已付清,或欠款低于欠费的起点。deleted:账户存储的内容已被删除,其欠款已核销。

      • in_debt_sincestringrequired

        发现账户欠款达到欠费起点的时间。

        format: date-time
      • owed_usdnumberrequired

        当前欠款:余额低于零的金额。已结束的欠款为 0。

      • data_deleted_atstring | nullrequired

        如果账户仍欠费,其存储内容的删除时间:发件方已接收的通知中所写的最晚日期。在欠款的通知尚未被接收时(此时不会删除任何东西),以及运营方冻结账户期间,为 null。以删除告终的欠款,为删除的时间。

        format: date-time
      • notice_daysintegerrequired

        欠费账户从第一条通知起有多少天的期限 (--debt-days)。

      • on_holdbooleanrequired

        运营方冻结了该账户:账户的任何东西都不会被删除,其天数也停止计算。

      • charge_atstring | nullrequired

        下次从账户银行卡扣收欠款的时间:欠款开始后或上次扣款后的第一个账单日的 UTC 00:00(账单日是账户订阅开始那天在每月中的日期;没有订阅时为第一次充值收款的那天;当月没有这一天时取当月最后一天)。已到的时间会在下一次检查时扣款。null:不会扣款,因为账户没有登记银行卡 (Balance.card) 或没有账单日、运营方冻结了账户、删除已经开始,或者欠款低于欠费的起点。扣收的是当时的欠款,向上取整到分,且不超过账户支出上限在本自然月剩余的额度 (Balance.reload_left_usd):因此剩下的欠款在下一个账单日扣收;如果上限剩余的额度低于欠费的起点,当月不扣款,下个月的第一次检查时扣收(在此之前这个时间保持为已到的时间)。

        format: date-time
      • last_chargerequired

        最近一次从账户银行卡扣收欠款的记录及其结果;第一次扣款之前为 null。

        以下之一:

        • DebtCharge
        • null
      • notices数组,元素为objectrequired

        这笔欠款的通知,最早的在前:第一条通知,以及在它被接收后将要发出的提醒;以及每次扣款失败的通知 (charge_failed)。

        • idstringrequired
        • objectstringrequired
        • kindin_debt或reminder_7或reminder_14或reminder_21或reminder_27或reminder_29另有 8 个required

          in_debt:欠款的第一条通知。reminder_<day>:在其后的第几天发送(天数由控制平面决定,--debt-reminder-days)。charge_failed:在账单日从账户银行卡扣收欠款失败;每次这样的扣款各一条。data_deleted:账户存储的内容已被删除,欠款已核销。storage_80、storage_100:在产生任何欠款之前,账户套餐包含的存储已用掉五分之四或已用完,且账户没有余额。subscription_charge_failed:到期的订阅周期月费无法扣收;每次这样的扣款各一条,包括第一次以及宽限期内的每次重试。reload_failed:一次自动充值无法扣款;每次各一条。reload_no_card:自动充值已开启且余额低于设定值,但账户没有登记可扣款的银行卡;这种情况持续期间每个自然月一条。included_80、included_100:套餐包含的 CPU 时间、内存、请求或流量已用掉五分之四或已全部用完,且账户没有余额,自动充值也不会充值;每个计量项、每个阈值、每个时段各一条。

        • stateto_send或accepted或failed或cancelledrequired

          to_send:尚未交给发件方,或已交出但尚无回复。accepted:发件方已接收并负责投递。failed:发件方表示无法投递;如果是欠款通知,过一段时间会重新生成一条。cancelled:不再发送(欠款已付清;或者后来的提醒已经说明了它要说的内容)。账户看不到已取消的通知。

        • due_atstringrequired

          从何时起交给发件方。

          format: date-time
        • sent_atstring | nullrequired

          交给发件方的时间(针对发件方已接收的通知);其他情况为 null。对欠款的第一条通知而言:即欠款天数的起算时刻。

          format: date-time
        • subjectstring | nullrequired

          邮件主题(交出之后才有)。

    • null
  • payment_holdrequired

    账户因付款问题被冻结、从何时开始,以及请联系支持团队;未被冻结的账户为 null。不说明原因:那是运营方的信息(GET /internal/accounts/{id},payment_hold)。

    以下之一:

    • AccountHoldShown
      • objectstringrequired
      • sincestringrequired
        format: date-time
      • messagestringrequired

        在处理之前,账户的任何东西都不能使用,也不会对它扣款,并请联系支持团队。

    • null
  • billing_addressrequired

    账户的付款地,其付款按该地纳税;null:尚未提供,付款页面会要求填写。

    以下之一:

    • BillingAddress
      • line1string | nullrequired
      • line2string | nullrequired
      • citystring | nullrequired
      • statestring | nullrequired

        州、省或地区;美国的州用两个字母表示,按州统计销售额。

      • postal_codestring | nullrequired
      • countrystringrequired

        ISO 3166-1 alpha-2 代码。

        pattern: ^[A-Z]{2}$
      • sourcestring | nullrequired

        由谁提供:账户、运营方 (PATCH /internal/accounts/{id})、账户在付款页面上填写、Stripe(客户门户,以 Stripe 的 customer.updated 为准)。

      • set_atstring | nullrequired
        format: date-time
    • null
  • tax_idrequired

    企业的税号,以及其核验结果;null:没有。

    以下之一:

    • TaxId
      • typestringrequired

        按 Stripe 的命名:eu_vat、gb_vat、au_abn 等。

      • valuestringrequired
      • verificationobjectrequired
        • statusstringrequired

          pending:正在核验(期间账户视为企业,如果之后未通过核验,以此身份收取的付款会被暂扣,交由运营方处理);verified;unverified:主管机构查不到它(账户不是企业);unavailable:无法核验(同样不视为企业;其付款会被标记给运营方)。

        • verified_namestring | nullrequired

          主管机构登记的名称(如果给出了)。

        • verified_addressstring | nullrequired
        • checked_atstring | nullrequired

          最后一次收到核验结果的时间。

          format: date-time
      • sourcestringrequired

        由谁提供:账户、运营方、账户在付款页面上填写、Stripe(客户门户)。

      • set_atstring | nullrequired
        format: date-time
    • null
  • taxobjectrequired

    账户所在地如何销售它购买的东西:按其账单地址确定,没有账单地址时无从得知(付款页面会要求填写)。

    • countrystring | nullrequired

      取自其账单地址。

    • regionstring | nullrequired

      适用这种情况的地区:eu-oss(欧盟)、小写的国家两字母代码(au、gb)、us-<state>。

    • sold_asstring | nullrequired

      registered:平台在当地已登记纳税,会加收税款(有已核验税号的企业改为反向征收);business_only:平台在当地未登记,只向企业销售;sold:平台在当地未登记,向所有人销售,不加税。

    • businessbooleanrequired

      账户是否为企业:其税号已通过核验,或正在核验。

    • can_paybooleanrequired

      账户能否在其所在地付款:只有在只面向企业销售的地方且账户不是企业时才为 false,此时充值、付款页面和付费套餐都会被拒绝 (403 tax_region_business_only),自动充值也不会进行。

400

invalid_json、unknown_field(请求体中的,或 billing_address、tax_id 中的:param 指明是哪一个)、unknown_parameter;invalid_field:email 不是有效地址,egress_overage_cap_bytes 不是整数字节数,持有余额的账户把 egress_overage 设为 stop,billing_address 不是有效地址(美国地址缺少州和 ZIP 码,加拿大地址缺少省或邮政编码),tax_id 缺少 type 和 value,或者 Stripe 不接受其中之一。
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

402

account_in_debt:账户欠费(余额低于零),付清之前账户的任何东西都不能使用:其密钥以及其沙箱令牌的每个调用都会这样被拒绝,以下除外:读取欠款和付款的调用;列出和读取其存储卷的备份,以及从备份创建存储卷的调用(POST /v1/volumes,带上 from_backup,正在删除账户存储的数据时除外),这是停止付款的账户最需要的;此外,除非控制平面以 --debt-allows-delete false 启动,还有列出、读取和删除账户存储的存储卷、快照和沙箱,以及删除其备份的调用。新建备份始终不行。在检查密钥的权限范围之前就拒绝,无论路径是什么。错误信息会说明欠款金额、起始时间、账户存储的数据何时会被删除、如何付款、可以删除存储的数据以免金额继续增长,以及仍然可以从备份创建存储卷(GET /v1/billing、debt)。
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(与其他地方一样);needs_balance:免费版账户或没有余额的账户把 egress_overage 设为 pay,需要先升级到付费版并充值;account_held:账户因付款问题被冻结,可以读取账户,但不能修改任何内容。
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

rate_limited (retryable):目前验证账户通知地址的链接发送次数过多(3 次,之后每十分钟一次);调用的任何部分都不会执行。
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

502

stripe_refused:Stripe 因格式以外的原因拒绝了账单地址或税号;它不会被设置(调用中在它之前给出的项可能已设置)。错误信息中附有 Stripe 的原话及其请求 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

503

stripe_unavailable:无法连接 Stripe 来设置账单地址或税号,因此未设置(调用中在它之前给出的项可能已设置):再次发起同一调用即可。可重试 (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 关闭