@appforge-ci/admin-cli (英语)

appforge-admin 用于车队管理的平台操作员CLI(注册号:, 列表,排出,恢复,重启,运行Mac minids上的维护脚本). 这个 是一个 单独 工具从 appforge (单位:千美元)packages/cli),用于 AppForge的客户,完全没有舰队命令——看 docs/self-hosting.md"Fleet Management"一节 说明为什么保留它们 分开 配置居住于 ~/.appforge-admin/config.json,独立于 ~/.appforge/config.json。 。 。 .

整个日常运行簿(读取机队状态,排除故障) NotReady编号 :offline 迷你、旋转、退出) 已安装,见 docs/fleet-management.md。 。 。 .

安装

在已经复制的机器上 (常见情况—— 你自己的笔记本电脑,或者一个麦克迷你 git clone(d) 建造和安装 打开 PATH 与 npm link数字 :

pnpm install                              # once, from the repo root
pnpm --filter @appforge-ci/admin-cli build
cd packages/admin-cli && npm link         # symlinks `appforge-admin` onto PATH

npm link 需要重新运行,只有当 符号链接本身得到 删除( 例如 ). npm uninstall -g @appforge-ci/admin-cli)——平原 重建(pnpm --filter @appforge-ci/admin-cli build足够选择 由于链接点在 dist/ 已经就位.

从 npm (一个没有退货的Mac得到它的方式): .github/workflows/publish.yml 发表 每个释放标签上的此软件包( e)git tag vX.Y.Z && git push origin vX.Y.Z,任务 publish-clis),这样 npm install -g @appforge-ci/admin-cli@latest 安装并重新运行,这就是您如何更新它。 这个 代理的自我更新确实如此 没有 在发布- mode Mac (# 852) 上触摸此安装: 在 Mac 的代理移动后 添加 Mac- side 命令的发布(install-vm-user,以相同的命令更新CLI,或 命令失败 unknown command复检出Mac,其代理自我更新也重建 这个CLI本身,但只有在它的退货已经建成的时候.

使用量

appforge-admin login --api-url <api-url> --admin-api-url <admin-api-url>   # once; add --web to approve in a browser instead of typing your password here
appforge-admin logout                                  # remove the login from THIS machine (the file and leftover copies) AND revoke its token on the server — see below
appforge-admin agents list
appforge-admin agents add-mac --name "my-mac-mini"    # run ON the mini you're enrolling — see docs/self-hosting.md; it ends the login there itself (--keep-login keeps it)
appforge-admin agents add-mac --force                 # re-enroll THIS Mac (rotate token / rename) — same fleet row, never a duplicate
appforge-admin agents decommission <agentId>          # permanently remove a mini (retired machine, or a stale duplicate row)
appforge-admin agents drain <agentId>
appforge-admin agents resume <agentId>
appforge-admin agents reboot <agentId>
appforge-admin agents restart <agentId>       # just the agent process (e.g. after a manual upgrade) — no reboot needed
appforge-admin agents cancel-build <agentId> <buildId>  # kill one wedged build, other concurrent builds on the same mini untouched
appforge-admin agents allow-remote-control <agentId> --on|--off  # authorize (or revoke) the VNC "Connect" button's mouse/keyboard control — off by default for every agent
appforge-admin agents allow-vpn <agentId>      # approve a Mac for site-to-site VPN duty (platform admin) — off by default; also deny-vpn <agentId> to revoke
appforge-admin agents run-script <agentId> <scriptName>
appforge-admin agents commands <agentId> [--limit 20]  # remote-command history + who issued each one — see docs/fleet-management.md
appforge-admin agents update <agentId> [--to <version>]   # roll one mini onto a new agent build (OTA) — see docs/fleet-management.md
appforge-admin agents update --all                        # every enrolled mini, one at a time
appforge-admin agents install-vm-helper [--no-gateway] [--allow-local-gateway]  # per-build VMs: the root-owned VM helper + sudoers line, and the VM gateway binary this package carries (root-owned, see below)
appforge-admin agents bootstrap [--full]              # install missing toolchains on THIS Mac
appforge-admin agents enroll                           # advanced: just a token, no local enrollment — see add-mac instead
appforge-admin agents label <agentId> canary m4        # set a Mac's operator labels (replaces them; selectors match label:canary); --clear removes all
appforge-admin fleet steps list                        # setup-step catalog: per step how many Macs applied / missing / failed / unknown, and which restart something (drain first)
appforge-admin fleet steps status [--step <id>]        # drift per Mac; a Mac that has not reported is shown as "not reported", not as drift
appforge-admin fleet steps apply <stepId> --selector <text> [--canary N] [--batch N] [--max-failures 10%|N] [--timeout MIN] [--force] [--dry-run] [--wait] [--yes]
appforge-admin fleet steps rollouts [--limit N]        # recent rollouts
appforge-admin fleet steps rollout <id>                # one rollout: policy, who/when, halt reason, per-Mac result
appforge-admin fleet steps cancel <id>                 # running Macs finish, the rest are skipped

向许多Macs推出一个设置步骤

fleet steps apply 替换为 ssh -t host 'sudo ...' 每Mac一次( 设计 : docs/fleet-steps.md) (中文(简体) ). 选择者是 要求并且绝不默认整个舰队: all, (中文(简体) ), ids:a,b, (中文(简体) ), name:mini-*, (中文(简体) ), label:canary, (中文(简体) ), percent:25, (中文(简体) ), missing:<step>, (中文(简体) ), failed:<step>与 + (AND) (韩语). 先试试看 --dry-run:它用M批号打印出“N Macs”(canary) ), K 已经应用"和每Mac表(批次,当前步态,跳过理性),并创建一无所有. 真实的运行打印 同一计划并请求确认,除非 --yes,然后打印推出的标识;推出的标识在服务器上运行,无论是否 CLI保持开放。 与 --wait cLI 跟着它,打印每个Mac的进度,如果推出停止,则退出非0 已取消或任何 Mac 失败( 停止原因和失败 Macs 的结果文本被打印) 。 Ctrl-C 等待只停留 观看; fleet steps rollout <id> 以后再展示出来 fleet steps cancel <id> 别闹了 服务器本身的不良消息 step id, 选择器或策略按原样打印。 重起炉灶首先消耗了Mac.

