nae —— NewBee App Engine CLI

平台命令行客户端。参数直达、默认人类可读，加 -o json 即出 JSON，便于脚本/管道里解析。

📖 完整文档（含用法范例 / 调试技巧）：https://workshop.newbeebox.com/app_engine/documents/nae-cli/ markdown 原文：https://workshop.newbeebox.com/app_engine/documents/nae-cli/md/

安装

npm i -g @newbeebox/newbeebox-app-engine-cli

需要 Node ≥ 18（用到内置 fetch）。

登录

CLI 用「个人访问令牌」鉴权。密钥明文只在创建时显示一次，请注意保存。

nae login

会引导你在浏览器打开网页端 「CLI 配置」 页创建一枚密钥，复制后粘贴回控制台即可。也可跳过交互直接传入：

nae login --token nae_xxxxxxxx

CI / 脚本场景免登录，直接用环境变量（优先级高于本地配置）：

export NAE_TOKEN=nae_xxxxxxxx
export NAE_BASE_URL=https://workshop.newbeebox.com   # 可选，默认即此
nae apps

配置存于 ~/.nae/config.json。nae logout 清除本地密钥。

输出契约

• stdout：默认人类可读文本；加 -o json 出美化 JSON、-c/--compact 出紧凑单行 JSON。logs/exec 始终直出原始文本。
• stderr：只放给人看的提示、进度、错误。
• 退出码：0 成功；1 业务错误；2 未登录/密钥失效；3 网络不可达。

所以脚本里可以安全地 nae apps -o json 2>/dev/null | jq '.[].AppID'。

命令

身份 / 配额

| 命令 | 说明 | |------|------| | nae whoami | 当前身份（uid/用户名/角色/命名空间） | | nae quota | 配额用量（CPU/内存/存储/应用数 的 已用/上限） | | nae llm | 内置 LLM 网关状态：月度额度/本月用量/令牌前缀/内置环境变量名/按模型明细 | | nae llm rotate --yes | 轮换网关令牌（旧令牌立即失效，在跑应用需重启拿新值） | | nae config | 查看本地配置（密钥脱敏） | | nae docs [主题或命令名] | 功能速览 + 线上文档直达链接（如 nae docs assets） |

应用

| 命令 | 说明 | |------|------| | nae apps [--all] | 列出应用（--all 仅管理员，看全平台） | | nae app <appid> | 应用详情/状态/设置 | | nae children <appid> | 子服务列表（如 Milvus 的 etcd/minio） | | nae create --app-id <id> [...] | 创建应用（见下） | | nae update <appid> [...] | 改配置（端口/资源/env/跟踪 tag 等；读-改-写，只覆盖传入字段） | | nae delete <appid> | 删除应用（模板级联清子服务/PVC/secret），幂等 |

创建普通应用：

nae create --app-id myweb --tag latest --port 8080 \
  --cpu 500m --mem 512Mi --env '{"FOO":"bar"}'
# 自带 basePath 的框架（如 Next.js）加 --keep-path-prefix
# 仅内部访问（不导出外链，只在集群内经 DNS+端口调用）加 --internal-only（创建后不可改）

创建模板应用：

nae create --kind template --app-id myredis \
  --template redis --storage 2Gi --config '{"password":"..."}'

创建静态站点（只要 app-id，之后用 nae pages deploy 发布）：

nae create --kind static --app-id mysite

静态站点

纯前端产物（HTML/CSS/JS）不用容器：zip 上传即发布，站点由 CDN 全球分发， 地址 https://pages.newbeebox.com/<appid>/。

| 命令 | 说明 | |------|------| | nae pages deploy <appid> [path] | 发布：目录就地打 zip（或直接给 .zip）上传，整站替换上线 | | nae pages refresh <appid> | 手动刷新 CDN 缓存（60 秒冷却），改动立即全网生效 | | nae pages deploys <appid> | 最近部署记录 | | nae pages rollback <appid> <did> | 回滚到某次成功部署（ID 见 deploys） | | nae pages files <appid> | 站点当前文件清单（只读） | | nae pages logs <appid> [--minutes N] | 源站访问日志 + 简单统计 | | nae pages stats <appid> | 边缘访问 7 天简报（延迟数小时） | | nae pages access-logs <appid> | 边缘访问日志逐行分页（留存 7 天） |

nae pages deploy mysite ./dist          # 打包 dist 目录并发布
nae pages deploy mysite site.zip        # 直接上传现成 zip
nae pages deploy mysite ./dist --no-refresh   # 发布但不刷缓存（改动最长 1 天后生效）

