使用文档

快速开始 Quick Start

从零到一台可用的 GPU 云主机只有四步，不需要提交任何身份资料。库存充足的型号从确认扣费到拿到 SSH 命令，通常在 3 分钟以内。

1. 注册账户

   在注册页填写邮箱与密码。验证邮件通常 1 分钟内送达，未收到请查看垃圾箱。任何能收信的邮箱都可以，包括 Proton、Tuta 等匿名服务商。

2. 充值钱包

   控制台 → 钱包，选择币种与链，向专属地址转账。USDT-TRC20 1 个确认即到账，约 1 分钟。首笔到账 ≥ ₮500 自动加赠 5%。

3. 创建实例

   控制台 → 创建实例，依次选择卡型、卡数、机房、计费周期与镜像。确认后从余额一次性扣除整个周期的费用。

4. 连接使用

   实例详情页显示 SSH 命令、Jupyter 链接与公网 IP。root 密码在创建时通过邮件与控制台各显示一次，之后只能重置。

拿到 SSH 命令之后，第一条命令一般是这样：

$ ssh -p 22071 [email protected]
The authenticity of host '[203.0.113.48]:22071' can't be established.
ED25519 key fingerprint is SHA256:Qm4vJ0d0f8Xh1M9y2kZ7YB4jH2fWm0m3K7v1cG1Vd6E.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
root@i-7c2f91a4:~# nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv
name, memory.total [MiB], driver_version
NVIDIA H100 80GB HBM3, 81559 MiB, 560.35.03

创建实例 Create Instance

进入 控制台 → 创建实例，页面自上而下分为六个选项组。所有选项在下单前都可以随意更改，价格实时显示在右侧汇总栏。

选项说明

交付时间与排队

库存充足的型号在确认扣费后 3 分钟内交付；裸金属整机需要重新灌装系统，约 20 分钟。若所选机房该型号暂无库存，订单进入排队中状态：排队期间只冻结对应余额，不开始计时，也不正式扣费；交付成功时才扣费并开始计算周期。排队超过 24 小时仍未交付的订单会自动取消并解冻余额，同时发送邮件通知。

实例状态

实例在生命周期内会经过以下状态，控制台与 API 中的 status 字段一致：

实例 ID 形如 i-7c2f91a4（前缀 i- 加 8 位十六进制），在控制台、API、CLI、Jupyter 域名与账单里保持一致。

SSH 连接 SSH Access

每个实例都有独立的公网 IPv4。SSH 服务通过宿主机端口映射暴露，端口在 22000–22999 范围内随机分配，其余端口 1:1 直通。实例详情页的「连接信息」会给出完整命令，例如：

$ ssh -p 22071 [email protected]

上传 SSH 公钥

建议在创建第一个实例之前，先到 设置 → SSH 公钥 上传公钥，之后每次创建实例都可以直接勾选。每个账户最多保存 10 把公钥，支持 ed25519、ecdsa 与 rsa（不低于 3072 位）。还没有密钥的话，在本机生成一把：

$ ssh-keygen -t ed25519 -C "gpuli-2026" -f ~/.ssh/gpuli
$ cat ~/.ssh/gpuli.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIB3k6q…7Yc gpuli-2026

把 .pub 文件的内容整行粘贴到控制台即可。公钥会在实例部署时写入 /root/.ssh/authorized_keys；对已经在运行的实例，可以在实例详情页点击「注入公钥」，或者自己用密码登录后手动追加。

推荐的 ~/.ssh/config

# ~/.ssh/config
Host h100-dfw
    HostName 203.0.113.48
    Port 22071
    User root
    IdentityFile ~/.ssh/gpuli
    ServerAliveInterval 30
    ServerAliveCountMax 6

之后只需 ssh h100-dfw。ServerAliveInterval 能避免跨洋链路上长时间无输出时被中间设备断开。

关闭密码登录

实例默认允许密码登录（密码在创建时显示一次）。确认公钥能用之后，建议关闭密码认证：

# sed -i 's/^#\?PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
# systemctl restart ssh

本地端口转发

TensorBoard、Gradio、vLLM 等只监听 localhost 的服务，不必开放公网端口，用 SSH 隧道带回本机即可：

