Flower 部署运行时实战指南：用 Deployment Runtime 组建 SuperLink 与双 SuperNode 联邦并运行 Flower App

Flower 部署运行时实战指南：用 Deployment Runtime 组建 SuperLink 与双 SuperNode 联邦并运行 Flower App

【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower

本文基于 Flower 官方 how-to 指南 how-to-run-flower-with-deployment-engine.rst，带你用最小配置完成一次完整的 Flower 部署流程：创建基于 PyTorch 的 Flower App，启动由一个 SuperLink（"服务端"）和两个 SuperNode（"客户端"）构成的联邦，并将该 App 提交到联邦上运行。读完本文，你将掌握flwr new、flower-superlink、flower-supernode、flwr config与flwr run的完整操作链路，并理解这些命令背后由 Flower 框架源码实现的 Runtime API / Fleet API 架构。

适用场景与前置条件

指南的目标是"用最小配置演示部署流程"，因此所有命令都假设在同一台机器的多个终端中执行，且这些终端共享同一个 Python 环境。开始之前请确认：

1. 已安装最新版本的flwrCLI（即flwr包，安装后可获得flwr、flower-superlink、flower-supernode等命令行可执行文件）。
2. 理解 Flower 部署的基本组件：SuperLink 负责联邦控制面（接收 Run、协调执行），SuperNode 运行ClientApp并执行联邦学习中的客户端训练。指南原文建议先阅读架构说明文档，理解各组件的职责与交互方式。

注意：真实部署中，SuperLink 与 SuperNodes 通常运行在与开发 Flower App 不同的机器/服务器上（开发端执行flwr new和flwr run）。本指南的命令在跨机器场景下依然适用，你只需把127.0.0.1替换为对应机器的 IP，并在各节点上准备好正确的依赖环境。一种更省事的跨机器部署方式是通过 Docker，仓库中的 framework/docker 目录提供了 SuperLink、SuperNode 等组件的 Docker 配置，可结合部署文档使用。

步骤 1：创建 Flower App

与其从零编写，推荐从官方 quickstart 模板起步，再按需求定制。创建一个新的 PyTorch Flower App：

$ flwr new @flwrlabs/quickstart-pytorch 🔗 Requesting download link for @flwrlabs/quickstart-pytorch... 🔽 Downloading ZIP into memory... 📦 Unpacking into /Users/alice/quickstart-pytorch... 🎊 Flower App creation successful. To run your Flower App, first install its dependencies: cd quickstart-pytorch && pip install -e . then, run the app: flwr run . 💡 Check the README in your app directory to learn how to customize it and how to run it using the Deployment Runtime.

命令执行后会按提示先cd quickstart-pytorch && pip install -e .安装依赖，再运行 App。

这里有一个关键概念需要区分（指南原文明确指出）：如果你直接执行flwr run .且未指定 SuperLink 连接，Flower 会命中 Flower Configuration 中默认的本地 profile（配置中address = ":local:"那一条）。此时 Flower 会把这次运行提交给一个受管理的本地 SuperLink，并以内置的Simulation Runtime（仿真运行时）执行——所有"客户端"都在一个进程内模拟。本指南的目标是走另一条路：让flwr run指向一个具名的 SuperLink 连接，使用真正的Deployment Runtime（部署运行时），即步骤 2 中手动启动的 SuperLink + SuperNodes。

生成的quickstart-pytorch项目结构与仓库中的示例 examples/quickstart-pytorch 一致：pytorchexample包内包含ServerApp、ClientApp、联邦策略（FedAvg 策略）与工具代码，examples/quickstart-pytorch/pyproject.toml 声明了依赖。建议用编辑器打开生成的代码熟悉一下再进入下一步；尤其注意ClientApp的代码，它会决定后面--node-config需要传什么参数。

步骤 2：启动 Flower 联邦（1 个 SuperLink + 2 个 SuperNode）

2.1 启动 SuperLink

在一个新终端中激活 Python 环境后，以不安全模式（不加密）启动 SuperLink：

$ flower-superlink --insecure

参数含义：

• flower-superlink：SuperLink 的 CLI 可执行文件名。它由包安装时注册的入口点提供，见 framework/pyproject.toml 的[project.scripts]段：flower-superlink = "flwr.superlink.cli:flower_superlink"、flower-supernode = "flwr.supernode.cli:flower_supernode"，还有flwr、flower-superexec、flwr-serverapp、flwr-clientapp等。
• --insecure：允许未加密通信。仅适用于本地测试，真实部署必须启用 TLS。

从源码层面看这条命令做了什么：flower_superlink.py 中的flower_superlink()解析命令行参数为SuperLinkLifespanConfig，随后由 FastAPI 应用对外提供服务——Runtime HTTP API 与 Control HTTP API 都挂在同一--host:--port（默认 8000 端口，即步骤 3 中config.toml的address = "127.0.0.1:8000"所指），而Fleet gRPC API（默认 9092 端口）由应用 lifespan 持有并启动。当传入--insecure时，_obtain_superlink_certificates()会打印安全警告并返回None，即跳过 TLS 证书、启动未加密 HTTP 服务；若不传该标志，则会尝试通过--ssl-certfile、--ssl-keyfile、--ssl-ca-certfile获取证书。源码中还能看到更严格的安全约束：--enable-supernode-auth（SuperNode 认证）要求必须启用 TLS 且 Fleet API 传输类型为gRPC-rere，否则直接报错退出——这从实现上印证了"生产环境必须加密"的说法。

