vps

Hostinger VPS

VPS API 提供对虚拟专用服务器的全面管理——从购买和设置到 Docker 部署、防火墙配置、SSH 密钥、备份、快照、操作系统重装、恢复模式、恶意软件扫描和性能监控。

目录

• 核心概念
• 常见模式
• API 参考
• 最佳实践
• 故障排查
• 参考资料

核心概念

虚拟机

具有专用 CPU、RAM、磁盘和网络资源的 VPS 实例。每个 VM 都有一个操作系统模板、root 访问权限和一个 IP 地址。VM 会经历以下状态：initial → running → stopped。

操作

对 VM 的异步操作（启动、停止、重启、重建等）会返回一个操作资源，其状态可供轮询。

Docker 管理器

直接在 VPS 实例上部署和管理 Docker Compose 项目。支持通过 docker-compose.yaml 内容或 GitHub URL 创建项目。

防火墙

控制入站流量的网络安全规则。默认情况下，所有入站流量都会被丢弃——你必须显式添加接受规则。每个 VM 同时只能激活一个防火墙。更改需要手动同步才能生效。

SSH 公钥

用于身份验证的 SSH 密钥。密钥在账户级别管理，并附加到特定的 VM 上。

操作系统模板

用于 VM 安装的预配置操作系统镜像（Ubuntu、Debian、CentOS 等），包括面板模板（例如带有 cPanel 或 Plesk 的模板）。

安装后脚本

在 VM 安装后运行的自动化脚本。保存到 /post_install 并具有可执行权限。输出写入 /post_install.log。最大大小：48KB。

备份与快照

• 备份：由 Hostinger 管理的自动定期备份
• 快照：用户发起的即时时间点捕获。每个 VM 只能有一个快照——创建新快照会覆盖现有快照

恢复模式

从恢复磁盘镜像启动 VM 以进行系统救援。原始磁盘挂载在 /mnt。

恶意软件扫描器（Monarx）

用于在 VPS 实例上检测和防御恶意软件的可选安全工具。

常见模式

购买并设置 VPS

# Step 1: Get available OS templates
curl -X GET "https://developers.hostinger.com/api/vps/v1/templates" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Step 2: Get available data centers
curl -X GET "https://developers.hostinger.com/api/vps/v1/data-centers" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Step 3: Purchase a VPS
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "hostingercom-vps-kvm2-usd-1m",
    "payment_method_id": 517244,
    "template_id": 1,
    "data_center_id": 1,
    "hostname": "my-server",
    "password": "SecurePass123!"
  }'

# Step 4: Setup purchased VM (if in initial state)
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/setup" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 1,
    "data_center_id": 1,
    "hostname": "my-server",
    "password": "SecurePass123!"
  }'

CLI（hapi）：

hapi vps vm list

Python SDK：

from hostinger_api import Hostinger

client = Hostinger(api_token="YOUR_API_TOKEN")

# List all VPS instances
vms = client.vps.virtual_machines.list()
for vm in vms:
    print(f"{vm.hostname} - {vm.state} - {vm.ip_address}")

TypeScript SDK：

import { Hostinger } from "hostinger-api-sdk";

const client = new Hostinger({ apiToken: "YOUR_API_TOKEN" });

const vms = await client.vps.virtualMachines.list();
for (const vm of vms) {
  console.log(`${vm.hostname} - ${vm.state} - ${vm.ipAddress}`);
}

PHP SDK：

use Hostinger\Api\HostingerApi;

$client = new HostingerApi('YOUR_API_TOKEN');

$vms = $client->vps->virtualMachines->list();
foreach ($vms as $vm) {
    echo "{$vm->hostname} - {$vm->state} - {$vm->ip_address}\n";
}

VM 生命周期操作

# List all VMs
curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Get VM details
curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Start VM
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/start" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Stop VM
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/stop" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Restart VM
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/restart" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Set hostname
curl -X PUT "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/hostname" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "hostname": "new-hostname.example.com" }'

# Set root password
curl -X PUT "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/root-password" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "password": "NewSecurePass123!" }'

# Recreate VM (DESTRUCTIVE - all data lost)
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/recreate" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 1,
    "password": "SecurePass123!"
  }'

部署 Docker Compose 项目

# List Docker projects on a VM
curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Deploy from docker-compose.yaml content
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "my-app",
    "content": "version: \"3\"\nservices:\n  web:\n    image: nginx:latest\n    ports:\n      - \"80:80\""
  }'

# Deploy from GitHub URL
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "my-app",
    "url": "https://github.com/user/repo"
  }'

