Skip to content
导航

创建数据库分支

从父分支（parent，分支的名称或 id；不指定时为根分支 main）的当前状态创建一个分支（slice DB6，Neon 的形式）：父分支的云盘按现状分叉（其节点在客户机写入暂停片刻时为它创建一个版本：相当于断电时的云盘，PostgreSQL 会通过 WAL 从中恢复），不复制任何数据；以及在其上运行的一个由单个有状态服务构成的应用，与根分支的一样：相同的镜像、规格和休眠设置，有自己的实例，独立休眠和唤醒，在项目网络中的名称为 <database>-<branch> (private_host)，有自己的端点。它的角色和密码与父分支相同：都在分叉时的数据中。其云盘按分叉以来变化的数据计费，从不超过它保存的数据量（storage.billed_bytes，以存储回收程序最近一次的计算为准：其最新版本从自己的对象中读取的数据量）；与父分支共享的部分算父分支的，只计费一次。带 expires_at 时，届时会自动删除（前提是已没有从它创建的分支）。调用会等待第一次启动（最多 150 秒），然后返回分支，或者 creating（仍在进行：对它发起 GET 查看）。也可以从根分支历史中的某个时刻创建分支 (from)：基于其云盘版本窗口中的版本，或者把其 WAL 归档重放到该时刻（几秒到几分钟：调用会等待）。所需权限范围：write。

POST
https://api.glac.ai/v1/databases/{id}/branches

授权

  • apiKeyHTTPrequired

路径参数

  • idstringrequired

    数据库的 id (db-…) 或名称。

请求体JSON必填

  • namestringrequired

    它在数据库中的名称：小写字母、数字和连字符，以字母开头；不能是 main。它在项目网络中的名称为 <database>-<branch>，最多 40 个字符。

  • parentoptionalstring | null

    创建它所依据的分支，用名称或 id 指定：不指定时为根分支 main。

  • expires_atoptionalstring | null

    自动删除的时间，必须是将来的时刻；null：永不。

    format: date-time
  • fromoptionalobject | null

    如果不是基于父分支的当前状态创建，所依据的内容（slice DB8 和 DB5）：at，根分支历史范围（history_seconds；只有根分支保留历史）内的一个时间，取法与恢复相同：如果 at 是整分钟或某个版本自身的时刻，取根分支云盘版本窗口中该时刻或之前最新的版本（每个有写入的 30 秒一个版本，PostgreSQL 会像断电后一样从中恢复）；否则（比窗口保留的更早、精确到秒，或带 exact），通过根分支的 WAL 归档精确取 at 本身，精确到毫秒（把 WAL 重放到该时刻并提升，然后才启动分支的实例），归档追溯不到时则拒绝（400 invalid_history；归档的存储拒绝接收其分段时为 503 database_archive_unavailable），拒绝时会指明窗口中该时刻或之前的版本：从不退而使用那个版本。快照 (snapshot) 属于之后的 slice。

    • atstringrequired
      format: date-time
    • exactoptionalboolean

      true：通过 WAL 归档精确取 at 本身，精确到毫秒，无论其精度如何。

Returns

201

分支：其 PostgreSQL 已能响应（awake，或之后已休眠），或者为 creating，第一次启动正在进行。