2.2 启动两个 SuperNode

本步需要两个终端，分别启动并连接到上述 SuperLink。

终端 1：启动第一个 SuperNode

$ flower-supernode \ --insecure \ --superlink 127.0.0.1:9092 \ --host 127.0.0.1 \ --port 9094 \ --node-config "partition-id=0 num-partitions=2"

终端 2：启动第二个 SuperNode

$ flower-supernode \ --insecure \ --superlink 127.0.0.1:9092 \ --host 127.0.0.1 \ --port 9095 \ --node-config "partition-id=1 num-partitions=2"

逐项解释：

• flower-supernode：SuperNode 的 CLI 可执行文件名（入口点实现见 flower_supernode.py）。
• --insecure：以不安全模式运行，允许未加密通信；生产环境需配置 TLS 证书。
• --superlink 127.0.0.1:9092：连接 SuperLink 的Fleet API（gRPC，默认 9092 端口）。如果 SuperLink 在其他机器上，把127.0.0.1换成该机器的 IP 即可。
• --host 127.0.0.1：SuperNode 监听 Runtime API 请求的主机地址。
• --port 9094/--port 9095：SuperNode 的Runtime API端口，用于与运行在其上的ClientApp通信。指南强调：只有在同一台机器上跑两个 SuperNode 时才需要手动指定不同端口；通常一台机器跑一个节点，可以省略--port使用默认值（这也解释了为什么示例中两个节点分别用 9094 和 9095）。
• --node-config "partition-id=N num-partitions=2"：这是与ClientApp行为强相关的运行时键值对。flwr new生成的ClientApp代码预期在运行时收到partition-id和num-partitions这两个键，用它对数据集做分区加载；两个 SuperNode 传入不同的partition-id（0 和 1），从而让各自运行的ClientApp使用不同的数据分片——这正是联邦学习中"数据分布在不同客户端"的最小化模拟。指南同时提醒：实际的ClientApp往往不做数据集分区，而是直接访问本地已有数据（例如一个图片目录路径），此时你应自行编写ClientApp，并让--node-config传递你真正需要的参数。

步骤 3：在联邦上运行 Flower App

此时两个 SuperNode 已连接到同一个 SuperLink，系统处于空闲状态，等待接收一个Run。要让flwr run把 App 提交到刚才手动启动的 SuperLink 上执行，需要在Flower Configuration文件中定义一条新的 SuperLink 连接。

Flower Configuration 文件在你首次使用任何 Flower CLI 命令时自动创建。用flwr config list可以查看可用的 SuperLink 连接及配置文件路径。

1. 查看配置

$ flwr config list Flower Config file: /path/to/.flwr/config.toml SuperLink connections: supergrid local (default)

2. 编辑config.toml，在文件末尾追加一条 SuperLink 连接：

[superlink.local-deployment] address = "127.0.0.1:8000" insecure = true

注意两点（指南原文强调）：

• [superlink.]后面的连接名可自定义，但不能包含点号（.），示例使用local-deployment；
• 连接名要与flwr run命令中指定的保持一致——本例用local-deployment时，flwr run也要写local-deployment。

address = "127.0.0.1:8000"指向 SuperLink 的 HTTP API 端口（步骤 2.1 中flower-superlink默认监听的主端口），insecure = true对应启动时的--insecure；真实部署中此处应改为证书配置而非 insecure 标志。

3. 提交运行

在另一个激活了 Python 环境的终端中执行：

$ flwr run . local-deployment --stream

--stream会持续转发ServerApp的日志，你可以据此跟踪这次 Run 的执行过程（各 SuperNode 上的ClientApp接收模型、训练、回传，SuperLink 聚合的完整联邦轮次）。如果要重跑或对代码做了修改后测试新版本，重新执行同一条命令即可。

小贴士：可以在 Flower Configuration 中把local-deployment设为默认连接，这样所有需要连接 SuperLink 的 Flower CLI 命令都不必每次显式指定连接名。

步骤 4：清理

在每个终端中按Ctrl+C停止对应进程：两个 SuperNode、一个 SuperLink，以及正在--stream的flwr run终端。

小结与要点回顾

贯穿全文的三个工程要点：

1. Simulation Runtime 与 Deployment Runtime 的边界：flwr run .命中默认:local:profile 时走本地仿真；只有显式指定具名 SuperLink 连接才进入部署运行时。这是理解 Flower 部署模型的第一步。
2. --node-config是 App 与节点之间的契约：它的键值对不是 Flower 框架固定的参数，而是由你的ClientApp代码决定——换数据、换 App 就要换配置。
3. 安全配置贯穿所有组件：SuperLink 与 SuperNode 的--insecure、config.toml的insecure = true只应出现在本地测试；源码中的证书加载逻辑（--ssl-certfile/--ssl-keyfile/--ssl-ca-certfile）和 SuperNode 认证对 TLS 的硬性要求，指明了从演示走向生产的改造路径。

后续可以进一步深入的方向：为 SuperLink 与 SuperNode 启用 TLS 连接、用 Docker 完成跨机器部署（参考 framework/docker 目录下的组件配置），以及阅读 examples/quickstart-pytorch 中生成的ServerApp/ClientApp代码以理解一个最小 Flower App 的完整结构。

【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower