简介：面向 SDN 初学者、Java 网络开发者及运维人员的 Floodlight 安装部署资料，聚焦开源控制器在 Ubuntu 环境下的环境准备与部署落地。Floodlight 以稳定性、易用性和完全开源著称，可作为理解控制器集中控制、网络可编程与扩展平台搭建的实践入口，适合需要从零搭建实验环境或补齐部署环节的读者参考。压缩包约 64.72MB，当前记录文件总数为 0，主要文件类型明细暂未提供，实际内容以解压结果为准；下载后宜先核对目录与文件完整性，再结合 Java 运行环境与 Ubuntu 系统条件开展学习。已有 554 人学习，说明其在 SDN 控制器入门与部署场景中具有一定参考价值。读者可从中获取 Floodlight 安装部署的整体思路、环境准备要点与 Ubuntu 实践参考，并借此加深对开源 SDN 控制器角色、集中控制模式及后续应用扩展方向的理解，适合作为实验搭建和部署排错的辅助材料。

1. Floodlight 是什么：一台 Java 控制器怎么接手 OpenFlow 交换机

交换机上电、网线插好，控制台里刷出一行Switch connected，从这一刻起这半个网络的转发行为就不由交换机自己决定了，而取决于你往流表里写了什么。Floodlight 就是站在中间的那个 Java 控制器：它监听端口等交换机连上来，把上报的端口、链路、主机信息收进内存，再用一套 REST 接口把状态交给你看，也接你下发的流表。听着像个普通中间件，但它直接决定数据面通不通。

它适合三类人：要验证自定义转发逻辑的网络研发、做 OpenFlow 实验的学生和工程师、想找一套能读能改的控制器底座而不想从零啃协议栈的人。下面从跑起来讲到改模块，再讲到踩过的坑。

2. 把 Floodlight 在本机跑通：构建、启动与第一次 REST 探活

这一章目标很单纯：让控制器在本地活着，日志里出现交换机监听，REST 端口能吐 JSON。先别接真交换机。

2.1 环境检查：JDK 版本、堆大小和两个端口

先把三件事确认掉，能省掉后面一大半莫名其妙的报错。

# 1) 确认 JDK 是 8：输出里出现 1.8 才算过 java -version 2>&1 | head -n 3 # 2) 确认构建工具在位（仓库根目录带 build.xml 用 ant，带 pom.xml 用 mvn） which ant mvn 2>/dev/null # 3) 确认 6653 / 8080 没被别人占；SS 是 Linux 上的写法 ss -lntp | grep -E ':(6653|8080)\b' || echo "both ports free"

我坚持用 JDK 8 不是念旧。控制器大量依赖反射和运行期动态加载模块，JDK 9 之后模块化把一批内部包封掉了，启动阶段直接抛UnsupportedClassVersionError或NoClassDefFoundError，日志只有两三行，看着像配置错，其实是运行环境错。构建和运行必须用同一个 JDK，JAVA_HOME和PATH一起改，改完回头复核java -version。

两个端口的含义要分清：6653 是 OpenFlow 通道，走的是二进制协议；8080 是 REST 服务，走 HTTP。千万别用 curl 打 6653，控制器会认为收到一条畸形 OpenFlow 消息，日志里刷一片解析异常，然后你以为是自己模块写错了。堆大小按机器给，个人虚拟机-Xmx512m够跑十几个交换机；如果打算在 PACKET_IN 上做深度解析，给到 1g，别让它频繁 GC 把响应拖到秒级。

端口冲突是新手最常中的一枪。8080 被别的 web 服务占了的表现是：进程活着，日志看着正常，REST 却返回别人的页面。ss -lntp一查就清楚，改端口在 properties 里改，键名以仓库里那份配置为准，通常是ofl.port、rest.port这一类。

2.2 一条构建命令产出可执行 jar

