修改应用

以下之一：

• StartCommand
• null

以下之一：

• array<string>
• null

以下之一：

• Ready{3 个属性}

  • httpoptionalstring

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

  • tcpoptionaltrue

    应用端口接受连接。

  • commandoptional{2 个变体}

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

    以下之一：

    • string
    • array<string>

    }

  }
• null

以下之一：

• Size{2 个属性}

  • vcpusoptionalinteger

    minimum: 1
  • memory_bytesoptionalinteger

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

    minimum: 134217728

  }
• null

以下之一：

• Scale{9 个属性}

  • min_instancesoptionalinteger

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

    minimum: 0
  • max_instancesoptionalinteger | null

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

    minimum: 1
  • concurrencyoptionalinteger | null

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

    maximum: 1000 · minimum: 1
  • sleep_after_msoptionalinteger | null

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

    maximum: 600000 · minimum: 0
  • sleep_notice_msoptionalinteger | null

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

    maximum: 60000 · minimum: 0
  • sleep_hold_max_msoptionalinteger

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

    maximum: 900000 · minimum: 0
  • 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]$
  • delete_after_msoptionalinteger | null

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

    maximum: 3600000 · minimum: 1000

  }
• null

以下之一：

• AppKeys{3 个属性}

  • fromoptional{2 个变体}

    发往该应用的请求在哪里携带键。携带键的请求发往该键的实例（键没有实例时会为它创建：POST /v1/apps/{app}/instances），不携带键的请求像其他请求一样处理。修改立即生效，对之后到来的请求有效。null：请求不携带键，只能通过 /v1/apps/{app}/instances 指定键。

    以下之一：

    • AppKeysFrom
    • null

    }
  • upgrade_on_deployoptionalboolean | null

    应用的每次部署都会产生一个批次，把各键的实例升级到新版本，每个实例在休眠时升级（以默认设置调用 POST /v1/apps/{app}/upgrades；slice U4），并停止之前部署产生的批次，让各键始终跟随最新版本。false（null 也一样，即未设置时的值）：键的实例停留在其版本上，直到被升级。

  • delete_after_idle_msoptionalinteger | null

    键控实例休眠多久后被删除，单位为毫秒，按其节点对其休眠时长的计算（其对象的 idle_since）：其键被释放，下一个携带该键的请求会用当时承接应用流量的版本创建新实例；事件 sandbox.deleted 会给出 reason: idle 和该键。最少一秒，没有上限。null（未设置时的值）：从不删除，键控实例一直属于该键，直到被删除。修改对应用现有的键控实例有效：会立即按应用当前的时间重新检查它们，之后每分钟检查一次，或者按应用给出的最短时间的频率检查，但间隔至少一秒。设置了自己的 delete_after_idle_ms 的实例 (PATCH /v1/sandboxes/{id}) 改按自己的设置，无论更长还是更短：由其节点删除它，控制平面得知后释放其键。被冻结的实例（因支出上限，或其账户的套餐、余额或欠款）在冻结期间不会被任何一方删除：解冻后，其当前的休眠从那时开始计算。

    minimum: 1000

  }
• null

以下之一：

• AppLogSettings{3 个属性}

  • outputoptionalboolean | null

    实例打印的内容是否记入日志。false：机器不读取它；实例照常打印，并保留最后 16 MiB，可在实例内部读取 (GET /v1/sandboxes/{id}/exec/exe-start)。为 false 期间打印的内容，改回 true 后也不会出现在日志中。

    default: true
  • keepoptionalboolean | null

    输出是否长期保留。false：它照常在机器上的日志中，并计为未保留（GET /v1/apps/{app}/logs/usage 的 keep_off）；日志会标出从哪里开始 (logs.keep_off)、到哪里结束 (logs.keep_on)。

    default: true
  • requestsoptional{2 个变体}

    以下之一：

    • object
    • null

    }

  }
• null

以下之一：

• AppTraceSettings{2 个属性}

  • sample_rateoptionalnumber | null

    接收请求的机器为应用请求创建 span 的比例：从读完请求头到响应的最后一个字节发出，带有请求的方法、路径、状态码和 id，并把实例的唤醒以及为它创建的实例作为事件。span 会发往项目中接收 traces 的导出目标。0（默认）：不创建，平台不参与请求的链路追踪：请求的 traceparent 和 tracestate 原样到达实例。大于 0：每个请求的实例都会得到一个以平台的 span 为父级的 traceparent，无论是否被采样，这样应用自己的 span（其 OpenTelemetry SDK 产生的）就是平台 span 的子级，按父级标志采样的 SDK 会与平台采样同样的请求。

    maximum: 1 · minimum: 0 · default: 0
  • trust_incomingoptionalboolean | null

    是否采用请求自带的 traceparent。true：平台的 span 位于调用方的链路中，是调用方 span 的子级，按调用方的说明采样（无论 sample_rate 是多少），调用方的 tracestate 也会随之传递。false（默认）：每个请求开始一条自己的链路，按 sample_rate 采样，其 span 链接到调用方的 span；调用方的 tracestate 不会到达实例。采用时，由调用方决定采样哪些请求，也就决定了发往导出目标的内容：对所有人开放的服务，请保持为 false（W3C Trace Context，第 8.1 节）。

    default: false

  }
• null

以下之一：

• object
• null

以下之一：

• ServiceNetworkGiven{2 个属性}

  • aliasesoptionalarray | null

    其他名称：由小写标签组成的主机名，可以带点 (pg.example.test)；不能是 localhost 或 internal，也不能在它们之下，不能以 sbx- 开头；每个只能出现一次，且不能是其他应用的名称或别名 (409 name_taken)。null：没有。

  • endpoint_modeoptional{2 个变体}

    vip：其名称解析为服务的地址。dnsrr：其名称解析为各实例的地址。null：vip。

    以下之一：

    • string
    • null

    }

  }
• null

以下之一：

• string
• null

以下之一：

• ServiceStopGiven{2 个属性}

  • signaloptionalstring | null

    首先发送的信号：SIGTERM、SIGINT、SIGQUIT、SIGHUP、SIGKILL、SIGUSR1、SIGUSR2、SIGWINCH 或 SIGPWR，带不带 SIG 均可。null：镜像自己的停止信号，没有则为 SIGTERM。

  • grace_msoptionalinteger | null

    强制终止之前给它多长时间。null：十秒。

    maximum: 600000 · minimum: 0

  }
• null

以下之一：

• RuntimeGiven{5 个属性}

  • ulimitsoptionalobject | null

    按 Docker 名称指定的资源限制（core、cpu、data、fsize、locks、memlock、msgqueue、nice、nofile、nproc、rss、rtprio、rttime、sigpending、stack）：一个数字同时作为软限制和硬限制，或者 {soft, hard}；-1 表示不限制。打开文件数 (nofile) 为 1 到 1048576，不能为 -1。不设置时：打开文件数 1024，最多可提高到 524288，与 Docker 下相同。

  • sysctlsoptionalobject | null

    按名称设置的客户机内核参数，即 Docker 允许容器设置的那些：net.*、kernel.shm*、kernel.msg*、kernel.sem、fs.mqueue.*。值为单行 1 到 1024 字节。客户机内核没有的参数会导致构建失败，并指明是哪一个。

  • tmpfsoptionalarray | null

    位于实例内存中的文件系统，在实例启动时挂载。

  • dnsoptional{2 个变体}

    以下之一：

    • RuntimeDnsGiven
    • null

    }
  • shm_size_bytesoptionalinteger | null

    /dev/shm 的大小。null：实例内存的一半。

    maximum: 1099511627776 · minimum: 1048576

  }
• null