查看应用

GET

https://api.glac.ai/v1/apps/{app}

授权

apiKeyHTTPrequired

路径参数

appstringrequired
应用的 id (app-...) 或名称。

Returns

200

应用的当前状态。

JSON

managed_byobject | nullrequired
唯一能修改它的东西（如果有的话）。object 为 database：它所属的数据库（id，见 /v1/databases）；其他任何会修改它的调用都会被拒绝，返回 409 managed_by_database。object 为 sandboxes（id 为 null）：属于沙箱产品，由项目的沙箱创建请求 (POST /v1/sandboxes) 创建：项目的默认沙箱应用 sbx-sandbox（其 image 为 null：每个沙箱都从其所在节点的基础模板创建，直到项目为它指定一个镜像：只带 image 的 PATCH，用该镜像创建一个新版本，此后不指定镜像的创建请求都从这个版本创建），或者某个创建请求指定的镜像的应用（image，与创建请求指定的一致；sbx-<the image's name>-<12 hex digits>，一个版本）。版本创建即就绪，应用的实例就是项目的沙箱；除了读取它及其版本、为默认沙箱应用指定镜像和删除它（其各版本的模板随之删除；下一个指定该镜像或不指定镜像的创建请求会重新创建它）之外，对它的任何调用都会被拒绝，返回 409 managed_by_sandboxes。null：不受任何东西管理。object 为 installation：它所属的托管应用安装（id，见 /v1/installations），只有该安装能修改它：其他任何会修改它的调用都会被拒绝，返回 409 managed_by_installation。
- objectdatabase或sandboxes或installationrequired
- idstring | nullrequired
}
publicbooleanrequired
是否在其默认域名 (url) 上响应。
volumes数组，元素为objectrequired
- volumestringrequired
- pathstringrequired
- read_onlybooleanrequired
- nocopyoptionalunknown
  只有给出为 true 时才会出现。
}
drives数组，元素为objectrequired
其实例挂载的云盘 (AppCreate.drives)：没有指定时为空列表 []。
- drivestringrequired
- pathstringrequired
- modestringrequired
}
key_drives数组，元素为objectrequired
每个键的实例自有的云盘 (AppCreate.key_drives)：没有给出时为空列表 []。
- namestringrequired
- pathstringrequired
- size_bytesinteger | nullrequired
  format: int64
- nocopyoptionalunknown
  只有给出为 true 时才会出现。
}
depends_on数组，元素为objectrequired
- servicestringrequired
- conditionstringrequired
}
networkobjectrequired
- aliases数组，元素为stringrequired
- endpoint_modestringrequired
}
kindstringrequired
files数组，元素为objectrequired
- pathstringrequired
- modeintegerrequired
- uidintegerrequired
- gidintegerrequired
- contentoptionalstring
- secretoptionalstring
}
userstring | nullrequired
working_dirstring | nullrequired
stoprequired
以下之一：
ServiceStop
signalstring | nullrequired
grace_msinteger | nullrequired
null
}
hostnamestring | nullrequired
runtimerequired
运行时设置 (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
}
privateobjectrequired
项目网络中的沙箱在哪里找到该应用：它在网络中的地址（只要它还在网络中就一直保留，无论是否重命名），以及它在 internal 下的名称。项目网络中的沙箱可以通过其名称、domain，以及它的每个 network.aliases（带或不带 .internal）找到它。
- addressstring | nullrequired
  项目地址段中的一个地址 (GET /v1/project)。只有站点的所有地址段都已划完时才为 null。
  
  pattern: ^10\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])(\.(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){2}$
- domainstringrequired
  <name>.internal.
}
idstringrequired
pattern: ^app-[0-9a-hjkmnp-tv-z]{16}$
objectapprequired
namestringrequired
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
}
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
}
tracesobjectrequired
应用请求的链路追踪包含哪些内容，每一项为给出的值或默认值 (AppTraceSettings)：sample_rate 为 0 时不产生任何 span。
- sample_ratenumberrequired
  maximum: 1 · minimum: 0
