Skip to content

云主机 ​

云主机是一台有自己公网 IP 的虚拟机。你用自己的 SSH 密钥、从你列出的地址登录,可以用 sudo 拿到 root。租期按小时预付。

key 的「用途」里要有「云主机」。你也可以在控制台的「云主机」页创建和管理。

创建云主机 ​

先请求 GET https://cloud.theyilabs.com/v1/compute/classes,从 classes 中选择可用规格。列表为空时,算力暂不可创建,请先使用模型 API。以下创建示例需要可用规格和足够的可用余额。

sh
RETRY_KEY=$(uuidgen)
curl https://cloud.theyilabs.com/v1/vms \
  -H "Authorization: Bearer $YI_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RETRY_KEY" \
  -d '{
    "class": "standard",
    "hours": 4,
    "ssh_public_keys": ["ssh-ed25519 AAAA… you@laptop"],
    "allowed_cidrs": ["203.0.113.10/32"]
  }'

同一次操作重试时复用这个 RETRY_KEY 和请求体;下一次新建资源时重新生成。

字段取值
class必填。GET /v1/compute/classes 里某个规格的 id。那里列出每种规格的 vCPU、内存、磁盘、每小时价格和停机保留费用。
archamd64(默认)或 arm64。可用的架构见 GET /v1/compute/classes。
pool可选:pool-1、pool-2 或 pool-3。不填由 Yi Cloud 选。现在开放的资源池见 GET /v1/compute/classes 里的 pools。旧的 cloud 字段已删除,传了返回 400。
hours预付的租期,整小时。1 到 168,默认 1。你的信任档位可能限制得更短,见配额与网络。
ssh_public_keys必填。1 到 10 个公钥,类型为 ssh-ed25519、ssh-rsa 或 ecdsa-sha2-nistp256。
allowed_cidrs必填。1 到 20 个允许 SSH 连入的地址段。IPv4 至少是 /8,IPv6 至少是 /32,可以更窄。
metadata可选。最多 20 对字符串,给你自己用。

创建时要带 Idempotency-Key。返回 202 和这台云主机,id 以 vm_ 开头。SSH 公钥和地址段在创建时确定,之后没有接口能修改。

反复查询 GET /v1/vms/{id},直到 state 变成 running,这时 public_ip 里就是它的地址。10 分钟内没有运行起来的云主机会被删除,状态为 failed,不收费。

选地区和机型 ​

不用 class,也可以自己选地区和具体机型。

  1. GET https://cloud.theyilabs.com/v1/compute/regions 列出开放的地区(新加坡、东京、美国(爱荷华)、伦敦、瑞典、斯德哥尔摩)和每个地区的机型系列及其架构。
  2. GET https://cloud.theyilabs.com/v1/compute/machine-types?region=tokyo&family=n2 列出该地区这个系列的机型:vCPU、内存、磁盘、每小时价格和停机保留费用。
  3. 创建时传 machine_type 和 region,不传 class:
sh
-d '{"machine_type":"n2-standard-4","region":"tokyo","hours":1,"ssh_public_keys":["ssh-ed25519 AAAA…"],"allowed_cidrs":["203.0.113.10/32"]}'

架构由机型系列决定,可以不传 arch;传了但不一致会返回 400。L4 系列(g2-standard-*)带一张 NVIDIA L4,需要 GPU 邀请。这样创建的资源会返回 region 和 machine_type。

登录 ​

sh
ssh pwc@203.0.113.25
  • 用户名是 pwc(见 ssh_user 字段),可以用 sudo 拿到 root。
  • 只能用密钥登录,密码登录和 root 直接登录都关闭了。
  • 只开放 TCP 22 端口,而且只对 allowed_cidrs 里的地址段开放。
  • 镜像是 Ubuntu 24.04 LTS。

你在云主机里有 root,所以里面运行的东西由你自己负责保护。出站规则和沙盒相同,见配额与网络。

租期 ​

  • 创建时预扣 hours 对应的租金,云主机第一次运行起来时全额扣费。一直没运行起来,预扣就释放。
  • prepaid_until 显示租期到什么时候。
  • 租期到了,云主机会被停止,不会被删除。见停机。

续费 ​

sh
curl https://cloud.theyilabs.com/v1/vms/$VM/renew \
  -H "Authorization: Bearer $YI_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"hours": 2}'
  • 续费按这台云主机的每小时价格,当场扣费。
  • 加上的小时数接在当前租期的末尾。租期已经结束的话,从现在算起。
  • 租期往后最远不能超过信任档位允许的最长租期,超过会返回 409 quota_exceeded。
  • 云主机运行过一次之后就能续费,停机时也可以。

控制台上的「续费 1 小时」按钮做的是同一件事,续一个小时。

停止、启动、重启、重装 ​

都是对 /v1/vms/{id}/{action} 发 POST,带 Idempotency-Key,返回 202。

操作效果
stop停止云主机。已预付的时间不退。磁盘和 IP 保留,按停机保留费用计费。
start启动停机的云主机。需要还有预付的时间,没有的话返回 402 insufficient_funds,先续费。
reboot重启正在运行的云主机。
reinstall清空系统盘并重新安装,公网 IP 保留。请求体必须是 {"confirm_destroy_disk": true}。云主机必须在运行或已停止。

同一时间只能有一个操作,上一个还没完成时再发会得到 409 conflict。如果重启或重装中途被打断、结果不确定,Yi Cloud 不会重做。它会停止这台云主机、把它隔离起来,error_code 设为 action_uncertain。请删掉它重新创建,或者联系我们。

停机 ​

  • 停机的云主机保留磁盘和公网 IP,按停机保留费用(stopped_micro_per_hour)计费。停机期间每满一小时扣一次,重新启动或删除时,不足一小时的部分按秒计。
  • 云主机最多停机 24 小时,之后会被删除。
  • 如果余额,或者创建它的 key 的花费上限付不起停机保留费用,它会被删除。

串口日志 ​

GET /v1/vms/{id}/serial 以文本返回云主机启动串口输出的最后 64 KiB。SSH 连不上时可以用它排查。内容是实时读取的,不会保存。

删除 ​

sh
curl -X DELETE https://cloud.theyilabs.com/v1/vms/$VM \
  -H "Authorization: Bearer $YI_CLOUD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

删除会销毁磁盘和上面的所有东西,无法撤销。状态先变成 deleting,再变成 deleted。

费用 ​

项目怎么扣
租期每小时价格 × hours,云主机第一次运行起来时全额扣。
续费每小时价格 × hours,当场扣。
停机停机保留费用,每满一小时扣一次,不足一小时的部分按秒计。

停机不退租金。单台云主机的回执在 GET /v1/vms/{id}/receipt,返回 JSON,加 ?format=csv 返回 CSV。见计费与回执。

列表 ​

GET /v1/vms 返回你工作区最近的 200 台云主机,最新的在前,包括已删除的。