Skip to content
导航

为沙箱的端口或应用注册域名

域名以小写形式保存,并去掉完全限定域名末尾可能带的点:App.Example.com. 和 app.example.com 是同一个域名。国际化域名要以 ASCII 形式给出 (xn--...)。请求体指定域名指向什么:sandbox 和 port,或者 app,二者不能同时给出。沙箱或应用可以用 id 或名称指定,按 id 保存。响应会说明哪些 DNS 记录可以证明域名所有权;系统会立即查找证明,然后以逐渐增大的间隔(5 秒起,每次翻倍,最长一小时)持续查找七天。

POST
https://api.glac.ai/v1/domains

授权

  • apiKeyHTTPrequired

请求头参数

  • Idempotency-Keyoptionalstring

    1 到 255 个字符:用相同的键和请求体再次请求会得到相同的响应,不会重复创建任何东西。

    maxLength: 255 · minLength: 1

请求体JSON必填

  • domainstringrequired

    域名,比如 app.example.com。

    maxLength: 254
  • sandboxoptionalstring

    沙箱的 id 或名称。需要与 port 一起使用。

  • portoptionalinteger
    maximum: 65535 · minimum: 1
  • appoptionalstring

    应用的 id 或名称:域名指向该应用,与其默认域名一样。不能与 sandbox 和 port 一起使用。

  • proxiedoptionalboolean

    域名是否经由平台的代理提供服务(见 Domain.proxied)。不给出时:平台有代理就经由代理。平台没有代理时设为 true 会返回 400 invalid_field。

Returns

201

注册信息,状态为 pending_verification。