- trust_incomingbooleanrequired
}
urlstring | nullrequired
应用的访问地址：https:// 加其默认域名 <name>-<the project's short name>.<the zone>。从应用创建的那一刻起，只要应用保持该名称，这个地址就属于它（在第一个版本就绪之前返回 503 app_not_deployed）。在没有为应用配置 DNS 区域 (--app-zone) 的控制平面上为 null。
directbooleanrequired
应用是否还在一个不经过平台代理、直达边缘节点的域名上响应 (direct_url)：在那里，请求体大小和响应停顿时长都不受代理的限制，除了边缘节点自身的限制外，没有任何东西保护应用。
checkpointrequired
键控实例运行期间的检查点：每隔 every_seconds 秒（默认 10，取值 1 到 600），把实例在某一时刻的内存和磁盘送到其节点的对象存储；节点的宿主机丢失时，实例会在另一个节点上从最新的检查点连同进程一起被接管，最多丢失此后做的事（休眠的实例从休眠状态接管，不会丢失任何东西）。每次节点会把它暂停几毫秒；发送的是自上一个检查点以来写入的内容，经过压缩；写入速度超过节点检查点链路承载能力的实例会落后，而不是把链路占满（实例的 checkpoint：last_at、behind_seconds、bytes_per_second、stored_bytes）。对象存储为实例最新检查点保存的数据，在实例运行期间按休眠状态 (state) 计费；发送的数据不计费。立即生效，不产生新版本：现有的实例会立即启用，之后创建的实例创建时就带有它。不适用于有状态服务的实例：其存储卷在对象存储中没有副本。实例的云盘（包括它自己的 key_drives）会与磁盘在同一时刻固定下来，接管时恢复到那一刻的状态；挂载了非云盘存储卷的实例不会创建检查点，其 checkpoint.error 会说明这一点。null：不启用（默认）。
以下之一：
object
null
}
direct_urlstring | nullrequired
应用不经代理时的访问地址：其默认域名的标签放在平台的直连 DNS 区域下 (https://<name>-<project>.direct.glac.run)。除非设置了 direct，否则为 null；平台没有代理时也为 null。
current_versionstring | nullrequired
承接应用流量的版本的 id：最新一次成功启动的部署，或者回滚指定的版本。在有版本就绪之前为 null。
deployingstring | nullrequired
正在部署、就绪后将承接流量的版本的 id。
build_failures数组，元素为objectrequired
应当服务承接应用流量的版本、但在部署后被要求构建时没能构建成功的节点（新加入的节点、其模板已不可用的节点、重新回来的节点），每个节点一项，按节点的 id；没有时为空。构建失败的节点会在上次尝试十分钟后再次被要求构建，构建成功后就不再出现在这里；在此期间由其他节点服务该版本。每次失败还会产生一个事件 app.build_failed，只产生一次。
- node_idstringrequired
  未能构建的节点。
- version_idstringrequired
  pattern: ^ver-[0-9a-hjkmnp-tv-z]{16}$
- errorobjectrequired
  codestringrequired
  节点给出的错误码；如果无法读取版本的机密，或者机密不允许发往其镜像的仓库，则为本控制平面的错误码（secret_not_found、secret_unreadable、invalid_field、secret_host_not_allowed）。
  
  messagestringrequired
  节点或镜像仓库的原话，由节点转达，不含凭据；或者本控制平面的说明，其中会指明是哪个机密。
- failed_atstringrequired
  最后一次尝试失败的时间。
  
  format: date-time
}
logs_stateobjectrequired
保存该应用日志的每个节点上日志的保存方式，以节点最近一次盘点（每隔几秒一次）中的说法为准。
- nodes数组，元素为objectrequired
  每个节点一项，按节点的 id；没有节点保存该应用的日志，或者没有节点报告（2026年10月24日之前的节点）时为空。
  
  node_idstringrequired
  for_goodbooleanrequired
  应用实例现在在该节点上打印的内容是否长期保留：上传到对象存储，按套餐保留天数保留，并计量。false：只保存在该节点上，照常可以读取，不计量，节点消失时随之消失（日志中的 logs.keep_off）。从控制平面检查时决定停止账户日志（其套餐的日志额度已用完，且没有余额支付更多），到节点得知这一决定之前，该节点上的值仍为 true：这期间打印的内容会长期保留并计量，没有余额支付时会被核销（对账单的 written_off_usd）。
  
  reasonsetting或over_plan或nullrequired
  不长期保留的原因：setting，应用的 logs.keep；over_plan，账户已用完套餐包含的日志额度，且没有余额支付更多。长期保留时为 null。
  
  sincestring | nullrequired
  从何时开始如此，以节点的时钟为准。null：节点没有记录时间。
  
  format: date-time
}
created_atstringrequired
format: date-time
updated_atstringrequired
format: date-time

400

unknown_parameter.

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：使用的是运营方的密钥或 SSH 网关的密钥；account_held：账户因付款问题被冻结，除 GET /v1/account 外，用它的密钥发起的所有调用都会这样被拒绝，而且在检查权限范围之前就拒绝 (x-error-codes)；installation_key_scope：限定于某个托管应用安装的密钥，用在了与该安装自身无关的调用上。（沙箱令牌会被转给其节点，节点对它没有的调用返回 404 no_such_route。）

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
随 already_moving 返回：该沙箱正在进行的迁移。
upgrade_idoptionalstring
随 upgrade_in_progress（该键尚未结束的升级）、upgrade_started（已开始的升级）和 rollback_gone（回退被拒绝的那次升级）返回：即那次升级。

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
随 move_over、move_going_back 和 move_taken_over 返回 (POST /internal/moves/{id}/cancel)：迁移的当前状态。
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  节点名称；之后已从记录中消失的节点为 null。
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  节点名称；之后已从记录中消失的节点为 null。
- epochintegerrequired
  迁移开始时表中记录的沙箱纪元：旧节点在这个纪元释放它，新节点在纪元加一时接管它，旧节点在纪元加二时收回它，从对象存储接管则在纪元加三时。
  
  minimum: 1
- stepstringrequired
  迁移的进展：releasing（正在请旧节点释放它；表中记录它在旧节点上）、taking_over（正在请新节点接管它；表中记录它在新节点上）、reclaiming（新节点拒绝了它，正在请旧节点收回）、restoring（旧节点没有保留它的任何东西，正从对象存储接管）、done（已在新节点上）、failed（留在原处，或回到了原处，或停在某个时间无法消除的故障或运营方的取消发生时所在的位置：error 说明原因）。
- whystringrequired
  发起迁移的原因：运营方的迁移、撤离或恢复。
- wakebooleanrequired
  新节点是否唤醒它：按调用的指定，或按迁移开始时它的状态（是否在运行）。
- from_storebooleanrequired
  新节点只从对象存储接管它。
- releaseobject | nullrequired
  旧节点释放时的响应（sandboxd/openapi/openapi.json，releaseSandbox），不含释放所用的密钥；响应之前为 null。
- takeoverobject | nullrequired
  结束迁移的那次接管的响应（节点文档中的 takeoverSandbox）：磁盘和内存来自哪里 (source)、各用了多长时间 (ms)、memory；之前为 null。
- errorrequired
  失败的迁移：失败原因（如果被带回旧节点，则为新节点的拒绝原因）；已完成的迁移：null；进行中的迁移：如果当前步骤要再次请求，则为该步骤上次得到的答复。
  
  以下之一：
  object
  null
- attemptsintegerrequired
  当前步骤已请求了多少次，仍没有得到确定的答复。
  
  minimum: 0
- next_attempt_atstring | nullrequired
  该步骤何时再次请求；不在等待时为 null。
  
  format: date-time
- batchstring | nullrequired
  它所属的撤离 (evc-…) 或恢复 (rcv-…)。
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
随 lease_held 返回：节点最后获得的租约最晚可以持有到何时，再加上让节点察觉租约到期所需的时间（在此之前 recoverNode 会被拒绝）。

format: date-time
activeoptionalobject | null
随 standby 返回：备用副本最后一次读取租约时的活动副本；没有副本持有租约时为 null。
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null（节点的 SecretHosts）。
problemsoptional数组，元素为object
随 invalid_definition 返回：定义中的每个问题，各附其位置和内容。
- atstringrequired
  在定义中的位置，用点分隔的路径 (services.web.port)；针对整个定义时为空。
- messagestringrequired
}
reportoptionalobject
随 compose_refused 返回：导入的报告，说明拒绝了什么、为什么以及要改什么。
- objectcompose_importrequired
- namestring | nullrequired
  模型的 name：即每个服务的标签 compose.project。null：模型没有名称。
- dry_runbooleanrequired
- strictbooleanrequired
- profiles数组，元素为stringrequired
- treatmentsobjectrequired
  报告中每种处理方式各有多少项。
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- items数组，元素为objectrequired
  模型的顶层元素：name，以及每个卷、网络、config、secret 和扩展。
  
  atstringrequired
  在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。
  
  treatmentdone或adapted或ignored或refusedrequired
  done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。
  
  whystringrequired
  changestring | nullrequired
  被拒绝的项：要改什么。其他情况为 null。