• 站点根（目录根或 zip 内唯一顶层目录）必须含 index.html 首页。
• 发布是整站替换：本次包里没有的旧文件会被删除；解包后总大小不超过存储配额（默认 2GB）。
• 目录打包自动跳过 .git/、符号链接与系统垃圾文件；上传直传对象存储，不经平台、不发凭据。

资产存储（OSS）

每个普通应用/静态站点自带独立对象存储空间（默认开通）：公开文件有 CDN 公网地址，私有文件走限时签名链接。

| 命令 | 说明 | |------|------| | nae assets quota <appid> | 配额与用量（公开/私有分列） | | nae assets ls <appid> [dir] [-V public\|private] | 逐层浏览（--marker 翻页） | | nae assets upload <appid> <file> [--dest p] [-V ...] | 上传（平台签票 → 直传 OSS，字节不经平台） | | nae assets link <appid> <path> | 给私有文件签限时访问链接 | | nae assets rm <appid> <path...> | 删除（--all --yes 清空整段） | | nae assets refresh <appid> [path...] | 刷新公开资产 CDN 缓存 | | nae assets stats <appid> | 近 7 天访问简报 |

nae assets upload myapp ./logo.png                 # 公开：立即获得 CDN 地址
nae assets upload myapp ./secret.json -V private   # 私有：访问走 nae assets link

构建（本机无 Docker）

没装 Docker、或不想本地 docker build && push？把带 Dockerfile 的项目目录交给平台代构建， 构建成功推镜像后照常触发自动部署（与你本地 push 等效）。

| 命令 | 说明 | |------|------| | nae build <appid> [path] | 打包本地目录上传，由平台代跑 docker build/push；缺省跟随日志直至结束 | | nae builds <appid> | 列出该应用最近的构建任务（状态 / 排队位置） | | nae build-logs <jobid> [-f] | 某构建任务日志（游标续读，-f 跟随至结束） | | nae build-cancel <jobid> | 取消排队中的任务（仅 queued 可取消） |

nae build myweb                      # 打包当前目录，构建并跟随日志
nae build myweb ./service --tag v2   # 指定上下文目录与镜像 tag
nae build myweb --dockerfile docker/Dockerfile.prod
nae build myweb --no-follow          # 只入队，稍后 nae build-logs <job> -f 再看

• 打包遵循上下文根的 .dockerignore，务必排除 node_modules/、构建产物、.git/；压缩后上限 200MB。
• 镜像运行时约束同样适用（非 root、端口 ≥ 1024）；Dockerfile 由你提供。
• 网页端「应用详情 → 构建」Tab 也能选项目文件夹上传，效果一致。

生命周期

| 命令 | 说明 | |------|------| | nae start <appid> | 启动 | | nae stop <appid> | 停止（缩到 0） | | nae restart <appid> | 滚动重启 | | nae scale <appid> <replicas> | 扩缩容 |

版本 / 回滚

| 命令 | 说明 | |------|------| | nae versions <appid> | 镜像版本历史 | | nae rollback <appid> [--seq N] | 回滚（默认上一版） |

运行态

| 命令 | 说明 | |------|------| | nae pods <appid> | Pod 列表 | | nae events <appid> [--limit N] | 事件/时间线 | | nae metrics <appid> [--history 1h|6h|24h|7d] | 实时用量；--history 看趋势 | | nae ingress <appid> [--range 24h] | 入口流量合计 + 趋势 | | nae logs <appid> [--pod P] [--container C] [--follow] [--tail N] | 日志（缺省自动取首个 Pod） | | nae exec <appid> -- <cmd...> | 在容器内执行一条命令（非交互；输出与退出码透传） | | nae fs ls/put/get/mkdir/rm <appid> ... | 容器文件操作（列/传/下/建目录/删；--pod/--container 可指定） |

转发调试

| 命令 | 说明 | |------|------| | nae forward app <appid> [--port N] [--local N] | 应用端口转发到本地（类 kubectl port-forward） | | nae forward llm [--local N] | 内置 LLM 网关转发到本地调试 |

模板

| 命令 | 说明 | |------|------| | nae templates | 可用模板目录 | | nae reset-password <appid> [--password pw] | 重置模板应用连接密码（不清数据） | | nae expand-storage <appid> <size> | 存储扩容（只增不减，立即生效，不影响已有数据） |

CLI 密钥的创建/查看/吊销仅在网页端「CLI 配置」页操作，命令行不提供。

全局选项

| 选项 | 说明 | |------|------| | -o, --output <format> | 输出格式：text（默认，人类可读）/ json | | -c, --compact | 紧凑 JSON（单行，隐含 -o json） | | --base-url <url> | 覆盖平台地址（亦可 NAE_BASE_URL） | | --token <token> | 覆盖访问密钥（亦可 NAE_TOKEN） |