安装

Subnetra 以 单个静态二进制 形式交付。无需系统级安装，也没有共享库需要管理—— 按你的环境选择合适的交付方式即可。

快速安装（交互式）

在 Linux 或 macOS 上，最快的方式是安装脚本。它会自动识别系统与架构、解析 最新 发布、用发布附带的 SHA256SUMS.txt 校验下载产物，并安装 subnetra 与 subnetrad——在写入任何文件前会先让你确认：

curl -fsSL https://raw.githubusercontent.com/jamiesun/subnetra/main/install.sh | sh

脚本是交互式的，并且 只安装两个二进制——绝不改动你的网络、防火墙或服务 （Subnetra 始终把主机网络规划留给你）。若目标目录中已安装 Subnetra，脚本会显示当前 版本并在覆盖前征求确认。如需无人值守安装，用 --yes 接受默认值：

curl -fsSL https://raw.githubusercontent.com/jamiesun/subnetra/main/install.sh | sh -s -- --yes

要把 Subnetra 作为常驻服务运行，加上 --service：它会以禁用状态安装加固过的 systemd（Linux）或 launchd（macOS）单元——绝不启动、也绝不碰你的网络——然后打印 完成配置并启用的步骤。完整服务配置见 部署。

想手动安装，或脚本未覆盖的平台？使用下面的 发布二进制，或在 Releases 页面 浏览全部产物。

无论采用哪种方式，守护进程在运行时都需要两样东西：NET_ADMIN 能力（用于创建 TUN 网卡）以及对 /dev/net/tun 的访问权。

容器镜像

带标签的发布会向 GHCR 推送多架构镜像，Docker 会自动选择正确的架构：

docker pull ghcr.io/jamiesun/subnetra:latest

# 守护进程需要 NET_ADMIN + TUN 网卡，并把 config.json 挂载到其工作目录
# （/etc/subnetra）。
docker run -d --name subnetra \
    --cap-add=NET_ADMIN --device=/dev/net/tun \
    -v "$PWD/config.json":/etc/subnetra/config.json:ro \
    ghcr.io/jamiesun/subnetra:latest

镜像内置 Docker HEALTHCHECK（subnetra status），因此当守护进程开始提供控制套接字 后，docker ps / Compose / Kubernetes 会报告其为 healthy，停止响应时报告 unhealthy。

amd64、arm64 与 arm/v7 镜像基于 busybox:musl 构建（内含两个静态二进制、 config.example.json 以及一个用于容器内调试的微型 BusyBox shell）。arm/v5 镜像基于 scratch 构建（仍为静态 musl，无调试 shell），并拼入同一份 :latest / :version 清单。Compose 与 Kubernetes 细节见 容器。

发布二进制

可在 Releases 页面 浏览并 下载任意发布。每个发布（vX.Y.Z）都会附上 amd64、arm64、armv7、armv5、mipsel、 mips 的 静态二进制 tar 包。Linux 二进制基于 musl-libc 全静态链接——ldd 显示 not a dynamic executable。

MIPS / OpenWrt： mipsel 为小端（ramips/mt7621/mt7628，多数现代 OpenWrt 设备）， mips 为大端（ath79/Atheros）。如何选对架构以及 procd 服务，见 OpenWrt Spoke 指南。

产物名带版本号，因此先解析一次版本，再下载、校验、安装：

