HestiaCP服务器管理：REST API使用完全指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00463/article/details/148552690

HestiaCP服务器管理：REST API使用完全指南

hestiacp Hestia Control Panel | A lightweight and powerful control panel for the modern web. 项目地址: https://gitcode.com/gh_mirrors/he/hestiacp

什么是HestiaCP的REST API

HestiaCP的REST API是一套强大的接口系统，允许开发者通过编程方式执行控制面板的核心功能。这套API不仅被HestiaCP自身用于DNS集群同步和WHMCS计费系统集成等内部操作，还可以用于：

自动化创建用户账户
管理域名和数据库
构建自定义的Web管理界面
与其他系统进行深度集成

API安全配置

IP白名单机制

自HestiaCP v1.4.0起，出于安全考虑，API增加了IP白名单机制：

远程服务器必须先在白名单中注册IP才能连接API
多个IP地址需要用换行符分隔
如需完全禁用IP过滤，可设置allow-all（不推荐生产环境使用）

API禁用选项

管理员可以通过服务器设置完全禁用API功能：

禁用后API文件将从服务器删除
所有API连接请求将被忽略
注意：某些功能可能在API禁用后无法正常工作

认证方式详解

推荐方式：访问密钥/密钥对（Access/Secret Key）

这是目前最安全且灵活的认证方式：

特性：

用户级别专属密钥
支持细粒度权限控制（如仅允许v-purge-nginx-cache命令）
可配置为仅允许API访问而禁用其他登录方式
可限制为仅管理员使用或开放给所有用户

创建命令示例：

# 创建具有特定权限配置的密钥
v-add-access-key 'admin' 'profile' test json

# 创建具有全部权限的密钥
v-add-access-key 'admin' '*' test json

自定义API密钥配置

高级用户可以创建自定义权限配置：

在/usr/local/hestia/data/api/目录下创建配置文件
配置文件内容示例：

ROLE='admin'  # 用户角色
COMMANDS='v-list-web-domains,v-add-web-domain,v-list-web-domain'  # 允许的命令列表

已弃用的认证方式

密码认证（Deprecated）

仅限管理员使用
密码变更需要同步更新所有使用场景
具有全部命令权限

API密钥（Deprecated）

仅限管理员使用
密码变更不影响API使用
具有全部命令权限

API返回代码详解

HestiaCP API使用标准化的返回代码系统，开发者应当正确处理这些状态码：

| 代码 | 名称 | 说明 | |------|---------------|-----------------------------------| | 0 | OK | 命令执行成功 | | 1 | E_ARGS | 参数不足 | | 2 | E_INVALID | 无效的对象或参数 | | 3 | E_NOTEXIST | 对象不存在 | | 4 | E_EXISTS | 对象已存在 | | 5 | E_SUSPENDED | 对象已被暂停 | | 6 | E_UNSUSPENDED | 对象已恢复 | | ... | ... | ...（完整列表参考官方文档） |