使用 Hoist CLI 在 VPS 提供商上部署和管理应用、服务器、数据库、域名及环境变量。
Hoist CLI.Hoist是专门为AI代理而建立的AI-native CLI. 当从代理(非TTY)中调用时, 它自动输出结构化的JSON, 并跳过交互式提
功能概述
Hoist CLI.Hoist是专门为AI代理而建立的AI-native CLI. 当从代理(非TTY)中调用时, 它自动输出结构化的JSON, 并跳过交互式提是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
核心要点
- 使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
- 该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。
- 从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。
使用与执行
实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。
结果检查与注意事项
执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。
Hoist CLI
Hoist 是一款原生支持 AI 的命令行工具（CLI），专为 AI 代理（agent）设计。当从 agent（非 TTY 环境）中调用时，它会自动输出结构化 JSON 格式结果，并跳过所有交互式提示。你只需直接运行命令即可。
你的行为准则
你是用户的基础设施向导，请务必全面、透明：
- 执行任何操作前，必须先向用户清晰说明你将要做什么：包括即将运行的命令、将创建/修改/删除的资源，以及预估成本。
- 在执行任何涉及创建、修改或销毁资源的操作前，必须获得用户明确确认。这包括：创建服务器、部署应用、添加数据库、删除域名、轮换密钥、设置环境变量等。
- 切勿对关键部署参数做假设。若用户说“部署这个”，而
hoist.json中未明确定义目标服务器、服务或端口，则必须主动询问具体是哪个服务器、哪个服务、哪个端口。 - 当存在多个可选项（如地域、服务器类型、数据库版本）时，需清晰列出所有选项，并附带上下文信息（如价格、地理位置、规格），帮助用户做出知情决策。
- 每次操作完成后，必须验证是否成功：运行
hoist status并向用户报告结果。 - 若操作失败，须先排查原因再重试。请严格遵循下方的故障排查流程。
智能默认值
当 Hoist 从 agent 环境中被调用时，会自动检测并填充合理默认值：
- 若未指定
--service，则默认部署全部应用服务； - 若未指定
--server，则自动从hoist.json中对应服务的配置中解析； - 若未指定
--name，则自动生成随机服务器名称； - 默认使用最便宜的服务器类型和列表中的第一个可用地域。
尽管存在默认值，仍须始终向用户呈现完整执行计划，并在执行前获取确认。
适用场景
- “部署这个应用” →
hoist deploy - “创建一台服务器” →
hoist server create - “搭建 Postgres” →
hoist deploy --template postgres --server - “添加一个域名” →
hoist domain add example.com - “当前运行了什么？” →
hoist status - “出问题了” → 先运行
hoist logs，再运行hoist logs traefik，最后运行hoist doctor - “全面检查系统状态” →
hoist doctor
不适用场景
- 未设置环境变量时进行云服务商初始化：
hoist init和hoist provider add均需依赖HOIST_*_API_KEY环境变量，或必须在交互式人工终端中运行。 - 通用编程开发任务：Hoist 仅用于基础设施管理，不适用于代码编写。
决策树
Hoist 是否已安装？（`which hoist`）
+-- 否 → 运行：`npm install -g hoist-cli`
+-- 是 → Hoist 是否已配置？（`hoist provider list`）
+-- 否 → 是否已设置 HOIST_*_API_KEY 环境变量？
+-- 是 → 运行：`hoist init`
+-- 否 → 提示用户运行：`hoist init`
+-- 是 → hoist.json 是否存在？
+-- 否 → 在询问项目名称与服务后，创建 hoist.json
+-- 是 → 用户想做什么？
+-- 创建新服务器 → `hoist server create`
+-- 导入已有服务器 → `hoist server import --ip `
+-- 部署应用 → `hoist deploy`
+-- 添加数据库 → `hoist deploy --template postgres --server `
+-- 添加域名 → `hoist domain add `
+-- 设置环境变量 → `hoist env set KEY=VAL`
+-- 查看状态 → `hoist status`
+-- 出现异常 → `hoist logs ` + `hoist doctor`
敏感操作 —— 必须人工介入
| 命令 | 行为 |
|---|---|
hoist init |
若已设置 HOIST_*_API_KEY 环境变量，则自动完成配置；否则进入交互式流程，需提示用户手动运行该命令。 |
hoist provider add |
要求指定 --type 参数，并从对应 HOIST_*_API_KEY 环境变量中读取 API 密钥。若环境变量缺失，应提示用户先设置。 |
hoist keys rotate |
轮换所有服务器上的 SSH 密钥。执行前必须获得用户确认。 |
hoist server destroy |
永久销毁指定服务器。执行前必须获得用户确认。 |
hoist template destroy |
销毁数据库及其全部数据。执行前必须获得用户确认。 |
hoist domain delete |
移除域名及其 SSL 配置。执行前必须获得用户确认。 |
支持的环境变量：HOIST_HETZNER_API_KEY、HOIST_VULTR_API_KEY、HOIST_DIGITALOCEAN_API_KEY、HOIST_HOSTINGER_API_KEY、HOIST_LINODE_API_KEY、HOIST_SCALEWAY_API_KEY
命令列表
完整命令参考请查阅 COMMANDS.md。
- 云服务商管理：
provider add、provider list、provider test、provider update、provider set-default、provider delete - 服务器管理：
server create、server import、server list、server status、server ssh、server destroy、server regions、server types、server stats - 应用部署：
deploy、deploy --service、deploy --template、--server deploy --repo、--branch rollback --service - 模板管理：
template list、template info、template services、template inspect、template backup、template destroy、template stop/start/restart、template public、template private - 域名管理：
domain add、domain add、--service domain list、domain delete - 环境变量管理：
env set、KEY=VAL env get、env list、env delete、env import、env export、echo KEY=VAL | env set--stdin - 可观测性：
logs、logs traefik、logs、--follow status、doctor - 技能同步：
skills sync、skills export [dir] - 其他命令：
keys show、keys rotate、config validate、--status
项目配置
请读取项目根目录下的 hoist.json 文件以获取当前项目上下文。
{
"project": "my-app",
"servers": { "prod": { "provider": "hetzner-1" } },
"services": {
"api": { "server": "prod", "type": "app", "source": ".", "port": 3000 }
}
}
部署流程
请逐步引导用户完成部署，并在每步执行前请求确认：
- 服务器选择：用户希望使用哪台服务器？若尚无可用服务器，需询问其期望的云服务商、地域、服务器类型及名称，并提供各选项的价格与规格对比。
- 服务类型：是部署应用还是数据库？若项目中不存在 Dockerfile，则依据 DOCKERFILES.md 自动生成，并在部署前向用户展示内容。
- 域名配置：询问用户是否需要绑定自定义域名。用户需确保将
example.com和www.example.com均解析至该服务器 IP 地址。 - 环境变量：询问
DATABASE_URL、各类 API 密钥及其他运行时配置项。若刚创建数据库，应主动推荐连接字符串。 - 最终确认：汇总服务器、服务、域名、环境变量及预估成本，请求用户最终批准。
部署完成后
hoist status— 验证服务是否正常运行，并检查是否存在配置漂移（drift）hoist logs— 验证应用是否成功启动hoist domain add— 若用户有需求，则添加自定义域名并启用 SSL
添加数据库后
hoist template inspect— 获取数据库凭证与连接字符串hoist env set— 将连接字符串注入应用环境变量DATABASE_URL= hoist template public— 仅当用户明确要求开放公网访问时执行--server - 告知用户数据库已就绪，并说明应用是否已使用新连接字符串重启。
故障排查流程
当出现问题时，请按顺序使用以下工具进行诊断：
1. 检查应用日志
hoist logs--lines 200
重点关注：崩溃循环、启动错误、缺失环境变量、数据库连接失败、端口配置错误等。
2. 检查反向代理日志
hoist logs traefik --lines 200
重点关注：502 错误、ACME 证书申请失败、TLS 配置异常等。
3. 检查基础设施状态
hoist doctor
检查 SSH 连通性、Docker 运行状态、Traefik 服务、防火墙策略及云服务商认证状态。
4. 检查项目当前状态
hoist status
显示当前实际运行的服务与配置定义之间的差异，同时汇报漂移情况与资源状态。
常见问题与修复方案
| 现象 | 排查方法 | 修复方式 |
|---|---|---|
| 502 Bad Gateway | 依次运行 hoist logs 和 hoist logs traefik |
修复应用崩溃或端口不匹配问题，然后重新部署。 |
| 网站无法加载 | hoist status |
使用 hoist deploy --service 重新部署对应服务。 |
| SSL 证书无效 | hoist logs traefik |
确认 DNS 已正确解析至服务器 IP，并等待下一次 ACME 自动重试。 |
| DNS 未生效 | hoist domain list |
用户需自行添加或修正 DNS A 记录。 |
| 返回内容异常 | hoist logs |
修复应用逻辑并重新部署。 |
| 数据库无法连接 | hoist template inspect |
启动模板服务，或修正连接字符串。 |
何时执行回滚
仅当本次部署引入了回归缺陷（regression），且上一版本运行正常时，才应执行回滚。
hoist rollback --service
执行前必须获得用户确认，并在回滚完成后使用 hoist status 验证状态。
错误参考
| 错误信息 | 解决方案 |
|---|---|
Run hoist init first |
若已设置环境变量，则直接运行 hoist init；否则提示用户以交互方式运行该命令。 |
Provider not found |
运行 hoist provider list 查看已注册的提供商标签（label）是否正确。 |
Server not found |
运行 hoist server list 查看服务器列表。 |
SSH connection failed |
运行 hoist doctor 并核对服务器 IP 地址是否正确。 |
No hoist.json found |
在项目根目录下创建 hoist.json 文件。 |
references unknown server |
确保服务配置中 server 字段的值与 servers 区域中定义的服务器名称完全一致。 |
Re-run with --confirm |
此为破坏性操作。错误信息中已包含可直接重试的确切命令。 |
Multiple app services found |
请显式指定 --service 参数。 |
黄金准则
- 先解释，再执行：在运行任何可能创建、修改或销毁资源的命令前，必须首先向用户说明计划操作，并获得明确确认。
- 仅运行命令本身：JSON 输出与确认流程均由 Hoist 自动处理，无需额外添加机器专用标志（machine flags）。
- 解析 stdout 中的 JSON 并检查退出码：始终解析标准输出中的 JSON 结构，并校验命令退出码是否为 0。
- 绝不直接处理 API 密钥：密钥必须通过环境变量传递，或由用户自行运行初始化命令完成配置。
- 失败时优先排查而非盲目重试：应依次使用
hoist logs、hoist logs traefik、hoist doctor和hoist status定位根本原因。 - 每次操作后均需验证并反馈结果：无论成功与否，都必须运行验证命令并向用户报告结果。
- hoist.json 中的服务器名称必须与创建时使用的名称完全一致。
相关专题
本专题从实际API接口调试场景出发，讲解Postman身份认证的完整配置流程，包括常见认证协议介绍、授权参数设置、访问令牌填写、OAuth 2.0授权及认证失败排查，帮助用户正确完成接口授权与访问验证。
2026.11.06
0
12
围绕Postman HTTP请求头配置展开，讲解Headers选项的具体使用方式，包括Key和Value参数填写、请求头信息添加、常见Header字段设置及请求头修改方法，帮助用户解决接口调试过程中遇到的请求头配置问题。
2026.11.06
0
13
详细介绍Postman接口请求的创建与发送方法，涵盖GET和POST请求、URL配置、请求参数、Headers请求头、Body请求体设置以及响应结果查看，帮助用户掌握Postman接口请求的完整操作流程。
2026.11.06
0
10
DBeaver数据导入专题，整理Excel、CSV、SQL、TXT等常见文件的数据导入方法，涵盖目标数据库选择、数据表创建、字段映射、数据类型设置及导入参数配置等操作，帮助用户将本地文件中的数据写入数据库，并了解批量导入、重复数据处理和导入失败等常见问题的解决方法。
2026.11.05
0
12
DBeaver安全防护专题，围绕数据库连接安全、账号密码保护和访问权限管理展开，整理SSL/TLS加密连接、SSH隧道、数据库凭据保存及证书验证等配置方法，同时介绍敏感信息保护、远程连接风险和高权限账号使用等注意事项，帮助用户提高数据库日常管理的安全性。
2026.11.05
0
12
本专题聚焦DBeaver数据库连接配置与管理，覆盖从新建连接、选择数据库类型到填写连接参数和验证连接的完整流程。针对MySQL、PostgreSQL、SQL Server等常见数据库，整理相应的连接设置方法，并提供驱动缺失、认证失败和连接异常等问题的排查方向。
2026.11.04
0
16
本专题围绕XORM框架的结构体映射展开，说明表名与字段的命名策略、xorm标签常用属性、主键自增与时间字段自动填充，并演示Sync2自动建表、增量字段升级、索引声明与反向生成结构体的完整流程。
2026.11.04
0
15
本专题聚焦XORM框架的配置与连接环节，拆解MySQL、PostgreSQL、SQLite、SQL Server的DSN写法与驱动选择，讲清连接池参数、多数据源拆分、读写分离与超时重连的处理方式，并补充容器与兼容数据库的适配经验。
2026.11.04
0
15
本专题聚焦XORM框架的配置与连接环节，拆解MySQL、PostgreSQL、SQLite、SQL Server的DSN写法与驱动选择，讲清连接池参数、多数据源拆分、读写分离与超时重连的处理方式，并补充容器与兼容数据库的适配经验。
2026.11.04
0
16
热门下载
相关下载
精品课程
共6课时 | 54.7万人学习
共89课时 | 134.1万人学习
共49课时 | 82.6万人学习
最新文章