基于Flower的联邦学习

基于Flower的联邦学习实验报告（macOS + OrbStack）

01. 实验目标

阶段 内容 目标
阶段A Flower Quickstart 本地模拟 在单台Ubuntu虚拟机中运行FedAvg联邦学习模拟，观察训练轮次与准确率变化
阶段B 两台虚拟机跨机通信实验 使用Server和Client两台虚拟机，通过Docker Compose部署Flower服务端与客户端，完成跨机联邦学习通信

实验完成后应掌握：

  • 使用Conda管理Python环境
  • 安装并运行Flower框架
  • 完成Flower Quickstart-PyTorch本地模拟
  • 配置两台Ubuntu虚拟机之间的网络通信
  • 使用Docker Compose部署Flower服务组件
  • 监控训练日志，判断实验是否成功

02. 实验环境

宿主环境：macOS + OrbStack（轻量级Linux虚拟化工具）
虚拟机：通过OrbStack创建的两台Ubuntu 22.04虚拟机，分别命名为server和client
虚拟网络：OrbStack默认桥接网络，两台虚拟机可通过局域网IP互相访问

提示：OrbStack 替代了传统桌面虚拟化软件，启动快、资源占用低，并自动处理网络和SSH密钥。

03. 阶段A：本地模拟实验

3.1 创建并进入 Ubuntu 虚拟机

在macOS终端执行以下命令，创建一台Ubuntu虚拟机（若已存在可跳过创建）并进入其shell：

1
2
orb create ubuntu client        # 创建名为 client 的虚拟机
orb shell client                # 进入 client 虚拟机（后面阶段B会用到 server）

以下操作均在client虚拟机内部执行。

3.2 安装 Miniconda

1
2
3
4
5
6
7
8
9
10
11
12
# 使用清华源下载 Miniconda 安装脚本
wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-aarch64.sh -O ~/miniconda.sh

# 非交互式安装到 ~/miniconda3
rm -rf ~/miniconda3
bash ~/miniconda.sh -b -p "$HOME/miniconda3"

# 加载 Conda
source ~/miniconda3/etc/profile.d/conda.sh

# 验证安装
conda --version

3.3 创建实验环境并安装 Flower

1
2
3
4
5
6
7
8
9
10
11
# 创建名为 flwr 的 Python 3.11 环境
conda create -n flwr python=3.11 -y
conda activate flwr

# 安装 Flower（清华源加速）
# 注意：版本需与 Docker 镜像版本一致，此处使用 1.18.0
pip install flwr==1.18.0 -i https://pypi.tuna.tsinghua.edu.cn/simple

# 验证 Flower 版本
flwr --version
Flower version: 1.18.0

3.4 获取 Quickstart-PyTorch 示例

1
2
3
4
5
6
7
8
9
mkdir -p ~/fedml_exp
cd ~/fedml_exp

# 浅克隆 Flower 仓库
git clone --depth=1 https://github.com/adap/flower.git
cd flower/examples/quickstart-pytorch

# 安装项目依赖
pip install . -i https://pypi.tuna.tsinghua.edu.cn/simple
1
2
3
pip install --upgrade huggingface_hub httpx


3.5 运行本地联邦学习模拟

在 ~/fedml_exp/flower/examples/quickstart-pytorch 路径下执行：

1
flwr run . --stream

终端将输出多轮训练日志，包含损失值和分类准确率。若能观察到准确率逐步上升，则阶段A成功。

截图要求： 截取 flwr run . --stream 的训练日志，需清晰显示若干轮训练的输出。

Flower联邦学习-2026-0602-16:51:04-1

04. 阶段B：跨机通信实验

4.1 创建第二台虚拟机并配置主机名

在macOS新开一个终端窗口，创建server虚拟机：

1
orb create ubuntu server

分别进入server和client虚拟机，设置主机名（OrbStack默认主机名可能已是server/client，可检查后跳过）：

1
2
3
4
5
# 在 server 虚拟机内
sudo hostnamectl set-hostname server

# 在 client 虚拟机内
sudo hostnamectl set-hostname client

4.2 记录虚拟机信息