- services数组，元素为objectrequired
  导入所采纳的服务，按模型中的顺序。
  
  namestringrequired
  服务的名称，也是其应用的名称。
  
  app_idstring | nullrequired
  其应用。null：试运行，且项目中没有该服务。
  
  pattern: ^app-
  statuscreated或changed或unchangedrequired
  导入对其应用做了（试运行时为将会做）什么：创建、写入变化的部分，或什么都不做。
  
  kindservice或jobrequired
  job：模型中有服务等待它完成，它会在每次需要它的部署中运行到结束。
  
  statefulbooleanrequired
  它挂载自己的存储卷：只有一个实例，由该实例持有存储卷。
  
  versionbooleanrequired
  导入的部署是否为它创建版本：即解析引用后其版本的构成与当前版本不同。
  
  items数组，元素为objectrequired
  atstringrequired
  在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。
  
  treatmentdone或adapted或ignored或refusedrequired
  done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。
  
  whystringrequired
  changestring | nullrequired
  被拒绝的项：要改什么。其他情况为 null。
  
  appobjectrequired
  导入写入的服务应用字段：其版本的构成，以及立即生效的设置。
  
  imagestring | nullrequired
  应用下一个版本的构成，连同其后的七个字段：即其最新版本的构成，加上此后的修改。null：应用没有镜像，也没有版本。
  
  image_pull_secretstring | nullrequired
  保存镜像仓库凭据的机密的名称。任何响应都不包含其值。null：没有。
  
  start_commandrequired
  以下之一：
  StartCommand
  null
  start_argsrequired
  放在镜像 ENTRYPOINT 之后、取代其 CMD 的内容。null：使用镜像的 CMD，或者整个 start_command。
  
  以下之一：
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  判断实例已启动的方式，版本的模板会在实例启动后保存：三者必须恰好给出一个。前两种从实例外部检查，所以服务必须监听所有地址 (0.0.0.0)。
  
  httpoptionalstring
  一个以 / 开头的路径：在应用端口上对它发起 GET，返回 200 到 399 之间的状态码。
  
  tcpoptionaltrue
  应用端口接受连接。
  
  commandoptional
  在实例中执行成功的一条命令。由实例的 shell 运行：参数列表会被写成一行交给它。
  
  以下之一：
  string
  array<string>
  env映射，值为stringrequired
  secrets映射，值为stringrequired
  机密的名称。任何响应都不包含值。
  
  sizeobjectrequired
  单个实例最多能使用的资源。按实际用量计费。
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  偶数个 MiB（即节点为虚拟机加载内存所用的 2 MiB 页的整数倍），以字节表示。其他任何大小都返回 400 invalid_field（param 为 size.memory_bytes）：没有节点会创建这种大小的实例，正如没有节点会创建这种大小的沙箱（节点的 SandboxLimitsCreate.memory_bytes）。
  
  minimum: 134217728
  volumes数组，元素为objectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  只有给出为 true 时才会出现。
  
  kindstringrequired
  files数组，元素为objectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  以下之一：
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regions数组，元素为stringrequired
  按 na、eu、ap 的顺序。
  
  scaleobjectrequired
  min_instancesintegerrequired
  无论有没有请求，应用在一个区域内保持运行的实例数：即下限。该区域服务该应用的节点按分摊 max_instances 的方式分摊它（两个节点、下限为 2：各一个；下限为 1：一个，在最先尝试的节点上；下限为 5：三个和两个），不在线的节点由其他节点补足。节点在收到通知时就创建自己那部分，而不是等到第一个请求，也不会因为空闲而停止或删除这些实例；它们按运行中的实例计量。0（未设置时的值）：没有下限。调低后，超出部分的实例从那一刻起视为空闲，并像空闲实例一样被停止和删除。最多为 max_instances（如果给出），且不超过账户套餐允许应用在一个区域请求的数量（caps.app_instances.limit：5、50 和 500）：超出会被拒绝，返回 403 plan_cap_reached。
  
  minimum: 0
  max_instancesinteger | nullrequired
  应用在一个区域内最多有多少个实例：由该区域服务该应用的节点分摊。最多为账户套餐允许应用请求的数量（caps.app_instances.limit：免费版 5，付费版 500）：超出会被拒绝，返回 403 plan_cap_reached；在允许的套餐上请求的数值会保留，但受当前套餐数值的限制。null：未指定数量的应用使用套餐的数值（caps.app_instances.default：免费版 2，付费版 50），如果 min_instances 更大则用它。告诉节点的数值，不超过账户除其他运行中资源外还能容纳的运行量，也不少于应用当前运行的实例数。
  
  minimum: 1
  concurrencyinteger | nullrequired
  单个实例同时处理的上限：边缘节点发给它的请求，加上它在项目网络上打开的连接（经由其服务的地址，节点会按连接把它们分给各个实例；或者直接连到它自己的地址）。达到上限的实例即为已满，更多的请求会创建新实例。null（未设置时的值）：没有上限。此时节点会在现有实例的 CPU 或内存接近其规格时增加实例，应用不必猜一个数字；一次只处理一个请求的服务应设为 1。
  
  maximum: 1000 · minimum: 1
  sleep_after_msinteger | nullrequired
  实例在没有请求时最多等待多久就停止，单位为毫秒。在这个上限以内，节点根据应用自己的流量选择等待时间：在应用最近一段时间里两次请求之间的间隔上，比较多运行一秒空闲与停止再恢复所花的 CPU 时间，选出成本最低的等待时间；这样，请求间隔比停止成本还短的应用会一直运行，请求间隔很长的应用则在最后一个响应结束后立即停止（0：总是立即停止）。null（未设置时的值）：平台的上限，三秒。设置过 100（2026年10月28日之前的默认值）的应用，从那天起视为 null。持续停止的实例会在 delete_after_ms 后被其节点删除，下一个需要实例的请求会得到一个新实例；min_instances 保持运行的实例既不会停止也不会删除。
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  在实例因空闲而停止之前多久，向连接到其客户机 /run/sbx/awake 的程序发送一行 sleep N，单位为毫秒：程序可以借此写出手头的数据、关闭连接，或者发起保持，从而推迟停止。无论它们是否响应，停止都会在这段时间之后到来；没有程序连接时，不会推迟。键控实例也会收到通知。0 或 null：不通知（默认）。
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  实例中的程序发起的保持，在空闲时间到期后最多还能让实例运行多久，单位为毫秒：程序连接 /run/sbx/awake，如果某个请求在响应之后还有后续工作，就在响应它之前发送 +，工作完成后发送 -（或关闭连接，或退出）；最后一个保持解除 sleep_after_ms 之后，实例停止。超过这个时间，无论有什么保持，实例都会停止；如果 sleep_notice_ms 要求通知，会先向已连接的程序发送 sleep N cap。保持期间实例在运行，并按运行计量。0：不理会保持。null：30000（默认）。
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  实例空闲多久后被删除，与停止使用同一个起算点：下一个需要实例的请求会得到一个新实例，即版本模板的克隆，不含被删除的实例在内存和磁盘中积累的东西（需要长久保存的数据请放在存储卷或数据库中）。一秒到一小时，一小时是平台的时间，也是上限：超出会被拒绝 (400 invalid_field)，需要保持预热的实例应计入 min_instances。null（未设置时的值）：节点的一小时 (--app-delete-after-seconds)。修改对应用现有的实例和之后创建的实例同样有效：每个节点至少每秒按应用当前的时间检查一次每个实例。不适用于应用的键控实例，键控实例用 keys.delete_after_idle_ms。
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  已停止的实例在保存内存并真正休眠之前保持暂停多久，单位为毫秒：暂停时，下一个请求在一两毫秒内得到响应，内存照常计量；休眠时，唤醒要多几毫秒，只计量它保存的数据。节点会把它限制在节点让任何实例保持暂停的最长时间内（十分钟）；宿主机内存不足、其他虚拟机需要占用槽位，或者有人请求休眠，都会让它更早休眠。null（默认）：节点的最长时间。数据库的 suspend_after_seconds 就是其应用的这一设置。
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  每天的某个 UTC 时刻 (HH:MM)，在此时唤醒应用中处于休眠状态的键控实例和有状态服务的实例，让它们完成等待唤醒才能做的工作（比如数据库维护）；节点根据应用请求创建和删除的实例只会被请求唤醒。唤醒本身不算活动：唤醒后运行的东西才算，运行完毕后实例会再次休眠。此外，无论这里怎么设置，有状态服务的实例都会为其 PostgreSQL 服务器 pg_cron 任务的下一次运行而被唤醒。null（默认）：不唤醒。数据库的 wake_daily_at 就是其应用的这一设置。
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  以下之一：
  object
  null
  egressobject | nullrequired
  与沙箱相同的出站规则（default、allow、deny、http、inject），没有时为 null；按调用给出的原样保存（PATCH 会像节点那样按键逐个合并）。规则立即生效，不产生新版本：服务该应用的节点会把它们应用到其组内的每个实例上，包括现有的实例（运行中的实例对其已有连接也生效）和之后创建的实例；键控实例不受这些规则约束。控制平面只检查它们是不是由这些键组成、不超过 256 KiB 的对象：规则的内容由节点在应用时检查，节点读不懂其规则的实例，所有出站流量都会被拒绝（节点日志会说明原因）。
  
  defaultoptionalallow或deny或null
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  任何连接都到达不了的端口，TCP 或 UDP，无论连往哪里，也无论规则的其他部分怎么说。浏览器会话的规则总是包含 25、465、587 以及矿池监听的端口（3333、4444、5555、7777、14444、45700）：无论其规则如何修改，控制平面都会把它们加上。
  
  metadata映射，值为stringrequired
  logsobjectrequired
  应用日志包含哪些内容，每一项为给出的值或默认值 (AppLogSettings)。
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  是否在其默认域名 (url) 上响应。
  
  depends_on数组，元素为objectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliases数组，元素为stringrequired
  endpoint_modestringrequired
  drivesoptional数组，元素为object
  其实例挂载的云盘 (AppCreate.drives)：没有指定时为空列表 []。
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptional数组，元素为object
  每个键的实例自有的云盘 (AppCreate.key_drives)：没有给出时为空列表 []。
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  只有给出为 true 时才会出现。
  
  runtimeoptional
  运行时设置 (AppCreate.runtime)。null：没有。
  
  以下之一：
  Runtime
  ulimits映射，值为RuntimeLimitGivenrequired
  sysctls映射，值为stringrequired
  tmpfs数组，元素为objectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  servers数组，元素为stringrequired
  search数组，元素为stringrequired
  options数组，元素为stringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  应用请求的链路追踪包含哪些内容，每一项为给出的值或默认值 (AppTraceSettings)：sample_rate 为 0 时不产生任何 span。
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumes数组，元素为objectrequired
  服务挂载的项目存储卷。
  
  modelstring | nullrequired
  它在模型中的名称。null：为有状态服务挂载但未命名卷的路径创建的。
  
  namestringrequired
  它在项目中的名称。
  
  idstring | nullrequired
  null：尚未创建 (to_make)。
  
  pattern: ^vol-
  sharedbooleanrequired
  有多个服务挂载它，或者某个服务有多个实例：每个服务的每个实例同时挂载它。
  
  statusto_make或made或there或externalrequired
  to_make：导入会创建它（试运行时对将要创建的存储卷这样说明）；made：本次导入创建了它；there：之前的导入创建了它，或者已有同名的存储卷；external：模型把它标为 external，而项目中已有它。
  
  used_by数组，元素为stringrequired