JSON
  • idstringrequired
    pattern: ^dom-[0-9a-hjkmnp-tv-z]{16}$
  • objectdomainrequired
  • domainstringrequired
  • sandbox_idstring | nullrequired

    域名指向的沙箱。沙箱被删除后它仍保留 (detached)。指向应用的域名为 null。

  • portinteger | nullrequired

    指向应用的域名为 null。

  • app_idstring | nullrequired

    域名指向的应用。应用被删除后它仍保留 (detached)。指向沙箱端口的域名为 null。

  • statusstringrequired

    pending_verification:DNS 中没有所有权证明(或者曾经有,但现在另一个注册拥有该域名:verification.status 为 lost)。pending_certificate:域名归本注册所有,但还没有证书;certificate.error 说明受阻的原因。active:正在提供服务。detached:它所指向的沙箱或应用已不存在。经由代理提供服务的域名,在代理用其证书提供服务后变为 active(proxy.status 为 active),在此之前为 pending_certificate。

  • proxiedbooleanrequired

    域名是否经由平台的代理提供服务(Cloudflare for SaaS:control/README.md,入口挡在 Cloudflare 后面):其 CNAME 指向 <token>.<zone>,代理持有其证书并先接收其请求,享有该 DNS 区域的防护和限制(请求体最大 100 MB;两次读取响应之间不超过 125 秒)。false:域名直接到达边缘节点,经由 <token>.<direct zone> 或边缘节点的地址,使用边缘节点自己的证书和限制。平台有代理时,注册默认经由代理,除非另有指定;平台没有代理时从不经由代理。

  • proxyrequired

    域名在代理上的情况(针对经由代理的注册):不经由代理的注册为 null。

    以下之一:

    • DomainProxy
      • statusstringrequired

        waiting:注册尚未取得其域名,在取得之前不会在代理上创建任何东西。full:平台的代理所服务的域名已达设定的数量,这个域名在等待空位。pending:代理正在验证域名并签发证书,域名指向这里后它会自动完成,添加了 records 时会更早完成。failed:代理放弃了、封禁了该域名,或拒绝接收它(errors 中附有它的原话)。active:代理正在为该域名提供服务。

      • hostname_statusstring | nullrequired

        代理对域名验证的说法,原样给出(pending、active、moved、blocked 等)。

      • certificate_statusstring | nullrequired

        代理对域名证书的说法(pending_validation、pending_issuance、pending_deployment、active、validation_timed_out 等)。

      • records数组,元素为objectrequired

        客户可以添加的记录,用于在域名指向这里之前就完成验证并签发证书(迁移目前在别处提供服务的网站时)。代理不再需要它们时为空。

        • typestringrequired
        • namestringrequired
        • valuestringrequired
        • forstringrequired

          它证明的内容:域名本身,或用于证书的域名。

      • http数组,元素为objectrequired

        客户也可以改为在域名当前指向的地方响应的内容:一个路径及其响应体。

        • urlstringrequired
        • bodystringrequired
        • forstringrequired
      • errors数组,元素为stringrequired

        代理所说的障碍,使用其原话。

      • checked_atstring | nullrequired

        平台最后一次从代理获知该域名情况的时间。

        format: date-time
    • null
  • verificationobjectrequired
    • statusstringrequired
    • recordsobjectrequired

      证明域名控制权的记录:任一条即可。只要项目和域名不变,它们就保持不变。

      • cnamerequired

        同时用作证明和路由。平台没有对应的 DNS 区域时为 null。

        以下之一:

        • DnsRecord
          • typeCNAME或TXTrequired
          • namestringrequired
          • valuestringrequired
        • null
      • txtrequired

        只用作证明:域名必须通过其他方式到达边缘节点。域名太长、无法在前面加上记录的标签时为 null。

        以下之一:

        • DnsRecord
          • typeCNAME或TXTrequired
          • namestringrequired
          • valuestringrequired
        • null
      • addresses数组,元素为stringrequired

        边缘节点的地址,用于 A 和 AAAA 记录。控制平面没有获知这些地址时为空。

    • checked_atstring | nullrequired

      最后一次查询 DNS 的时间。

      format: date-time
    • verified_atstring | nullrequired
      format: date-time
    • errorrequired

      proof_not_found、other_proof_present(DNS 中既有本注册的证明,也有另一个的:只有本注册的证明单独存在时,域名才会归本注册)、proof_being_confirmed(找到了单独存在的本注册证明;域名目前在为另一个注册提供服务,至少十分钟后再次单独找到该证明时才会归本注册)、dns_unavailable、gave_up(七天都没有该记录)、lost。这里说的都是 DNS 和边缘节点对任何人都公开的信息,从不涉及另一个注册的任何内容。

      以下之一:

      • Problem
        • codestringrequired
        • messagestringrequired
      • null
  • certificateobjectrequired
    • statusstringrequired

      控制平面最后一次与边缘节点进行 TLS 握手时,边缘节点为该域名出示的证书。

    • not_beforestring | nullrequired
      format: date-time
    • not_afterstring | nullrequired
      format: date-time
    • checked_atstring | nullrequired
      format: date-time
    • errorrequired

      没有证书的原因;或者,在证书有效(status 为 valid)的情况下,按目前的状况它为什么不会被续期:proof_gone、not_reaching_edge、not_resolving 或 dns_unavailable(项目会收到事件 domain.renewal_stopped,情况解除时收到 domain.renewal_resumed)。proof_gone(证明该注册的记录已不在 DNS 中:在它重新出现之前,不会申请或续期证书)、not_resolving、not_reaching_edge(发往该域名 80 端口的请求,没有经由该域名的每个 A 和 AAAA 地址到达边缘节点,或者经由另一台服务器到达:位于代理或 CDN 之后的域名得不到证书)、dns_unavailable(DNS 对该域名没有响应:对已有有效证书的域名,要连续三次检查都如此)、waiting_for_turn(证书的申请速率有限制)、too_many_removed_domains(账户移除的域名已达边缘节点可等待处理的上限,边缘节点仍持有它们的证书:在边缘节点释放一部分之前,不会签发新证书)、not_issued(CA 没有签发证书)、edge_unreachable、no_edge。对经由代理提供服务的域名:proxy_pending(代理正在验证域名并签发证书)、proxy_failed(代理放弃了:proxy.errors 中附有它的原话)、proxy_blocked、proxy_moved(域名已不再指向这里)、proxy_full(平台的代理所服务的域名已达设定的数量,这个域名在等待)、proxy_refused(代理拒绝接收该域名)。

      以下之一:

      • Problem
        • codestringrequired
        • messagestringrequired
      • null
  • created_atstringrequired
    format: date-time

400

invalid_json、unknown_field、unknown_parameter;missing_field:缺少 domain,或者既没有 app,也没有 sandbox 和 port;invalid_field:某个字段类型错误,端口超出范围,app 与 sandbox 或 port 一起给出(param 指明多给的那个);invalid_domain:不是域名(由字母、数字和连字符组成的标签,至少两个,最多 253 个字符,不能是地址,也不能是预览 URL 第一个标签的形式);wildcard_not_supported:*.example.com;domain_reserved:平台自己的域名,或其下的域名。
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:密钥没有 admin 权限范围;needs_api_key:使用的是沙箱令牌或运营方的密钥;domain_limit_reached:项目的域名数已达单个项目的上限(默认 100,除非控制平面另有设置);account_held:账户因付款问题被冻结,除 GET /v1/account 外,用它的密钥发起的所有调用都会这样被拒绝,而且在检查权限范围之前就拒绝 (x-error-codes)。
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

404

sandbox_not_found:项目中没有该沙箱。app_not_found:项目中没有该应用。
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

409

domain_exists:本项目已注册过该域名(其他项目注册了它不构成障碍);idempotency_key_reused。
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 关闭