--api-url编号 :--admin-api-url 只要先把那个传出去 login —— 说 他们被保存到 ~/.appforge-admin/config.json 之后又重新使用过. 只有管理员的账户 PLATFORM_ADMIN_EMAILS 密钥可以在此登录; 查看 docs/self-hosting.md。 。 。 .

基于密码 login (无) --web) 以交互方式促进2FA 代码,如果账户已启用,则没有 --totp-code 也没有 --recovery-code 被通过——见: docs/security.md'是"2FA (TOTP)" 注释. login --web设备授权流程没有密码步骤 所有,所以它不受影响 无论是哪种方式.

永远不要将登录留在构建的Mac上

login 存储长寿 afk_ API 令牌输入 ~/.appforge-admin/config.json。一个平台管理员的标志 驱动整个舰队 (排水,重启,更新,VNC,招生) 和为租户建造的Mac作为同一个用户运行他们的标准级建筑,所以任何 他们可以读取该文件。 保持登录在自己的机器上。 如果您必须登录一个已建 Mac (用于 agents add-mac,登录 结束于 add-mac 完成; 其它情况下, 运行 appforge-admin logout 等你们结束的时候:

• appforge-admin logout 删除 config.json 和任何 config.json.* 复制到旁边( 被杀死的保存的临时文件, a) .bak, (中文(简体) ), 打印删除的内容, 将目录中的其他所有内容单独保存( 从未输入目录) , 当运行时安全 什么都没有 A 类 config.json 即同义链接是未链接的,而不是跟随的:它指向的文件的输出名称,它保留.
• 这个 也取消服务器上的令牌 (单位:千美元)DELETE /auth/token 打开 --api-url, 认证 API; 第952期: 符号停止工作 有一次,所以一个已经读过的副本已经死了。 文件首先读取,然后在任何网络呼叫之前取出,所以Mac是干净的,即使 aPI 无法访问; 每个已保存的复制件的代号被撤销, 每个代号都与它旁边保存的 API URL 相对 。 如果撤销失败(下行), 航道之前的控制平面) logout 仍然删除登录, 0 退出, 表示无法撤销, 并打印手册 从信任的机器上运行的跟踪 : appforge tokens list (标志是标记) admin-cli:<email> 密码登录后, admin-cli:device-flow 之后 login --web以所创造的时间配他 appforge tokens revoke <id>,并再次登录 在这里。 用手删除文件不会撤销任何内容。 信使从来印出.
• login 在构建时打印一个警告, 作为您登录的账户运行( 代理服务器的配置或启动代理列表在您的家中, 或 一个没有代理的笔记本电脑 也没有任何代理的 别人. agents add-mac 完成时总是 ENDS 登录( 也是服务安装失败时, 因为Mac 已登录) 因为它刚刚使这个账户成为一个构建账户:它撤销了符号并删除了文件,与 logout。 。 。 . agents add-mac --keep-login 保留登录以运行更多 appforge-admin 从 Mac 命令并打印出一行提醒 替换; 运行 logout 当完成. appforge-agent doctor 失败( e)cli-credentials-off-build-mac) 当登录被存储在Mac上时 一个特工 警告和支票什么也拒绝 当吊销必须用手进行时, appforge tokens list 是最新的第一,50到 页面:添加 --offset 50 如果旧登录符不在第一个 为了避免在Mac上登入,请用一次性的代币登入 在自己的机器上铸造appforge-admin agents enroll,则 appforge-agent enroll 在麦克上; infra/mac-mini-setup/provision-remote.sh 执行此任务 : docs/fleet-management.md,"输入一个Mac而不留下登录".

