Skip to Content
IoT 应用开发IronFlock CLI登录与设备管理

登录与设备管理

这些命令与 IronFlock 实例(云端或 Appliance)通信,而不是与它们所运行的机器通信。ironflock login 在本机保存一个 API 密钥,whoami 显示该密钥所属的帐户,logout 移除该密钥。之后,ironflock device create、list 和 delete 处理您项目中的设备。agent install、os flash 和 os install 可以通过 --project 和 --name 为您创建设备。

它们都不需要 root,并且都可以在 Linux、macOS 和 Windows 上运行。它们只作用于本机:--host 和 --hosts 会以退出码 2 被拒绝,密钥和凭据文件都绝不会发送到另一台机器(通过 SSH 管理远程机器)。

login 和 whoami 需要一个其 API 服务能应答 GET /v1/ironflock/whoami 的实例(API 端点)。IronFlock 云端可以。没有该路由的实例会返回 404,命令会如实说明。IronFlock Appliance 运行 IronFlock API 服务后会提供该路由;尚未运行该服务的 Appliance 版本无法与这些命令配合使用。这些命令只与实例的 API 通信,不与其他任何东西通信,并且像 ironflock 的其他所有请求一样使用环境中的代理(HTTPS_PROXY、NO_PROXY)。

实例

默认是云端。--instance,或者在未给出时由环境变量 IRONFLOCK_INSTANCE,指定另一个实例:一台 Appliance。给出您手头有的信息,命令会从中推导出 API 的地址:

您给出API 是
什么都不给,或 ironflock.com、studio.ironflock.com 或 api.ironflock.comhttps://api.ironflock.com
Appliance 的域名 factory.example.comhttps://api.factory.example.com
打开 Studio 所用的地址 https://factory.example.com/projects/12https://api.factory.example.com
API 自身的主机 api.factory.example.comhttps://api.factory.example.com

没有协议时,默认为 https://。纯 http 只用于环回地址,即本机上的服务栈。环回地址以外的 IP 地址会被拒绝:Appliance 的 API 通过其名称访问。处于纯 HTTP 模式的 Appliance 没有 api.<domain>,login 无法访问它。实例的证书会对照本机的信任存储以及 --ca-cert 的证书颁发机构(一个 PEM 文件,多个时可多次给出)进行检查,例如为 Appliance 证书签名的贵公司 CA。没有任何办法关闭该检查。

凭据文件

login 将密钥保存在您用户配置文件夹中 ironflock 文件夹下的 credentials.json 中:Linux 上是 ~/.config/ironflock/,Mac 上是 ~/Library/Application Support/ironflock/,Windows 上是 %LOCALAPPDATA%\ironflock\credentials\。它为每个实例保存一个条目,并且只有您可读。其他人可以读取或更改的文件或文件夹不会被使用:命令以退出码 3 结束,说明如何修复,并且不做任何更改。

对于脚本和 CI,IRONFLOCK_API_KEY 保存一个密钥,每个命令都会用它代替已保存的密钥。login 绝不会读取或保存它。

变量含义
IRONFLOCK_INSTANCE未给出 --instance 时使用的实例
IRONFLOCK_API_KEY代替已保存密钥使用的 API 密钥
HTTPS_PROXY、NO_PROXY发往实例的请求所用的代理

ironflock login

先询问实例该密钥属于谁,然后为该实例保存 API 密钥。

ironflock login [--key-file <file>] [--instance <domain or URL>] [--ca-cert <file>]...
$ ironflock login --key-file key.txt --instance factory.example.com Logged in to https://api.factory.example.com as operator (account 12). The key is stored in /home/operator/.config/ironflock/credentials.json.

运行平台: Linux、macOS 和 Windows。Root: 不需要。询问: 无。

标志含义
--key-file <file>保存密钥的文件或管道。默认:标准输入(当它不是终端时)
--instance <instance>实例。默认:IRONFLOCK_INSTANCE,否则为云端
--ca-cert <file>除本机的证书颁发机构之外要信任的证书颁发机构;多个时可多次给出
  • 密钥绝不出现在命令行上。 它来自文件或管道,命令绝不会在终端上询问它。两者都没有时,命令以退出码 2 结束,并说明如何传入密钥。密钥前后的空白会被去掉。密钥是 40 个 0-9 和 a-f 字符;其他任何内容都会在发出任何请求之前被拒绝,错误消息不会复述它。
  • 在保存任何内容之前,会先询问实例该密钥属于谁。实例不接受的密钥、无法应答的实例、不受信任的证书或无法访问的实例,都会以退出码 1 结束,之前保存的内容保持不变。
  • 登录到已有登录的实例会替换原有登录。 其他实例的登录保持不变。
  • 请求不跟随任何重定向,这样密钥就不会发往其他主机。
  • 使用 --json 时,结果是一个对象,包含 action(logged_in)、instance、account_id、username、scopes、restriction 和 credential_file。

将密钥放入一个只有您可读的文件,然后登录:

