登录与设备管理
这些命令与 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.com | https://api.ironflock.com |
Appliance 的域名 factory.example.com | https://api.factory.example.com |
打开 Studio 所用的地址 https://factory.example.com/projects/12 | https://api.factory.example.com |
API 自身的主机 api.factory.example.com | https://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,也没有已保存的登录;或者凭据文件无法使用。未向平台发出请求 |
| 4 | device delete 的询问被回答为“否”,或者无法询问且未给出 --yes。未删除任何内容 |
| 130 | 在向平台发出请求时被中断。更改可能已经生效 |