- secrets数组，元素为objectrequired
  模型中授予服务的 secrets。
  
  modelstringrequired
  它在模型中的名称。
  
  namestringrequired
  保存它的项目机密：即模型中的名称，其中机密名称不允许的每个字符都写成下划线。
  
  therebooleanrequired
  项目中是否已有它。导入（非试运行）时如果它还不存在，会被拒绝，返回 404 secret_not_found。
  
  used_by数组，元素为stringrequired
- left_out数组，元素为objectrequired
  属于未启用 profile 的服务，导入不会处理它们。
  
  namestringrequired
  profiles数组，元素为stringrequired
- absent数组，元素为stringrequired
  项目中有而模型中没有的服务：保持原样。
- deploystring | nullrequired
  导入触发的部署 (GET /v1/deploys/{id})。null：试运行，或者没有服务需要新版本。
  
  pattern: ^dpl-
}
accountsoptional数组，元素为object
随 sole_owner 返回：该用户是唯一所有者的那些账户。
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

404

app_not_found：项目中没有该应用。其他项目的应用对它来说不存在。

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
随 already_moving 返回：该沙箱正在进行的迁移。
upgrade_idoptionalstring
随 upgrade_in_progress（该键尚未结束的升级）、upgrade_started（已开始的升级）和 rollback_gone（回退被拒绝的那次升级）返回：即那次升级。

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
随 move_over、move_going_back 和 move_taken_over 返回 (POST /internal/moves/{id}/cancel)：迁移的当前状态。
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  节点名称；之后已从记录中消失的节点为 null。
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  节点名称；之后已从记录中消失的节点为 null。
- epochintegerrequired
  迁移开始时表中记录的沙箱纪元：旧节点在这个纪元释放它，新节点在纪元加一时接管它，旧节点在纪元加二时收回它，从对象存储接管则在纪元加三时。
  
  minimum: 1
