LightNode CLI
    cn
    • cn
    • en
    • lnctl CLI 使用文档
    • lnctl 安装指南

    lnctl CLI 使用文档

    本文档用于说明 lnctl 的常用命令、全局参数、认证方式、输出规则以及典型操作流程。

    1. 快速开始#

    查看全局帮助：
    查看指定资源命令帮助：
    查看版本信息：

    2. 全局参数#

    lnctl 支持以下全局参数，所有子命令均可使用。
    参数说明
    --output输出格式，支持 json / yaml / table
    --timeout请求超时时间，单位秒，范围 10-300，默认值 30
    --version输出版本信息
    说明：
    如果 --output 的值非法，CLI 会自动回退到默认 json。
    如果当前命令不支持指定的输出格式，也会自动回退到默认 json。
    如果 --timeout 的值非法或超出范围，CLI 会自动回退到默认 30。
    示例：

    3. 命令总览#

    lnctl 当前支持以下一级资源命令：
    命令说明
    vpsVPS 实例管理
    firewall安全组查询
    image镜像查询
    ssh-keySSH Key 查询
    region地域查询
    package套餐查询
    task异步任务查询
    api-key本地 API Key 管理
    upgrade升级 lnctl

    4. 认证说明#

    lnctl 默认使用本地保存的 API Key 进行认证。
    默认文件路径：
    ~/.lnctl/api-key.key
~/.lnctl/api-keys.enc

    4.1 首次执行业务命令#

    如果首次执行需要认证的业务命令，例如：
    当本地没有默认 API Key 时，CLI 会自动进入交互配置流程：
    Enter local api-key name (local label only, not sent to server): dev
Enter api-key: ********
Saved api-key "dev" and set it as current.
    保存成功后，当前命令会继续执行。
    后续命令会自动读取当前默认 API Key。

    4.2 local api-key name 是什么#

    local api-key name 是本地用于区分不同 API Key 的名称，不会发送到服务端。
    常见命名示例：
    dev
