`serve` 会打印一个 URL。在任何浏览器中打开它，你就能获得一个终端、一个文件浏览器，以及通往该机器网络的代理——或者从另一个终端用 `bitbang connect <url>` 连接同一台机器，这会添加端口转发（`-L`）和文件复制（`bitbang cp`）。连接是端到端加密且点对点的；`bitba.ng` 服务器负责介绍两端，然后退出。

`bitbang` 是一个单一的静态 Go 二进制文件。它是 [BitBang 项目](https://github.com/richlegrand/bitbang) 的一部分；这份 [白皮书](https://github.com/richlegrand/bitbang/blob/main/whitepaper.md) 深入介绍了其设计。

## 对比

|                                | ngrok                  | Tailscale                      | `bitbang`           |
| ------------------------------ | ---------------------- | ------------------------------ | ------------------- |
| 首次使用前的设置         | 账户 + authtoken    | 账户 + 每台设备登录 | **运行一条命令** |
| 要分享某物，你运行    | 一个 Web 服务器，外加 ngrok | 他们的客户端在两台机器上 | **`bitbang serve`** |
| 远端浏览器获得的内容 | 你已经在运行的 Web 服务器 | 什么都没有——它需要他们的客户端 | **一个终端、一个文件浏览器，以及远程网络上的 Web 应用** |
| 数据路径                      | 他们的服务器          | P2P（中继回退）           | **P2P（中继回退）** |
| 端到端加密           | 默认不启用         | 是                            | **是**             |

## 快速食谱

**访问家中的服务**

- [从任何地方挂载你的家庭 NAS（SMB）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#mount-your-home-nas-from-anywhere-smb)
- [从任何地方观看你的媒体库（Jellyfin）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-your-media-library-from-anywhere-jellyfin)
- [从任何地方使用你自己的 LLM（Ollama、Open WebUI）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#use-your-own-llm-from-anywhere-ollama-open-webui)
- [查看你的安防摄像头（Frigate）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-security-cameras-frigate)
- [在不暴露的情况下访问你的家庭自动化（Home Assistant）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-your-home-automation-without-exposing-it-home-assistant)
- [打印到你的家用打印机（IPP、CUPS）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#print-to-your-home-printer-ipp-cups)

**进入一台机器**

- [在 NAT 后面的机器上获取 shell](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-on-a-machine-behind-nat)
- [从手机获取 shell](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#get-a-shell-from-your-phone)
- [远程桌面进入 Windows 机器（RDP）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#remote-desktop-into-a-windows-machine-rdp)
- [访问 Linux 或 Mac 桌面（VNC）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-linux-or-mac-desktop-vnc)
- [SSH 到没有开放端口的机器（OpenSSH）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#ssh-to-a-machine-with-no-open-port-openssh)
- [设置无头 Raspberry Pi](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#set-up-a-headless-raspberry-pi)

**与他人分享**

分享只需给某人一个唯一的 URL 或二维码，让他们获得访问权限。权限可以定制，并可设置为在几分钟、几小时等时间内过期。

- [分享文件而无需上传到任何地方](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#share-files-without-uploading-them-anywhere)
- [向某人展示你的项目](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#show-someone-your-project)
- [给某人一个会过期的访问权限](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#give-someone-access-that-expires)
- [从手机查看你的代理会话（Claude Code、tmux）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#check-your-agent-session-from-your-phone-claude-code-tmux)
- [修复别人的路由器](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#fix-someone-elses-router)

**开发与设备**

- [从你的开发机器访问数据库（Postgres、MySQL）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#reach-a-database-from-your-dev-machine-postgres-mysql)
- [同步无法互相发现的设备（Syncthing）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#sync-devices-that-cannot-find-each-other-syncthing)
- [从浏览器观看机器人（ROS、Foxglove）](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#watch-a-robot-from-a-browser-ros-foxglove)

**技巧**

- [转发监听器暴露了什么](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#what-a-forwarding-listener-exposes)
- [让你局域网上的其他机器使用转发](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#let-other-machines-on-your-lan-use-a-forward)
- [已知无法工作的情况](https://github.com/richlegrand/bitbang/blob/main/cookbook.md#known-not-to-work)

## 使用 `bitbang`

每个连接都有两端：一个**监听器**（`bitbang serve`，运行在被访问的机器上）和一个**连接器**（浏览器，或 `bitbang` CLI，运行在发起访问的机器上）。一个监听器 URL 可同时服务两种连接器。

### 监听器：`bitbang serve````
bitbang serve                    # everything: shell + proxy + files + forward
bitbang serve shell              # just a terminal
bitbang serve files ~/share      # just a directory (-files-upload to allow uploads)
bitbang serve proxy localhost:8080       # just one web app, straight at the URL
bitbang serve proxy a.lan:80,b.lan:80    # ...or several, chosen in the browser
bitbang serve forward 127.0.0.1:22       # just TCP, for `connect -L`

bitbang serve shell files ~/share proxy nas.lan:8096   # any combination

该命令在发布后立即返回，因此对于已在进行的任务，可以使用 `Ctrl-Z`、`bitbang share`、`fg` 来恢复。托管需要在 Unix 或 WSL 上使用 tmux 3.2+。原生 Windows 客户端可以打开 URL，但无法托管共享。

默认情况下，该命令会打印两个 bearer URL：

- **控制 URL** 可以输入，权限与本地键盘相同。一次只能连接一个控制器。
- **查看 URL** 仅限观看。输入在到达 tmux 之前即被丢弃，最多可有 `--max-viewers` 个查看者同时连接（默认 16）。

`--read-only` 完全省略控制凭据。查看者和控制者的限制在每次连接的整个生命周期内都有效，即使在其打开 shell 之前也是如此。

共享默认持续运行直到停止；`--ttl` 设置生命周期（例如 `--ttl 1h`）。共享 URL 是临时的，绝不会保存到 `devices.json` 中。`share stop`、TTL 到期或移除源会话会断开远程对等连接，但不会停止源会话。

重新运行 `bitbang share` 会重新打印正在运行的共享的 URL。如果你传入的标记与正在运行的共享不一致（例如对具有控制 URL 的共享使用 `--read-only`），它会明确说明，而不是返回旧 URL；`bitbang share rotate` 会用使用新标记的共享替换当前共享。

后台工作进程在分离的 `_bbshare_*` tmux 管理会话中运行，因此无需管理守护进程或 PID 文件。

共享不会更改任何 tmux 选项。使用 tmux 默认的 `window-size latest` 时，窗口会跟随活动的读写客户端；单独的查看者仍会提供唯一可用的尺寸。如果 `window-size` 已被覆盖，`share` 会报告该情况，但不会更改用户的配置。

### 分发受限访问：`bitbang link`

一个监听器、一个 URL，以及你需要的任意数量的**访问链接**。每个链接都是该同一 URL 上的一个独立代码，授予监听器所提供功能的子集，并可选地在固定时间失效：```
bitbang link edit                # add entries in $EDITOR
bitbang link ls                  # what you have handed out
bitbang link rm <label>          # revoke one
bitbang link qr <label>          # its URL and QR code

(empty)```
  0) owner  files forward proxy shell
     https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#_vtQ0JCPe7s
  1) ana    files  expires in 6d
     https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#T-Ty_HhvLfY
  2) ben    files /srv/photos
     https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#L6La8OzBO74
  3) dev    forward 127.0.0.1:5432 shell
     https://bitba.ng/8ach_I7oQk2vBb9xYzT0Lw#8kmI3LYzB7E

监听器在注册时将配置交给信令服务器，服务器再将其提供给任何连接方——因此两端都使用你的中继，我们的服务器从不参与其中。任何 coturn，或像 Cloudflare 或 Twilio 这样的托管提供商，都可以使用。

该文件是 JSON 格式，采用你的提供商交给你的以下三种形式之一：```json
[{"urls": ["turn:turn.example.net:3478"], "username": "user", "credential": "pass"}]

I need the input content to translate. Please provide the chunk of Markdown content you'd like me to translate from English to Chinese.```json
{"iceServers": [{"urls": ["turn:turn.example.net:3478"], "username": "u", "credential": "p"}]}

`-L` 仅转发 **TCP**，与 `ssh -L` 类似。`-L` 默认绑定 `127.0.0.1`，除非你传入
`-g`，这会使转发的端口可从你的本地网络访问——而
任何访问该端口的人都能获得隧道所到达的任何内容，且其前方没有任何 BitBang
凭据。

监听端需要 `bitbang serve forward` 或 `bitbang serve`。默认情况下，
`forward` 链接可到达**监听端能到达的任何主机:端口**，而不仅仅是你所想的那个，
因此为数据库分发的链接也能到达该网络的其余部分。通过指定其可访问的内容来缩小范围：```
bitbang serve forward db.internal:5432        # this link reaches one service

Linux 和 macOS。检测你的操作系统和架构（Linux 上为 `amd64`、`arm64` 和 `armv7`），从最新的 [GitHub release](https://github.com/richlegrand/bitbang-cli/releases) 下载二进制文件，对照该 release 的 `checksums.txt` 验证其 SHA-256，然后安装到 `~/.local/bin/bitbang`。

Windows 构建版本以 `bitbang-windows-amd64.exe` 和
`bitbang-windows-arm64.exe` 的形式发布。从 Releases 下载相应的二进制文件，
将其重命名为 `bitbang.exe`，并放置在你的 `PATH` 中。
**从源码构建：** 参见 [下文](#building-from-source)。

**macOS 和 Gatekeeper。** 上述一键安装不受影响：`curl` 不会
设置 `com.apple.quarantine` 属性，因此它获取的二进制文件可以正常运行。
如果你改为在浏览器中从 Releases 页面下载 `bitbang-darwin-arm64`，macOS 会将其隔离并拒绝打开，因为该 release 的二进制文件未经公证。可通过以下任一方式清除隔离属性：```
xattr -d com.apple.quarantine ./bitbang-darwin-arm64

发布标签没有 `v` 前缀（`0.5.0`，而不是 `v0.5.0`）。

### 安装 URL 的工作原理

`bitba.ng/install` 是一个重定向，而不是托管的脚本。其链路如下：

1. `curl` 访问 `https://bitba.ng/install`，该地址 302 重定向到本仓库（`main` 分支）中的 [`install.sh`](https://github.com/richlegrand/bitbang-cli/blob/HEAD/install.sh)。
2. 脚本在你的 shell 中运行，检测操作系统和架构，并从 `https://github.com/richlegrand/bitbang-cli/releases/latest/download/bitbang-linux-<arch>` 下载二进制资源。
3. 它从同一发布版本获取 `checksums.txt`，并验证二进制的 SHA-256。
4. 安装到 `~/.local/bin`（可覆盖）。

安装脚本位于本仓库中，与它所安装的代码放在一起——因此你可以将它与二进制文件一起审查，而规范的 bitba.ng 主机只拥有短 URL。自托管者可以将自己主机的 `/install` 指向他们发布的任何脚本：信令服务器的 `INSTALL_URL` 环境变量控制重定向目标（为空 → 404）。

## 命令参考

每个子命令和标志都记录在 **[CLI.md](https://github.com/richlegrand/bitbang-cli/blob/HEAD/CLI.md)** 中，`bitbang <command> --help` 会在终端中打印相同的内容。

## 从源码构建

需要 Go 1.25+。纯 Go，静态链接（`CGO_ENABLED=0`）——跨编译非常简单，无运行时依赖。```
go build ./cmd/bitbang/

# cross-compile:
GOOS=linux   GOARCH=arm64        go build -o bitbang-arm64 ./cmd/bitbang/
GOOS=linux   GOARCH=arm GOARM=7  go build -o bitbang-armv7 ./cmd/bitbang/
GOOS=windows GOARCH=amd64        go build -o bitbang.exe   ./cmd/bitbang/
GOOS=darwin  GOARCH=arm64        go build -o bitbang-macos ./cmd/bitbang/

Shell 命令、文件共享、代理和 CLI 客户端均支持在 Windows 上运行。交互式浏览器和 CLI shell 使用 Windows ConPTY，包括终端输入回显、行编辑、VT 输出和调整大小事件。ConPTY 需要 Windows 10 版本 1809 或 Windows Server 2019 或更高版本。

## 图表

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/47068/d68fcddad62ab84f11a549906a2b5abf2330fb25f39b3c1a1266eac7257a080d.png" alt="bitbang CLI shell 和文件共享" width="760">
  <img src="https://assets.kitploit.com/production/public/readmes/47068/55bb6866c22504a6434e3dee8cb998e747cd73cb9d0bfa5e0bc0ede7b90ce262.png" alt="bitbang CLI 代理操作" width="720">  
</p>

## 路线图

现已推出：**shell、文件和代理**，可从浏览器或 CLI 访问，此外还有 **TCP 端口转发**、scp 风格的文件复制、带已保存设备表的**临时配对**、**终端共享**（`bitbang share`）以及**访问链接**（`bitbang link`），后者可收窄并限定 URL 授予的权限范围。已设计并即将推出：

- **串口桥接** -- 从本地虚拟端口驱动远程 `/dev/ttyUSB0`（例如通过互联网运行 Arduino IDE）。相关问题已在此处提交：[这里](https://github.com/richlegrand/bitbang-cli/issues/3)。
- **远程桌面** -- 通过 WebRTC 视频轨道传输屏幕，通过数据通道传输键盘/鼠标。

## 许可证

MIT -- 参见 [LICENSE](https://github.com/richlegrand/bitbang-cli/blob/HEAD/LICENSE)。

## 贡献

欢迎提交 Issue 和 PR。

配方则有所不同：它们位于 [cookbook](https://github.com/richlegrand/bitbang/blob/main/cookbook.md) 中，存放在 [bitbang](https://github.com/richlegrand/bitbang) 仓库里，因为它们横跨所有项目而非仅限本项目。添加配方需在该仓库提交 PR。

要让配方被*收录*，还需要为每个 README 应展示该配方的项目提交一个小的 PR -- 上面的 [配方](#recipes) 列表在此处手动维护。这是有意为之：每个项目自行决定哪些配方值得展示给自己的读者，而不是让每个 README 都收录所有配方。