# @appforge-ci/admin-cli 中文文档

规范地址：https://npmcn.com/package/%40appforge-ci/admin-cli/

版本：0\.3\.29
npm 元数据更新时间：2026-10-24T09:14:19.262Z
中文译文更新时间：2026-11-06T21:05:55.003Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40appforge-ci/admin-cli
原文对照：https://npmcn.com/package/%40appforge-ci/admin-cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：7 MB，85 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：4 个
- 首次发布：2026-09-23T07:59:52.488Z
- 最新版本发布：2026-10-24T09:14:19.094Z
- 近 30 天下载量：2333（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

`appforge-admin` ——用于车队管理的平台-操作员CLI(滚动,列表,排出,恢复,重启,运行于Mac迷你机上的维护脚本). 这是一个 **单独** 工具从 `appforge` (单位:千美元)`packages/cli`),用于AppForge的客户,没有车队

## 安装

```sh
npm install @appforge-ci/admin-cli
```

也可以使用：`pnpm add @appforge-ci/admin-cli`、`yarn add @appforge-ci/admin-cli`、`bun add @appforge-ci/admin-cli`

## README

# @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`数字 :

```bash
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本身,但只有在它的退货已经建成的时候.

## 使用量

```bash
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`(单位:千美元) **当地** 当无二进制时,显而无所为,无所出错. 要用发行者自己的旗帜来建造一个:

```sh
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节.

## 常见问题

### @appforge-ci/admin-cli 是什么？

appforge-admin ——用于车队管理的平台-操作员CLI\(滚动,列表,排出,恢复,重启,运行于Mac迷你机上的维护脚本\)\. 这是一个 单独 工具从 appforge \(单位:千美元\)packages/cli\),用于AppForge的客户,没有车队

### 如何安装 @appforge-ci/admin-cli？

在项目目录运行 npm install @appforge-ci/admin-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 appforge-admin，可以用 npx appforge-admin 直接运行。

### @appforge-ci/admin-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/appforge-ci\_\_admin-cli 是否存在。

### @appforge-ci/admin-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @appforge-ci/admin-cli 可以商用吗？

@appforge-ci/admin-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @appforge-ci/admin-cli 的下载量有多少？

根据 npm 官方下载统计，@appforge-ci/admin-cli 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,333 次，日均约 78 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @appforge-ci/admin-cli 还在维护吗？

最新版本 0\.3\.29 发布于 2026/10/24（14 天前）；至今共发布 36 个版本，其中过去 12 个月发布了 36 个；首次发布于 2026/09/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。