JSON
  • objectstringrequired
  • idstringrequired
    pattern: ^br-[0-9a-hjkmnp-tv-z]{16}$
  • namestringrequired
  • parentstring | nullrequired

    创建它所依据的分支，按 id；根分支没有。

  • endpointstringrequired

    其端点的名称，命名方式与 Neon 相同：随机生成，这样地址中就不会出现数据库或项目的任何名称。

    pattern: ^ep-[a-z]+-[a-z]+-[0-9a-f]{8}$
  • statecreating或failed或awake或paused或asleep或unavailable另有 2 个required

    其实例的状态：运行时为 awake，暂停层级把它保存在内存中时为 paused，已保存时为 asleep；其节点连不上（或它没有实例）时为 unavailable；数据库还没有实例或没能创建实例时为 creating 和 failed。删除过程中为 deleting，删除后为 deleted。

  • hoststring | nullrequired

    其公开地址，即在数据库所在区域和 DNS 区域下的端点：<endpoint>.<region>.<zone> (ep-calm-river-1a2b3c4d.na.db.glac.run)，端口 5432，只用 TLS；在有边缘节点提供 PostgreSQL 服务时（控制平面的 --database-zone）才有，没有时，或数据库没有可用于命名的区域时，为 null。

  • pooler_hoststring | nullrequired

    其连接池的公开地址（其实例中的 PgBouncer）：<endpoint>-pooler.<region>.<zone>，端口 5432；在有边缘节点提供 PostgreSQL 服务时（控制平面的 --database-zone）才有，没有时，或数据库没有可用于命名的区域时，为 null。

  • connection_uristring | nullrequired

    客户端通过其公开地址连接的方式：postgresql://<owner>@<host>/<database>?sslmode=require，只有给出密码的响应（创建、重设）中才带有所有者的密码；数据库自己的分支使用其父分支的密码；在有边缘节点提供 PostgreSQL 服务时（控制平面的 --database-zone）才有，没有时，或数据库没有可用于命名的区域时，为 null。

  • pooled_uristring | nullrequired

    通过其连接池连接，方式相同：postgresql://<owner>@<pooler_host>/<database>?sslmode=require；在有边缘节点提供 PostgreSQL 服务时（控制平面的 --database-zone）才有，没有时，或数据库没有可用于命名的区域时，为 null。

  • private_hoststringrequired

    它在项目网络中的名称：根分支为数据库的名称；数据库自己的分支为 <database>-<branch>。

  • private_uristringrequired

    项目中的沙箱和服务连接它的方式：postgresql://<owner>@<private_host>:5432/<database>，只有给出密码的响应（创建、重设）中才带有所有者的密码。数据库自己的分支使用其父分支的角色和密码。

  • sizeobjectrequired

    其实例的上限；按实际用量计费。

    • vcpusintegerrequired
    • memory_bytesintegerrequired
  • storageobjectrequired

    其云盘 (GET /v1/drives/{drive_id})。

    • drive_idstring | nullrequired
    • size_bytesinteger | nullrequired

      与创建时给出的一致；null：云盘的默认值。

    • durabilitystrict或standardrequired

      其云盘的级别，以其节点的说法为准：strict（提交在对象存储收到后才返回）或 standard。

    • used_bytesinteger | nullrequired

      其云盘中的数据量，以其节点最后一次的说法为准；节点报告之前为 null。

    • billed_bytesinteger | nullrequired

      其云盘保存数据的计费依据：根分支为其中的数据量；数据库自己的分支为分叉以来变化的数据（以回收程序最近一次的计算为准：其最新版本从对象存储中自己的对象读取的数据量），从不超过其中的数据量：回收程序报告之前为 0。没有任何报告之前为 null。

  • app_idstring | nullrequired

    其应用 (GET /v1/apps/{app_id})，创建后才有。

  • instance_idstring | nullrequired

    其实例，即一个沙箱（/v1/sandboxes/{instance_id}：可以读取它、在其中运行命令），如果有的话。

  • start_commandrequired

    其服务器的运行情况，以其实例所在节点的说法为准（实例的 start_command，见 sandboxd/openapi/openapi.json 中的 SandboxStartCommand）：status（running；restarting：已结束，将在 restarting_at 重新启动；exited）、restarts（结束后在其虚拟机中被重新启动了多少次，数据保持原样：PostgreSQL 靠其 WAL 恢复）、last_exit（status、signal、at）、restarting_at。每次启动还会产生一个事件 instance.restarted。没有实例，或其节点尚未报告时为 null。

    以下之一：

    • InstanceStartCommand
      • statusstringrequired

        running：正在运行（或者它留下的东西仍占用着其输出）；restarting：已结束，将在 restarting_at 重新启动；exited：已结束，不会再被启动。

      • restartsintegerrequired

        自沙箱创建以来，它在虚拟机中被重新启动了多少次，跨越其虚拟机的多次启动累计。

        format: int64 · minimum: 0
      • last_exitrequired

        上一次运行如何结束；还没有运行结束过时为 null。

        以下之一：

        • object
        • null
      • restarting_atstring | nullrequired

        处于 restarting 时：下一次运行的开始时间，按其客户机的时钟（届时如果虚拟机在休眠，会在醒来时启动）。其他情况为 null。

        format: date-time
    • null
  • expires_atstring | nullrequired

    自动删除的时间（前提是已没有从它创建的分支）：根分支，以及创建时没有设置它的分支，永不自动删除。

    format: date-time
  • created_atstringrequired
    format: date-time

400

