API 自动化
用星渡 API 整理 VPS 和节点：从只读脚本开始
用最小权限 API Key 读取当前组织的服务器与节点，再逐步接入部署任务。包含密钥保存、请求状态、超时重试和自动化边界。
先创建只读 API Key
在控制台的 API 密钥页面，由组织所有者或管理员创建密钥。首次自动化只授予 hosts:read 与 nodes:read，用于读取服务器和节点清单；不需要一开始就授予安装、删除或读取节点凭据的权限。
密钥绑定组织范围。切换组织时应重新核对使用的密钥与预期资源，不要根据服务器名称猜测所属组织。需要机器注册时使用独立的 Agent 接入流程，不能把浏览器 API Key 当作机器身份。
运行公开文档里的 Python 示例
打开公开 API 文档，复制使用 Python 标准库的只读示例。云端接口前缀为 https://xingdu.app/api/v1；自托管替换为自己的 HTTPS 控制端地址。示例使用隐藏输入读取密钥，不把密钥写进脚本或终端参数。
先请求 GET /hosts，再请求 GET /nodes，检查 data 中的 ID 和名称是否对应自己的工作空间。脚本不要为了调试而完整打印请求头、连接凭据或订阅内容。计划导出清单时，也应限制生成文件的权限和保留时间。
再把部署接入自动化
需要自动安装时，再创建或调整具有 nodes:write 权限的密钥。提交 POST /hosts/{srv_id}/deployments，HTTP 202 只表示任务已排队，之后轮询部署列表中的 state；只有 Agent 回报结果才能判断任务是否完成。
网络超时可能发生在服务端已经接受请求之后。先读取任务列表核对状态，再决定是否重试，避免重复安装。401 应检查密钥，403 检查角色与范围，409 检查当前资源或 Agent 状态，429 应退避重试。
让脚本可以停用和审计
为不同用途使用独立密钥，并保留不含秘密的操作记录，例如时间、资源 ID、动作与结果。脚本需要停止时撤销对应 API Key；这不会自动卸载已经运行的节点，也不会撤回客户端已经下载的连接凭据。
本文提供的是接口使用步骤，不代表某个第三方自动化平台已经集成星渡。先在一台非关键服务器验证读取、安装、状态查询与卸载，再扩大自动化范围。