(umask 077; cat > key.txt) ironflock login --key-file key.txt

在 cat > key.txt 之后,在终端中输入或粘贴密钥,以 Ctrl-D 结束;login 保存密钥后,请删除 key.txt。

ironflock whoami

显示密钥所属的帐户,以及该密钥可以做什么。

ironflock whoami [--instance <domain or URL>] [--ca-cert <file>]...
$ ironflock whoami --instance factory.example.com Instance: https://api.factory.example.com Account: operator (12) Scopes: devices:read, devices:write Restriction: the projects 3 Key: stored by 'ironflock login' on 2026-11-19 10:00 UTC

设置了 IRONFLOCK_API_KEY 时,使用的密钥就是它,否则是 login 为该实例保存的密钥。两者都没有时,命令以退出码 3 结束,并给出要运行的 login。Scopes 是密钥的权限范围,没有任何权限范围时为 none。Restriction 为 none: everything the account may do、the projects 3, 5 或 the app 5。使用 --json 时,结果包含 instance、account_id、username、scopes、restriction、key_source(environment 或 credential_file),对于已保存的密钥还包含 logged_in_at。

实例不再接受的已保存密钥(例如已在 Studio 中删除的密钥)不会被移除:错误消息会给出用来替换它的 login。

ironflock logout

移除某个实例的已保存密钥。其他实例的登录保持不变。

ironflock logout [--instance <domain or URL>]
$ ironflock logout --instance factory.example.com Logged out of https://api.factory.example.com: its key is removed from /home/operator/.config/ironflock/credentials.json. The key itself stays valid until it is deleted in Studio.

logout 不与任何实例通信:在您于 Studio 中删除该密钥之前,它一直有效。没有已保存的登录不算错误:命令会如实说明,并以退出码 0 结束。设置了 IRONFLOCK_API_KEY 时,会有一条提示说明命令仍在使用该变量。

ironflock device create

在项目中创建一个设备,并写入设备的 .flock 文件,该文件包含设备的凭据。

ironflock device create --project <project> --name <name> -o <file.flock> [flags]
$ ironflock device create --project 12 --name press-7 -o press-7.flock Created the device press-7 (key 345) in the project Packaging (key 12). Its .flock is in press-7.flock: it holds the device's credentials, which the platform shows no more. 'sudo ironflock agent install -c press-7.flock' connects a machine as this device.

运行平台: Linux、macOS 和 Windows。Root: 不需要。需要: 具有权限范围 devices:write 的密钥;按名称给出的项目会使用 devices:read 查找。

标志含义
--project <project>必需。项目的键或名称
--name <name>必需。设备的名称:1 到 100 个字母、数字、点、下划线和连字符。项目中尚不能有同名设备
-o、--output <file>必需。用于保存 .flock 的文件,名称为 *.flock;或 - 表示标准输出
--description <text>最多 2000 个字符
--wifi-ssid <name>设备的 Wi-Fi 网络。与 --wifi-password-file 一起使用
--wifi-password-file <file>包含网络密码的文件或管道。与 --wifi-ssid 一起使用
--force-o 的文件已存在时将其替换
--instance、--ca-cert与 whoami 相同
  • 按名称给出的项目 会在密钥可以使用的项目中查找,并且必须恰好是一个项目的名称。没有匹配项目的名称为退出码 1。多个项目共用的名称为退出码 2,消息会给出这些项目的键。
  • .flock 文件从第一个字节起就是私有的:模式为 0600,在 Windows 上则是只授予您访问权的访问控制列表。已存在的文件不会在没有 --force 的情况下被替换;文件夹和名称会在创建设备之前检查,因为 API 只在创建设备时返回凭据。在没有文件模式的文件系统上(例如格式化为 FAT 的 U 盘),文件不是私有的:请将其写入机器的磁盘,再从那里复制。
  • -o - 将文件写入标准输出,标准输出不能是终端,例如用于通过管道将其传给另一台机器。此时结果行写入标准错误。
  • 不会输出文件的任何内容:结果通过键和名称指明设备,以及项目。
  • 如果在设备创建之后出现故障,错误消息会如实说明,并给出删除该设备的命令。

按照设备代理程序命令中的说明使用该文件连接机器,或使用 os flash 将其写入驱动器。

ironflock device list

列出您的帐户有权访问的、位于密钥可行事项目中的设备。

ironflock device list [--project <project>] [--instance <instance>] [--ca-cert <file>]...
$ ironflock device list --project Packaging KEY NAME PROJECT STATUS ARCHITECTURE AGENT 17 press-7 12 CONNECTED amd64 1.4.2 18 press-8 12 CONFIGURING amd64 -

需要: 具有权限范围 devices:read 的密钥。--project 只保留一个项目的设备。没有设备不算错误:命令会显示 No devices.。使用 --json 时,结果包含 instance 和 devices,每个设备包含 device_key、name、project_key、description、status、architecture 和 agent_version。只会从响应中读取这些字段:设备的凭据绝不在其中。

ironflock device delete

从项目中删除一个设备。已删除的设备无法恢复。

ironflock device delete --project <project> <device_key> [--yes] [--instance <instance>] [--ca-cert <file>]...
$ ironflock device delete --project Packaging 17 This deletes the device 17 from the project Packaging (key 12) of https://api.ironflock.com. A deleted device cannot be brought back. Delete the device 17? [y/N] Deleted the device press-7 (key 17) from the project 12.

需要: 具有权限范围 devices:write 的密钥。设备的键是唯一的参数。命令会说明将删除什么并询问,默认选中“No”;--yes 回答“是”。没有终端时以及使用 --json 时,它不询问,并且除非给出 --yes,否则以退出码 4 结束:此时不会删除任何内容。不在该项目中或密钥无法看到的设备会得到 404。

使用 --project 和 --name 安装新设备

ironflock agent install、ironflock os flash 和 ironflock os install 接受 --project <project> --name <name> 来代替 -c <device.flock>。命令会创建设备,并使用平台发送的 .flock 继续,与使用 -c 的文件继续完全相同。.flock 保存在内存中,不会保存在任何需要您照管的文件中。

sudo ironflock agent install --project Packaging --name press-9 --yes ironflock os flash --project 12 --name cell-4 -d /dev/sdb ironflock --host admin@machine os install --project 12 --name cell-4 --disk /dev/sda --yes --wait-online
标志含义
--project <project>要在其中创建设备的项目:其键或名称,与 device create 相同
--name <name>新设备的名称,与 device create 相同
--instance <instance>实例,与 whoami 相同
--ca-cert <file>agent install:实例证书的证书颁发机构。os flash 和 os install 有自己的 --ca-cert,用于设备;与 --project 一起使用时,它也会被实例信任
--wait-online[=<duration>]仅限通过 --host 运行的 os install:在那里的命令完成后,最多等待指定时长(1 分钟到 2 小时;单独给出时为 15 分钟),直到平台看到设备在线。值跟在 = 后面,例如 --wait-online=20m
  • --project 和 --name 必须一起使用,且不能与 -c 同时使用。agent install 和 os flash 需要二者之一;os install 两者都没有时,与以前一样使用已安装代理程序的 .flock。--dry-run 与 --project 一起使用会被拒绝,因为试运行不会创建任何东西。
  • 使用的密钥与 whoami 的相同:IRONFLOCK_API_KEY,否则为已保存的登录。用 sudo 运行的命令以 root 身份运行,并查找 root 的登录:请使用 sudo --preserve-env=IRONFLOCK_API_KEY 传入密钥,或者在您自己的机器上使用 --host 运行命令。使用 --host 时,平台由您的机器发出请求,目标机器只会得到 .flock:密钥、凭据文件和 IRONFLOCK_API_KEY 都绝不会到达它。
  • 平台只在创建设备的响应中提供设备的 .flock。因此,项目中已有的名称会被拒绝(退出码 1):请使用该设备的 .flock 和 -c 安装该设备,或者先使用 device delete 将其删除。
  • 如果在设备创建之后某个步骤失败,错误消息会如实说明,并给出移除该设备的 device delete 命令。请运行该命令,然后再次运行同一个命令。

错误

失败时以退出码 1 结束,并给出一句说明。实例给出的说明跟在状态码之后。

响应说明的内容
无法访问、证书不受信任无法访问实例,并附带关于 --ca-cert 的提示
400实例拒绝了请求,以及原因
401实例不接受该密钥,以及密钥的来源。对于已保存的密钥,给出用来替换它的 login
403密钥无权执行此操作:其权限范围,或其被限定的项目或应用,不允许这样做。whoami 会显示它们
404对于 delete:设备不在该项目中,或密钥无法看到它。对于 create:对于此密钥,该项目不存在
409与平台现有内容的冲突,例如项目中已有同名设备
500、503、504平台不可用。对于 create 和 delete,还会说明更改可能已经生效,以及可用来查看的 device list

请求一旦发出之后的任何失败,以及在 create 或 delete 等待期间按下 Ctrl-C 之后,消息都会说明更改可能已经生效。重复操作之前请运行 ironflock device list:对同一名称再次 create 会产生冲突,而 API 不会再次返回第一个设备的凭据(Studio 可以下载其配置文件)。

退出码

这些命令使用与每个命令相同的退出码。

代码在此处的含义
0完成
1实例或平台拒绝或失败、项目名称没有匹配的项目,或无法写入文件
2命令行有误:缺少标志或标志错误、项目名称由多个项目共用、文件已存在但未给出 --force、--host 或 --hosts。未向平台发出请求
3没有登录:未设置 IRONFLOCK_API_KEY,也没有已保存的登录;或者凭据文件无法使用。未向平台发出请求
4device delete 的询问被回答为“否”,或者无法询问且未给出 --yes。未删除任何内容
130在向平台发出请求时被中断。更改可能已经生效
Last updated on