test
prod

    4.3 管理本地 API Key#

    查看 API Key 管理帮助：
    添加 API Key：
    查看本地已保存的 API Key：
    切换当前默认 API Key：
    删除 API Key：
    说明：
    lnctl api-key add 会交互输入 local api-key name 和 api-key。
    lnctl api-key add <name> 会使用指定名称，只交互输入 api-key。
    如果名称已存在，更新前需要确认。
    如果当前没有默认 API Key，新保存的 API Key 会自动成为默认值。
    如果当前已经有默认 API Key，新保存的 API Key 只会保存，不会自动切换。
    lnctl api-key delete <name> --force 会跳过删除确认。
    --force 不支持 -f 简写。
    --force 只跳过确认，不会忽略 API Key 不存在的错误。

    4.4 删除默认 API Key 后的处理规则#

    如果删除的是当前默认 API Key，CLI 会自动处理新的默认 API Key：
    剩余 API Key 数量处理方式
    0 个清空当前默认值
    1 个自动切换到剩余的 API Key
    多个根据删除方式决定
    当剩余多个 API Key 时：
    交互删除或非 --force 删除时，会提示选择新的默认 API Key。
    使用 --force 删除时，会自动选择稳定顺序中的第一个名称。

    5. 参数值与特殊字符#

    如果参数值包含特殊字符，例如密码中包含逗号、空格或其他特殊符号，推荐使用以下写法：
    建议：
    使用 = 连接参数名和值。
    使用单引号包围参数值。
    示例：
    该规则同样适用于 reset-password、reset-os 等需要传入密码的命令。

    6. VPS 管理#

    6.1 查询实例详情#

    6.2 查询实例列表#

    vps list 默认输出 table。
    分页查询：

    6.3 创建实例#

    创建 VPS 时，--password 与 --ssh-key-uuid 二选一。
    使用密码创建：
    使用 SSH Key 创建：

    6.4 密码规则#

    create、reset-password、reset-os 中使用 --password 时，密码需要符合以下规则：
    长度为 8-30 位。
    必须包含大写字母：[A-Z]。
    必须包含小写字母：[a-z]。
    必须包含数字：[0-9]。
    必须包含以下特殊字符之一：
    ()`~!@#$*-+={}[]:;,.?/

    6.5 主机名称规则#

    实例名称需要符合以下规则：
    最大长度 64 个字符。
    只能包含：
    大写字母
    小写字母
    数字
    连字符 -

    6.6 停止实例#

    6.7 启动实例#

    6.8 重启实例#

    6.9 重置密码#

    跳过确认：
    说明：
    新密码需要符合上文的密码规则。
    如果密码包含特殊字符，建议使用 --password='<new-password>'。

    6.10 重装系统#

    重装系统时，--password 与 --ssh-key-uuid 二选一。
    使用密码重装：
    使用 SSH Key 重装：
    跳过确认：
    说明：
    使用 --password 时，密码需要符合上文的密码规则。
    如果密码包含特殊字符，建议使用 --password='<password>'。

    6.11 删除实例#

    跳过确认：

    7. 只读资源查询#

    7.1 查询安全组#

    7.2 查询镜像#

    image list 默认输出 table，表格中包含 REGION 列。
    如需完整结构：

    7.3 查询 SSH Key#

    7.4 查询地域#

    7.5 查询套餐#

    8. 异步任务查询#

    创建、删除、开关机、重装系统等变更类命令，可能会返回异步任务。
    可以通过以下命令查询任务状态：
    也可以直接传入任务 ID：

    9. 升级 lnctl#

    检查并升级到当前 release channel 的 latest 版本：
    跳过确认，适合脚本或自动化环境：
    即使当前已经是 latest，也重新下载并安装：
    说明：
    lnctl upgrade 不需要 LightNode API Key。
    Linux 和 macOS 会在同目录生成备份文件：lnctl.bak。
    Windows 会在当前终端启动 helper cmd 进程，继续完成延迟替换。
    Windows 备份文件为同目录：lnctl.exe.bak。
    Windows 升级的最终成功或失败结果会回到当前终端输出。

    10. 输出规则#

    10.1 默认输出格式#

    命令类型默认输出
    list 类命令table
    非 list 命令json
    说明：
    list 类命令如果没有显式传入 --output，默认输出 table。
    非 list 命令默认输出 json。
    需要完整结构时，建议显式使用 json 或 yaml。
    示例：

    10.2 非法 output 处理#

    如果显式传入非法 --output，CLI 会提示：
    Invalid output value, reset to default: json
    并自动回退到 json。
    例如：

    10.3 不支持 table 的场景#

    如果当前命令不支持 table，但显式传入了 --output table，CLI 会提示：
    Invalid output value, reset to default: json
    并自动回退到 json。

    10.4 非法 timeout 处理#

    如果显式传入非法 --timeout，CLI 会提示：
    Invalid timeout value, reset to default: 30
    并自动回退到 30。

    11. 常见操作流程#

    11.1 首次使用#

    如果本地没有 API Key，会自动进入交互配置流程。
    配置完成后，可以查看当前 API Key：

    11.2 创建一台 VPS#

    先查询地域、套餐和镜像：
    然后创建 VPS：
    如果命令返回异步任务，可以继续查询任务状态：

    11.3 重装一台 VPS#

    跳过确认：

    11.4 删除一台 VPS#

    跳过确认：

    12. 常见排查#

    12.1 提示 API Key 缺失#

    优先检查以下内容：
    当前终端是否可交互。
    是否已经执行过 lnctl api-key add。
    ~/.lnctl/api-key.key 是否存在。
    ~/.lnctl/api-keys.enc 是否存在。
    本地是否已经设置当前默认 API Key。
    可执行以下命令查看：

    12.2 变更命令返回异步任务#

    创建、删除、开关机、重装系统等命令可能先返回异步任务。
    继续查询任务状态：

    12.3 输出内容太长不易读#

    列表类命令优先使用默认 table 输出。
    如果需要查看完整字段，再切换为：
    或：
    示例：

    12.4 lnctl upgrade 偶发网络失败#

    如果看到以下类型的下载错误：
    EOF
connection reset
timeout
    可以按以下顺序处理：
    1.
    直接重试一次：
    2.
    如果本机配置了代理，优先确认代理是否可用。
    3.
    重点关注错误输出中的 URL 和 Network error 字段。
    CLI 当前会先做短重试，再输出收敛后的网络错误提示。

    12.5 Windows 升级会继续占用当前终端#

    这是预期行为。
    原因：
    Windows 不能在运行中的 lnctl.exe 进程内直接覆盖自己。
    lnctl upgrade 会启动 helper cmd 进程，在当前终端继续完成最终替换。
    处理方式：
    请保持当前终端打开。
    等待最终输出：
    Upgrade completed.
    或：
    Upgrade failed: ...
    升级完成后，可以再次确认版本：
    Modified at 2026-07-02 02:21:58
    Next
    lnctl 安装指南
    Built with