在每台虚拟机中查询IP地址（OrbStack下通常为192.168.215.x或10.x.x.x段）：

1
hostname -I

假设获得：

  • SERVER—IP = 192.168.139.150（示例，用实际值替换）
  • CLIENT-IP = 192.168.139.14
  • choco = root（OrbStack默认以root用户运行，可用whoami确认）

后续命令中的192.168.139.150、192.168.139.14、choco均需替换为实际值。

4.3 实验前检查

4.3.1 网络连通性

在client上测试与server的连通性：

1
ping 192.168.139.150          # 通后 Ctrl+C 停止

在server上测试与client的连通性：

1
ping 192.168.139.14

4.3.2 SSH 互信

39

在client上验证：

1
ssh choco@192.168.139.150

成功登录后，exit退回client。

4.3.3 Docker 环境检查

两台虚拟机均需安装Docker及Compose插件。OrbStack创建的Ubuntu通常预装Docker，检查版本：

1
2
docker --version
docker compose version

若未安装，执行：

1
curl -fsSL https://get.docker.com | sh

4.3.4 防火墙放行端口

在server上执行：

1
sudo ufw allow 9091:9093/tcp

4.4 在 Client 上准备 Flower 仓库

在client虚拟机中（确保已激活flwr环境）：

1
2
3
cd ~
git clone --depth=1 --branch v1.18.0 https://github.com/adap/flower.git
cd flower/framework/docker/distributed

后续阶段B的主要操作都以此目录为工作路径。

4.5 生成 TLS 证书

在client的~/flower/framework/docker/distributed目录下，执行证书生成（需替换192.168.139.150）：

1
sudo env SUPERLINK_IP=192.168.139.150 docker compose -f certs.yml -f ../complete/certs.yml run --rm --build gen-certs

完成后检查证书目录及证书中的IP：

1
2
ls superlink-certificates/
openssl x509 -in superlink-certificates/server.pem -noout -text | grep -A2 "Subject Alternative Name"

输出中应包含IP Address:192.168.139.150，否则后续TLS握手会失败。

Flower联邦学习-2026-0602-17:41:43-2

4.6 复制服务端配置到 Server

从client创建server上的部署目录并复制文件：

1
2
3
4
5
6
7
8
9
10
ssh choco@192.168.139.150 "mkdir -p ~/distributed/examples/quickstart-sklearn-tabular"

sudo chown -R $USER:$USER superlink-certificates

scp -r server \
    superlink-certificates \
    choco@192.168.139.150:~/distributed

scp ../../examples/quickstart-sklearn-tabular/pyproject.toml \
    choco@192.168.139.150:~/distributed/examples/quickstart-sklearn-tabular/

验证复制结果：

1
scp ~/flower/examples/quickstart-sklearn-tabular/pyproject.toml choco@192.168.139.150:~/distributed/examples/quickstart-sklearn-tabular/ && ls -l ~/distributed/superlink-certificates"

应看到server目录、证书文件（ca.crt, ca.key, server.pem等）和pyproject.toml。

4.7 在 Server 上启动 Flower 服务组件

通过SSH登录server并完成部署：

1
ssh choco@192.168.139.150
1
2
3
4
5
6
7
8
9
10
11
12
13
cd ~/distributed

# 创建 SuperLink 状态目录并授权
mkdir -p server/state
sudo chown -R 49999:49999 server/state

# 调整证书权限（Docker容器内用户UID为49999）
sudo chown -R 49999:49999 superlink-certificates
sudo chmod 600 superlink-certificates/server.key superlink-certificates/ca.key
sudo chmod 644 superlink-certificates/ca.crt superlink-certificates/server.pem superlink-certificates/server.csr superlink-certificates/ca.srl

# 启动服务端容器
sudo env PROJECT_DIR="$HOME/distributed/examples/quickstart-sklearn-tabular" docker compose -f server/compose.yml up --build -d

检查容器运行状态：