$ ssh -p 22071 -N -L 6006:localhost:6006 -L 7860:localhost:7860 [email protected]
# 然后在本机浏览器打开 http://localhost:6006

Windows 用户

Windows 10 / 11 自带 OpenSSH 客户端，直接在 PowerShell 里执行上面的命令即可；也可以使用 Termius、MobaXterm 或 WSL。密钥请保持 OpenSSH 格式，PuTTY 的 .ppk 需要先用 PuTTYgen 导出为 OpenSSH 公钥再上传。

Jupyter JupyterLab

除「Ubuntu 22.04 裸机」与「Windows Server 2022」外，所有镜像都预装 JupyterLab 4.2，并通过我们的边缘节点以 HTTPS 反向代理暴露，无需自己配证书。地址固定为：

https://<instance-id>.jup.gpuli.com
# 例如
https://i-7c2f91a4.jup.gpuli.com/lab?token=b7e1f4c2a9d0…

访问令牌在实例详情页「连接信息」中显示，点击「打开 Jupyter」会自动带上令牌。Jupyter 以 root 运行，工作目录为 /root，存储卷若挂载在 /data 会直接出现在文件树中。

管理 Jupyter 服务

# systemctl status jupyter           # 查看状态
# systemctl restart jupyter          # 重启（安装新内核后需要）
# systemctl disable --now jupyter    # 不需要时彻底关闭
# cat /etc/gpuli/jupyter.env        # 令牌与端口配置

令牌保存在 /etc/gpuli/jupyter.env 的 JUPYTER_TOKEN 中，修改后重启服务生效，控制台显示的链接会在 1 分钟内同步。Jupyter 在实例内监听 127.0.0.1:8888，只有我们的代理能访问，不会直接暴露在公网 IP 上。

添加内核

# conda create -n myenv python=3.11 -y && conda activate myenv
# pip install ipykernel
# python -m ipykernel install --name myenv --display-name "Python (myenv)"

预装镜像 Images

镜像每月至少滚动更新一次，更新只影响新创建的实例，不会改动已经在运行的实例。所有 Linux 镜像基于 Ubuntu 22.04 LTS，NVIDIA 驱动 560.35，预装 tmux、htop、nvtop、rclone、aws-cli 与 Miniconda。

镜像内的具体版本可以在实例里执行 cat /etc/gpuli/image-release 查看。如需固定某个历史版本（例如 2026-03 的 PyTorch 2.4 镜像），在 API 的 image 字段中附带日期后缀：pytorch-2.4-cuda12.1@2026-03-18，历史镜像保留 12 个月。

快照 Snapshots

快照是实例系统盘的完整副本（不含存储卷）。每个实例包含 1 份免费快照，额外快照按实际占用 ₮0.05 / GB / 月计费。快照独立于实例存在：实例销毁后快照仍会保留，可以随时用它在同机房或其他机房创建新实例。

• 创建快照时实例会短暂冻结 I/O（通常 2–5 秒），不需要停机。
• 1 TB 系统盘的首次快照约需 10–20 分钟，后续快照为增量，通常几分钟。
• 跨机房复制快照免费，100 GB 约需 10–30 分钟。
• 快照 ID 形如 snap-3e9a01c7。

$ gpuli snapshot create i-7c2f91a4 --name before-cuda-upgrade
snap-3e9a01c7  creating  i-7c2f91a4  DFW-1
$ gpuli snapshot list
ID             NAME                  SIZE     REGION  CREATED
snap-3e9a01c7  before-cuda-upgrade   412 GB   DFW-1   2026-08-30 14:02 UTC
snap-11f0b2d8  vllm-prod-base        286 GB   DFW-1   2026-07-19 03:41 UTC
$ gpuli instance create --from-snapshot snap-3e9a01c7 --gpu h100sxm --region ORD-1 --cycle week

持久化存储卷 Persistent Volumes

存储卷是独立于实例的 NVMe 块设备，₮0.08 / GB / 月，最小 100 GB，最大 16 TB，只能挂载到同机房的实例，同一时刻只能挂载到一个实例。适合数据集、模型权重与训练检查点：实例到期或更换卡型时，卸载再挂到新实例即可，数据不动。

