403 deployment_management_forbidden,应用 Token 在路由权限检查中被拒绝。这不是创建 hosted 部署的 API。
读取配置
GET /v1/deployment 返回 200,包含 config、revision、restart_required、可选 ingress 状态、environment_overrides。Revision 是解析并填入默认值后的配置 JSON 的 SHA-256;restart_required 比较保存版本与当前进程启动版本。
500 deployment_configuration_invalid。
替换配置
PUT /v1/deployment 接受严格 {config,expected_revision}。Expected_revision 必须是 64 字符字符串,匹配 GET 返回的当前版本。Config 是完整替换,不是合并:
No-proxy 允许
* 或 schema 的主机式模式,不接受 URL、任意 shell 表达式或通用正则表达式。环境优先级见配置,保存值未必覆盖显式进程环境。
将 GET 的 revision 和完整预期配置写入 deployment-update.json。例如 {config:{no_proxy:[],ingress:{mode:"cloudflare"}},expected_revision:...} 选择临时入口并删除已保存 outbound_proxy。文件必须使用真实 JSON,不要原样复制此说明性记法。
{config,revision,restart_required:true}。实现获得独占文件锁、检查版本、写入私有临时文件并原子替换 deployment.json;不重启进程,也不建立已验证隧道。省略字段会恢复默认值,包括 cloudflare 入口,不能通过省略保留旧配置。
409 deployment_configuration_changed 表示版本过期,应重新读取并核对完整配置意图。409 deployment_configuration_busy 表示更新锁存在,处理锁前先调查正在写入的进程。响应丢失可能发生在文件已替换之后,重试前先读取保存版本和配置,并通过本地管理流程安排重启。后续重启失败不会自动回滚已保存配置。
重试临时凭据入口
POST /v1/deployment/ingress/retry 无必需请求体,通常返回 200 和当前可用 ingress 状态。运行环境 HEXAGON_ACCESS_TUNNEL 必须等于 cloudflare,否则 409 development_ingress_disabled。
停止入口
POST /v1/deployment/ingress/stop 无必需请求体,等待已配置 ingress 服务停止后返回 200 和可用状态。它不改写已保存入口模式,不禁用未来进程启动,也不关闭 Sessions。
409 active_run,检查不限于当前租户。停止入口可能影响后续任务凭据交付,恢复工作前确认就绪。两项操作均没有请求幂等键,也不改变已保存配置版本。
严格更新请求不合法返回 400 invalid_request。来源:配置与环境组合、路由条件、入口生命周期。示例假定 HEXAGON_API_URL 不带 /v1 并使用本地 owner Token。本轮没有修改配置、进程或隧道。
SDK 示例:先保存意图,再修改设置
使用已初始化的 local-workspace owner 客户端。这些独立函数演示明确切换至一个已经部署的外部 HTTPS 凭据入口,不会创建主机、安装证书或配置反向代理。仅定义函数不改变设置。选择实际 origin 前先阅读网络指南。config:status、environment_overrides、revision 等属于响应元数据,不是配置字段。更新时由服务端校验 origin 和完整配置,辅助函数本身不证明配置正确。
提交函数发送最初观察到的 revision。deployment_configuration_changed 要求与最新保存配置比较,不能自动换用新 revision;成功响应丢失后也可能出现相同冲突。遇到 deployment_configuration_busy 应调查正在写入的操作,不删除其锁文件。保存返回新 config、revision 和 restart_required,不会重启控制平面或验证入口;即使重启,显式进程环境仍可能覆盖保存值。
重试和停止是分别选择的运维操作,不是每次保存后的固定步骤。临时入口重试要求运行中的 cloudflare 模式;保存 external 模式不会让它成为外部端点修复接口。重试响应可能描述仍在进行的尝试。停止不修改保存的 ingress 配置,不关闭 Session,也不禁止下次启动。数据库中任意非终态 Run 都会阻止这两个操作,不只检查调用方租户。后续调用 deployment GET 是状态观察,不保证入口就绪。
通用停止请求使用不带 /v1 的 /deployment/ingress/stop,补足便捷方法缺口,不绕过角色或活动 Run 检查。若可选 ingress 服务未提供状态响应体,操作被接受后仍可能发生 JSON 解码失败;应查询 deployment/health,不能推断操作没有发生。示例不实现重启、轮询期限或自动重试。本地语法和类型检查与真实配置迁移、隧道验证是不同范围。
下一步:本地工作区、网络配置、HTTP 总览。