bunny-tools

# Bunny CLI 和 MCP 服务器 [](https://www.npmjs.com/package/bunny-tools) [](https://www.npmjs.com/package/bunny-tools) [](https://github.com/bytekcorp/bunny-tools/actions/workflows/ci.yml) [](https://github.com/bytekcorp/bunny-tools/actions/workflows/e2e-nightly.yml) [](LICENSE) **软件包：** `bunny-tools` **·** **二进制文件：** `bunny` **·** **Node.js 版本：** ≥20 ## 为什么使用 bunny-tools Bunny.net 是一个优秀的 CDN/存储/DNS/流媒体平台，但是从终端管理它一直是 DIY 领域。 bunny-tools 解决了这个问题，提供了一个涵盖存储、CDN、DNS、流媒体和边缘脚本的二进制文件，以及一个内置的 MCP 服务器，以便 AI 代理可以驱动每个命令： - **`bunny deploy` 适用于静态网站。** 如果您使用过 `firebase deploy`，则会熟悉其人体工程学设计 → 公共目录 → SHA 缓存差异 → 并行上传 → CDN 消除，全部在一个命令中。 - **`bunny.json` 是您的单一真实来源。** 版本控制在 git 中。每个命令都遵循它。 JSON 模式发布在 `unpkg.com/bunny-tools/schema/bunny.schema.json`。 - **通过 MCP 实现 AI 原生。** AI 代理看到的表面与您看到的一样 - 每个代理都不需要单独的插件。 `bunny install mcp` 一次注册到 Claude Code 中。 - **经过验证的端到端。** 185 个单元测试 + 每夜针对真实 Bunny 账户的漂移检测。我们在 Bunny API 更改破坏您的部署之前捕获它们。 ## 安装 ### 作为 CLI ```bash npm install -g bunny-tools ``` ### 作为 MCP 服务器（推荐用于 AI 工作流） 对于 Claude Code： ```bash claude mcp add bunny-tools npx -y bunny-tools mcp ``` 对于 Claude Desktop，请添加到 `claude_desktop_config.json`： ```json { "mcpServers": { "bunny-tools": { "command": "npx", "args": ["-y", "bunny-tools", "mcp"] } } } ``` 安装后，任何 Claude 会话都可以使用 15 个高级工具（`bunny.deploy`、`bunny.purge`、区域/ DNS CRUD）以及 3 个资源（`bunny://manifest`、`bunny://agents`、`bunny://config/current`），而无需事先了解。有关完整的工具表面，请参见下面的 [MCP 服务器](#mcp-服务器-ai-集成)。 ## 快速入门 ```bash bunny init # 交互式：身份验证 + 功能选择器 + bunny.json bunny deploy --dry-run # 预览 bunny deploy # 存储同步 + CDN 消除 ``` `bunny init` 带您完成： 1. Bunny 账户 API 密钥（如果已在环境变量或密钥链中，则跳过） 2. 功能多选 - 存储 + CDN、DNS、流媒体、Magic Containers、边缘脚本 3. 每个功能配置（例如，对于存储 + CDN：公共目录、存储区域、密码、拉取区域、清除策略） CI 的非交互式表单： ```bash bunny init --non-interactive --features=storage \ --api-key=$BUNNY_API_KEY \ --storage-zone=my-app \ --storage-password=$BUNNY_STORAGE_PASSWORD \ --pull-zone=12345 ``` 添加 `--ci` 以生成 `.github/workflows/bunny-deploy.yml` 以用于 GitHub Actions。 ## AI 代理的快速入门 安装 MCP 服务器（参见 [安装](#安装)）后，Claude Code 和 Claude Desktop 可以驱动每个命令。进入任何项目并尝试： | 您说的话 | 会发生什么 | | --- | --- | | **"使用 bunny-tools 为此项目设置 CI/CD"** | 运行 `bunny init`，使用官方操作写入 `.github/workflows/deploy.yml`，并列出您需要添加的机密 | | **"将此网站部署到 Bunny"** | 读取现有的 `bunny.json`，运行 `bunny deploy`（首先进行干预） | | **"清除标记为 release-2026-04 的 CDN 缓存"** | 调用 `bunny.purge`，标签为 `release-2026-04` | | **"显示我的 Bunny 账户信息"** | 调用 `bunny.whoami` + 列出可达区域计数 | | **"在 example.com 的 Bunny DNS 区域中添加一个 A 记录到 www → 1.2.3.4"** | 解析区域 ID，调用 `bunny.dns_record_add` | 要获得最佳效果，请在新项目中将 2 行提示放入 `CLAUDE.md`： ```markdown ## 部署 该项目使用 bunny-tools。运行 `bunny init` 进行首次设置，然后运行 `bunny deploy`。参见 `bunny manifest --pretty` 以获取完整的命令曲面。 ``` 这将 Claude 锚定到该项目的 bunny-tools。 --- ## 设置和身份验证 | 命令 | 描述 | | --- | --- | | `bunny init` | 交互式设置 - 身份验证 + 功能选择器 + bunny.json | | `bunny configure` | 演练 - 将凭证存储在命名配置文件中 | | `bunny configure list` | 列出所有凭证配置文件 + 范围（掩码） | | `bunny configure switch <name>` | 设置活动配置文件 | | `bunny configure remove <name> [scope]` | 删除配置文件或其中的单个范围 | | `bunny use [alias]` | 从 `.bunnyrc` 切换活动别名（或列出别名） | | `bunny whoami` | 显示当前帐户上下文 + 可达区域计数 | | `bunny docs [topic]` | 在浏览器中打开 Bunny.net 文档 | **示例** ```bash bunny configure --profile=staging bunny configure switch staging ``` ## 部署和清除 | 命令 | 描述 | | --- | --- | | `bunny deploy` | 将公共目录同步到存储区域并清除 CDN 缓存 | | `bunny purge <target>` | 按 URL、 `tag:<name>` 或 `pullzone:<id>` 进行清除 | **示例** ```bash bunny deploy --dry-run bunny purge tag:release-2026-05 ``` ## 存储（文件操作） | 命令 | 描述 | | --- | --- | | `bunny storage upload <local> <remote>` | 将单个文件上传到活动区域 | | `bunny storage download <remote> <local>` | 从区域下载单个文件 | | `bunny storage list [path]` | 列出存储区域路径 | | `bunny storage delete <path>` | 删除文件或路径（对目录使用 `--recursive`） | | `bunny storage sync <local-dir>` | 镜像本地目录到区域 - SHA 缓存差异，并行上传 | **示例** ```bash bunny storage sync ./dist --zone=my-app ``` ## 存储区域 | 命令 | 描述 | | --- | --- | | `bunny storagezone list` | 列出存储区域 | | `bunny storagezone get <id\|name>` | 获取存储区域 | | `bunny storagezone create <name>` | 创建存储区域 | | `bunny storagezone update <id> --body=<json>` | 更新存储区域（原始 JSON 正文） | | `bunny storagezone delete <id>` | 删除存储区域 | ## 拉取区域（CDN） > **提示：** `bunny cdn ...` 在 `bunny pullzone ...` 任何地方都有效 - Bunny 的仪表板称这些为 "CDN"，所以别名是为了肌肉记忆。规范名称遵循 Bunny 的 API（`pullzone`）。 | 命令 | 描述 | | --- | --- | | `bunny pullzone list` （或 `bunny cdn list`） | 列出拉取区域 | | `bunny pullzone get <id>` | 获取拉取区域 | | `bunny pullzone create <name>` | 创建拉取区域 | | `bunny pullzone update <id> --body=<json>` | 更新拉取区域（原始 JSON 正文） | | `bunny pullzone delete <id>` | 删除拉取区域 | | `bunny pullzone edgerule list <id>` | 列出拉取区域上的边缘规则 | | `bunny pullzone edgerule add <id> --rule=<json>` | 添加边缘规则（原始 JSON 规则） | | `bunny pullzone edgerule delete <id> <rule-id>` | 删除边缘规则 | | `bunny pullzone hostname list <id>` | 列出链接到拉取区域的自定义主机名 | | `bunny pullzone hostname add <id> <hostname>` | 链接主机名 + 提供 Let's Encrypt 证书 + ForceSSL。幂等。 `--no-force-ssl` 退出 HTTP→HTTPS 重定向 | | `bunny pullzone hostname remove <id> <hostname>` | 取消链接自定义主机名 | **示例** ```bash bunny cdn edgerule list 12345 # 将 DNS 连接到拉取区域（2 个步骤 - `add` 执行链接 + 证书 + ForceSSL # 操作；`--no-force-ssl` 退出 HTTP→HTTPS 重定向）： bunny pullzone hostname add 5780316 example.com # ~2-90s bunny dns record add 783181 PULLZONE @ --pull-zone=5780316 # 或通过原子连接域命令一次完成所有操作： bunny domain connect 5780316 example.com --dns-zone=783181 ``` ## DNS | 命令 | 描述 | | --- | --- | | `bunny dns list` | 列出 DNS 区域 | | `bunny dns get <id\|domain>` | 获取 DNS 区域 | | `bunny dns create <domain>` | 创建 DNS 区域 | | `bunny dns delete <id>` | 删除 DNS 区域 | | `bunny dns record list <zone>` | 列出区域上的记录 | | `bunny dns record add <zone> <type> <name> <value>` | 添加记录（位置参数） | | `bunny dns record update <zone> <record-id> --body=<json>` | 更新记录 | | `bunny dns record delete <zone> <record-id>` | 删除记录 | **支持的记录类型：** 标准 `A`、`AAAA`、`CNAME`、`TXT`、`MX`、`SRV`、`CAA`、`NS` 以及 Bunny 路由类型 `REDIRECT`、`PULLZONE`、`PTR`、`SCRIPT`。`PULLZONE` 和 `SCRIPT` 需要 `--link-name=<id>`（链接的拉取区域/脚本 ID）。对于 `PULLZONE`，您可以使用便捷标志 `--pull-zone=<id>` 代替，它将从拉取区域的元数据中填充值和链接名称。（`FLATTEN` 在 Bunny 的 OpenAPI 规范中记录，但实时 API 拒绝它；如果 Bunny 在服务器端启用，则删除支持的类型 - 重新添加时）。 **示例** ```bash # 标准 A 记录 bunny dns record add 783181 A www 1.2.3.4 --ttl=300 # 重定向 www → https://example.com bunny dns record add 783181 REDIRECT www https://example.com # 将 DNS 连接到拉取区域 - 自动填充值 + 链接名称 bunny dns record add 783181 PULLZONE "" --pull-zone=5780316 # 或原始表单，如果您已经知道 pz 名称 bunny dns record add 783181 PULLZONE "" my-pz-name --link-name=5780316 ``` ## 流媒体 | 命令 | 描述 | | --- | --- | | `bunny stream library list` | 列出流媒体库 | | `bunny stream library create <name>` | 创建流媒体库 | | `bunny stream library delete <id>` | 删除流媒体库 | | `bunny stream video list <library>` | 列出库中的视频 | | `bunny stream video upload <library> <file>` | 将视频上传到库 | | `bunny stream video delete <library> <video-id>` | 删除视频 | **示例** ```bash bunny stream video upload 42 ./demo.mp4 --title="My demo" ``` ## 魔法容器 | 命令 | 描述 | | --- | --- | | `bunny containers app list` | 列出容器应用 | | `bunny containers app delete <id>` | 删除容器应用 | > `containers app create` 延迟到 v0.2 - Bunny 的 v3 模式需要 `runtimeType` + `containerTemplates[]` + `autoScaling`，而当前 CLI 界面尚未对其进行建模。现在，请通过 Bunny 仪表板进行管理。 ## 边缘脚本 | 命令 | 描述 | | --- | --- | | `bunny scripting list` | 列出边缘脚本 | | `bunny scripting deploy <name> --code=<file>` | 创建或更新脚本（双模式） | | `bunny scripting delete <id>` | 删除脚本 | **示例** ```bash bunny scripting deploy my-router --code=./worker.js ``` ## 发现和 AI | 命令 | 描述 | | --- | --- | | `bunny manifest --pretty` | 完整的 JSON 注册机（机器可读曲面） | | `bunny manifest --names` | 每行一个命令名称 - 适合 shell 补全 | | `bunny <any-command> --help-json` | 任何命令的 JSON 帮助 | | `bunny mcp` | 启动 MCP stdio 服务器（15 个工具，3 个资源） | 参见 [`AGENTS.md`](./AGENTS.md) 以获取 AI 代理的指导。 --- ## 全局标志 适用于任何命令： | 标志 | 效果 | | --- | --- | | `-c, --config <path>` | 覆盖 `bunny.json` 位置 | | `--cwd <dir>` | 像从此目录启动一样运行 | | `-e, --env <alias>` | 一次性 `.bunnyrc` 别名 | | `-p, --profile <name>` | 一次性凭证配置文件 | **示例** ```bash bunny --profile=staging deploy ``` ## 配置 **`bunny.json`**（每个项目，git 跟踪）： ```jsonc { "$schema": "https://unpkg.com/bunny-tools/schema/bunny.schema.json", "deploy": { "publicDir": "dist", "ignore": ["bunny.json", ".bunnyrc", "**/.*", "**/node_modules/**"], "storageZone": "my-app", "region": "ny", "concurrency": 8, "pullZones": [{ "id": 12345, "purge": "all" }] } } ``` **`.bunnyrc`**（每个开发者别名，gitignored）： ```json { "default": "prod", "aliases": { "prod": { "storageZone": "my-app", "pullZones": [12345] }, "staging": { "storageZone": "my-app-stg", "pullZones": [12346] } } } ``` **多账户配置文件（`~/.config/bunny-tools/credentials.json`）： ```jsonc { "active": "default", "profiles": { "default": { "account": "...", "storage:my-app": "..." }, "staging": { "account": "...", "storage:my-app-stg": "..." } } } ``` 使用 `bunny configure switch <name>` 切换活动配置文件，或一次性使用 `bunny --profile=<name> <cmd>` 或 `BUNNY_PROFILE=<name>`。 ## 身份验证模型 四个身份验证范围（都使用 `AccessKey` HTTP 头）： - `account` - 帐户 API 密钥 - `storage:<zone>` - 存储区域密码（每个区域） - `stream:<lib>` - 流媒体库 API 密钥（每个库） - `database:<name>` - 数据库访问密钥 **解析器链（每个调用站点）：`--flag` → 作用域 env（例如 `BUNNY_STORAGE_PASSWORD_MY_APP`）→ 通用 env (`BUNNY_STORAGE_PASSWORD`) → OS 密钥链（`<profile>:<scope>` 密钥）→ `~/.config/bunny-tools/credentials.json` → 交互式提示。 ## GitHub Actions `bunny init --ci` 生成一个使用 npm-install + `bunny deploy` 的工作流： ```yaml - name: 安装 bunny-tools run: npm install -g bunny-tools - name: 部署 env: BUNNY_API_KEY: ${{ secrets.BUNNY_API_KEY }} BUNNY_STORAGE_PASSWORD_MY_APP: ${{ secrets.BUNNY_STORAGE_PASSWORD_MY_APP }} run: bunny deploy ``` 一个复合动作包装器（`bytekcorp/bunny-tools-deploy-action@v1`）正在 v0.2 路线图中提供更符合人体工程学的设计。上面的 npm-install 表单是 v0.1 的规范路径。 ## MCP 服务器（AI 集成） 安装步骤在上面 [安装 → 作为 MCP 服务器](#作为-mcp-服务器推荐用于ai工作流) 下。配置完成后，服务器暴露： **工具（15 个）：** `bunny.deploy`、`bunny.purge`、`bunny.init`、`bunny.manifest`、`bunny.whoami`、存储区域 CRUD、拉取区域 CRUD、DNS 区域 + 记录 CRUD，以及 `bunny.run` 作为任何 CLI 调用逃生舱。 **资源（3 个）：** - `bunny://manifest` - 完整的 JSON 注册表（机器可读曲面） - `bunny://agents` - AGENTS.md（工作流、陷阱、AI 代理约定） - `bunny://config/current` - 从 `bunny.json` + 活动别名解析的配置 **跨项目使用。** 安装 MCP 服务器后，将 2 行提示放入任何新项目的 `CLAUDE.md` 以将 Claude 锚定到 bunny-tools： ```markdown ## 部署 该项目使用 bunny-tools。运行 `bunny init` 进行首次设置，然后运行 `bunny deploy`。参见 `bunny manifest --pretty` 获取完整的命令曲面。 ``` ## 开发 ```bash git clone https://github.com/bytekcorp/bunny-tools cd bunny-tools npm ci npm run build npm test npm run dev -- manifest --pretty ``` 有关针对真实 Bunny 帐户的端到端测试（漂移检测），请参见 [`docs/e2e-testing.md`](docs/e2e-testing.md)。 有关发布说明，请参见 [`docs/deployment-guide.md`](docs/deployment-guide.md)。 ## 常见问题 **这是官方 Bunny.net CLI 吗？** 不，bunny-tools 是社区 CLI。Bunny.net 发布 [`@bunny.net/cli`](https://www.npmjs.com/package/@bunny.net/cli)，专注于数据库、Magic Containers 和 Edge 脚本。 bunny-tools 涵盖不同的曲面（存储、CDN、DNS、流媒体、边缘脚本）并附带一个 MCP 服务器用于 AI 代理。 **为什么二进制文件名为 `bunny`？** 短且符合品牌。注意 `@bunny.net/cli` 也安装了一个 `bunny` 二进制文件，因此安装两者都会发生冲突 - 选择一个或为另一个使用 `npx`。 **我可以在 CI 中使用它吗？** 是的。 `bunny init --ci` 生成一个 `.github/workflows/bunny-deploy.yml`。所有命令都遵循 `BUNNY_API_KEY` 和每个区域作用域的环境变量。 **它在没有 Node.js 的情况下是否有效？** 目前仅支持 npm（Node 20+）。 单独的二进制文件正在 v0.2 路线图中开发中。 ## 许可 MIT - 参见 [LICENSE](./LICENSE)。