# 走 Maven 的仓库 mvn -q clean package -DskipTests # 走 ant 的仓库（老一些的分支常见） ant clean && ant # 产出物一般落在 target/ 下，先确认 jar 存在再谈启动 ls -lh target/*.jar

clean是为了避免上次构建的 class 混进新 jar——模块加载是按类名走的，旧类残留会让人对着一份「明明改过的代码」怀疑人生。-DskipTests是首轮构建的实用选择：全量测试会拖很久，而且其中一部分需要真实交换机环境，本地跑必挂，报错信息还会误导你。

首次构建要拉一堆依赖。离线机器上这一步会卡住十几分钟然后超时，看着像网络问题，其实是仓库里没有本地缓存。我一般先在能联网的机器上把依赖缓存目录整体拷过去，再执行-o（离线）构建。构建成功的判据不是「没报错」，而是target/下产出一个带主类的可执行 jar，unzip -l能看到META-INF/MANIFEST.MF里写了Main-Class。

2.3 第一次启动：日志里必须出现的三类行

# 最简启动：走 classpath 里自带的那份默认配置 java -Xmx512m -jar target/floodlight.jar # 要改端口或模块列表，用 -cf 指到你自己的配置文件 java -Xmx512m -jar target/floodlight.jar -cf conf/floodlight.properties

-cf这个参数很关键。默认配置是从 jar 内部的 classpath 读的，你改了源码里的 properties 却不重新打包，运行起来还是旧配置——这个坑我踩过不止一次，症状是「配置明明改了，端口纹丝不动」。把配置文件放到 jar 外面、用-cf显式指过去，改一次生效一次。

启动日志里我会盯三类行：模块加载完成的那些Loaded module ...，REST 服务挂载端口的行，以及 OpenFlow 监听的行。三样都出现，说明模块系统、HTTP 服务、交换机会话三块都活着。少哪一样，问题范围就锁在哪一块，比盲目看完整日志快得多。日志级别在仓库的日志配置文件里调，调试模块加载时我会临时把模块系统的包调到 DEBUG，能看清模块之间的依赖解析顺序。

2.4 先打 REST，而不是先接交换机

# 列出当前已加载的模块：这一步能过，说明 REST 和模块系统都活着 curl -s http://127.0.0.1:8080/wm/core/module/loaded/json | python -m json.tool | head -n 30 # 控制器自身概览：能看出已连交换机数量和运行状态 curl -s http://127.0.0.1:8080/wm/core/controller/summary/json

/wm是框架统一挂载的前缀，几乎所有内置接口都在它下面。第一步查「已加载模块」而不是查业务接口，是因为它是最不容易骗人的探针：模块列表里没有你写的类，后面所有 404 都能一句话解释完。

交换机数量返回 0 是正常的，现在还没接任何东西。如果 curl 直接Connection refused，说明 REST 服务压根没起来，大概率是模块清单里少了 REST 相关模块，回 properties 里找。这一步过了，再进入接交换机的阶段，问题定位会清爽很多。

3. 模块化机制拆开看：IFloodlightModule 的四个方法决定你的代码什么时候跑

控制器不是「写个 main 就完事」的结构。所有功能都做成模块，模块之间通过服务接口互相调用，框架负责按依赖顺序初始化它们。搞不清这套加载机制，你会遇到「代码明明写了却没执行」这类玄学问题。

3.1 三个必答问题：我提供什么、我依赖谁、我什么时候初始化

一个模块类要实现IFloodlightModule，核心是回答三个问题。

第一，我对外提供什么服务。getModuleServices()返回一组服务接口的 Class 对象，表示「别的模块可以通过这些接口找到我」。不打算被别人调用，就返回空集合，别强行造接口。

第二，我自己依赖谁。getModuleDependencies()返回一组服务接口的 Class 对象，框架据此做拓扑排序，保证你被初始化时依赖已经在位。这里漏写是最常见的翻车点：代码里context.getServiceImpl(...)拿到 null，运行期空指针，日志只告诉你某一行炸了，不告诉你少声明了一个依赖。

