free5gc 5G核心网安装与测试实战：从环境搭建到端到端验证

1. 项目缘起与整体设计思路1.1 为什么选择 free5gc 作为核心网实验平台做移动通信核心网方向的朋友大概都有过这样的困扰想动手验证一个信令流程或者调一个用户面转发的参数结果发现手头能用的实验环境要么是昂贵的商用设备要么是黑盒到根本看不到内部状态。几年前我开始系统性地搭建核心网实验环境时也走过不少弯路直到把目光锁定在 free5gc 上才算真正找到了一个能“看得见、改得动、跑得起来”的开源方案。free5gc 是一个基于 3GPP Release 15 规范实现的开源 5G 核心网项目用 Go 语言编写。它把 5G 核心网里那些原本抽象的服务化架构网元——AMF、SMF、UPF、AUSF、UDM、PCF、NRF、NSSF 等等——全部用软件的方式实现出来跑在通用的 Linux 服务器或者虚拟机上。这意味着你不需要任何专用硬件一台配置还过得去的机器就能把整个 5G 核心网“装”进去。我之所以在多个开源核心网方案里最终选了它主要基于三点考量。第一是规范贴合度高它的接口设计、信令流程基本严格对照 3GPP 的 TS 23.501、TS 23.502 等文档做协议学习时对照性很强。第二是代码可读性好Go 语言的并发模型天然适合处理核心网这种高并发信令场景而且代码结构清晰想追踪某个流程时顺着函数调用就能摸清楚。第三是社区活跃度遇到问题时能较快找到参考版本迭代也比较稳定。这个项目标题里的“installation and test”说白了就是两件事把环境搭起来以及验证它到底能不能正常工作。听起来简单但实际操作中从依赖安装、配置调整到测试验证每一步都有不少细节值得说道。这篇文章就是把我自己反复搭建、调试、踩坑的完整过程整理出来适合刚接触核心网实验的初学者也适合想快速搭一套验证环境做二次开发的中级开发者。1.2 整体架构与部署形态的取舍在动手之前有必要先把 free5gc 的部署形态讲清楚因为这直接决定了你后面安装和测试的方式。free5gc 支持两种典型的部署方式裸机直接部署和容器化部署。裸机部署就是把各个网元编译成二进制可执行文件直接跑在宿主机上容器化部署则是把每个网元打包成容器镜像通过编排工具统一管理。我个人的建议是如果你是第一次接触先用裸机方式跑一遍。原因很实在——裸机部署能让你清楚地看到每个网元启动时加载了哪些配置文件、监听了哪些端口、依赖了哪些外部服务。这个过程对理解核心网的运行机制帮助极大。等你把裸机流程摸透了再上容器化就会觉得一切顺理成章。从架构上看free5gc 的网元之间通过服务化接口SBI通信底层走的是 HTTP/2 协议。控制面网元之间通过 NRF 做服务注册和发现用户面则通过 PFCP 协议在 SMF 和 UPF 之间建立会话。测试的时候你需要一个模拟终端行为的工具通常用 UERANSIM 来充当 gNB 和 UE 的角色让它和核心网完成注册、会话建立、数据转发这一整套流程。整个实验环境的逻辑拓扑大致是这样的UERANSIM 模拟的 gNB 通过 N2 接口连到 AMF通过 N3 接口连到 UPFUE 通过 gNB 接入后核心网完成鉴权、注册、PDU 会话建立最终 UE 能通过 UPF 访问外部数据网络。测试的核心目标就是把这整条链路跑通并且能观察到每个环节的状态变化。提示在规划环境时务必先确认你的机器满足最低配置要求。free5gc 全套网元加上 UERANSIM建议至少 4 核 CPU、8GB 内存磁盘预留 20GB 以上。如果内存不足编译阶段就可能因为 OOM 被系统杀掉进程。2. 环境准备与依赖安装的关键细节2.1 操作系统与基础依赖的选择free5gc 官方推荐在 Ubuntu 18.04 或 20.04 上部署我实测下来 20.04 LTS 的兼容性最好。如果你用的是其他发行版理论上也能跑但可能会在依赖包名称和内核模块上遇到额外麻烦新手不建议折腾。基础依赖里最关键的是Go 语言环境。free5gc 对 Go 版本有明确要求太老的版本编译会报错太新的版本偶尔也会有兼容性问题。我一般选择官方文档推荐的稳定版本安装时注意把GOPATH和PATH配置正确否则后面编译时会提示找不到命令。除了 Go还需要安装一系列系统库和工具包括编译工具链、Git、以及一些网络相关的工具包。这里我列一个我常用的依赖清单你可以对照着检查依赖项作用备注Go 语言环境编译 free5gc 源码版本需匹配官方要求Git拉取源码仓库基本工具build-essential编译工具链提供 gcc、make 等libssl-dev加密库开发文件部分网元依赖iptables网络地址转换配置用户面转发需要iproute2网络接口管理配置网卡和路由安装完这些之后还有一个容易被忽略的步骤加载内核模块。UPF 在做用户面转发时可能会用到 TUN 设备或者特定的网络功能需要提前确认相关模块已经加载。你可以用lsmod查看如果缺失就用modprobe手动加载。注意不同内核版本对网络模块的支持有差异。如果你在容器里做实验可能需要在宿主机层面就配置好相关模块和权限否则容器内的 UPF 无法正常创建网络接口。2.2 源码获取与编译过程中的实操要点依赖装好之后就可以拉取源码了。free5gc 的代码分散在多个仓库里核心网元各自独立另外还有一个统一的配置文件仓库。我的做法是建一个专门的工作目录把所有相关仓库都放在同一层级下这样编译和配置时路径引用不容易出错。拉取源码时有个小技巧优先使用稳定发布版本的分支或标签而不是直接拉主分支。主分支虽然功能最新但可能处于开发中间状态编译失败或者运行异常的概率更高。我早期就因为图省事直接拉了主分支结果某个网元编译报错排查了半天才发现是上游代码正在重构。编译过程本身不算复杂进入每个网元的目录执行编译命令即可。但有几个点需要留意。第一编译顺序有讲究某些网元依赖公共库最好先把公共库编译好。第二编译时的环境变量要正确特别是GOPATH和模块代理设置如果网络环境导致依赖下载缓慢可以配置国内镜像源加速。第三编译产物要统一管理我习惯把所有编译好的二进制文件集中放到一个bin目录下方便后续启动脚本统一调用。编译完成后你可以用file命令检查一下生成的二进制文件确认架构和平台匹配。如果编译过程中出现大量“package not found”的错误八成是依赖没下载完整可以尝试清理模块缓存后重新下载。2.3 配置文件的结构与修改逻辑free5gc 的配置文件是整个部署里最容易让人头大的部分。它把各个网元的配置集中在一个仓库里每个网元对应一个 YAML 文件。这些配置文件里定义了网元的监听地址、端口、依赖的其他网元地址、以及各种业务参数。我刚开始看这些配置时也是一头雾水后来总结出一个理解方法把配置文件分成“网络连接”和“业务参数”两类来看。网络连接部分主要配置本网元监听哪个 IP、哪个端口以及要连接的其他网元在哪里业务参数部分则涉及 PLMN、切片、QoS 等与业务逻辑相关的内容。修改配置时最关键的是保证各网元之间的地址引用一致。比如 AMF 的配置里要写清楚 NRF 的地址SMF 的配置里要写清楚 UPF 的地址如果这些地址对不上网元启动后虽然进程还在但服务注册会失败整个系统就跑不通。我建议在修改前先画一张简单的地址分配表把每个网元用的 IP 和端口都列清楚改的时候对照着来能避免很多低级错误。另外配置文件里的 PLMN 设置要和 UERANSIM 那边的配置保持一致包括 MCC、MNC、TAC 这些参数。如果两边对不上UE 注册时会直接被拒绝而且报错信息往往不够直观容易让人误以为是核心网本身出了问题。3. 核心网元启动与测试链路搭建3.1 网元启动顺序与状态确认free5gc 的网元启动是有依赖关系的不能随便乱起。正确的顺序大致是先启动 NRF因为它是服务注册中心其他网元都要向它注册然后启动 UDM、AUSF 这类提供用户数据和鉴权服务的网元接着启动 AMF、SMF 这些控制面核心网元最后启动 UPF 用户面网元。我一开始没在意顺序结果 AMF 先于 NRF 启动导致 AMF 注册失败日志里一堆连接被拒绝的错误。后来养成习惯写了一个启动脚本按顺序拉起各个网元每个之间间隔一两秒等前一个稳定后再起下一个。启动之后怎么确认网元真的正常工作了我的经验是看日志加查端口双管齐下。每个网元启动后都会输出日志正常情况下能看到服务注册成功的提示。同时可以用ss或netstat命令查看网元是否在预期端口上监听。如果日志里出现反复重连或者注册失败的记录那就要回头检查配置和依赖网元的状态。还有一个细节NRF 的 Web 控制台是个很好用的工具。它提供了一个可视化的界面能看到当前有哪些网元注册上来、它们的服务状态如何。测试阶段我经常开着这个页面随时确认各网元是否在线。3.2 UERANSIM 的配置与接入测试核心网跑起来之后就需要一个“终端”来接入测试。UERANSIM 是目前最常用的开源模拟工具它能模拟 gNB 和 UE 的行为完成从小区搜索到注册、会话建立的完整流程。UERANSIM 的配置主要分两块gNB 的配置和 UE 的配置。gNB 配置里要写清楚它连接的 AMF 地址、本地的 N2 和 N3 接口地址、以及 PLMN 信息。UE 配置里则要写清楚 IMSI、密钥、OP 等鉴权相关参数这些参数必须和核心网 UDM 里配置的用户数据一致否则鉴权会失败。我第一次配的时候鉴权参数没对上UE 一直注册不上日志里显示鉴权失败。排查时我把 UDM 里的用户数据和 UE 配置逐字段对比才发现是 OP 值写错了。这个教训告诉我鉴权参数一定要逐字符核对一个字符不对就会导致整个流程卡住。配置好之后先启动 gNB再启动 UE。gNB 启动后会尝试连接 AMF如果连接成功日志里会有相应提示。UE 启动后会发起注册流程你可以在 AMF 的日志里看到注册请求的处理过程在 SMF 的日志里看到会话建立的过程。如果一切顺利UE 会成功注册并建立一个 PDU 会话此时它应该能获取到一个 IP 地址。3.3 数据面连通性验证与抓包分析控制面跑通只是第一步真正验证核心网是否工作正常还得看数据面能不能通。UE 注册并建立 PDU 会话后会得到一个 IP 地址这个地址是由 SMF 分配的通过 UPF 转发。你要验证的是UE 能不能通过这个 IP 访问外部网络。最直接的验证方法是在 UE 侧 ping 一个外部地址。如果 ping 通了说明用户面转发链路是通的。如果 ping 不通问题可能出在几个地方UPF 的转发规则没配好、iptables 的 NAT 规则缺失、或者路由表不对。我遇到过好几次 ping 不通的情况最后发现都是 iptables 的 MASQUERADE 规则没加导致 UE 的流量出了 UPF 之后没法做地址转换自然就到不了外网。抓包是排查数据面问题最有效的手段。我通常会在 UPF 的 N3 接口和 N6 接口上分别抓包对比看数据包有没有正确转发。如果 N3 口能看到包但 N6 口看不到说明 UPF 内部转发有问题如果 N6 口能看到包但没有回包那可能是外部网络的路由或者 NAT 问题。这种分段排查的思路能帮你快速定位问题出在哪一段。提示抓包时建议用-w参数把包保存成文件再用分析工具打开仔细看。实时抓包刷屏太快容易漏掉关键信息。4. 常见问题排查与实战避坑经验4.1 网元启动失败与注册异常排查在实际操作中网元启动失败是最常见的问题之一。表现可能是进程直接退出也可能是进程还在但日志里不断报错。我把常见的原因和排查方法整理成了一个速查表现象可能原因排查方法进程启动后立即退出配置文件格式错误检查 YAML 缩进和字段名日志提示端口被占用端口冲突用 ss 命令查占用进程服务注册失败NRF 未启动或地址错误确认 NRF 状态和配置地址反复重连依赖网元不可达检查网络连通性和防火墙鉴权失败用户参数不一致逐字段核对 UDM 和 UE 配置我印象最深的一次排查是 SMF 启动后一直无法向 NRF 注册。日志里只显示连接超时但 NRF 明明是启动着的。后来用curl手动测试 NRF 的接口地址发现是配置文件里 NRF 的地址写成了主机名而 DNS 解析有问题。改成 IP 地址后立刻就好了。这个经历让我养成了一个习惯配置文件里尽量用 IP 地址少用主机名能避免很多解析相关的坑。4.2 用户面不通的典型原因与解决思路用户面不通是测试阶段另一个高频问题。UE 能注册成功但就是上不了网这种情况十有八九是用户面配置的问题。我总结下来用户面不通主要有这么几类原因。第一类是UPF 的 N3/N6 接口配置错误比如接口地址写错、绑定的网卡不对。第二类是iptables 规则缺失特别是 NAT 规则没有它 UE 的私网地址出不了公网。第三类是路由问题UPF 所在主机没有正确配置路由导致回包找不到路。第四类是MTU 不匹配这个比较隐蔽表现为小包能通大包不通需要调整接口的 MTU 值。排查时我的顺序是先确认 UPF 接口状态再检查 iptables 规则然后看路由表最后考虑 MTU。这个顺序是从最常见到最不常见排列的能帮你少走弯路。另外UPF 的日志级别可以调高让它输出更详细的转发信息对定位问题很有帮助。4.3 性能与稳定性方面的实操心得环境跑通之后如果你打算用它做持续测试或者二次开发那就得关注性能和稳定性了。性能方面free5gc 在普通服务器上的表现其实相当不错但有几个地方容易成为瓶颈。UPF 的用户面转发是最吃性能的环节如果只是功能验证默认配置够用但如果要做吞吐量测试可能就需要考虑用 DPDK 或者其他加速方案。NRF 的服务发现在高并发场景下也可能成为瓶颈不过一般实验环境不会遇到这个问题。稳定性方面我遇到过一个比较典型的问题长时间运行后某个网元的内存占用持续增长。这通常是代码里的资源没有正确释放导致的。对于实验环境定期重启网元是个简单有效的办法如果要做长期运行建议加上监控观察各网元的内存和 CPU 变化趋势。还有一点经验日志管理很重要。free5gc 各网元的日志输出量不小如果不做轮转磁盘很快就会被占满。我一般会配置日志轮转策略或者把日志输出到单独的目录并定期清理。这个细节看似不起眼但真到了磁盘满了导致服务异常的时候你就会意识到它的重要性。4.4 测试用例设计与结果判读最后聊聊测试本身。搭环境的目的终究是为了测试而测试用例设计得好不好直接决定了你能从实验里获得多少有价值的信息。我的建议是从简到繁、分层验证。第一层是单网元功能测试比如单独验证 AMF 能不能正常处理注册请求。第二层是网元间接口测试比如验证 AMF 和 SMF 之间的会话建立流程。第三层是端到端测试也就是 UE 从注册到上网的完整流程。每一层都验证通过后再往上叠加复杂度。结果判读时不要只看成功或失败要看流程细节。比如注册成功但注册时延比预期长很多这可能暗示着某个环节存在性能问题。再比如会话建立成功但中间经历了多次重试这说明网络存在不稳定因素。这些细节往往比单纯的“通不通”更有价值。我在实际测试中养成了一个习惯每次测试都记录关键时间点和日志片段。这样当结果异常时可以快速回溯到具体环节。时间久了这些记录本身就成了一份宝贵的经验库再遇到类似问题时对照历史记录往往能很快找到方向。整个 free5gc 的安装和测试过程说到底是一个不断遇到问题、分析问题、解决问题的过程。每一个坑踩过之后你对这套系统的理解就会深一层。等你把整条链路都跑通并且能稳定复现的时候回头再看那些配置文件和日志会发现它们不再是天书而是一张清晰的地图。