1. 先回答问题为什么在 Ubuntu 20.04 上要选择 Docker 部署 FATE1.1 FATE 联邦学习框架到底解决什么问题FATE 联邦学习框架的核心场景是让多个参与方在不直接暴露原始数据的前提下共同完成模型训练和评估。传统机器学习通常会先把各方数据汇总到中心节点再统一建模这在数据合规要求越来越严格的环境里会面临很大阻力。联邦学习换了一个思路数据留在本地各方只交换模型参数、梯度或者经过加密计算的中间结果通过协作得到全局模型。我第一次接触 FATE 的时候最大的感受是它不是一个单体软件而是一整套分布式系统。整套环境包含任务调度节点、计算节点、存储节点、可视化平台和算法组件。部署 FATE 的过程本质上是在一台或几台机器上把这些组件全部拉起来并让它们正确互联。这也是为什么很多人用源码方式安装时会卡住组件太多、依赖太杂任何一个版本错位都会导致环境起不来。1.2 源码安装的痛点和 Docker 方案的优势FATE 的源码部署依赖 Python、Java、MySQL、Redis、Nginx 等一大堆环境。不同组件对 Python 包版本、JVM 版本、系统库版本都有各自要求。就算费劲装好一次隔几个月想升级小版本又可能踩到新的依赖冲突。Docker 方案把这些问题整体封装掉了。镜像里的操作系统、运行时、依赖库和 FATE 组件是配套打包的部署时只需要拉镜像、启动容器不用手工解决编译链接和环境变量问题。对新手来说出错后最有效的恢复手段就是“删掉容器重新来”这比在物理环境里一层层回滚爽快得多。对老手来说Docker 也方便做多版本并存和资源隔离尤其是想要在开发机模拟多个独立 FATE 实例时容器几乎是最优解。1.3 单机模拟和多机联邦先想清楚你要哪种部署 FATE 之前要明确目标。如果你只是学习联邦学习原理、写算法 Demo、调试数据处理流程单机 Docker 部署完全够用。单机模式会把多个“参与方”跑在同一台机器的不同容器里网络互通、任务调度都在本地完成体验上非常接近真实集群。但如果你要对接真实业务让不同机构的机器真正参与联邦训练那就要走多机部署模式。多机部署涉及角色划分、IP 互通、证书配置、端口开放、时间同步等一系列问题复杂度比单机高一截。我的建议是先在单机环境把 toy 示例和一个小型真实任务跑通再考虑多机扩展。顺序反了你会同时面对“环境问题”和“算法问题”排查时很难定位边界。2. Ubuntu 20.04 环境准备把地基打扎实再动手2.1 系统、CPU、内存和磁盘的硬性检查Ubuntu 20.04 是长期支持版本对 Docker 的兼容性比较成熟作为 FATE 部署环境是稳妥的选择。部署前先确认系统版本、CPU 架构、内存和磁盘空间。虽然官方文档只给了最低参数但我建议内存不要低于 8 GB磁盘剩余空间不要低于 20 GB架构优先选 x86_64。cat /etc/os-release uname -a nproc free -h df -h这四条命令看起来基础却能避免很多后期问题。我遇到过一台 4 GB 内存的测试机镜像都拉完了容器全部启动结果 MySQL 反复重启。翻日志才发现是内存分配不足进程被系统杀掉。后来把机器内存扩到 8 GB同样的部署脚本一次通过。磁盘也是一样FATE 相关镜像加起来好几个 GB容器运行时日志、数据库数据还会继续增长系统盘太满会让 Docker 服务本身出现异常。2.2 Docker 引擎安装与 docker compose 组件处理Docker 安装方式不少我习惯从 Docker 官方源安装这样能拿到较新的引擎和 compose 插件。如果你所在网络访问官方源不稳定可以先配置操作系统的软件源镜像再执行安装。sudo apt update sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo deb [archamd64 signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后可以通过sudo docker run hello-world验证引擎是否正常。注意FATE 部署脚本依赖容器编排能力需要确保 compose 命令可用。检查方式是执行docker compose version确认输出正常。如果你同时用独立二进制方式装过旧版 docker-compose系统里可能同时存在两种调用方式这会带来隐患部署脚本里如果写的是docker-compose而你只保留了docker compose插件脚本会在编排阶段报 command not found。建议统一成一种删除多余版本。2.3 配置镜像加速和日志大小限制拉取 FATE 镜像时如果直接连公共镜像仓库网络环境差一些的时候容易超时。可以给 Docker daemon 配置 mirror 加速地址。不同加速服务的效果差异较大选择你网络环境里实际可达且信任的地址就好。sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json EOF { registry-mirrors: [https://your-mirror.example.com], log-driver: json-file, log-opts: {max-size: 50m, max-file: 3} } EOF sudo systemctl restart docker同时限制 Docker 日志文件大小这个是实操里很容易忽略的点。FATE 容器在训练任务调试阶段会打印大量日志尤其是 Notebook 和计算节点一旦日志无限增长/var/lib/docker 会快速膨胀。我见过最夸张的情况是整个系统盘被容器日志占满SSH 都登录不进去。加完日志限制后建议定期用docker system df检查磁盘占用。2.4 端口清单、防火墙和后期的多机扩张FATE 单机部署会启动多个容器占用的端口包括 Web 页面、API 服务、数据库、缓存、任务调度、节点通信等用途。常见的有 8080、8081、3306、6379、9360、9370、9380、8888、8000 等。如果你只是本机演示端口冲突相对好处理直接停掉占用端口的服务即可。如果机器开启了防火墙记得确认这些端口没有被拦截。多机联调之前端口规划会直接影响后续联调成本。我建议在部署文档里记一张端口清单注明每个端口对应什么服务、是否需要对外开放、允许的访问来源是什么。很多多机联调问题都出在“容器起来了但跨机访问不了”十有八九是安全组规则漏放行了某个通信端口。与其到时候逐台机器排查不如第一次部署就同步把端口规划做好。3. Docker 安装 FATE 完整实操从脚本命令到容器起跑3.1 认识部署工具包里有什么FATE 官方部署工具的结构在不同版本里会微调但核心思路一致通过一个初始化脚本解析配置生成 docker-compose.yml然后拉取镜像、启动容器。拿到部署包后先别急着跑命令花十分钟把 README、配置文件和目录结构看一遍。部署包里常见的内容包括一键部署脚本、compose 模板、环境变量配置、示例证书等。执行脚本之前建议先看脚本里有没有依赖 curl、unzip、tar 这类基础命令。有些精简系统默认没装 unzip解压部署包就会失败但报错提示并不明显。mkdir -p ~/fate cd ~/fate unzip fate_docker_deploy.zip -d . cd fate_docker_deploy3.2 一键部署命令到底在执行什么把部署包放到固定目录后执行类似这样的命令bash build_standalone_docker.sh --version 1.x.x脚本会自动完成环境检查、生成 compose 文件、拉取镜像、启动容器并做健康检查。这里的版本号需要替换成你当前部署包的版本通常 README 里会写清楚。指定版本号的目的是让脚本去拉取对应 tag 的镜像避免脚本和镜像版本不匹配。执行过程中会看到大量日志核心阶段包括检查端口、生成部署文件、拉取镜像、创建 Docker 网络、启动 MySQL 和 Redis、启动 FATE 各组件、等待健康检查通过。每个阶段都有明显的日志输出比如pull complete、Creating network、Starting container。卡在哪一步就大概率是那一步的环境问题不要盲目重跑整个脚本。3.3 启动后用 docker ps 验证组件状态脚本执行完成后第一时间确认所有容器是否稳定运行。用下面的命令列出容器状态和端口映射docker ps --format table {{.Names}}\t{{.Ports}}\t{{.Status}}正常情况下你会看到 MySQL、Redis、FATE 的调度服务、计算服务、Board 服务、Notebook 等容器都处于 Up 状态。如果某个容器反复 Restarting就要立刻去看日志。docker logs container_name --tail 200我个人的经验是容器能被创建出来已经说明镜像拉取成功剩下问题多数集中在资源不足、端口冲突、配置依赖这三个方向。查看日志时要看容器第一次启动时的完整输出而不是只看最后几行。有些错误发生在启动早期日志滚动后反而被刷掉了。3.4 访问 FATE Board 和 Notebook检查部署结果部署完成后通过浏览器访问 FATE Board这是可视化的任务管理界面。默认端口通常是 8080但不同版本可能有调整以生成后的 compose 文件里实际映射端口为准。Notebook 入口一般映射在 8888 或 8000用于写代码和执行联邦学习 pipeline。远程服务器上访问时记得把 localhost 换成服务器 IP并且确认防火墙和安全组已经放行。如果页面打开后显示空白或连接失败先执行docker ps再看端口映射有没有生效curl -I http://localhost:8080如果宿主机能通但浏览器访问时不行重点查安全组或者云平台防火墙。如果宿主机也访问不通则检查容器状态和 Board 日志。这里有个小坑一些部署脚本会给容器名加上随机后缀浏览器调试时要看准实际映射端口不要照着文档里的“默认值”死磕。4. 常见安装失败的场景与排查技巧实录4.1 镜像拉取超时或连接不稳定这是出现频率最高的问题。现象通常是部署脚本停在Pulling阶段进度条长时间不动或者直接报TLS handshake timeout、i/o timeout这类网络错误。解决思路分三步。第一步确认宿主机网络能到达镜像仓库可以用curl -I测试。第二步给 Docker daemon 配置加速 mirror然后重启 Docker。第三步手动拉取关键镜像观察具体卡在哪个镜像。手动拉取的命令大概是docker pull federatedai/eggroll:1.x.x docker pull federatedai/fateboard:1.x.x docker pull mysql:8.0 docker pull redis:5手动拉取还有一个好处能看到磁盘和带宽的真实占用判断到底是网络慢还是磁盘空间不够。如果某个镜像反复在最后一层失败大概率是连接被重置重试几次往往能成功。所有依赖镜像都拉完后再跑部署脚本就非常快脚本只在本地做容器创建和启动。4.2 端口被占用导致容器启动失败FATE 单机部署占用的服务端口非常多如果机器上本来就有 MySQL、Redis、Nginx 或者其他 Web 服务容器编排时很容易报port is already allocated。排查时先确认端口占用情况sudo ss -lntp | grep -E 8080|3306|6379|9360|9370|9380|8888|8000确认占用后最简单的办法是停掉冲突服务。如果你确实需要保留原有服务再考虑修改 compose 端口映射。但这里要注意FATE 组件之间通过容器网络内部的 service 名和默认端口通信宿主机映射端口改掉通常不影响容器间互访。可是某些管理端界面或客户端配置文件里写死的地址仍然指向旧端口只改 compose 表面映射会留下隐藏问题。需要全局搜索配置文件里的端口引用确保所有关联配置都同步调整。4.3 内存不足导致 MySQL 或 Redis 反复重启部署脚本走到最后容器看似都创建了但docker ps里 MySQL 或 Redis 一直在 Restarting这是资源问题的典型信号。查看进程被杀的日志通常会出现OutOfMemoryError或者内核日志里能看到oom-killer。处理方式首先是释放宿主机内存关掉不必要的 Java 或 Python 进程。其次检查 Docker 的资源限制配置确认 compose 里没有把 mem_limit 设得过低。还可以临时调整/proc/sys/vm/overcommit_memory但这个内核参数会影响整个系统的内存分配策略生产环境不要随意更改。最稳妥的方式还是保证宿主机内存至少 8 GB并预留 2 GB 以上余量给系统本身。4.4 容器全部正常但训练任务一直等待资源容器状态正常、页面也能打开但提交训练任务后一直处于 pending这类问题隐蔽在通信层。FATE 的计算通信底座会自动注册节点如果容器无法按预期解析服务名或互相访问任务就会一直申请不到资源。这时不要急着看上层训练日志先进入容器验证网络连通性docker exec -it container_name bash ping another_service_name确认同一 Docker 网络里的容器能互相ping通。如果 ping 不通检查 compose 里的自定义网络配置、容器的 network aliases、以及宿主机 hosts 文件。跨多机部署时还要检查所有节点的时钟是否同步时间偏差过大会导致通信握手失败。这个问题很隐蔽不容易在部署阶段暴露通常要到任务调度阶段才体现。所以多机环境里第一时间做时间同步可以少踩很多坑。5. 安装成功后的功能验证与快速上手5.1 先跑官方 Toy 示例验证系统闭环部署环境完成后不要急着用自己的业务数据跑训练先把官方自带的 toy_example 跑通。这个示例模拟两个参与方之间的一次极小规模联邦建模专门用来验证底层通信和任务调度是否正常。进入 FATE 客户端容器找到官方示例目录docker exec -it fate_client_container_name bash cd /data/projects/fate/python/examples/toy_example/ python run_toy_example.py 100 1看到任务成功返回说明部署配置没问题。如果这一步失败后面所有训练任务都可能失败必须先排查环境。Toy 示例的价值在于它足够简单问题范围很窄不是数据问题不是算法问题基本就是环境链路问题。5.2 用 Python 客户端提交一个最小横向训练任务Toy 示例跑通后你可以在 Notebook 或命令行客户端里创建一个真实的最小任务。核心流程包括上传数据、定义参与方、编写 pipeline、提交任务、查看结果。建议从横向联邦学习任务开始因为它的数据结构最简单多个参与方拥有相同特征空间、不同样本空间。先复制示例里的 DSL 和 pipeline 配置把数据路径改成自己的样本数据跑通后再逐步调整特征工程和模型参数。不要从零开始写 pipeline示例配置里的组件连接方式往往是最稳定的一套模板改比写快得多。5.3 单机模拟多方和真实多机构联动的差异单机部署的“多个参与方”实际上运行在同一个 Docker network 里它们之间通过服务名通信不存在真实跨机构网络链路的时延、丢包、安全隔离问题。因此单机验证通过只能说明功能逻辑正确不能完全等同于真实多机构环境的行为。真正跨机构部署时需要为每个参与方单独部署一套 FATE 环境并配置彼此的 IP、端口、证书和角色信息。这时候要考虑网络访问控制、数据传输加密、节点异常恢复等内容。学习阶段先把单机吃透等有机会接触真实业务环境时你会发现单机阶段建立的组件概念和排查思路都能直接迁移过去。6. 部署完成后留下的几条实操建议6.1 提前为容器设置资源配额Docker 默认不限制容器的 CPU 和内存使用但 FATE 训练任务在数据量增大后非常吃资源。如果不做限制一个任务可能把宿主机内存全部吃掉导致其他服务甚至 SSH 都失去响应。建议在 compose 文件里给关键容器增加 resource limits比如将计算节点容器的内存限制在一个明确的上限。具体数值要根据业务数据量来定宁可先设置一个观察基线再根据监控调整。容器资源配额的意义不是限制性能而是保护宿主机整体稳定性。分布式训练场景里单个任务异常不能拖垮整台机器否则排查成本会成倍增加。6.2 日志和数据目录的日常维护FATE 的容器会持续产生三类数据运行日志、数据库内容、模型产物。如果这些数据都落在 Docker 默认目录或系统盘上磁盘早晚会被写满。建议把数据盘单独挂载并在 compose 配置中显式指定 volume 路径让业务数据与系统盘分离。日常巡检可以关注下面三个命令docker system df du -sh /var/lib/docker/* docker system prune -f --volumes使用docker system prune前务必确认没有需要的容器数据因为它会清理未被引用的资源。我吃过一次亏清完临时环境后才发现某个数据库卷没有外部备份恢复起来非常麻烦。清理操作永远先备份、再执行。6.3 升级和卸载前一定要留好备份FATE 版本升级不是简单替换镜像 tag数据库表结构、组件启动参数、前端页面路由都可能变化。升级前至少做好三件事导出 MySQL 数据、保存当前 compose 文件、记录当前镜像版本。没有备份就升级一旦失败回滚会非常痛苦。卸载环境也是一样。执行docker compose down -v会连容器、网络和卷一起清理如果没有提前备份数据删除之后基本无法找回。我会在每个部署目录里放一个 README记录部署日期、镜像版本、自定义参数和需要注意的坑。这比依赖记忆可靠得多尤其当你同时管理多套环境的时候。最后分享一个很小但很实用的习惯部署完成后顺手把 FATE Board 默认账号密码和 MySQL root 密码改掉。很多示例环境停留在默认口令状态一旦容器暴露在局域网里容易被扫描工具盯上。改密码只是多花几分钟却能避免后续被薅成“挖矿肉鸡”的尴尬。等真正开始多机联调时一个干净、安全、有备份记录的起点会让你从容很多。