1
2
3
4
sudo docker ps
CONTAINER ID   IMAGE                   COMMAND                  CREATED         STATUS         PORTS                                                             NAMES
769f3cee632a   server-serverapp        "flwr-serverapp --in…"   3 seconds ago   Up 2 seconds                                                                     server-serverapp-1
d76a6c48b241   flwr/superlink:1.18.0   "flower-superlink --…"   3 seconds ago   Up 2 seconds   0.0.0.0:9092-9093->9092-9093/tcp, [::]:9092-9093->9092-9093/tcp   server-superlink-1

应看到server-superlink-1和server-serverapp-1等容器状态为Up。

4.8 在 Client 上启动 Flower 客户端组件

从server退出SSH（或另开终端），回到client虚拟机：

1
exit   # 如果还在server上
1
2
cd ~/flower/framework/docker/distributed
sudo env SUPERLINK_IP=192.168.139.150 PROJECT_DIR="$HOME/flower/examples/quickstart-sklearn-tabular" docker compose -f client/compose.yml up --build -d

验证：

1
sudo docker ps

应看到client-supernode-1-1、client-supernode-2-1等容器处于Up状态。

4.9 配置远程联邦学习任务

在client的~/flower目录下（即Flower仓库根目录），向pyproject.toml追加远程部署配置。注意：该追加命令仅执行一次，需将192.168.139.150替换为实际IP：

1
2
3
4
5
6
7
8
cd /home/choco/flower/examples/quickstart-sklearn-tabular/
cat >> pyproject.toml <<'EOF'

[tool.flwr.federations.remote-deployment]
default = true
address = "192.168.139.150:9093"
root-certificates = "/home/choco/flower/framework/docker/distributed/superlink-certificates/ca.crt"
EOF

检查配置是否写入（不应被#注释）：

1
tail -n 10 pyproject.toml

4.10 运行联邦学习任务并监控日志

回到distributed目录并启动训练：

1
flwr run /home/choco/flower/examples/quickstart-sklearn-tabular/ remote-deployment --run-config "num-server-rounds=3" --stream

正常输出应包含：

  • Connection successful
  • Starting Flower ServerApp
  • [ROUND 1]、[ROUND 2]、[ROUND 3] 及每轮分类准确率

4.10.1 常见故障排查

问题一：Method not found!

原因：Flower CLI 版本与 Docker 容器版本不一致。阶段A安装的 flwr 1.30.0 与 Docker 镜像 flwr/superlink:1.18.0 不兼容。

解决：

1
2
3
source ~/miniconda3/etc/profile.d/conda.sh
conda activate flwr
pip install flwr==1.18.0 -i https://pypi.tuna.tsinghua.edu.cn/simple

问题二：Failed to read certificate file

原因：pyproject.toml 中证书路径使用了相对路径，但 flwr run 执行时工作目录不同导致找不到证书文件。

解决：将证书路径改为绝对路径：

1
2
cd /home/choco/flower/examples/quickstart-sklearn-tabular/
sed -i 's|root-certificates = ".*"|root-certificates = "/home/choco/flower/framework/docker/distributed/superlink-certificates/ca.crt"|' pyproject.toml

若长时间停在[ROUND 1]无进展，可检查SuperNode日志：

1
sudo docker compose -f client/compose.yml logs --tail=150

若有Connection attempt failed, retrying，尝试重启客户端：

1
2
sudo docker compose -f client/compose.yml down
sudo env SUPERLINK_IP=192.168.139.150 PROJECT_DIR="$HOME/flower/examples/quickstart-sklearn-tabular" docker compose -f client/compose.yml up --build -d

然后重新运行flwr run命令。

4.10.2 运行结果

Flower联邦学习-2026-0602-19:03:44-3

4.11 清理实验资源

实验完成后，分别停止客户端和服务端容器。

在client上：

1
2
cd ~/flower/framework/docker/distributed
sudo docker compose -f client/compose.yml down

在server上：

1
ssh choco@192.168.139.150 "cd ~/distributed && sudo docker compose -f server/compose.yml down -v"

05. 实验提交要求

本实验提交 2 张截图：

截图 内容 关键点
截图1 阶段A flwr run . --stream 的训练日志 包含多轮训练，准确率上升趋势
截图2 阶段B 跨机联邦学习运行日志 显示3轮训练及最终分类准确率，[ROUND 1] 至 [ROUND 3] 完整输出