> ## 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.

# 管理本地工作区

本地工作区包含控制平面配置、私有身份与加密密钥；数据库保存任务和连接记录。两者共同构成可恢复的部署，不能只保留其中一份。

先完成[安装](https://docs.hexagon.autos/zh-CN/start/install.md)。以下命令在仓库根目录执行，使用与你首次启动相同的 DATABASE\_URL 与 HEXAGON\_DATA\_DIR。

## 日常命令

```sh theme={null}
npm run local -- doctor
npm run local -- status
npm run local -- start
```

`doctor` 检查 Node、数据库以及按用途需要的 Python、OpenSSH、cloudflared。可选依赖缺失不等于所有功能不可用。`status` 返回管理服务的健康信息；服务管理与凭据入口健康不同。

默认数据目录为 `.local/control-plane`。指定 `HEXAGON_DATA_DIR` 后持续使用同一路径，避免误发现另一个工作区。Python `Hexagon.local(data_directory=...)` 和 TypeScript `Hexagon.local({dataDirectory: ...})` 可以显式选择本地数据目录。

不要手工把 owner Token 复制到前端。Console 与 SDK 使用各自的本地发现流程。重启产生新的本地浏览器身份；它不意味着数据库中的业务记录丢失。

## 保持工作区选择一致

仅使用不同数据目录，并不能构成完整隔离的部署。两个工作区并行运行时，应分别配置 PostgreSQL 目标、私有数据目录、API 端口、预览端口和凭据 listener 端口，各自配置入口路由。launcher 使用 `PORT` 探测 `127.0.0.1`，并读取所选目录的 owner 文件；用不同端口或目录执行 status/stop，可能查询另一个服务或无法鉴权。每个生命周期命令都应沿用相同环境。

| 配置 | 重启前后必须保持对应 |
| - | - |
| `DATABASE_URL` | 原任务、连接记录与 schema |
| `HEXAGON_DATA_DIR` | 匹配的 owner 身份、加密密钥与保存配置 |
| `PORT` | launcher 健康/身份检查与 SDK API 地址 |
| `PREVIEW_PORT` / `HEXAGON_ACCESS_PORT` | 本部署独立 listener 及对应路由 |

不要让两个 launcher 共用数据目录，不复制另一工作区的 owner 文件绕过鉴权，也不删除目录来解决未知云操作。多个工作区是明确配置的独立部署，不是内置多工作区切换器或高可用拓扑。

## 修改持久配置

在 Console Settings → Network & ingress 编辑，或准备无凭据的配置文件：

```json theme={null}
{"no_proxy":[],"ingress":{"mode":"cloudflare"}}
```

```sh theme={null}
npm run local -- configure /absolute/path/deployment-config.json
npm run local -- restart
```

更新使用 revision 冲突保护。显式进程环境覆盖保存的网络配置，no\_proxy 合并并包含 loopback。配置文件不保存 Provider 密钥。需要持续关闭凭据入口时保存 disabled 模式；临时停止 tunnel 不是修改持久配置。

## 计划停机

先完成或取消活动 Run，关闭不用的云 Session 并确认删除，再运行：

```sh theme={null}
npm run local -- stop
```

启动器发现活动 Run 会拒绝停止。它核验服务身份和 PID 后才发信号，等待优雅退出，不会无条件强杀。如果进程存在但无法认证，检查私有 `service.log`、正确端口与工作区，而不是删除 PID 文件并另启一份。

控制平面停机期间无法保证按时执行云资源期限。未决清理记录保存在数据库，启动后仍需核对；停止本机服务不删除云资源。

## 维护完成标准

用同一配置重启后，历史 Session、连接和产物仍可读，凭据可用，新的测试任务能够执行且清理确认。只看到管理端口监听不算云路径健康。备份前同时核对数据库、密钥和部署配置，参阅[现有备份流程](https://github.com/NexusFox88/docs/blob/main/resources/docs/local-installation.md#backup-upgrade-and-restore)。

依据：[本地启动器](https://github.com/NexusFox88/docs/blob/main/resources/tooling/local.ts)、[部署配置](https://github.com/NexusFox88/docs/blob/main/resources/modules/deployment/settings.ts)。下一步：[网络入口](https://docs.hexagon.autos/zh-CN/operate/networking.md)、[资源对账](https://docs.hexagon.autos/zh-CN/operate/reconciliation.md)、[备份恢复](https://docs.hexagon.autos/zh-CN/operate/backup-restore.md)。

[11 月 18 日本地发行包演练](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-18-local-beta-delivery.md)记录了独立云任务、停止后的工作区备份恢复、Session/连接留存与解密，以及恢复后的新云任务。这是有日期的 local 模式证据，不是本次重启了你的服务。


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