跳转到主要内容
Hexagon 当前提供 npm 脚本和本地管理启动器,没有独立的 hexagon deploy 命令。源码命令在仓库根目录完成 npm ci 后执行。权威实现是 package.json与 tooling/local.ts。

调用方式与环境

不带子命令的 npm run local 默认执行 status。npm 的 -- 之后的参数传给启动器。启动器使用位置参数,不是通用选项解析器;没有独立 --help 分支,未知子命令会输出用法并失败。多余参数被忽略不代表支持该选项。 同一实例的命令使用一致的数据目录、数据库和端口。缺省数据库 URL 不会创建 PostgreSQL 或数据库。TEST_DATABASE_URL 用于测试,不会选择启动器数据库。部署网络配置见网络指南。 所有调用都会先创建尚不存在的数据目录,包括 status。除 status 外,还会取得目录中的独占 operation.lock,正常结束时释放。锁冲突不能直接通过删除文件解决,先确认是否仍有操作运行,再调查陈旧锁。

托管服务命令

启动成功输出包含状态、Console URL、owner 凭据文件与字段位置,以及凭据访问状态,不输出 owner Token。源码 npm run dev 在前台启动控制平面,不是托管启动器,也没有文件监听;直接启动前执行 npm run db:migrate。避免前台和托管实例意外同时处理同一数据集。 捕获的启动器错误写入 stderr,退出码为 1。正常命令退出零,除非检查主动设置失败码。npm 还会输出脚本包装信息,所以不能把 npm run 的全部 stdout 假设成单个 JSON 文档。就绪和清理结论都不能只看退出码。

保存部署配置

输入文件是配置对象,不是 API envelope。以下示例用于有意关闭凭据 ingress 的开发实例:
命令经过 schema 与 revision 检查后替换保存配置,不做局部合并;未填写字段采用 schema 默认值。ingress 可选 cloudflare、disabled、external,后者通过 url 提供 HTTPS origin。outbound_proxy 可选,no_proxy 默认空数组。精确 URL 约束见 settings.ts。 结果包含 revision 和 restart_required: true,不会自动重启。显式环境变量仍可能覆盖保存文件。关闭 ingress 后,受保护云执行无法访问控制平面凭据服务,不能把它作为正常云连接配置。外部 ingress 与代理设置见网络指南。

导出诊断

目标文件必须不存在,父目录必须存在。命令创建权限为 0600 的 JSON,输出 {"written":true}。它使用字段白名单的诊断投影,包含时间、平台、架构、Node、可达性和服务状态,不打包原始日志、任意健康字段、Token 或用户提示词。服务不可达时仍可生成报告并成功退出,应检查 reachable 与各状态。分享前审阅报告。

离线备份与恢复

先关闭全部 Session 并停止服务,显式选择对应的源数据库和数据目录。目标必须是新目录,父目录需存在。备份检查本地身份与加密材料匹配,用 pg_dump 导出所选 schema,并包含 master.key、owner.json、可选部署配置、数据库 dump 和完整性 manifest。结果报告目录、schema、文件与 state: verified。备份含秘密,必须保持私有。失败可能留下不完整目标,不能把它作为已验证备份复用。
目标数据库必须已经存在,且不含用户表、视图或序列。数据目录应不存在或为空,启动器锁除外。恢复检查 manifest 和哈希,执行 pg_restore,验证身份,返回 requires_start: true 和恢复的 schema,不自动启动服务或重建云资源。恢复的 schema 非默认值时,需配置对应 search path。备份恢复要求 PostgreSQL 客户端工具与相应权限。 恢复失败后不要盲目重试,可能已有数据库或 staging 变化。按备份恢复指南调查。backup_close_sessions_first、backup_identity_mismatch、restore_database_not_empty、restore_integrity_failed 指向不同问题,不能删除源身份来绕过检查。

失败、超时与部分完成

PostgreSQL 子进程辅助函数的期限为 120 秒,之后发送 SIGTERM,再过五秒可能发送 SIGKILL。这只针对其 pg_dump/pg_restore 子进程,不是本地启动器的控制平面 stop 命令;后者不会强杀。恢复子进程使用单个 PostgreSQL 事务,但后续身份检查和私有文件移动是另外的步骤,整个恢复过程不是一个原子操作。 备份结果 state: verified 表示备份过程完成了来源身份检查并写出 dump 与哈希,不代表已经演练恢复该备份。同样,恢复返回 requires_start: true 表示还需要验证服务启动与就绪。完整操作见备份恢复手册。

源码开发与验证脚本

发布检查器可在 npm 分隔符之后传入 --artifact <directory> 检查产物;模式扫描不等于完整秘密检测。证据范围、私有产物和门禁说明见测试指南。 实云脚本单独使用:verify:cloud -- <private-config> [harness ...]、verify:compatibility -- <private-config>、verify:serverless -- <provider> <harness-key>。它们可能创建资源并产生云端和模型费用,输入与范围也不同,运行前阅读测试指南。内部故障注入脚本不是安装步骤。 build:local 产出的发行目录使用不同的生成 package manifest,只提供 local、start、db:migrate。用 npm ci --omit=dev 安装依赖,再执行 npm run local -- start 或 npm start。不能假设源码验证脚本也存在于发行目录。本地构建成功不代表已有公开软件包或下载渠道。

本页验证范围

命令清单通过 npm run(退出 0)核对,该命令只列举脚本。随后在临时数据目录中执行了隔离启动器检查:stopped 状态、有效配置、服务不可达时导出诊断、拒绝覆盖诊断、未知命令、缺少配置输入、无效配置,共七项。确认了退出码、原文件保留、私有文件权限和锁释放,临时文件已清理。 这些检查不使用数据库,也没有启动或停止服务。迁移、备份恢复、运行实例就绪和云验收未在本检查中执行;上述操作语义依据启动器、配置、备份、诊断与构建实现核对,历史运维证据仍保留自己的范围和日期。 下一步:安装、本地工作区、测试指南。