跳转到内容
[ PIER ]

联邦

联邦链接独立的 Pier 核心。一个主核心可以拉取其对等核心的项目和堆栈的只读视图，并且——在被授予令牌后——从一个面板对这些对等核心上的堆栈进行部署、重启和拆除。每个核心保留自己的数据库；联邦是一个控制覆盖层，而不是一个合并的安装。

联邦授权仅限 Owner；下面的读和写表面是管理员级别的操作。

读联邦（同步）

Section titled “读联邦（同步）”

一个后台调度器轮询每个已注册的对等核心，并刷新其项目和堆栈的本地缓存。同步大约每 45 秒运行一次（在短暂的启动延迟之后），从每个对等核心的常规读 API 获取项目和堆栈，并在一个事务中替换该对等核心的缓存行。轮询失败时会保留最后已知的数据，而不是清空缓存，因此面板可以显示某个对等核心的视图有多陈旧。

缓存的只读视图在主核心上暴露于：

  • GET /api/v1/federation/projects —— 本地加上缓存的对等核心项目，按来源打标签。
  • GET /api/v1/federation/stacks —— 对堆栈也是如此，包括每个对等核心是否已为写操作完成配对。
  • GET /api/v1/federation/status —— 每个对等核心的同步记账（上次同步、上次错误、连续失败次数）。
  • POST /api/v1/federation/sync —— 触发一次带外刷新，而不是等待定时器。

对等令牌授权

Section titled “对等令牌授权”

核心间的身份验证使用联邦令牌。在对等核心上，操作员生成一个令牌（POST /api/v1/federation-tokens 带一个标签）；明文仅显示一次，并且只以 SHA-256 哈希加上一段可见的短前缀的形式存储。操作员将其复制到主核心，主核心在写调用时通过 X-Pier-Federation 头发送它。

在对等核心上管理令牌：

  • GET / POST /api/v1/federation-tokens —— 列出并生成。
  • DELETE /api/v1/federation-tokens/{id} —— 吊销（一种保留该行以供审计的软吊销）。

一个联邦令牌只授权对等核心的联邦控制表面——创建和管理主核心部署的那些堆栈。它无法触及对等核心的用户、会话或管理员设置，也不授予对该对等核心自己已拥有的堆栈的控制权。

写联邦

Section titled “写联邦”

有令牌就位后，主核心通过透传路由控制对等核心的堆栈，这些路由通过 X-Pier-Federation 通道转发到对等核心：

操作路由（主核心）
创建堆栈POST /api/v1/federation/peer/{server_id}/stacks
部署POST /api/v1/federation/peer/{server_id}/stacks/{stack_id}/deploy
下线POST /api/v1/federation/peer/{server_id}/stacks/{stack_id}/down
重启POST /api/v1/federation/peer/{server_id}/stacks/{stack_id}/restart
日志GET /api/v1/federation/peer/{server_id}/stacks/{stack_id}/logs
释放POST /api/v1/federation/peer/{server_id}/stacks/{stack_id}/release

在对等核心上，这些请求落在一个专用的 /api/v1/agent 路由器上，由联邦令牌门控。以这种方式创建的每个堆栈都归签发令牌所有：对等核心强制执行所有权，因此一个主核心无法管理另一个主核心的联邦堆栈，而释放一个堆栈会将它交还给对等核心自己的面板，且不触碰其运行中的容器。

在对等核心之间迁移堆栈

Section titled “在对等核心之间迁移堆栈”

你可以用 POST /api/v1/stacks/{id}/migrate 将一个堆栈从本地核心移动到一个已配对的对等核心，传入目标服务器。迁移仅限于无状态的 Compose 堆栈——带有具名或匿名卷的堆栈会被拒绝，因为它的数据不会随之一起迁移。该流水线在目标上创建并部署堆栈，然后拆除源端并移除其本地记录。

DNS 切换不是自动化的。每台服务器运行自己的 Traefik，因此迁移之后你需要自己将堆栈的域名重新指向新服务器。响应会返回源域名，作为针对这一步骤的提示。

后续步骤

Section titled “后续步骤”