> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 本地部署配置 HTTP 契约

四个接口管理当前本地控制平面工作区，只有部署配置服务存在时才注册，要求 owner 身份并额外要求租户为 local-workspace。其他租户返回 `403 deployment_management_forbidden`，应用 Token 在路由权限检查中被拒绝。这不是创建 hosted 部署的 API。

## 读取配置

`GET /v1/deployment` 返回 **200**，包含 config、revision、restart\_required、可选 ingress 状态、environment\_overrides。Revision 是解析并填入默认值后的配置 JSON 的 SHA-256；restart\_required 比较保存版本与当前进程启动版本。

```sh theme={null}
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" "$HEXAGON_API_URL/v1/deployment"
```

Config 包含可选 outbound\_proxy、no\_proxy、ingress。配置了 ingress 服务时，状态包含 state、attempts、checked\_at，可能有 code。Environment\_overrides 包含 proxy/ingress 布尔提示，不暴露实际值，也不枚举全部环境覆盖。Deployment.json 不存在时使用默认值；文件不可读或内容无效返回 `500 deployment_configuration_invalid`。

## 替换配置

`PUT /v1/deployment` 接受严格 `{config,expected_revision}`。Expected\_revision 必须是 64 字符字符串，匹配 GET 返回的当前版本。Config 是完整替换，不是合并：

| 字段 | 契约 |
| - | - |
| outbound\_proxy | 可选 HTTP/HTTPS origin，不含用户名、密码、query、fragment 或非根路径 |
| no\_proxy | 默认空数组，最多 128 项，每项最多 253 字符且匹配支持的主机模式 |
| ingress | 默认 `{mode:"cloudflare"}`，按模式使用严格对象 |
| ingress.mode | cloudflare、disabled 或 external |
| ingress.url | 仅 external 必填，必须为符合上述 URL 限制的 HTTPS origin |

No-proxy 允许 `*` 或 schema 的主机式模式，不接受 URL、任意 shell 表达式或通用正则表达式。环境优先级见[配置](https://docs.hexagon.autos/zh-CN/reference/configuration.md)，保存值未必覆盖显式进程环境。

将 GET 的 revision 和完整预期配置写入 deployment-update.json。例如 `{config:{no_proxy:[],ingress:{mode:"cloudflare"}},expected_revision:...}` 选择临时入口并删除已保存 outbound\_proxy。文件必须使用真实 JSON，不要原样复制此说明性记法。

```sh theme={null}
curl --fail-with-body --silent --show-error --request PUT \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @deployment-update.json "$HEXAGON_API_URL/v1/deployment"
```

成功返回 **200**、`{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`。

```sh theme={null}
curl --fail-with-body --silent --show-error --request POST \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/deployment/ingress/retry"
```

处理器发起 retry 后不等待完成，立即读取状态，因此成功响应不证明入口 ready。通过 deployment/health 查询并检查状态。Ingress 服务本身可选，不能仅因路由存在就假定一定返回状态对象或实际发起了尝试。

## 停止入口

`POST /v1/deployment/ingress/stop` 无必需请求体，等待已配置 ingress 服务停止后返回 **200** 和可用状态。它不改写已保存入口模式，不禁用未来进程启动，也不关闭 Sessions。

```sh theme={null}
curl --fail-with-body --silent --show-error --request POST \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/deployment/ingress/stop"
```

Retry 和 stop 都会在数据库存在**任何非终态 Run** 时返回 `409 active_run`，检查不限于当前租户。停止入口可能影响后续任务凭据交付，恢复工作前确认就绪。两项操作均没有请求幂等键，也不改变已保存配置版本。

严格更新请求不合法返回 `400 invalid_request`。来源：[配置与环境组合](https://github.com/NexusFox88/docs/blob/main/resources/modules/deployment/settings.ts)、[路由条件](https://github.com/NexusFox88/docs/blob/main/resources/apps/control-plane/server.ts)、[入口生命周期](https://github.com/NexusFox88/docs/blob/main/resources/modules/deployment/ingress.ts)。示例假定 HEXAGON\_API\_URL 不带 `/v1` 并使用本地 owner Token。本轮没有修改配置、进程或隧道。

## SDK 示例：先保存意图，再修改设置

使用已初始化的 local-workspace owner 客户端。这些独立函数演示明确切换至一个已经部署的外部 HTTPS 凭据入口，不会创建主机、安装证书或配置反向代理。仅定义函数不改变设置。选择实际 origin 前先阅读[网络指南](https://docs.hexagon.autos/zh-CN/operate/networking.md)。

```python theme={null}
from copy import deepcopy


def prepare_external_ingress(client, https_origin):
    current = client.deployment()
    config = deepcopy(current['config'])
    config['ingress'] = {'mode': 'external', 'url': https_origin}
    return {'config': config, 'expected_revision': current['revision']}


def apply_deployment_intent(client, intent):
    return client.update_deployment(intent['config'], intent['expected_revision'])


def retry_temporary_ingress(client):
    return client.retry_ingress()


def stop_current_ingress(client):
    return client.request('POST', '/deployment/ingress/stop')
```

```typescript theme={null}
type DeploymentIntent = { config: unknown; expected_revision: string };

async function prepareExternalIngress(client: Hexagon, httpsOrigin: string) {
  const current = await client.deployment();
  const config = structuredClone(current.config);
  config.ingress = { mode: 'external', url: httpsOrigin };
  return { config, expected_revision: current.revision } satisfies DeploymentIntent;
}

async function applyDeploymentIntent(client: Hexagon, intent: DeploymentIntent) {
  return await client.updateDeployment(intent.config, intent.expected_revision);
}

async function retryTemporaryIngress(client: Hexagon) {
  return await client.retryIngress();
}

async function stopCurrentIngress(client: Hexagon) {
  return await client.request('POST', '/deployment/ingress/stop');
}
```

准备函数读取当前 revision，复制整个 config，保留已保存的 outbound\_proxy 和 no\_proxy，只替换 ingress；这一步不写文件。先审阅并私下持久化意图，再单独提交。不要把 deployment GET 的整个响应当作 `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，不能推断操作没有发生。示例不实现重启、轮询期限或自动重试。本地语法和类型检查与真实配置迁移、隧道验证是不同范围。

下一步：[本地工作区](https://docs.hexagon.autos/zh-CN/operate/local-workspace.md)、[网络配置](https://docs.hexagon.autos/zh-CN/operate/networking.md)、[HTTP 总览](https://docs.hexagon.autos/zh-CN/reference/http.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.