WireGuard 网格

单台 Pier 服务器是自包含的，但一旦你添加了远程服务器，通常会希望它们通过私有、加密的网络通信，而不是走公网。Pier 将这个网络构建为主机级 WireGuard 覆盖网络：每台服务器都获得一个稳定的私有 IP，服务器之间的流量在加密隧道中传输。

网格管理仅限 Owner。这里描述的每个端点都位于全局 Owner 角色门控之后。

覆盖网络如何构建

网格通过刻意设计、可审查的步骤组装而成，这样某个错误只会让向导停滞，而不会破坏正在运行的隧道：

步骤	端点	发生了什么
配置	`PUT /api/v1/network/mesh`	设置子网、监听端口和保活间隔。仅在网格被禁用时允许。
预检	`GET /api/v1/network/mesh/preflight`	在你提交之前，检查每台服务器是否有可达的 `pier-net-helper`。
启用	`POST /api/v1/network/mesh/enable`	为每台服务器分配一个私有 IP，并开启网格。
配置（应用）	`POST /api/v1/network/mesh/configure`	安装 WireGuard，为每个节点生成一对密钥，写入 `wg0.conf` 并将每条隧道拉起。
禁用	`POST /api/v1/network/mesh/disable`	将每个接口关闭并清除对等条目。

子网必须是 /30 或更大的前缀——/31 和 /32 没有留下可用主机，会被拒绝。本地核心始终被分配第一个主机地址，因此你可以在环境文件和运维手册中硬编码它。

configure 阶段是有序执行的，因此部分失败会提前停止并保留一个可恢复的状态。出错的对等节点会被标记上 helper 的消息；你通过先禁用再重新启用、然后重新运行 configure 来清除它。

pier-net-helper

Pier 从不在核心或代理进程中运行特权 WireGuard 命令。每台服务器都运行一个小型 root 守护进程 pier-net-helper，它监听一个 Unix 套接字——默认是 /run/pier/net.sock，可通过 PIER_NET_HELPER_SOCKET 环境变量覆盖。核心通过该套接字直接与本地 helper 通信；对于远程服务器，它通过代理的网格代理（mesh proxy）在固定的 HTTPS 通道上路由相同的操作。

私钥在节点上生成并留在那里。核心渲染每个 wg0.conf 时不包含 PrivateKey 行——helper 在写入文件时注入节点本地的密钥。

正是因为这种拆分，才存在网格预检检查：它向每台服务器扇出一个状态探测，如果任何节点缺少可达的 helper，就拒绝启动 Enable 向导，这样你可以提前运行改造安装程序，而不是在配置过程中才发现缺口。

核心到核心的对等网格

上述步骤将一个核心连接到它直接管理的服务器（本地节点及其代理）。要连接两个独立的核心，你需要将它们的网格配对：

POST /api/v1/network/mesh/pair/{id} —— 将本核心的网格与已注册的对等核心配对。
POST /api/v1/network/mesh/peer/{id}/unpair —— 在双方拆除配对。

配对是由发起方分配的：发起核心从自己的子网为远程核心的节点分配网格 IP，通过 peer-token 通道发送该计划，并将远程节点存储为外部对等节点，从而使自己的 wg0.conf 为它们新增 [Peer] 区块。在此版本中，两个核心必须已经将彼此注册为对等节点，并且目标核心的网格在配对前必须处于禁用状态。

服务 DNS

在覆盖网络之上，你可以注册逻辑服务名称，它们解析到当前承载某个服务的节点。像 db 这样的名称会变成 db.mesh，在部署时作为 extra_hosts 条目注入到每个堆栈中，这样消费方服务连接的是一个稳定的名称而不是 IP。

在以下位置管理这些映射（仅限 Owner）：

GET / POST /api/v1/network/service-dns
PUT / DELETE /api/v1/network/service-dns/{name}

名称遵循收紧后的 RFC 1123 标签规则——小写字母、数字和连字符，以字母数字开头和结尾，最多 31 个字符——并且不能与现有服务器名称冲突。添加或更改一个映射会排队一次后台重新部署，以便运行中的堆栈拾取新的 extra_hosts 条目。

后续步骤

服务器与代理 —— 添加加入网格的远程服务器。
数据库集群 —— 依赖覆盖网络的跨服务器集群。
网络 —— 每主机的 pier-net Docker 网络。