在 控制台 → 存储卷 创建并挂载后，卷会以 /dev/vdb（虚拟化实例）或 /dev/nvme1n1（裸金属）出现。首次使用需要格式化：

# lsblk
NAME    SIZE  TYPE  MOUNTPOINT
vda     1T    disk
├─vda1  1T    part  /
vdb     2T    disk
# mkfs.ext4 -L data /dev/vdb            # 仅首次，会清空数据
# mkdir -p /data && mount /dev/vdb /data
# echo 'LABEL=data /data ext4 defaults,nofail 0 2' >> /etc/fstab
# df -h /data
Filesystem  Size  Used  Avail  Use%  Mounted on
/dev/vdb    2.0T  28K   1.9T   1%    /data

使用 LABEL= 而不是设备名，是因为卷挂到别的实例时设备名可能不同。nofail 保证卷未挂载时实例仍能正常启动。

扩容

在控制台把卷从 2 TB 扩到 4 TB 之后，在实例内在线扩展文件系统，不需要卸载：

# resize2fs /dev/vdb

卸载

控制台点「卸载」前请先在实例内 umount /data，否则可能丢失尚未写入的数据。存储卷的数据不在实例的 7 天保留期规则之内：只要卷存在并正常扣费，数据就一直在。

对象存储 S3 Object Storage

S3 兼容对象存储，₮0.015 / GB / 月，出口流量免费，与同机房实例内网直连。适合存放数据集、模型发布件与备份，与 aws-cli、boto3、rclone、s5cmd、Hugging Face hf_transfer 等工具直接兼容。

访问密钥在 控制台 → 存储卷 → 对象存储 → 访问密钥 生成，Access Key 以 GPULIAK 开头，Secret Key 只显示一次。Region 字段填 us-east-1 即可（我们不校验该值）。

aws-cli 示例

$ pip install awscli
$ aws configure
AWS Access Key ID: GPULIAK7Q2M4XR9B1E
AWS Secret Access Key: ****************************************
Default region name: us-east-1
Default output format: json

$ export EP=https://s3.dfw1.gpuli.com
$ aws --endpoint-url $EP s3 mb s3://my-datasets
$ aws --endpoint-url $EP s3 cp ./laion-subset.tar s3://my-datasets/
$ aws --endpoint-url $EP s3 sync s3://my-datasets /data/laion --no-progress
$ aws --endpoint-url $EP s3 presign s3://my-datasets/ckpt-step-42000.safetensors --expires-in 3600

rclone 配置

# ~/.config/rclone/rclone.conf
[gpuli-dfw]
type = s3
provider = Other
access_key_id = GPULIAK7Q2M4XR9B1E
secret_access_key = ****************************************
endpoint = https://s3-internal.dfw1.gpuli.com
acl = private

# 多线程上传 checkpoints
$ rclone copy /data/ckpt gpuli-dfw:my-datasets/ckpt --transfers 16 --s3-chunk-size 64M

单个对象最大 5 TB，分片上传自动处理。桶名全站唯一，长度 3–63 位，只允许小写字母、数字与连字符。桶默认私有；需要公开读的资源可以在控制台把桶策略切到「公开读」，此时对象可通过 https://s3.dfw1.gpuli.com/<bucket>/<key> 直接下载。

端口映射与公网 IP Networking

每个实例包含 1 个独立的美国公网 IPv4，25 Gbps 共享出口，不限流量。除 SSH 之外的所有端口都是 1:1 直通，不需要任何映射配置。

额外 IPv4 与 IPv6

额外公网 IPv4 ₮4 / 个 / 月，每实例最多 4 个，在实例详情页「网络」中申请，30 秒内生效，附加 IP 以别名形式配置到 eth0。IPv6 /64 段免费，提交工单申请（2025-03 起 DFW-1 / IAD-1 / ORD-1 支持）。实例在「已到期」保留期内 IP 不变；销毁后 IP 释放，不保证再次分配到同一地址。

示例：把 vLLM 暴露到公网

# python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-32B-Instruct --host 0.0.0.0 --port 8000 \
    --api-key sk-my-own-secret --tensor-parallel-size 2