第三，getServiceImpls()把接口和实现对上号。声明了服务却不在这里注册，别的模块getServiceImpl拿到的还是 null。

生命周期只有三个方法：init()拿服务、做准备；startUp()注册监听器、挂 REST 路由；shutdown()收尾。分清楚很重要——init()阶段别的模块可能还没 startUp，你在这里主动调用别人的方法，行为是不确定的。

3.2 把模块写进加载清单：properties 里的模块列表与启动顺序

模块清单是一个逗号分隔的全类名列表，写在 properties 里。这里有个硬性事实：classpath 里有你的类不等于它会被加载，框架只实例化清单里列出的类。所以「我代码写了、编译过了、就是不生效」的第一嫌疑永远是清单。

另一个高频错误是只写自己那一个模块。清单是覆盖式的，不是追加式的——你把默认那份几十个模块的列表替换成一行自己的类，结果是 REST 框架、拓扑管理、流表下发全都不加载，控制器起来了但什么都干不了。正确做法是把默认清单整份复制到 jar 外，末尾追加自己的类名，再看情况删。

启动顺序不用你操心，框架按getModuleDependencies()做排序。但清单里模块之间的隐式依赖还是要人脑过一遍：你的模块要挂 REST 路由，就必须在依赖里声明 REST 服务接口，否则startUp阶段拿到的服务可能是 null。

3.3 写一个最小模块：监听交换机上的 PACKET_IN 并挂一个 REST 路由

下面这段是能直接改吧改吧用的骨架，包名换成你自己的命名空间。

