服务器与代理

一个 Pier 核心可以管理的不止它自己的主机。你将一台远程服务器添加为代理——一个轻量、无状态的守护进程（pier-agent），核心通过固定的 HTTPS 通道驱动它。核心始终是唯一的控制平面；代理只是运行 Docker 命令并上报指标。

添加、移除服务器以及向服务器部署，在面板中都是管理员级别的操作。

登记一个代理

当你创建一个代理类型的服务器时，核心会生成一个短期的引导令牌并交给你一条安装命令。该脚本（由 GET /api/v1/servers/install-script 提供）在新主机上运行，并：

1. 如果缺失则安装 Docker 和 Compose 插件，并创建 pier-net Docker 网络。
2. 使用引导令牌进行身份验证，从核心下载 pier-agent 二进制文件。
3. 安装 pier-net-helper（处于休眠状态——在核心发送网格操作之前它什么都不做）。
4. 为代理生成一个自签名 TLS 证书，并计算其 SHA-256 叶子指纹。
5. 执行握手，用一次性引导令牌换取长期代理令牌。
6. 通过首次心跳确认存活。

安装脚本通过 curl --cacert 固定核心自己的自签名证书，因此代理通过经过验证的 HTTPS 而不是 -k 进行回调。

引导令牌到持有者令牌的握手

引导令牌是一次性且短期的。代理在 POST /api/v1/servers/{id}/handshake 处花掉它，核心作为响应生成长期代理令牌。该长期令牌仅返回一次，并且在核心上只以 SHA-256 哈希形式存储；代理将明文保存在它的 systemd 环境文件中。

针对已兑换的引导令牌的第二次握手会被拒绝。如果安装命令泄露或被重新运行，请在面板中重新创建该服务器以签发新的引导令牌——Pier 不会悄悄地重新签发凭据。

此后，代理用 Authorization: Bearer <agent token> 对每个请求进行身份验证。你可以从面板轮换它（POST /api/v1/servers/{id}/rotate）：核心先将新令牌推送给代理，并且只有在代理确认后才持久化它，因此失败的轮换永远不会让核心失去同步。

证书指纹固定

核心到代理的通道是 HTTPS，但代理是通过原始 IP（或网格 IP）访问的，没有 PKI 链。核心不是验证证书颁发机构，而是固定代理的 TLS 叶子指纹——即安装脚本计算并在握手期间发送的那个 SHA-256。此后每次核心到代理的调用都会对照该固定值进行验证，因此通道可防范证书替换。当代理重新生成其证书后，一个重新确认的指纹可以在后续心跳中到达以重新固定。

指标与部署

一旦登记完成，代理会暴露：

• 指标 —— CPU、内存、磁盘、Docker 版本和容器数量，呈现在服务器卡片中（GET /api/v1/servers/{id}/metrics，代理转发到代理的 /metrics）。
• 部署 —— 在代理上部署或停止一个 Compose 堆栈（POST /api/v1/servers/{id}/deploy 和 /stop）。核心发送渲染后的 Compose YAML；代理将其写入自己的数据目录并运行 docker compose。

核心还会按定时器轮询已注册的对等节点，同时代理推送自己的心跳，因此面板能反映每台服务器的状态。

将代理提升为核心

代理可以被提升为一个完整的 pier-core。核心从它的数据库导出一个提升包并发送给代理（POST /api/v1/servers/{id}/promote）。代理写入该包，下载 pier-core 二进制文件，将该包导入一个全新的数据库，安装一个 systemd 单元，停止 pier-agent 并启动 pier。提升以分离方式运行，因此代理可以在新核心接管时停止自身。

后续步骤

• WireGuard 网格 —— 通过加密覆盖网络连接你的服务器。
• 联邦 —— 链接独立的核心并控制对等堆栈。
• 项目与服务 —— 你部署到服务器上的内容。