# 本机测试
$ curl -s http://203.0.113.48:8000/v1/models -H "Authorization: Bearer sk-my-own-secret"

独享带宽

需要稳定大流量（例如多机数据同步、对外分发模型）的用户可申请独享 10 Gbps 出口，₮180 / 月，不限流量，工单申请后 1 个工作日内开通。

充值与账单 Wallet & Billing

gpuli.com只接受加密货币，所有费用以 USDT（写作 ₮）计价并从预付余额中扣除。每个账户在 钱包页 都有一组专属充值地址，按币种与链区分，长期不变。

• 非 USDT / USDC 币种按到账时刻三家交易所中位价折算为 ₮ 记入余额，折算汇率与原始金额都会在交易记录里注明。
• 最低充值 ₮10 等值；首笔到账 ≥ ₮500 自动加赠 5%，无需申请。
• 转错链的资产若落在我们持有私钥的地址上，提交工单并附交易哈希，1–3 个工作日人工入账，收取 ₮20 手续费；转到非我们控制的地址无法找回。
• 充值取得的余额不支持提现，只能用于平台消费；只有推广返佣可以提现为 USDT，每周一次、最低 ₮50。实例创建后 1 小时内可无理由退款，退回余额。

账单

账单页按时间列出每一笔扣费与充值，每条记录包含实例 ID、周期起止、金额与关联交易哈希，可导出 CSV。每笔扣费都可以下载 PDF 收据，收据仅显示账户 ID、金额与周期，不含姓名或公司信息，因为我们没有这些信息。

自动续费 Auto Renew

自动续费按实例独立开关，在实例详情页或创建时勾选，API 中对应 auto_renew 字段。开启后的流程：

1. 到期前 3 天与 1 天，分别发送提醒邮件，邮件中注明续费金额与当前余额。
2. 到期前 24 小时，系统尝试从余额扣除下一周期费用，成功后周期无缝衔接，实例不重启。
3. 余额不足时，每 6 小时重试一次直到到期；每次失败都会发邮件。
4. 到期仍未续费，实例进入「已到期」并停机，数据与 IP 保留 7 天，期间充值后点击「续费」即恢复。
5. 保留期结束，磁盘按 NIST 800-88 标准擦除，不可恢复。存储卷与快照不受影响。

未开启自动续费的实例，可以在到期前任意时间手动续费，新周期从原到期时间接续，不会损失剩余时间。周租实例续费时可以直接切换为月租。

API 参考 REST API v2

API v2 自 2023-05 起提供，所有控制台功能均可通过 API 完成。Base URL：

https://api.gpuli.com/v2

认证

在 控制台 → API 密钥 创建密钥，形如 gpuli_live_9f3c1e7a4b2d8c6e0f5a1b3c7d9e2f48，只显示一次。密钥可设置为「只读」或「读写」，可限制来源 IP，可随时吊销。所有请求在 Header 中携带：

Authorization: Bearer gpuli_live_9f3c1e7a4b2d8c6e0f5a1b3c7d9e2f48
Content-Type: application/json

• 请求与响应均为 JSON，时间为 ISO 8601 UTC，金额为以 ₮ 计的字符串（如 "1899.00"）。
• 列表接口支持 ?page=1&per_page=50，per_page 最大 100。
• POST 请求可携带 Idempotency-Key 头，24 小时内相同 key 的重复请求返回首次结果，避免网络重试导致重复扣费。
• 速率限制每密钥 600 次 / 分钟，剩余额度在响应头 X-RateLimit-Remaining 中。

接口列表

curl 示例

# 查看 DFW-1 的 H100 SXM 库存
$ curl -s "https://api.gpuli.com/v2/gpus?region=DFW-1&id=h100sxm" \
    -H "Authorization: Bearer gpuli_live_9f3c1e7a4b2d8c6e0f5a1b3c7d9e2f48"
{
  "data": [{
    "id": "h100sxm", "name": "NVIDIA H100 SXM", "vram_gb": 80,
    "price": { "week": "549.00", "month": "1899.00" },
    "stock": { "DFW-1": 112, "IAD-1": 58, "ORD-1": 31 }
  }]
}

