进阶 hestiacp.com 2026-11-15 08:32:00 · 7 阅读

第15章 REST API

第15章 REST API

### REST API Hestia REST API 可用于执行控制面板的核心功能。例如,我们在内部使用它来同步 DNS 集群,以及集成 WHMCS 计费系统。该 API 还可以用于创建新的用户账户、域名、数据库,甚至构建替代的 Web 界面。API 参考文档提供了 PHP 代码示例,展示如何将 API 集成到应用或脚本中。不过,你使用任何其他语言与 API 通信也是完全可以的。

随着 Hestia v1.6.0 版本的发布,我们引入了更高级的 API 系统,允许非管理员用户使用特定的命令。

### 无法连接到 API 随着 Hestia v1.4.0 版本的发布,我们决定加强安全措施。如果你希望从远程服务器连接 API,首先必须将其 IP 地址加入白名单。添加多个地址时,请使用换行符分隔。若要绕过 IP 过滤,删除所有现有的 IP 地址并写入 `: allow-all`。

### 能否禁用 API? 可以,你可以通过服务器设置禁用 API。禁用后,相关文件将从服务器上删除,所有连接都将被忽略。请注意,某些功能在禁用 API 时可能无法正常工作。

密码 vs API 密钥 vs 访问密钥

#### 访问密钥 * 针对特定用户。 * 可限制权限。例如,仅允许 `v-purge-nginx-cache`。 * 可以禁用其他登录方式,但允许使用 API 密钥。 * 可以限制为仅管理员用户,或允许所有用户使用。

#### 密码 * 危险:此方法已弃用。 * 仅应由管理员用户使用。 * 更改管理员密码需要在所有使用处进行更新。 * 允许运行所有命令。

#### API 密钥 * 危险:此方法已弃用。 * 仅应由管理员用户使用。 * 更改管理员密码不会带来后果。 * 允许运行所有命令。

### 设置访问/密钥认证 要创建访问密钥,请按照我们文档中的指南操作。

提示:或者使用以下命令创建。如果要创建一个需要管理员权限的访问密钥,请通过初始管理员用户创建 API 密钥!

```bash v-add-access-key 'admin' 'profile' test json ```

如果你希望使用 API 密钥支持所有命令,请使用:

```bash v-add-access-key 'admin' '*' test json ```

### 创建自己的 API 密钥配置文件 在 `/usr/local/hestia/data/api/` 目录下创建一个新文件,内容如下:

```bash ROLE='admin' COMMANDS='v-list-web-domains,v-add-web-domain,v-list-web-domain' ```

* 角色:user 或 admin。 * 命令:以逗号分隔的列表,包含你所需的所有命令。 * 如果你使用的软件已经支持哈希格式,请使用 `ACCESS_KEY:SECRET_KEY` 代替旧的 API 密钥。

### 创建 API 密钥 警告:此方法已被上述访问/密钥认证所取代。我们强烈建议使用这种更安全的方法。

运行命令 `v-generate-api-key`。

返回代码

| 值 | 名称 | 注释 | | :--- | :--- | :--- | | 0 | OK | 命令已成功执行 | | 1 | E_ARGS | 提供的参数不足 | | 2 | E_INVALID | 对象或参数无效 | | 3 | E_NOTEXIST | 对象不存在 | | 4 | E_EXISTS | 对象已存在 | | 5 | E_SUSPENDED | 对象已暂停 | | 6 | E_UNSUSPENDED | 对象已恢复 | | 7 | E_INUSE | 对象被其他对象使用,无法删除 | | 8 | E_LIMIT | 由于托管套餐限制,无法创建对象 | | 9 | E_PASSWORD | 密码错误/无效 | | 10 | E_FORBIDEN | 此用户无法访问该对象 | | 11 | E_DISABLED | 子系统已禁用 | | 12 | E_PARSING | 配置损坏 | | 13 | E_DISK | 磁盘空间不足,无法完成操作 | | 14 | E_LA | 服务器繁忙,无法完成操作 | | 15 | E_CONNECT | 连接失败。主机无法访问 | | 16 | E_FTP | FTP 服务器无响应 | | 17 | E_DB | 数据库服务器无响应 | | 18 | E_RDRRDtool 更新数据库失败 | | 19 | E_UPDATE | 更新操作失败 | | 20 | E_RESTART | 服务重启失败 | | 21 | E_BACKUP | 备份失败 |

评论 (0)