invalid_json；unknown_field（包括之后的 slice 才支持的字段：from.snapshot）；missing_field：缺少 name；invalid_name：名称无效，或者对于 <database>-<branch> 来说太长（最多 40 个字符）；invalid_field：parent 不是文本，expires_at 不是将来的时刻；unknown_parameter。from.exact 也可能返回 invalid_field。invalid_history（param 为 from.at）：根分支的历史中没有该时间（超出 history_seconds、晚于现在、整分钟时间既不在根分支云盘的版本窗口内也不在其 WAL 归档范围内，或者精确到秒的时间或带 exact 的时间超出了归档范围：早于其最早的基础备份、落在其缺口 (history.gaps) 中，或者数据库根本不保留归档；错误信息会说明各自能追溯到何时，以及窗口中该时间或之前的版本，可以用那个版本自身的时刻创建分支），或者从根分支以外的分支创建（只有根分支保留历史）。
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

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

  • upgrade_idoptionalstring

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

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

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

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

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

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

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

    • epochintegerrequired

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

      minimum: 1
    • stepstringrequired

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

    • whystringrequired

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

    • wakebooleanrequired

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

    • from_storebooleanrequired

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

    • releaseobject | nullrequired

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

    • takeoverobject | nullrequired

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

    • errorrequired

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

      以下之一：

      • object
      • null
    • attemptsintegerrequired

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

      minimum: 0
    • next_attempt_atstring | nullrequired

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

      format: date-time
    • batchstring | nullrequired

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

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

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

    format: date-time
  • activeoptionalobject | null

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

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

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

  • problemsoptional数组，元素为object

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

    • atstringrequired

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

    • messagestringrequired
  • reportoptionalobject

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

    • objectcompose_importrequired
    • namestring | nullrequired

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

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

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

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

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

      • atstringrequired

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

      • treatmentdone或adapted或ignored或refusedrequired

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

      • whystringrequired
      • changestring | nullrequired

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

    • services数组，元素为objectrequired

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

      • namestringrequired

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

      • app_idstring | nullrequired

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

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

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

      • kindservice或jobrequired

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

      • statefulbooleanrequired

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

      • versionbooleanrequired

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

      • items数组，元素为objectrequired
        • atstringrequired

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

        • treatmentdone或adapted或ignored或refusedrequired

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

        • whystringrequired
        • changestring | nullrequired

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

      • appobjectrequired

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

        • imagestring | nullrequired

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

        • image_pull_secretstring | nullrequired

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

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

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

          以下之一：

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

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

          • httpoptionalstring

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

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

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

            以下之一：

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

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

        • sizeobjectrequired

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

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

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

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

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

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

          以下之一：

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

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

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

            minimum: 0
          • max_instancesinteger | nullrequired

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

            minimum: 1
          • concurrencyinteger | nullrequired

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

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

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

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

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

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

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

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

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

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

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

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

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

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

          以下之一：

          • object
          • null
        • egressobject | nullrequired

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

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

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

        • metadata映射，值为stringrequired
        • logsobjectrequired

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

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

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

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

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

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

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

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

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

        • runtimeoptional

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

          以下之一：

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

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

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

      服务挂载的项目存储卷。

      • modelstring | nullrequired

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

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

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

      • statusto_make或made或there或externalrequired

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

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

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

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

      • therebooleanrequired

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

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

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

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

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

    • deploystring | nullrequired

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

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

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

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

