# 范围 CLI ## 目标是什么 Ambit 将应用程序部署到云中的方式使它们完全无法从公共互联网访问。只有在用户的私有 Tailscale 网络中注册的设备才能连接到它们。从外界的角度来看，该应用程序并不存在——没有可供查找的 IP 地址，也没有可供扫描的端口。这很重要，因为将数据库、仪表板或内部工具放在普通互联网上会迫使您构建登录页面、配置防火墙并针对陌生人强化应用程序。 Ambit 跳过了所有这些。访问控制在网络级别处理：如果设备位于 Tailscale 网络上，则可以访问应用程序；如果设备位于 Tailscale 网络上，则可以访问应用程序；如果不是，则在应用程序看到它之前连接就会被拒绝。您创建的每个专用网络称为**范围**。部署到它的每个应用程序都会在该网络名称下获得一个人类可读的地址 - 因此“http://my-app.lab”意味着“lab”范围内的“my-app”应用程序。这些地址会自动适用于在用户 Tailscale 帐户中注册的任何设备。 ## 安装直接通过 npx 运行 — 无需全局安装： npx @cardelli/ambit ## 它是如何工作的图LR A[Tailscale 上的您的设备] -->|Tailscale 隧道| B[Ambit路由器
Fly.io虚拟机] B -->|Flycast / 私有 IPv6| C[您的应用
没有公共IP] Ambit 在 Fly.io 上创建一个路由器，加入用户的 Tailscale 网络，并为该 Ambit 通告私有 IPv6 子网。它还设置了拆分 DNS，以便“*.”查询解析到正确的应用程序。使用“ambit deploy”部署的应用程序会在网络上获得一个私有 Flycast 地址，并且永远不会收到公共 IP。 ## 先决条件 * 安装并验证了`flyctl`（`fly auth login`） * 安装并连接尾秤（`tailscale up`） * Tailscale API 访问令牌 (`tskey-api-...`) — 在创建一个 ## 命令 ### `npx @cardelli/ambit create <网络>` 创建新的专用网络。这是设置新范围时要运行的第一个命令。它在 Fly.io 上部署路由器，将其连接到用户的 Tailscale 网络，并配置分离 DNS，以便可以通过名称访问网络上的应用程序。 npx @cardelli/ambit 创建实验室 npx @cardelli/ambit create lab --org my-org --region sea npx @cardelli/ambit 创建实验室 --no-auto-approve **标志：** * `--org ` — Fly.io 组织别名 * `--region ` — Fly.io 区域（默认值：`iad`） * `--api-key ` — Tailscale API 访问令牌（如果省略，则会交互式提示） * `--tag ` — 路由器的 Tailscale ACL 标记（默认值：`tag:ambit-`） * `--manual` — 跳过自动 Tailscale ACL 配置（tagOwners + autoApprovers） * `--no-auto-approve` — 跳过等待路由器和批准路由（仅部署，稍后配置） * `-y, --yes` — 跳过确认提示 * `--json` — 输出为 JSON（意味着 `--no-auto-approve`） **它的作用：** 1. 验证 Fly.io 身份验证和 Tailscale API 密钥 2.自动配置ACL：将标签添加到Tailscale策略中的`tagOwners`和`autoApprovers`中（用`--manual`跳过） 3. 检查同一网络上是否有重复的路由器 4. 在自定义网络上创建 Fly.io 应用程序 5. 创建一次性、标签范围的 Tailscale 身份验证密钥（从不将 API 令牌发送到路由器） 6. 设置机密：`TAILSCALE_AUTHKEY`、`NETWORK_NAME`、`ROUTER_ID` 7. 部署路由器容器 8.等待设备加入tailnet并发现真实子网（例如`fdaa:4a:d38b::/48`） 9. 如果 ACL 中未配置 autoApprovers，则通过 API 批准子网路由 10. 配置分割 DNS (`*.` → 路由器) 11. 如果可能的话，在本地启用接受路由使用“--no-auto-approve”或“--json”时，将跳过步骤 8-11。 **ACL 自动配置：** 默认情况下，ambit 修补 Tailscale 策略以添加路由器标签的 `tagOwners` 和 `autoApprovers` 条目。使用“--manual”，用户必须自己配置策略，然后路由器才能加入 tailnet： 1. **可视化编辑器**（推荐）：前往，点击“添加标签”，添加所有者为“autogroup:admin”的“tag:ambit-”。 2. **ACL 文件** ：前往并添加到 tagOwners： "tagOwners": { "tag:ambit-<网络>": ["autogroup:admin"] } **部署路由器后**，CLI 会打印推荐的 ACL 规则，包括真实子网。向用户显示此输出 - 它包含“acls”访问规则所需的子网（其范围永远不会自动配置）： {“action”：“接受”，“src”：[“group：YOUR_GROUP”]，“dst”：[“tag：ambit-<网络>：53”]} {“action”：“接受”，“src”：[“group：YOUR_GROUP”]，“dst”：[“fdaa：4a：d38b :: / 48：*”]} ### `npx @cardelli/ambit share <网络> <成员> [<成员>...]` 通过将每个成员的两条接受规则添加到 Tailscale 策略的“acls”部分，授予一个或多个成员对网络的访问权限： 1. **DNS 规则** : ` → :53` — 让成员解析 `*.` 名称 2. **子网规则** : ` → :*` — 让成员访问网络上的所有应用程序每个成员必须是以下之一：“group:”字符串、“tag:”字符串、“autogroup:”字符串或有效的电子邮件地址。在进行任何 API 调用之前，所有成员均经过 Zod 验证。 npx @cardelli/ambit 共享浏览器组：团队 npx @cardelli/ambit 共享浏览器组：team alice@example.com 组：contractors npx @cardelli/ambit 共享浏览器组：team --org my-org **标志：** * `--org ` — Fly.io 组织别名 * `--json` — 输出为 JSON **它的作用：** 1. 验证所有成员（在接触 API 之前失败并出现明显错误） 2. 发现网络的路由器（如果没有找到则死亡） 3.从路由器机器获取子网 4. 从路由器的 Tailscale 设备获取标签（回退到 `tag:ambit-`） 5.读取当前ACL策略 6. 幂等地为每个成员添加 DNS 和子网接受规则 7. 运行健全性检查（`assertAdditivePatch`）以验证没有现有数据被意外删除 8. 在写入之前根据 Tailscale API 验证更新后的策略 9. 在一次调用中推送更新的策略该命令是幂等的——当规则已经存在时重新运行它是安全的（没有重复）。需要具有 ACL 写入权限的 Tailscale API 令牌（“policy_file”范围）。失败并出现 403 明显错误。 ### `npx @cardelli/ambit 部署 .` 将应用程序部署到专用网络上。网络可以指定为名称的一部分 (`my-app.lab`) 或使用 `--network` (`my-app --network lab`)。这是“fly deploy”的安全替代方案：它始终传递“--no-public-ips”和“--flycast”，在 Fly.toml 上运行飞行前检查以查找危险设置，并审核结果以验证没有分配公共 IP。存在三种互斥的部署模式： **配置模式**（默认）- 使用本地 `fly.toml`： npx @cardelli/ambit 部署 my-app.lab npx @cardelli/ambit 部署 my-app.lab --config ./custom.toml **镜像模式** — 部署不带 Fly.toml 的 Docker 镜像： npx @cardelli/ambit 部署 my-app.lab --imageregistry.fly.io/my-app:latest npx @cardelli/ambit 部署 my-app.lab --imageregistry.fly.io/my-app:latest --main-port 3000 **模板模式** — 从 GitHub 存储库获取模板并部署它： npx @cardelli/ambit 部署 my-browser.lab --template ToxicPine/ambit-templates/chromatic npx @cardelli/ambit 部署 my-browser.lab --template ToxicPine/ambit-templates/chromatic@v1.0 npx @cardelli/ambit 部署 my-shell.lab --template ToxicPine/ambit-templates/wetty **标志：** * `--network ` — 目标网络（替代 `app.network` 简写） * `--org ` — Fly.io 组织 * `--region ` — 主要区域 * `--config ` — Fly.toml 的显式路径（配置模式） * `--image ` — 要部署的 Docker 镜像（镜像模式） * `--main-port ` — 图像模式下 HTTP 服务的内部端口（默认值：80，“无”可跳过） * `--template ` — GitHub 模板参考（模板模式） * `-y, --yes` — 跳过确认 * `--json` — 输出为 JSON **模板参考格式：** owner/repo 从默认分支获取仓库根目录 owner/repo/path 从默认分支中获取子目录 owner/repo/path@tag 获取带标签的版本 owner/repo/path@branch 获取特定分支 owner/repo/path@commit 获取特定提交该模板必须包含“fly.toml”（通常是 Dockerfile 或预构建的映像引用）。该模板是从 GitHub 的 tarball API 获取、提取、飞行前扫描和部署的。临时目录会自动清理。 ### `npx @cardelli/ambit 列表网络` 在表格中列出所有网络及其路由器，显示网络名称、应用程序名称、区域、计算机状态、Tailscale 连接状态和 ACL 标记。 npx @cardelli/ambit 列表网络 npx @cardelli/ambit 列表网络 --org my-org --json ### `npx @cardelli/ambit 列表应用 <网络>` 在显示应用程序名称、区域和计算机状态的表中列出特定网络上的所有工作负载应用程序。 npx @cardelli/ambit 列出应用实验室 npx @cardelli/ambit 列表应用实验室 --json ### `npx @cardelli/ambit status` 显示网络和应用程序状态。如果没有子命令，则默认显示所有网络（与“状态网络”相同）。 npx @cardelli/ambit status # 所有网络的摘要 npx @cardelli/ambit statusnetworks # 同上 npx @cardelli/ambit status network lab # 一个网络的详细视图 npx @cardelli/ambit status app my-app.lab # 一个应用程序的详细视图 npx @cardelli/ambit status app my-app.lab --json # JSON 输出网络详细信息包括：机器状态、SOCKS5 代理地址、Tailscale IP、子网和网络上的应用程序。应用程序详细信息包括：Fly.io 应用程序名称、机器、Flycast IP 和路由器状态。 ### `npx @cardelli/ambit 销毁网络 <名称>` / `npx @cardelli/ambit 销毁应用程序 <应用程序>.<网络>` 破坏网络（路由器）或工作负载应用程序。 **破坏网络** — 拆除路由器并清理所有相关资源。部署在网络上的应用程序不会被删除——只会删除路由器。 npx @cardelli/ambit 摧毁网络实验室 npx @cardelli/ambit 破坏网络实验室 --yes npx @cardelli/ambit destroy network lab --manual # 跳过 ACL 清理 **它的作用：** 1. 找到网络的路由器应用程序 2.清除分割DNS配置 3. 移除Tailscale装置 4. 销毁Fly.io应用程序 5.自动清理ACL：从Tailscale策略中的`tagOwners`和`autoApprovers`中删除标签（使用`--manual`跳过） `--manual` 跳过 ACL 清理步骤（步骤 5）。当 API 令牌缺乏 ACL 写入权限或用户自行管理策略时使用它。如果 ACL 清理失败并返回 403，ambit 会发出警告并建议使用“--manual”重新运行。销毁后，用户仍然需要手动删除引用该标签的任何“acls”规则（ambit 永远不会自动触及“acls”条目）。告诉他们可以这样做： * **可视化编辑器**：转到并从“访问规则”部分删除规则 * **ACL 文件** ：转到并从 `acls` 中删除引用 `tag:ambit-` 的条目 **销毁应用程序** — 从网络中删除工作负载应用程序。 npx @cardelli/ambit 销毁应用程序 my-app.lab npx @cardelli/ambit destroy app my-app --network lab npx @cardelli/ambit 销毁应用程序 my-app.lab --yes ### `npx @cardelli/ambit doctor` 对本地环境和路由器基础设施进行健康检查。每当出现问题时就运行它 - 它会检查最常见的故障点并提供修复提示。如果没有子命令，则默认检查所有路由器（与“doctor network”相同）。 npx @cardelli/ambit doctor # 检查所有路由器 npx @cardelli/ambit doctor network lab # 检查一个网络 npx @cardelli/ambit doctor app my-app.lab # 检查一个应用程序及其路由器 npx @cardelli/ambit doctor app my-app.lab --json # JSON 输出 **检查：** * 安装 Tailscale CLI * Tailscale已连接（BackendState =正在运行） * 启用接受路由 * 路由器存在并且机器正在运行 * 路由器在 tailnet 中可见 * 已批准的子网路由（自动批准未批准的路由） ## 模板准备部署模板可在“ToxicPine/ambit-templates”中找到：模板|描述 ---|--- `ToxicPine/ambit-templates/chromatic` | Headless Chrome 在端口 9222 上公开 Chrome DevTools 协议 - 适用于需要专用网络上的浏览器的 AI 代理或脚本。 `ToxicPine/ambit-templates/wetty` |具有 Web 终端、持久主目录、无密码 sudo 和自动启动/停止的云 devshell。 `ToxicPine/ambit-templates/opencode` |私有 OpenCode Web 工作区 — 基于 Nix 的环境，具有持久主页和自动启动/停止功能。 `ToxicPine/ambit-openclaw` |一个自托管的 OpenClaw 实例——您可以通过 WhatsApp、Telegram、Discord 和其他聊天应用程序与之交谈的个人 AI 助手。 npx @cardelli/ambit 部署 my-browser.lab --template ToxicPine/ambit-templates/chromatic npx @cardelli/ambit 部署 my-shell.lab --template ToxicPine/ambit-templates/wetty npx @cardelli/ambit 部署 my-code.lab --template ToxicPine/ambit-templates/opencode npx @cardelli/ambit 部署 my-gateway.lab --template ToxicPine/ambit-openclaw ## 常见工作流程 ### 首次设置 # 1. 创建路由器 — ambit 自动配置 ACL (tagOwners + autoApprovers) npx @cardelli/ambit 创建实验室 # 2. 重要提示：读取终端输出 — 它会打印推荐的 acls 规则 # 与真实的子网。将这些内容呈现给用户，以便他们可以限制 # 谁在他们的 tailnet 上可以到达这个网络（ambit 从来不写 acls 规则）。 # 如果您跳过此步骤，Ambit 将正常工作，但如果用户想要访问 - # 控制哪些设备可以访问哪些网络，推荐这样做。 # 3. 部署应用程序 npx @cardelli/ambit 部署 my-app.lab # 4. 现在可以从尾网上的任何设备通过 http://my-app.lab 访问应用程序 # 5. 与群组共享网络（自动添加 acls 规则）： npx @cardelli/ambit 共享实验室组：团队 # 6. 进一步微调访问： # - 邀请其他人：https://login.tailscale.com/admin/users # - 编辑访问规则：https://login.tailscale.com/admin/acls/visual/general-access-rules # 如果 API 令牌缺少 ACL 写入权限，请使用 --manual 并首先手动配置 ACL： # npx @cardelli/ambit 创建实验室 --manual ### 与团队共享网络 npx @cardelli/ambit share browsers group:team # 单组 npx @cardelli/ambit 共享浏览器组：team alice@example.com # 组 + 用户 npx @cardelli/ambit share browsers group:team group:contractors # 多个组 # 为每个成员添加两个 acls 规则：DNS (tag:53) + 子网 (*:*) # 在任何 API 调用之前验证所有成员（组：*、标签：*、自动组：* 或电子邮件） # 幂等 — 可以安全地重新运行 ### 从模板部署 npx @cardelli/ambit 部署 my-browser.lab --template ToxicPine/ambit-templates/chromatic # → 无头 Chrome 位于 my-browser.lab:9222，可通过 CDP 访问 ### 调试连接 npx @cardelli/ambit doctor network lab #检查所有常见故障点 npx @cardelli/ambit status network lab # 详细的网络/路由器状态 npx @cardelli/ambit status app my-app.lab # 检查特定应用程序 npx @cardelli/ambit list apps lab # 列出网络上的所有应用程序 ### 拆解 npx @cardelli/ambit destroy app my-app.lab # 删除应用程序 npx @cardelli/ambit destroy network lab # 删除整个网络 # ambit 自动从 ACL 中的 tagOwners 和 autoApprovers 中删除 tag:ambit-lab # 用户仍然需要手动删除引用该标签的所有 acls 规则： # 可视化编辑器：https://login.tailscale.com/admin/acls/visual（访问规则部分） # 或者 ACL 文件：从 acls 中删除引用 tag:ambit-lab 的条目 # 如果 API 令牌缺少 ACL 写入权限，请使用 --manual 跳过 ACL 清理： # npx @cardelli/ambit 销毁网络实验室 --manual ## ACL配置指南默认情况下，Ambit 自动管理 Tailscale 策略中的“tagOwners”和“autoApprovers”。它永远不会触及“acls”（访问规则）——这些规则是用户编写的，必须手动配置。 **自动管理的范围（默认）：** * `tagOwners`：在`create`/`destroy network`上添加/删除路由器标签 * `autoApprovers.routes`：在`create`/`destroy network`上添加/删除子网路由 **`ambit share` 配置什么：** * `acls`：添加组→标签：53和组→子网：*（DNS +数据访问）的接受规则 **用户必须手动配置的内容（不使用`ambit share`时）：** * `acls`：自定义规则限制哪些用户/设备可以访问网络（ambit 在`create`之后打印推荐的格式）当“ambit create”或“ambit destroy”因 ACL 权限错误而失败时，请告诉用户使用“--manual”重新运行，然后自行配置策略。他们有两个选择： 1. **可视化编辑器**（对于大多数用户来说更容易）：将他们引导至上的相关部分 - 标签、自动审批者或访问规则。 2. **ACL 文件**（对于喜欢代码的用户）：将他们定向到并提供终端输出中的准确 JSON。始终显示“ambit create”的终端输出，其中包含真实子网和推荐的“acls”规则 - 用户需要它来限制对网络的访问。 ## 故障排除症状|修复 ---|--- “ACL 写入权限被拒绝”/HTTP 403 | API 令牌缺少“policy_file”写入范围。对于“创建”/“销毁网络”，请使用“--manual”重新运行。对于“share”，请使用具有“policy_file”范围的令牌。 “标签未在 tagOwners 中配置”（使用 `--manual`）|在的可视化编辑器中添加 `tag:ambit-`，或将 `"tag:ambit-": ["autogroup:admin"]` 添加到 ACL 文件中的 tagOwners。路由器已部署但无法访问 |运行“npx @cardelli/ambit doctor”。检查本地是否启用了接受路由。 “等待设备超时” |检查路由器日志。最常见的原因：Tailscale API 密钥过期或无效。应用程序未解析为“.” |验证拆分 DNS 是否已配置：“npx @cardelli/ambit status network ”。检查尾网中的路由器是否在线。 “Flyctl 未找到” |从安装

范围Cli

包含技能