细节和限度: docs/security.md,"一个CLI登录 从不停留在建设Mac上". 标志性自取(问题为#952)由单位和路由测试覆盖;尚未与所部署的控制平面(UNVERIFIED)对接,直到记录到日期运行.

VM 网关二进制

appforge-admin agents install-vm-helper 并安装 VM 网关 ("软网"", docs/vm-gateway.md),将载有该设备的用户空间网络 站点对站点的VPN 输入一个建筑 VM, at /etc/appforge/bin/softnet (基层拥有, 0555其散列记录于 /etc/appforge/softnet.manifest.json二进制船 在此软件包中,在一份清单旁边: dist/softnet 财务报告和审定财务报表 dist/softnet.manifest.json (sha256、大小、承诺、版本、Go工具链和 source数字 : ci 或者说 local) (中文(简体) ). install-vm-helper 对照清单(大小,SHA-256,arm64 Mach-O头)核查二进制,然后才能改变任何情况并拒绝继续不匹配; 也拒绝,改变什么, 一个包裹,其清单说 local (一个二进制的或复制的,包括实验室的建筑)除非 --allow-local-gateway 有赏赐的,有明白的 上面写着 ci 为实验室二进制始终; --no-gateway 离开大门。 这不是代理商故意签名的OTA捆绑的一部分(该捆绑是在代理商账户可以写的地方被打包的;见 docs/security.md) (中文(简体) ).

已发布的软件包总是带有发布工作流程的构建. .github/workflows/publish.yml 交叉编译从标签的 承诺 (可复制: -trimpath,则 go.mod 工具链,带有空缓存的第二个构建必须给出相同的字节)并运行 node scripts/vm-gateway.mjs check --require-ci --version V --commit SHA 在此之前 pnpm publish它拒绝一个不是CI所制造的包裹.

地方发展/离职 (今天的工作,直到 npm 发布配置). pnpm --filter @appforge-ci/admin-cli build 运行 tsc 接下来 scripts/vm-gateway.mjs stage,则留下一个 dist/softnet 单列出一个匹配的列表,并给出一个被复制到(或用 make vm-gateway 内 packages/vpn-proxy(单位:千美元) 当地 当无二进制时,显而无所为,无所出错. 要用发行者自己的旗帜来建造一个:

pnpm --filter @appforge-ci/admin-cli build
pnpm --filter @appforge-ci/admin-cli gateway:build     # needs Go; writes dist/softnet and dist/softnet.manifest.json (source: local, version dev)
node packages/admin-cli/scripts/vm-gateway.mjs check   # ok (softnet dev, commit ..., local build, sha256 ...)
appforge-admin agents install-vm-helper --allow-local-gateway   # on a lab Mac, as the agent's account, without sudo (a released package needs no flag)

gateway:build 套装 GOFLAGS 自己,所以一个开发者 -tags=vmgwlab 无法意外地产生实验室二进制; 实验室建设( make vm-gateway-lab)仅用于基准值 docs/manual-vm-validation.md 绝不能安装在为任何人建造的Mac上。 当地建筑需求 appforge-admin agents install-vm-helper --allow-local-gateway (只有Mac实验室)和 麦克然后运行它 run --gateway 但不为它广告VM VPN特性:只有发布工作流程的构建,在代理商的最小版本上或以上,才能赚取这个收入. pnpm publish 此软件包运行 check --require-ci 首prepublishOnly)),因此手工操作的本地建筑出版失败. 一个真正的Mac的全部安装和验证配方是 docs/manual-vm-validation.md 第9节.