- stepstringrequired
  迁移的进展：releasing（正在请旧节点释放它；表中记录它在旧节点上）、taking_over（正在请新节点接管它；表中记录它在新节点上）、reclaiming（新节点拒绝了它，正在请旧节点收回）、restoring（旧节点没有保留它的任何东西，正从对象存储接管）、done（已在新节点上）、failed（留在原处，或回到了原处，或停在某个时间无法消除的故障或运营方的取消发生时所在的位置：error 说明原因）。
- whystringrequired
  发起迁移的原因：运营方的迁移、撤离或恢复。
- wakebooleanrequired
  新节点是否唤醒它：按调用的指定，或按迁移开始时它的状态（是否在运行）。
- from_storebooleanrequired
  新节点只从对象存储接管它。
- releaseobject | nullrequired
  旧节点释放时的响应（sandboxd/openapi/openapi.json，releaseSandbox），不含释放所用的密钥；响应之前为 null。
- takeoverobject | nullrequired
  结束迁移的那次接管的响应（节点文档中的 takeoverSandbox）：磁盘和内存来自哪里 (source)、各用了多长时间 (ms)、memory；之前为 null。
- errorrequired
  失败的迁移：失败原因（如果被带回旧节点，则为新节点的拒绝原因）；已完成的迁移：null；进行中的迁移：如果当前步骤要再次请求，则为该步骤上次得到的答复。
  
  以下之一：
  object
  null
- attemptsintegerrequired
  当前步骤已请求了多少次，仍没有得到确定的答复。
  
  minimum: 0
- next_attempt_atstring | nullrequired
  该步骤何时再次请求；不在等待时为 null。
  
  format: date-time
- batchstring | nullrequired
  它所属的撤离 (evc-…) 或恢复 (rcv-…)。
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
随 lease_held 返回：节点最后获得的租约最晚可以持有到何时，再加上让节点察觉租约到期所需的时间（在此之前 recoverNode 会被拒绝）。

format: date-time
activeoptionalobject | null
随 standby 返回：备用副本最后一次读取租约时的活动副本；没有副本持有租约时为 null。
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
随 secret_host_not_allowed 返回：机密可以发往的主机，即机密上设置的主机；没有设置时为 null（节点的 SecretHosts）。
problemsoptional数组，元素为object
随 invalid_definition 返回：定义中的每个问题，各附其位置和内容。
- atstringrequired
  在定义中的位置，用点分隔的路径 (services.web.port)；针对整个定义时为空。
- messagestringrequired
}
reportoptionalobject
随 compose_refused 返回：导入的报告，说明拒绝了什么、为什么以及要改什么。
- objectcompose_importrequired
- namestring | nullrequired
  模型的 name：即每个服务的标签 compose.project。null：模型没有名称。
- dry_runbooleanrequired
- strictbooleanrequired
- profiles数组，元素为stringrequired
- treatmentsobjectrequired
  报告中每种处理方式各有多少项。
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- items数组，元素为objectrequired
  模型的顶层元素：name，以及每个卷、网络、config、secret 和扩展。
  
  atstringrequired
  在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。
  
  treatmentdone或adapted或ignored或refusedrequired
  done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。
  
  whystringrequired
  changestring | nullrequired
  被拒绝的项：要改什么。其他情况为 null。