401

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

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

  • upgrade_idoptionalstring

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

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

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

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

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

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

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

    • epochintegerrequired

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

      minimum: 1
    • stepstringrequired

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

    • whystringrequired

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

    • wakebooleanrequired

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

    • from_storebooleanrequired

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

    • releaseobject | nullrequired

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

    • takeoverobject | nullrequired

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

    • errorrequired

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

      以下之一：

      • object
      • null
    • attemptsintegerrequired

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

      minimum: 0
    • next_attempt_atstring | nullrequired

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

      format: date-time
    • batchstring | nullrequired

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

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

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

    format: date-time
  • activeoptionalobject | null

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

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

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

  • problemsoptional数组，元素为object

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

    • atstringrequired

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

    • messagestringrequired
  • reportoptionalobject

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

    • objectcompose_importrequired
    • namestring | nullrequired

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

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

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

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

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

      • atstringrequired

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

      • treatmentdone或adapted或ignored或refusedrequired

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

      • whystringrequired
      • changestring | nullrequired

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

    • services数组，元素为objectrequired

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

      • namestringrequired

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

      • app_idstring | nullrequired

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

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

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

      • kindservice或jobrequired

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

      • statefulbooleanrequired

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

      • versionbooleanrequired

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

      • items数组，元素为objectrequired
        • atstringrequired

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

        • treatmentdone或adapted或ignored或refusedrequired

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

        • whystringrequired
        • changestring | nullrequired

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

      • appobjectrequired

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

        • imagestring | nullrequired

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

        • image_pull_secretstring | nullrequired

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

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

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

          以下之一：

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

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

          • httpoptionalstring

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

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

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

            以下之一：

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

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

        • sizeobjectrequired

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

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

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

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

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

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

          以下之一：

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

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

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

            minimum: 0
          • max_instancesinteger | nullrequired

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

            minimum: 1
          • concurrencyinteger | nullrequired

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

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

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

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

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

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

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

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

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

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

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

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

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

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

          以下之一：

          • object
          • null
        • egressobject | nullrequired

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

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

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

        • metadata映射，值为stringrequired
        • logsobjectrequired

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

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

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

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

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

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

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

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

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

        • runtimeoptional

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

          以下之一：

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

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

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

      服务挂载的项目存储卷。

      • modelstring | nullrequired

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

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

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

      • statusto_make或made或there或externalrequired

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

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

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

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

      • therebooleanrequired

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

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

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

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

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

    • deploystring | nullrequired

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

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

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

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

402

account_in_debt：账户欠费（余额低于零），付清之前账户的任何东西都不能使用：其密钥以及其沙箱令牌的每个调用都会这样被拒绝，以下除外：读取欠款和付款的调用；列出和读取其存储卷的备份，以及从备份创建存储卷的调用（POST /v1/volumes，带上 from_backup，正在删除账户存储的数据时除外），这是停止付款的账户最需要的；此外，除非控制平面以 --debt-allows-delete false 启动，还有列出、读取和删除账户存储的存储卷、快照和沙箱，以及删除其备份的调用。新建备份始终不行。在检查密钥的权限范围之前就拒绝，无论路径是什么。错误信息会说明欠款金额、起始时间、账户存储的数据何时会被删除、如何付款、可以删除存储的数据以免金额继续增长，以及仍然可以从备份创建存储卷（GET /v1/billing、debt）。
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

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

  • upgrade_idoptionalstring

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

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

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

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

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

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

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

    • epochintegerrequired

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

      minimum: 1
    • stepstringrequired

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

    • whystringrequired

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

    • wakebooleanrequired

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

    • from_storebooleanrequired

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

    • releaseobject | nullrequired

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

    • takeoverobject | nullrequired

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

    • errorrequired

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

      以下之一：

      • object
      • null
    • attemptsintegerrequired

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

      minimum: 0
    • next_attempt_atstring | nullrequired

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

      format: date-time
    • batchstring | nullrequired

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

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

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

    format: date-time
  • activeoptionalobject | null

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

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

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

  • problemsoptional数组，元素为object

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

    • atstringrequired

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

    • messagestringrequired
  • reportoptionalobject

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

    • objectcompose_importrequired
    • namestring | nullrequired

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

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

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

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

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

      • atstringrequired

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

      • treatmentdone或adapted或ignored或refusedrequired

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

      • whystringrequired
      • changestring | nullrequired

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

    • services数组，元素为objectrequired

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

      • namestringrequired

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

      • app_idstring | nullrequired

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

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

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

      • kindservice或jobrequired

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

      • statefulbooleanrequired

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

      • versionbooleanrequired

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

      • items数组，元素为objectrequired
        • atstringrequired

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

        • treatmentdone或adapted或ignored或refusedrequired

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

        • whystringrequired
        • changestring | nullrequired

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

      • appobjectrequired

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

        • imagestring | nullrequired

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

        • image_pull_secretstring | nullrequired

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

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

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

          以下之一：

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

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

          • httpoptionalstring

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

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

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

            以下之一：

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

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

        • sizeobjectrequired

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

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

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

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

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

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

          以下之一：

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

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

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

            minimum: 0
          • max_instancesinteger | nullrequired

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

            minimum: 1
          • concurrencyinteger | nullrequired

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

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

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

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

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

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

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

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

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

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

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

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

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

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

          以下之一：

          • object
          • null
        • egressobject | nullrequired

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

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

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

        • metadata映射，值为stringrequired
        • logsobjectrequired

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

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

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

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

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

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

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

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

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

        • runtimeoptional

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

          以下之一：

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

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

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

      服务挂载的项目存储卷。

      • modelstring | nullrequired

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

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

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

      • statusto_make或made或there或externalrequired

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

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

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

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

      • therebooleanrequired

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

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

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

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

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

    • deploystring | nullrequired

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

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

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

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