# Get project containers and stats
curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker/my-app/containers" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# View project logs (last 300 entries)
curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/docker/my-app/logs" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Start / Stop / Restart / Update / Delete project
curl -X POST ".../docker/my-app/start" -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
curl -X POST ".../docker/my-app/stop" -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
curl -X POST ".../docker/my-app/restart" -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
curl -X POST ".../docker/my-app/update" -H "Authorization: Bearer $HOSTINGER_API_TOKEN"
curl -X DELETE ".../docker/my-app/down" -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

配置防火墙

# Create a firewall
curl -X POST "https://developers.hostinger.com/api/vps/v1/firewall" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "web-server" }'

# Add rules (default drops all — add accept rules for ports you need)
curl -X POST "https://developers.hostinger.com/api/vps/v1/firewall/1/rules" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "tcp",
    "port": "80",
    "source": "0.0.0.0/0",
    "action": "accept"
  }'

# Activate firewall on a VM
curl -X POST "https://developers.hostinger.com/api/vps/v1/firewall/1/activate/12345" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Sync firewall after rule changes
curl -X POST "https://developers.hostinger.com/api/vps/v1/firewall/1/sync/12345" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

SSH 密钥管理

# Create SSH key
curl -X POST "https://developers.hostinger.com/api/vps/v1/public-keys" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-laptop",
    "key": "ssh-ed25519 AAAA... user@host"
  }'

# Attach key to VM
curl -X POST "https://developers.hostinger.com/api/vps/v1/public-keys/attach/12345" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [1, 2] }'

# List keys on a VM
curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/public-keys" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

备份与快照

# List backups
curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/backups" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Restore a backup (DESTRUCTIVE - overwrites all data)
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/backups/99/restore" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Create a snapshot (overwrites existing snapshot)
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/snapshot" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Get current snapshot
curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/snapshot" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Restore from snapshot
curl -X POST "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/snapshot/restore" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

监控性能

# Get VM metrics (CPU, memory, disk, network, uptime)
curl -X GET "https://developers.hostinger.com/api/vps/v1/virtual-machines/12345/metrics?date_from=2025-05-01T00:00:00Z&date_to=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

API 参考

虚拟机

方法	端点	描述
GET	/api/vps/v1/virtual-machines	列出所有 VM
POST	/api/vps/v1/virtual-machines	购买新 VM
GET	/api/vps/v1/virtual-machines/{id}	获取 VM 详情
POST	/api/vps/v1/virtual-machines/{id}/setup	设置已购买的 VM
POST	/api/vps/v1/virtual-machines/{id}/start	启动 VM
POST	/api/vps/v1/virtual-machines/{id}/stop	停止 VM
POST	/api/vps/v1/virtual-machines/{id}/restart	重启 VM
POST	/api/vps/v1/virtual-machines/{id}/recreate	重建 VM（破坏性操作）
PUT	/api/vps/v1/virtual-machines/{id}/hostname	设置主机名
DELETE	/api/vps/v1/virtual-machines/{id}/hostname	重置主机名
PUT	/api/vps/v1/virtual-machines/{id}/root-password	设置 root 密码
PUT	/api/vps/v1/virtual-machines/{id}/panel-password	设置面板密码
PUT	/api/vps/v1/virtual-machines/{id}/nameservers	设置名称服务器
GET	/api/vps/v1/virtual-machines/{id}/metrics	获取指标
GET	/api/vps/v1/virtual-machines/{id}/public-keys	获取已附加的 SSH 密钥
GET	/api/vps/v1/virtual-machines/{id}/actions	获取操作历史
GET	/api/vps/v1/virtual-machines/{id}/actions/{actionId}	获取操作详情

Docker Manager (实验性)

方法	端点	说明
GET	.../docker	列出项目
POST	.../docker	创建项目
GET	.../docker/{name}	获取项目内容
GET	.../docker/{name}/containers	获取容器及统计信息
GET	.../docker/{name}/logs	获取项目日志 (最近 300 条)
POST	.../docker/{name}/start	启动项目
POST	.../docker/{name}/stop	停止项目
POST	.../docker/{name}/restart	重启项目
POST	.../docker/{name}/update	更新项目
DELETE	.../docker/{name}/down	删除项目 (不可逆)

防火墙

方法	端点	说明
GET	/api/vps/v1/firewall	列出防火墙
POST	/api/vps/v1/firewall	创建防火墙
GET	/api/vps/v1/firewall/{id}	获取防火墙详情
DELETE	/api/vps/v1/firewall/{id}	删除防火墙
POST	/api/vps/v1/firewall/{id}/rules	创建规则
PUT	/api/vps/v1/firewall/{id}/rules/{ruleId}	更新规则
DELETE	/api/vps/v1/firewall/{id}/rules/{ruleId}	删除规则
POST	/api/vps/v1/firewall/{id}/activate/{vmId}	在 VM 上激活
POST	/api/vps/v1/firewall/{id}/deactivate/{vmId}	在 VM 上停用
POST	/api/vps/v1/firewall/{id}/sync/{vmId}	将规则同步到 VM