ARCH=amd64   # 取值：amd64 | arm64 | armv7 | armv5 | mipsel | mips
VER=$(curl -fsSLI -o /dev/null -w '%{url_effective}' \
        https://github.com/jamiesun/subnetra/releases/latest | sed 's#.*/tag/##')

curl -fsSLO "https://github.com/jamiesun/subnetra/releases/download/$VER/subnetra-$VER-linux-$ARCH.tar.gz"
curl -fsSLO "https://github.com/jamiesun/subnetra/releases/download/$VER/SHA256SUMS.txt"
sha256sum --ignore-missing -c SHA256SUMS.txt        # 安装前先校验

tar -xzf "subnetra-$VER-linux-$ARCH.tar.gz"
cd "subnetra-$VER-linux-$ARCH"
sudo install -m 0755 subnetrad subnetra /usr/local/bin/
subnetrad --version

releases/latest/download/<asset> 路径始终指向当前发布，但产物名内嵌版本号—— 因此仍需按上面解析 VER，或者直接用 安装脚本。

离线 / 隔离网络安装

无法访问容器仓库的设备，可使用每个发布附带的、按架构区分的可 docker load 镜像 tar 包（subnetra-image-<version>-<arch>.tar.gz）：

docker load < subnetra-image-<version>-arm64.tar.gz   # -> ghcr.io/jamiesun/subnetra:<version>
docker run -d --name subnetra \
    --cap-add=NET_ADMIN --device=/dev/net/tun \
    -v "$PWD/config.json":/etc/subnetra/config.json:ro \
    ghcr.io/jamiesun/subnetra:<version>

macOS Spoke 二进制

每个发布还附带原生 macOS 二进制，用于以 Spoke 身份运行 Subnetra—— subnetra-<version>-macos-arm64.tar.gz（Apple Silicon）与 -amd64.tar.gz（Intel）。 它们是 Mach-O 二进制，仅链接 libSystem（零第三方依赖）。

安装脚本 同样适用于 macOS，并会自动为你清除 Gatekeeper 隔离属性。

tar -xzf subnetra-<version>-macos-arm64.tar.gz
cd subnetra-<version>-macos-arm64
# Gatekeeper 会隔离下载的二进制——清除隔离属性（或从源码构建）：
xattr -d com.apple.quarantine subnetrad subnetra 2>/dev/null || true

./subnetra --print-network-plan --config config.json   # 预览主机网络规划
sudo ./subnetrad --config config.json                  # 创建 utun 需要 root

创建 utun 网卡以及应用 ifconfig / route 规划都需要 root。macOS 仅作为 Spoke 支持（Hub 仍保持 Linux/RouterOS）；见 macOS Spoke 指南。

从源码构建

需要 Zig 0.16.0 及以上。

# 本机构建（默认 ReleaseSmall；本地开发可加 -Doptimize=Debug）
zig build

# 静态交叉编译
zig build -Dtarget=x86_64-linux-musl     # amd64
zig build -Dtarget=aarch64-linux-musl    # arm64
zig build -Dtarget=arm-linux-musleabihf  # armv7（硬浮点）
zig build -Dtarget=arm-linux-musleabi    # armv5（软浮点）
zig build -Dtarget=mipsel-linux-musl     # mipsel（小端：ramips/mt7621 — OpenWrt）
zig build -Dtarget=mips-linux-musl       # mips（大端：ath79/Atheros — OpenWrt）

# 运行测试
zig build test

# 运行守护进程
zig build run

产物位于 zig-out/bin/：subnetrad（守护进程）与 subnetra（控制工具）。

调整对端数量上限

对端注册表与解析后的配置都是固定容量、零分配的数组，因此单个节点能容纳的最大网格对端 数量是一个编译期构建选项（-Dmax-peers），而非运行时配置字段。默认 32，上限 128：

zig build -Dmax-peers=64                       # 把本节点对端上限提升到 64
zig build -Dmax-peers=128 -Dtarget=aarch64-linux-musl   # 与交叉编译目标组合

一个 hub 最多管理这么多 spoke。这是逐节点的容量旋钮——它不在链路上协商，因此一个 只连接单个 hub 的 spoke 无需跟随 hub 的更大上限。控制面策略表大小 （MAX_POLICY_ENTRIES）由该值自动推导，因此提升上限会自动增大策略容量（默认 32 对应 272 条策略表）。

把它调得过高是在用内存与延迟换容量：reactor 是单线程、每包对对端做 O(N) 扫描（开启 obfuscate 时每个入站数据报还要逐对端试解掩），因此超大网格更应当拆分为多个 hub， 而不是让单个 hub 挂上数百个 spoke。

ARMv5 注意： ARMv5 没有硬件原子指令，因此标准库的线程化 I/O 脚手架会引用 musl 未提供的 legacy __sync_* 内建函数。由于 Subnetra 严格单线程， src/atomic_shim.zig 提供了一份可证明正确的普通（非原子）实现，在 comptime 处门控， 仅 为 ARMv6 以前的目标编译进来——其他所有架构逐字节不受影响。

验证安装

# Linux：确认二进制全静态
ldd ./subnetrad          # -> "not a dynamic executable"
ls -lh ./subnetrad       # -> < 512 KB

# 任意平台：打印版本横幅
./subnetrad --version

下一步：前往 快速上手 拉起一个 Hub 和一个 Spoke。