# 创建实例
$ curl -s -X POST https://api.gpuli.com/v2/instances \
    -H "Authorization: Bearer gpuli_live_9f3c1e7a4b2d8c6e0f5a1b3c7d9e2f48" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 6c1d2a0e-2026-0902-01" \
    -d '{"gpu":"h100sxm","count":1,"region":"DFW-1","cycle":"month",
         "image":"pytorch-2.5-cuda12.4","ssh_keys":["key_01h8zq"],"auto_renew":true}'
{
  "id": "i-7c2f91a4", "status": "provisioning", "gpu": "h100sxm", "count": 1,
  "region": "DFW-1", "cycle": "month", "charged": "1899.00",
  "expires_at": "2026-10-02T08:14:07Z",
  "ssh": { "host": "203.0.113.48", "port": 22071, "user": "root" },
  "jupyter": "https://i-7c2f91a4.jup.gpuli.com",
  "created_at": "2026-09-02T08:14:07Z"
}

Python 示例

import os, time, requests

API = "https://api.gpuli.com/v2"
H = {"Authorization": f"Bearer {os.environ['GPULI_API_KEY']}"}

# 创建实例并等待就绪
r = requests.post(f"{API}/instances", headers=H, json={
    "gpu": "4090", "count": 4, "region": "LAS-1", "cycle": "week",
    "image": "comfyui", "ssh_keys": ["key_01h8zq"],
})
r.raise_for_status()
inst = r.json()

while inst["status"] in ("queued", "provisioning"):
    time.sleep(10)
    inst = requests.get(f"{API}/instances/{inst['id']}", headers=H).json()

print(inst["id"], f"ssh -p {inst['ssh']['port']} root@{inst['ssh']['host']}")
# i-b02e4d17 ssh -p 22418 [email protected]

错误响应统一为 {"error": {"code": "insufficient_balance", "message": "…", "details": {…}}}，错误码见常见错误码。

命令行工具 gpuli CLI · gpuli-cli 1.8.3

gpuli 是官方命令行工具，封装了 API v2 的全部接口，适合脚本化管理与在实例之间跳转。需要 Python 3.9 以上，支持 Linux、macOS 与 Windows。源码与更新日志见 GitHub，发行版本见 PyPI，两处的签名与校验和一致。

$ pip install gpuli-cli
$ gpuli --version
gpuli-cli 1.8.3 (api v2)
$ gpuli login
Paste your API key (gpuli_live_…): ********
Saved to ~/.config/gpuli/credentials (mode 600). Account u_8f3a1c… · balance ₮1,284.50

常用命令

# 1. 查库存与价格
$ gpuli gpu list --region DFW-1
ID         NAME               VRAM   WEEK    MONTH   STOCK
h200       NVIDIA H200        141G   ₮739    ₮2,599  38
h100sxm    NVIDIA H100 SXM    80G    ₮549    ₮1,899  112
mi300x     AMD MI300X         192G   ₮489    ₮1,699  24
…

# 2. 创建实例
$ gpuli instance create --gpu h100sxm --count 1 --region DFW-1 \
      --cycle month --image pytorch-2.5-cuda12.4 --ssh-key mykey --auto-renew
i-7c2f91a4  provisioning  charged ₮1,899.00  expires 2026-10-02 08:14 UTC

# 3. 直接 SSH 进去（自动读取端口与 IP）
$ gpuli ssh i-7c2f91a4
root@i-7c2f91a4:~# 

其他常用子命令：gpuli instance list、gpuli instance renew i-… --cycle month、gpuli instance destroy i-…、gpuli wallet、gpuli volume attach vol-… i-…、gpuli snapshot create、gpuli ticket new。所有命令支持 --json 输出，方便配合 jq 使用。完整帮助：gpuli --help。

常见错误码 Error Codes

API、CLI 与控制台使用同一套错误码。CLI 会把错误码显示在输出最后一行，控制台在页面顶部的红色提示条中显示。

遇到文档未覆盖的错误，请在工单中附上响应里的 request_id（响应头 X-Request-Id），我们能据此在 30 天内查到对应的服务端记录。