SSH 密钥、模板、脚本、备份、快照、恢复、PTR、恶意软件

方法	端点	说明
GET/POST/DELETE	/api/vps/v1/public-keys	管理 SSH 密钥
POST	/api/vps/v1/public-keys/attach/{vmId}	将密钥附加到 VM
GET	/api/vps/v1/templates	列出操作系统模板
GET	/api/vps/v1/templates/{id}	获取模板详情
GET/POST/PUT/DELETE	/api/vps/v1/post-install-scripts	管理脚本
GET	/api/vps/v1/data-centers	列出数据中心
GET	.../backups	列出备份
POST	.../backups/{id}/restore	恢复备份
GET/POST/DELETE	.../snapshot	管理快照
POST	.../snapshot/restore	恢复快照
POST/DELETE	.../recovery	启动/停止恢复模式
POST/DELETE	.../ptr/{ipId}	管理 PTR 记录
GET/POST/DELETE	.../monarx	管理恶意软件扫描器

最佳实践

安全性

• 尽可能始终附加 SSH 密钥并禁用密码认证
• 配置防火墙 — 默认丢弃所有流量，仅添加所需的端口
• 任何规则变更后都要同步防火墙 — 变更不会自动应用
• 每个 VM 只能有一个防火墙 — 在单个防火墙中规划规则
• 在生产服务器上安装 Monarx 恶意软件扫描器
• 使用强密码 (12 个以上字符，大小写混合，包含数字，未被泄露)

备份与恢复

• 在执行破坏性操作 (重建、重大变更) 前先创建快照
• 请记住：创建新快照会覆盖现有快照
• 备份恢复会覆盖 VM 上的所有数据
• 使用恢复模式进行文件系统修复 — 原始磁盘位于 /mnt

Docker

• Docker Manager 端点属于实验性 — 可能会有变化
• GitHub URL 会自动解析到 master 分支中的 docker-compose.yaml
• 部署同名项目会替换原有项目
• 使用日志端点调试容器问题

性能

• 监控指标以合理调整 VPS 套餐规格
• 仅在清楚自己在做什么的情况下设置自定义名称服务器 — 错误配置会破坏 DNS 解析

安装后脚本

• 脚本最大大小：48KB
• 脚本以 /post_install 身份运行，输出写入 /post_install.log
• 先在非生产 VM 上测试脚本

故障排查

VM 无法启动

• 检查操作历史以获取错误详情
• VM 可能处于恢复模式 — 请先停止恢复
• 检查 VM 是否处于 initial 状态 — 先运行安装程序

无法通过 SSH 连接到 VM

• 确认 SSH 密钥已附加（而不仅仅是存在于账户中）
• 检查防火墙是否允许端口 22
• 确认规则更改后防火墙已同步
• 尝试使用 root 密码登录进行诊断

防火墙规则未生效

• 规则更改后需要手动同步：POST .../firewall/{id}/sync/{vmId}
• 每个 VM 只能有一个活动防火墙
• 默认策略为 DROP — 确保所需端口存在接受规则

Docker 项目无法启动

• 检查项目日志：GET .../docker/{name}/logs
• 验证 docker-compose.yaml 是否有效
• 确保所需端口未被占用
• 检查 VM 是否有足够的资源（CPU、RAM、磁盘）

重建时密码被拒绝

• 必须为 12 个字符以上，包含大写字母、小写字母和数字
• 密码会根据泄露密码数据库进行检查
• 尝试使用完全唯一且复杂的密码

操作卡在进行中

• 轮询操作状态：GET .../actions/{actionId}
• 某些操作需要几分钟（重建、备份恢复）
• 如果长时间卡住，请联系支持

另请参阅

以下深入指南可在本技能目录中找到：

• deployment-workflow.md — 面向 Docker 化应用的 SSH 优先部署工作流（7 步流程、回滚策略、验证级别）
• docker-patterns.md — Docker Compose 部署模式（WordPress、Node+Redis+Postgres、Traefik SSL、生命周期管理）
• firewall-patterns.md — 常见防火墙配置（Web 服务器、数据库、Docker 主机、邮件服务器、TypeScript/PHP 示例）
• terraform-examples.md — 使用 Hostinger Terraform Provider 的基础设施即代码（VPS 配置、SSH 密钥、防火墙、完整基础设施示例）

参考资料

• Hostinger API 文档
• Hostinger API 变更日志
• Python SDK
• TypeScript SDK
• PHP SDK
• 命令行工具
• Terraform Provider
• Ansible Collection
• MCP 服务