403

key_scope、needs_api_key、account_held（与其他地方一样）；product_not_open：无服务器 Postgres 尚未在本平台开放 (--products)；drive_limit_reached：云盘数将超出账户套餐允许项目保留的上限，与分叉时一样；spend_limit_reached、balance_used_up：项目受限；account_share_reached：账户在进行分叉的节点的数据盘上已占满自己的份额。plan_cap_reached：database_branches，分支数将超出该套餐下单个数据库允许的上限（免费版 10 个，付费版 500 个）；在免费版上为 database_cu_hours 或 account_database_cu_hours，该数据库（或账户所有数据库合计）本自然月的计算量已用完。
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

database_not_found；branch_not_found（param 为 parent）：数据库中没有该名称或 id 的分支。
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

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

  • upgrade_idoptionalstring

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

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

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

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

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

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

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

    • epochintegerrequired

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

      minimum: 1
    • stepstringrequired

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

    • whystringrequired

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

    • wakebooleanrequired

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

    • from_storebooleanrequired

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

    • releaseobject | nullrequired

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

    • takeoverobject | nullrequired

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

    • errorrequired

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

      以下之一：

      • object
      • null
    • attemptsintegerrequired

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

      minimum: 0
    • next_attempt_atstring | nullrequired

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

      format: date-time
    • batchstring | nullrequired

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

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

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

    format: date-time
  • activeoptionalobject | null

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

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

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

  • problemsoptional数组，元素为object

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

    • atstringrequired

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

    • messagestringrequired
  • reportoptionalobject

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

    • objectcompose_importrequired
    • namestring | nullrequired

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

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

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

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

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

      • atstringrequired

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

      • treatmentdone或adapted或ignored或refusedrequired

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

      • whystringrequired
      • changestring | nullrequired

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

    • services数组，元素为objectrequired

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

      • namestringrequired

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

      • app_idstring | nullrequired

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

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

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

      • kindservice或jobrequired

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

      • statefulbooleanrequired

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

      • versionbooleanrequired

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

      • items数组，元素为objectrequired
        • atstringrequired

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

        • treatmentdone或adapted或ignored或refusedrequired

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

        • whystringrequired
        • changestring | nullrequired

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

      • appobjectrequired

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

        • imagestring | nullrequired

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

        • image_pull_secretstring | nullrequired

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

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

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

          以下之一：

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

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

          • httpoptionalstring

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

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

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

            以下之一：

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

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

        • sizeobjectrequired

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

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

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

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

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

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

          以下之一：

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

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

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

            minimum: 0
          • max_instancesinteger | nullrequired

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

            minimum: 1
          • concurrencyinteger | nullrequired

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

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

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

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

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

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

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

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

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

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

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

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

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

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

          以下之一：

          • object
          • null
        • egressobject | nullrequired

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

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

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

        • metadata映射，值为stringrequired
        • logsobjectrequired

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

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

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

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

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

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

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

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

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

        • runtimeoptional

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

          以下之一：

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

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

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

      服务挂载的项目存储卷。

      • modelstring | nullrequired

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

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

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

      • statusto_make或made或there或externalrequired

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

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

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

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

      • therebooleanrequired

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

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

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

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

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

    • deploystring | nullrequired

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

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

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

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

409