- services数组，元素为objectrequired
  导入所采纳的服务，按模型中的顺序。
  
  namestringrequired
  服务的名称，也是其应用的名称。
  
  app_idstring | nullrequired
  其应用。null：试运行，且项目中没有该服务。
  
  pattern: ^app-
  statuscreated或changed或unchangedrequired
  导入对其应用做了（试运行时为将会做）什么：创建、写入变化的部分，或什么都不做。
  
  kindservice或jobrequired
  job：模型中有服务等待它完成，它会在每次需要它的部署中运行到结束。
  
  statefulbooleanrequired
  它挂载自己的存储卷：只有一个实例，由该实例持有存储卷。
  
  versionbooleanrequired
  导入的部署是否为它创建版本：即解析引用后其版本的构成与当前版本不同。
  
  items数组，元素为objectrequired
  atstringrequired
  在模型中的位置：对服务而言，是其属性（ports[0]、depends_on.db、environment.KEY），针对整个服务时为空；对顶层而言，是元素 (volumes.db-data)。
  
  treatmentdone或adapted或ignored或refusedrequired
  done：在平台上含义相同；adapted：平台用另一种方式实现同样的效果；ignored：只对本地运行有意义（带 strict 时会被拒绝）；refused：平台做不到，而忽略它会让程序悄悄出错。
  
  whystringrequired
  changestring | nullrequired
  被拒绝的项：要改什么。其他情况为 null。
  
  appobjectrequired
  导入写入的服务应用字段：其版本的构成，以及立即生效的设置。
  
  imagestring | nullrequired
  应用下一个版本的构成，连同其后的七个字段：即其最新版本的构成，加上此后的修改。null：应用没有镜像，也没有版本。
  
  image_pull_secretstring | nullrequired
  保存镜像仓库凭据的机密的名称。任何响应都不包含其值。null：没有。
  
  start_commandrequired
  以下之一：
  StartCommand
  null
  start_argsrequired
  放在镜像 ENTRYPOINT 之后、取代其 CMD 的内容。null：使用镜像的 CMD，或者整个 start_command。
  
  以下之一：
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  判断实例已启动的方式，版本的模板会在实例启动后保存：三者必须恰好给出一个。前两种从实例外部检查，所以服务必须监听所有地址 (0.0.0.0)。
  
  httpoptionalstring
  一个以 / 开头的路径：在应用端口上对它发起 GET，返回 200 到 399 之间的状态码。
  
  tcpoptionaltrue
  应用端口接受连接。
  
  commandoptional
  在实例中执行成功的一条命令。由实例的 shell 运行：参数列表会被写成一行交给它。
  
  以下之一：
  string
  array<string>
  env映射，值为stringrequired
  secrets映射，值为stringrequired
  机密的名称。任何响应都不包含值。
  
  sizeobjectrequired
  单个实例最多能使用的资源。按实际用量计费。
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  偶数个 MiB（即节点为虚拟机加载内存所用的 2 MiB 页的整数倍），以字节表示。其他任何大小都返回 400 invalid_field（param 为 size.memory_bytes）：没有节点会创建这种大小的实例，正如没有节点会创建这种大小的沙箱（节点的 SandboxLimitsCreate.memory_bytes）。
  
  minimum: 134217728
  volumes数组，元素为objectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  只有给出为 true 时才会出现。
  
  kindstringrequired
  files数组，元素为objectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  以下之一：
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regions数组，元素为stringrequired
  按 na、eu、ap 的顺序。
  
  scaleobjectrequired
  min_instancesintegerrequired
  无论有没有请求，应用在一个区域内保持运行的实例数：即下限。该区域服务该应用的节点按分摊 max_instances 的方式分摊它（两个节点、下限为 2：各一个；下限为 1：一个，在最先尝试的节点上；下限为 5：三个和两个），不在线的节点由其他节点补足。节点在收到通知时就创建自己那部分，而不是等到第一个请求，也不会因为空闲而停止或删除这些实例；它们按运行中的实例计量。0（未设置时的值）：没有下限。调低后，超出部分的实例从那一刻起视为空闲，并像空闲实例一样被停止和删除。最多为 max_instances（如果给出），且不超过账户套餐允许应用在一个区域请求的数量（caps.app_instances.limit：5、50 和 500）：超出会被拒绝，返回 403 plan_cap_reached。
  
  minimum: 0
  max_instancesinteger | nullrequired
  应用在一个区域内最多有多少个实例：由该区域服务该应用的节点分摊。最多为账户套餐允许应用请求的数量（caps.app_instances.limit：免费版 5，付费版 500）：超出会被拒绝，返回 403 plan_cap_reached；在允许的套餐上请求的数值会保留，但受当前套餐数值的限制。null：未指定数量的应用使用套餐的数值（caps.app_instances.default：免费版 2，付费版 50），如果 min_instances 更大则用它。告诉节点的数值，不超过账户除其他运行中资源外还能容纳的运行量，也不少于应用当前运行的实例数。
  
  minimum: 1
  concurrencyinteger | nullrequired
  单个实例同时处理的上限：边缘节点发给它的请求，加上它在项目网络上打开的连接（经由其服务的地址，节点会按连接把它们分给各个实例；或者直接连到它自己的地址）。达到上限的实例即为已满，更多的请求会创建新实例。null（未设置时的值）：没有上限。此时节点会在现有实例的 CPU 或内存接近其规格时增加实例，应用不必猜一个数字；一次只处理一个请求的服务应设为 1。
  
  maximum: 1000 · minimum: 1
  sleep_after_msinteger | nullrequired
  实例在没有请求时最多等待多久就停止，单位为毫秒。在这个上限以内，节点根据应用自己的流量选择等待时间：在应用最近一段时间里两次请求之间的间隔上，比较多运行一秒空闲与停止再恢复所花的 CPU 时间，选出成本最低的等待时间；这样，请求间隔比停止成本还短的应用会一直运行，请求间隔很长的应用则在最后一个响应结束后立即停止（0：总是立即停止）。null（未设置时的值）：平台的上限，三秒。设置过 100（2026年10月28日之前的默认值）的应用，从那天起视为 null。持续停止的实例会在 delete_after_ms 后被其节点删除，下一个需要实例的请求会得到一个新实例；min_instances 保持运行的实例既不会停止也不会删除。
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  在实例因空闲而停止之前多久，向连接到其客户机 /run/sbx/awake 的程序发送一行 sleep N，单位为毫秒：程序可以借此写出手头的数据、关闭连接，或者发起保持，从而推迟停止。无论它们是否响应，停止都会在这段时间之后到来；没有程序连接时，不会推迟。键控实例也会收到通知。0 或 null：不通知（默认）。
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  实例中的程序发起的保持，在空闲时间到期后最多还能让实例运行多久，单位为毫秒：程序连接 /run/sbx/awake，如果某个请求在响应之后还有后续工作，就在响应它之前发送 +，工作完成后发送 -（或关闭连接，或退出）；最后一个保持解除 sleep_after_ms 之后，实例停止。超过这个时间，无论有什么保持，实例都会停止；如果 sleep_notice_ms 要求通知，会先向已连接的程序发送 sleep N cap。保持期间实例在运行，并按运行计量。0：不理会保持。null：30000（默认）。
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  实例空闲多久后被删除，与停止使用同一个起算点：下一个需要实例的请求会得到一个新实例，即版本模板的克隆，不含被删除的实例在内存和磁盘中积累的东西（需要长久保存的数据请放在存储卷或数据库中）。一秒到一小时，一小时是平台的时间，也是上限：超出会被拒绝 (400 invalid_field)，需要保持预热的实例应计入 min_instances。null（未设置时的值）：节点的一小时 (--app-delete-after-seconds)。修改对应用现有的实例和之后创建的实例同样有效：每个节点至少每秒按应用当前的时间检查一次每个实例。不适用于应用的键控实例，键控实例用 keys.delete_after_idle_ms。
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  已停止的实例在保存内存并真正休眠之前保持暂停多久，单位为毫秒：暂停时，下一个请求在一两毫秒内得到响应，内存照常计量；休眠时，唤醒要多几毫秒，只计量它保存的数据。节点会把它限制在节点让任何实例保持暂停的最长时间内（十分钟）；宿主机内存不足、其他虚拟机需要占用槽位，或者有人请求休眠，都会让它更早休眠。null（默认）：节点的最长时间。数据库的 suspend_after_seconds 就是其应用的这一设置。
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  每天的某个 UTC 时刻 (HH:MM)，在此时唤醒应用中处于休眠状态的键控实例和有状态服务的实例，让它们完成等待唤醒才能做的工作（比如数据库维护）；节点根据应用请求创建和删除的实例只会被请求唤醒。唤醒本身不算活动：唤醒后运行的东西才算，运行完毕后实例会再次休眠。此外，无论这里怎么设置，有状态服务的实例都会为其 PostgreSQL 服务器 pg_cron 任务的下一次运行而被唤醒。null（默认）：不唤醒。数据库的 wake_daily_at 就是其应用的这一设置。
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  以下之一：
  object
  null
  egressobject | nullrequired
  与沙箱相同的出站规则（default、allow、deny、http、inject），没有时为 null；按调用给出的原样保存（PATCH 会像节点那样按键逐个合并）。规则立即生效，不产生新版本：服务该应用的节点会把它们应用到其组内的每个实例上，包括现有的实例（运行中的实例对其已有连接也生效）和之后创建的实例；键控实例不受这些规则约束。控制平面只检查它们是不是由这些键组成、不超过 256 KiB 的对象：规则的内容由节点在应用时检查，节点读不懂其规则的实例，所有出站流量都会被拒绝（节点日志会说明原因）。
  
  defaultoptionalallow或deny或null
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  任何连接都到达不了的端口，TCP 或 UDP，无论连往哪里，也无论规则的其他部分怎么说。浏览器会话的规则总是包含 25、465、587 以及矿池监听的端口（3333、4444、5555、7777、14444、45700）：无论其规则如何修改，控制平面都会把它们加上。
  
  metadata映射，值为stringrequired
  logsobjectrequired
  应用日志包含哪些内容，每一项为给出的值或默认值 (AppLogSettings)。
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  是否在其默认域名 (url) 上响应。
  
  depends_on数组，元素为objectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliases数组，元素为stringrequired
  endpoint_modestringrequired
  drivesoptional数组，元素为object
  其实例挂载的云盘 (AppCreate.drives)：没有指定时为空列表 []。
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptional数组，元素为object
  每个键的实例自有的云盘 (AppCreate.key_drives)：没有给出时为空列表 []。
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  只有给出为 true 时才会出现。
  
  runtimeoptional
  运行时设置 (AppCreate.runtime)。null：没有。
  
  以下之一：
  Runtime
  ulimits映射，值为RuntimeLimitGivenrequired
  sysctls映射，值为stringrequired
  tmpfs数组，元素为objectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  servers数组，元素为stringrequired
  search数组，元素为stringrequired
  options数组，元素为stringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  应用请求的链路追踪包含哪些内容，每一项为给出的值或默认值 (AppTraceSettings)：sample_rate 为 0 时不产生任何 span。
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumes数组，元素为objectrequired
  服务挂载的项目存储卷。
  
  modelstring | nullrequired
  它在模型中的名称。null：为有状态服务挂载但未命名卷的路径创建的。
  
  namestringrequired
  它在项目中的名称。
  
  idstring | nullrequired
  null：尚未创建 (to_make)。
  
  pattern: ^vol-
  sharedbooleanrequired
  有多个服务挂载它，或者某个服务有多个实例：每个服务的每个实例同时挂载它。
  
  statusto_make或made或there或externalrequired
  to_make：导入会创建它（试运行时对将要创建的存储卷这样说明）；made：本次导入创建了它；there：之前的导入创建了它，或者已有同名的存储卷；external：模型把它标为 external，而项目中已有它。
  
  used_by数组，元素为stringrequired
- secrets数组，元素为objectrequired
  模型中授予服务的 secrets。
  
  modelstringrequired
  它在模型中的名称。
  
  namestringrequired
  保存它的项目机密：即模型中的名称，其中机密名称不允许的每个字符都写成下划线。
  
  therebooleanrequired
  项目中是否已有它。导入（非试运行）时如果它还不存在，会被拒绝，返回 404 secret_not_found。
  
  used_by数组，元素为stringrequired
- left_out数组，元素为objectrequired
  属于未启用 profile 的服务，导入不会处理它们。
  
  namestringrequired
  profiles数组，元素为stringrequired
- absent数组，元素为stringrequired
  项目中有而模型中没有的服务：保持原样。
- deploystring | nullrequired
  导入触发的部署 (GET /v1/deploys/{id})。null：试运行，或者没有服务需要新版本。
  
  pattern: ^dpl-
}
accountsoptional数组，元素为object
随 sole_owner 返回：该用户是唯一所有者的那些账户。
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}