package net.example.floodlight.demo; import java.util.*; import net.floodlightcontroller.core.*; import net.floodlightcontroller.core.module.*; import net.floodlightcontroller.restserver.IRestApiService; import org.projectfloodlight.openflow.protocol.OFMessage; import org.projectfloodlight.openflow.protocol.OFType; import org.projectfloodlight.openflow.protocol.OFPacketIn; public class HelloModule implements IFloodlightModule { private IFloodlightProviderService provider; private IRestApiService restApi; // 不对外提供服务，返回空集合 @Override public Collection<Class<? extends IFloodlightService>> getModuleServices() { return Collections.emptyList(); } @Override public Map<Class<? extends IFloodlightService>, IFloodlightService> getServiceImpls() { return Collections.emptyMap(); } // 依赖必须写全，漏一个就是运行期 null @Override public Collection<Class<? extends IFloodlightService>> getModuleDependencies() { Collection<Class<? extends IFloodlightService>> deps = new ArrayList<>(); deps.add(IFloodlightProviderService.class); deps.add(IRestApiService.class); return deps; } @Override public void init(FloodlightModuleContext context) throws FloodlightModuleException { provider = context.getServiceImpl(IFloodlightProviderService.class); restApi = context.getServiceImpl(IRestApiService.class); // 路由注册放 init 末尾：此时 REST 服务的挂载点已就绪 restApi.addRoutable(new HelloWebRoutable()); } @Override public void startUp(FloodlightModuleContext context) { provider.addOFMessageListener(OFType.PACKET_IN, new PacketInLogger()); } @Override public void shutdown() { } // 监听器：只打日志，把消息继续往下传 private static class PacketInLogger implements IOFMessageListener { @Override public Command receive(IOFSwitch sw, OFMessage msg, FloodlightContext cntx) { OFPacketIn in = (OFPacketIn) msg; // 生产环境别把这个打 INFO，会淹掉日志 System.out.println("packet_in from " + sw.getId() + " port " + in.getInPort()); return Command.CONTINUE; // 千万别返回 STOP，不然别的模块收不到包 } @Override public String getName() { return "helloPacketIn"; } @Override public boolean isCallbackOrderingPrereq(OFType type, String name) { return false; } @Override public boolean isCallbackOrderingPostreq(OFType type, String name) { return false; } } }

逻辑说明：init()里取服务，因为这时候框架已经把依赖模块的实例建好了；startUp()里注册监听器，因为这时候交换机会话管理已经跑起来，注册才能收到后续消息。receive()的返回值是三个坑里最容易翻车的一个——Command.CONTINUE表示交棒给下一个监听器，Command.STOP表示这条消息到此为止。新手为了「不让别人干扰」返回 STOP，结果发现自己的转发逻辑吃掉所有 PACKET_IN，别的模块再也收不到包，拓扑学习直接停摆。

参数说明：addOFMessageListener的第一个参数是消息类型枚举，除了 PACKET_IN 还有 PORT_STATUS、FLOW_REMOVED 等，按需监听，别图省事监听全量——每来一个包都进你的回调，性能会很难看。getName()返回的字符串在回调排序里会被用来标识本监听器，重名会让排序行为变得不可预测。

REST 路由那边，实现一个RestletRoutable，getBasePath()返回挂载路径（比如hello），getRestlet()里把子路径挂到资源类上，资源类用注解声明 HTTP 方法。访问时是/wm/hello/ping。挂载路径里不要再写/wm，框架会自动加。

清单里加上你的类：

# 注意：这是覆盖式配置，先把默认清单整份复制过来，再在末尾追加 floodlight.modules=net.floodlightcontroller.restserver.RestApiServer,\ net.floodlightcontroller.core.internal.FloodlightProvider,\ net.example.floodlight.demo.HelloModule

写好启动，然后打/wm/hello/ping。返回 200 说明三件事同时对上了：类在清单里、依赖声明完整、路由挂载路径没拼错。

4. REST 接口实操：拓扑、流表下发与一次 ping 的对照实验

模块机制是底座，日常干活九成时间花在 REST 上。这一章把「看」和「改」两条路走一遍。

4.1 只读接口先摸清家底：交换机、链路、主机

# 已连交换机列表：拿到 DPID，后面下发流表要用 curl -s http://127.0.0.1:8080/wm/core/controller/switches/json | python -m json.tool # 拓扑链路：两端 DPID + 端口号 curl -s http://127.0.0.1:8080/wm/topology/links/json | python -m json.tool # 主机表：控制器从 ARP/DHCP 里学到的主机位置 curl -s http://127.0.0.1:8080/wm/device/ | python -m json.tool

交换机列表里返回的 DPID 是十六进制字符串，格式是 8 组两字节，下发流表时必须原样粘贴，少写一位前导零就会被判成格式错误。链路接口给的是「A 的某端口连到 B 的某端口」，做路径计算时注意方向，同一条链路可能只出现一次。

/wm/device/返回空是常见现象，不是故障——主机表靠控制器从广播包里学习，没有流量就没有条目。想让它有内容，先在仿真环境里发一个 ping，再回来看。调试时把| python -m json.tool挂上，能把压缩成一行的 JSON 展开，比肉眼找括号快得多。

4.2 staticflowpusher 的字段怎么填：优先级、匹配域与动作

curl -s -X POST http://127.0.0.1:8080/wm/staticflowpusher/json \ -H 'Content-Type: application/json' \ -d '{ "switch": "00:00:00:00:00:00:00:01", "name": "flow-h1-to-h2", "priority": "1000", "eth_type": "0x0800", "ipv4_src": "10.0.0.1", "ipv4_dst": "10.0.0.2", "in_port": "1", "active": "true", "actions": "output=2", "idle_timeout": "0", "hard_timeout": "0" }' # 查回来确认真的写进去了 curl -s http://127.0.0.1:8080/wm/staticflowpusher/list/all/json | python -m json.tool # 实验做完记得清，否则下次调试被旧流干扰 curl -s -X DELETE http://127.0.0.1:8080/wm/staticflowpusher/clear/all/json

参数说明：

4.3 用仿真器造一个三角拓扑，验证一条流从 PACKET_IN 到流表命中

本机装一个轻量拓扑仿真器就够，命令行入口是mn，支持指定远程控制器和 OpenFlow 版本。

# 三台交换机串成一条线，交换机显式声明支持 OpenFlow 1.3 sudo mn --controller=remote,ip=127.0.0.1,port=6653 \ --topo=linear,3 \ --switch=ovsk,protocols=OpenFlow13 # 在仿真器命令行里发一个 ping，同时盯控制器日志 mininet> h1 ping -c 3 h2

第一条 ping 必丢，这是设计如此：交换机上没有匹配流，包进 PACKET_IN 上来，控制器算完路径再下发流表，第二个包才通。观察点有三个——控制器日志里该出现 PACKET_IN 回调和流表下发，交换机列表里该有三台设备，链路接口里该有两条链路。

如果 ping 通了但从头到尾没看到 PACKET_IN，八成是仿真器里的交换机默认流表直接放行了，跟你写的逻辑没关系。反之如果一直不通、PACKET_IN 也不上来，先确认 OpenFlow 版本协商成功——版本不匹配时匹配域字段（比如ipv4_src）会被交换机直接拒绝，返回的错误信息藏在控制器日志里，不会在 curl 的响应里体现。

5. 避坑与排查：五条踩过的血泪记录

下面五条都是「现象看着像 A，实际是 B」的类型，按「现象 → 原因 → 解决」记。

5.1 启动两三秒就退出，日志只有一行异常

现象：java -jar之后进程瞬间结束，日志末尾是UnsupportedClassVersionError或者找不到某个类。

原因：JDK 版本不对。高版本 JDK 上跑，字节码版本和反射访问都过不去；还有一种情况是构建用 JDK 8、运行用 JDK 11，编译产物在旧 VM 上加载失败。

解决：java -version和构建时的JAVA_HOME一起核对，两处都切到 8；如果机器上装了多个 JDK，用绝对路径启动$JAVA8_HOME/bin/java -jar ...，避免 shell 里的 PATH 偷偷生效。

5.2 交换机一直重连，控制器日志刷握手失败

现象：仿真器里交换机状态在 connecting 和 disconnected 之间反复，控制器的交换机列表永远是空的。

原因：6653 端口被占或被防火墙拦；或者两边 OpenFlow 版本谈不拢。版本问题的典型特征是握手能过一点，然后在特性协商阶段断开。

解决：ss -lntp | grep 6653确认监听者是不是你的控制器；仿真器侧显式声明 OpenFlow 版本，控制器侧确认允许的版本范围配置；实在没头绪就在 DEBUG 级别看握手日志，里面会写明对方报的版本号。

5.3 自己加的路由返回 404，模块日志看不出异常

现象：/wm/hello/ping返回 404，但控制器启动正常，别的内置接口都能访问。

原因：三种可能——模块类没进floodlight.modules清单；getBasePath()返回值里手写了/wm前缀导致路径变成/wm/wm/hello；init()里注册路由时 REST 服务还没挂载完成。

解决：先打/wm/core/module/loaded/json，确认你的类名在列表里；再看访问路径有没有重复前缀；最后把restApi.addRoutable(...)从startUp()挪到init()末尾。这三步我一般按顺序走，九成问题在第一步。

5.4 流表下发返回 200，ping 还是不通

现象：POST 成功，list/all/json里能看到这条流，但数据面没反应，PACKET_IN 也没停。

原因：优先级被别的流压住；in_port写成了对端端口；actions里的输出端口号是拓扑图上脑补的编号，跟交换机实际的本地端口号不一致；idle_timeout设得太短，包还没到就过期了。

解决：priority临时拉到 1000 排除干扰；用交换机详情接口核对端口号，别信拓扑图；idle_timeout一律先设 0。另外下发完清一遍旧流，很多人是被自己上一轮实验的残留流坑了。

5.5 拓扑链路返回空数组，但交换机都连上了

现象：/wm/topology/links/json返回[]，交换机列表却有三台。

原因：链路发现依赖控制器周期性发送探测包，仿真器或中间设备的过滤规则把它丢了；或者拓扑/链路发现相关模块没在清单里。

解决：确认模块清单里链路发现和拓扑管理都在；仿真器里别加阻断探测包的流表规则；刚启动时等一轮探测周期再查，别在启动后一秒就断言拓扑坏了。

6. 把控制器当成被测系统：一份冒烟脚本与三个我固定不改的参数习惯

改完模块手工 curl 一遍的时代我早过了。每次动代码先跑一份冒烟脚本，比人脑记命令可靠。它的价值不在自动化，而在于把「我以为环境是好的」变成「我知道环境是好的」。

import json, urllib.request BASE = "http://127.0.0.1:8080" def call(method, path, body=None, timeout=5): data = json.dumps(body).encode() if body is not None else None req = urllib.request.Request(BASE + path, data=data, method=method, headers={"Content-Type": "application/json"}) with urllib.request.urlopen(req, timeout=timeout) as resp: raw = resp.read().decode() return resp.status, (json.loads(raw) if raw[:1] in "{[" else raw) def smoke(): # 1) 模块系统：自己的模块在不在加载列表里 _, mods = call("GET", "/wm/core/module/loaded/json") assert any("HelloModule" in m for m in mods), "模块没被加载，先查 properties 清单" # 2) 交换机会话：至少一台在线 _, sw = call("GET", "/wm/core/controller/switches/json") assert sw, "没有交换机连上来，先查 6653 端口和 OpenFlow 版本" dpid = sw[0]["dpid"] # 直接复用，避免手打 DPID 出错 # 3) 写一条最低干扰的流：只做 output，不匹配任何字段 flow = {"switch": dpid, "name": "smoke", "priority": "1", "active": "true", "actions": "controller", "idle_timeout": "0", "hard_timeout": "0"} call("POST", "/wm/staticflowpusher/json", flow) # 4) 查回来确认，再清掉，保持环境干净 _, flows = call("GET", "/wm/staticflowpusher/list/all/json") assert "smoke" in json.dumps(flows), "流表没写进去" call("DELETE", "/wm/staticflowpusher/clear/all/json") print("smoke ok") if __name__ == "__main__": smoke()

逻辑说明：四步是递进的，前一步不通过就没必要跑后面——模块没加载，讨论流表没有意义。dpid从接口里取而不是写死，是因为仿真环境每次重建拓扑后 DPID 可能变，写死会让你对着一条「下发给不存在交换机」的请求查半小时。清理步骤一定要有，冒烟脚本自己污染环境是最讽刺的事。

三个我固定不改的参数习惯：priority永远从极值开始试（调试期 1000，冒烟期 1），中间值会让你分不清是匹配没中还是被压住；idle_timeout调试期恒为 0，任何非零值都是给自己埋的定时炸弹；in_port只从接口取，绝不手敲。这三条不是规范，是被坑出来的肌肉记忆。

还有一条经验关于日志：PACKET_IN 回调里打日志一定要限流或者降到 DEBUG。我曾经在一次压测里把回调日志开到 INFO，日志文件十分钟涨到几个 G，磁盘写满后控制器假死，排查方向还被日志本身带偏——那次的教训是，黑匣子淹没了，比没有黑匣子更糟。

最后一句实话：Floodlight 这类控制器最适合当「能读能改的底座」，不适合当黑盒生产设备用。你要是只想让网络通，用现成的交换机配置更快；你要是想验证一套自己的转发逻辑、想在流表层面做实验，它值得投入那两三天把模块机制和 REST 接口摸熟。我从改第一个模块到能独立写转发逻辑，中间隔了差不多一周的晚上，回头看最费时间的不是写代码，是搞明白「为什么我的代码没被加载」。希望你少走这一段，希望帮到你。

本文还有配套的精品资源，点击获取