name_taken：数据库中已有该名称的分支（main 是根分支的名称），或者项目中已有名为 <database>-<branch> 的应用或名为 <database>-<branch>-data 的云盘；database_busy (retryable)：数据库或父分支正在创建或删除；database_failed：其第一次启动或父分支的第一次启动失败了。
JSON
  • errorobjectrequired
    • typestringrequired
    • codestringrequired
    • messagestringrequired
    • paramstring | nullrequired
    • retryablebooleanrequired
    • request_idstringrequired
    • docs_urlstring | nullrequired
  • move_idoptionalstring

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

  • upgrade_idoptionalstring

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

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

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

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

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

    • toobjectrequired
      • idstringrequired
      • namestring | nullrequired

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

    • epochintegerrequired

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

      minimum: 1
    • stepstringrequired

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

    • whystringrequired

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

    • wakebooleanrequired

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

    • from_storebooleanrequired

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

    • releaseobject | nullrequired

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

    • takeoverobject | nullrequired

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

    • errorrequired

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

      以下之一：

      • object
      • null
    • attemptsintegerrequired

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

      minimum: 0
    • next_attempt_atstring | nullrequired

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

      format: date-time
    • batchstring | nullrequired

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

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

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

    format: date-time
  • activeoptionalobject | null

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

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

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

  • problemsoptional数组，元素为object

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

    • atstringrequired

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

    • messagestringrequired
  • reportoptionalobject

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

    • objectcompose_importrequired
    • namestring | nullrequired

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

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

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

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

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

      • atstringrequired

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

      • treatmentdone或adapted或ignored或refusedrequired

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

      • whystringrequired
      • changestring | nullrequired

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

    • services数组，元素为objectrequired

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

      • namestringrequired

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

      • app_idstring | nullrequired

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

        pattern: ^app-
      • statuscreated或changed或unchangedrequired

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

      • kindservice或jobrequired

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

      • statefulbooleanrequired

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

      • versionbooleanrequired

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

      • items数组，元素为objectrequired
        • atstringrequired

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

        • treatmentdone或adapted或ignored或refusedrequired

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

        • whystringrequired
        • changestring | nullrequired

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

      • appobjectrequired

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

        • imagestring | nullrequired

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

        • image_pull_secretstring | nullrequired

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

        • start_commandrequired

          以下之一：

          • StartCommand
          • null
        • start_argsrequired

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

          以下之一：

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

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

          • httpoptionalstring

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

          • tcpoptionaltrue

            应用端口接受连接。

          • commandoptional

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

            以下之一：

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

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

        • sizeobjectrequired

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

          • vcpusintegerrequired
            minimum: 1
          • memory_bytesintegerrequired

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

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

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

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

          以下之一：

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

          按 na、eu、ap 的顺序。

        • scaleobjectrequired
          • min_instancesintegerrequired

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

            minimum: 0
          • max_instancesinteger | nullrequired

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

            minimum: 1
          • concurrencyinteger | nullrequired

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

            maximum: 1000 · minimum: 1
          • sleep_after_msinteger | nullrequired

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

            maximum: 600000 · minimum: 0
          • sleep_notice_msinteger | nullrequired

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

            maximum: 60000 · minimum: 0
          • sleep_hold_max_msintegerrequired

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

            maximum: 900000 · minimum: 0
          • delete_after_msinteger | nullrequired

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

            maximum: 3600000 · minimum: 1000
          • suspend_after_msoptionalinteger | null

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

            maximum: 86400000 · minimum: 1000
          • wake_daily_atoptionalstring | null

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

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

          以下之一：

          • object
          • null
        • egressobject | nullrequired

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

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

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

        • metadata映射，值为stringrequired
        • logsobjectrequired

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

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

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

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

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

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

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

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

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

        • runtimeoptional

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

          以下之一：

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

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

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

      服务挂载的项目存储卷。

      • modelstring | nullrequired

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

      • namestringrequired

        它在项目中的名称。

      • idstring | nullrequired

        null：尚未创建 (to_make)。

        pattern: ^vol-
      • sharedbooleanrequired

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

      • statusto_make或made或there或externalrequired

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

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

      模型中授予服务的 secrets。

      • modelstringrequired

        它在模型中的名称。

      • namestringrequired

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

      • therebooleanrequired

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

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

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

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

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

    • deploystring | nullrequired

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

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

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

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

503

database_unavailable (retryable)：父分支此刻没有云盘；node_unavailable：父分支所在的节点，或为分叉选定的节点连不上；drive_in_store：此刻没有节点持有父分支的云盘；unavailable：父分支所在的节点此刻无法为其创建版本；no_capacity：没有节点有空间容纳分支的实例，或运行归档重放的机器；database_archive_unavailable：根分支的机器没有把最后一段 WAL 发送到归档，或者归档还无法追溯到精确到秒的时间（或 exact），因为其存储从那之前就一直拒绝接收分段（database.archive_failing；错误信息会说明从何时开始，以及窗口中该时间或之前的版本）；database_restore_failed：归档重放到该时刻后，没能得到一个已提升的 PostgreSQL（错误信息附有它最后的输出）；drive_unreadable：对象存储给不出分支云盘所依据版本的全部数据块（窗口中的版本，或归档基础备份的快照）：没有创建任何东西。稍后再请求一次。
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 关闭