Free5GC + UERANSIM：从零搭建5G端到端测试环境-编程实验室

1. 为什么需要搭建5G端到端测试环境？

在5G技术研发和学习过程中，很多开发者会遇到一个共同难题：没有真实的5G网络设备进行测试。商用5G基站和核心网设备价格昂贵，普通开发者根本无法承担。这时候，开源工具Free5GC和UERANSIM就成为了绝佳的解决方案。

Free5GC是目前最活跃的开源5G核心网项目，完整实现了3GPP Release 15标准。而UERANSIM则是开源的5G无线接入网和终端模拟器。两者配合使用，可以在普通PC上搭建完整的5G网络环境，包括核心网、基站和终端。我去年开始接触这个组合，实测下来发现它不仅能满足学习需求，甚至可以用来开发验证一些5G应用场景。

这个环境特别适合以下几类人群：

想深入学习5G协议栈的开发者
需要测试5G应用但缺乏真实设备的团队
高校和研究机构进行5G相关课题研究
准备考取5G相关认证的技术人员

2. 环境准备与基础配置

2.1 硬件与系统要求

虽然说是模拟环境，但对硬件还是有一定要求。根据我的实测经验，建议配置如下：

两台x86架构主机（物理机或虚拟机均可）
每台至少4核CPU/8GB内存/50GB存储
Ubuntu 20.04 LTS操作系统（其他Linux发行版可能需调整命令）

我最初尝试在Windows的WSL2中部署，结果发现网络配置太复杂，最后还是老老实实用了Ubuntu虚拟机。这里有个小技巧：如果用VMware，建议给两台虚拟机都配置两块网卡：

第一块用NAT模式（用于上网下载软件包）
第二块用Host-Only模式（用于核心网和基站间通信）

2.2 基础软件安装

在两台机器上都需要先安装基础工具链：

sudo apt update && sudo apt upgrade -y sudo apt install -y git curl net-tools make gcc g++ autoconf libtool pkg-config libmnl-dev libyaml-dev

这些工具主要用于代码编译和网络调试。其中libmnl-dev和libyaml-dev是两个容易遗漏但很重要的库，缺少它们会导致后续编译失败。我曾经因为漏装libyaml-dev，调试了整整一个下午才发现问题所在。

3. Free5GC核心网部署

3.1 Golang环境配置

Free5GC是用Go语言开发的，所以需要先安装特定版本的Go环境。这里有个坑要注意：必须使用Go 1.17.8版本，其他版本可能会导致兼容性问题。

cd ~ wget https://dl.google.com/go/go1.17.8.linux-amd64.tar.gz sudo tar -C /usr/local -zxvf go1.17.8.linux-amd64.tar.gz mkdir -p ~/go/{bin,pkg,src}

配置环境变量时，建议直接修改.bashrc文件：

echo 'export GOPATH=$HOME/go' >> ~/.bashrc echo 'export GOROOT=/usr/local/go' >> ~/.bashrc echo 'export PATH=$PATH:$GOPATH/bin:$GOROOT/bin' >> ~/.bashrc echo 'export GO111MODULE=auto' >> ~/.bashrc source ~/.bashrc

验证安装是否成功：

go version # 应该输出：go version go1.17.8 linux/amd64

3.2 Free5GC源码编译

获取源码时建议使用递归克隆，这样可以一次性获取所有子模块：

git clone --recursive -b v3.3.0 -j `nproc` https://github.com/free5gc/free5gc.git

如果遇到子模块为空的情况（这在网络不稳定时经常发生），需要手动初始化NFs目录下的各个模块：

cd ~/free5gc/NFs rm -rf * git clone -b v1.2.0 https://github.com/free5gc/amf.git git clone -b v1.2.0 https://github.com/free5gc/ausf.git # 其他NF模块同理...

编译时如果报错，建议先执行make clean再重新编译。我遇到过几次编译失败，都是因为残留的中间文件导致的。

3.3 关键配置修改

Free5GC的配置文件都在~/free5gc/config目录下，有三个关键文件需要修改：

amfcfg.yaml- 主要配置AMF的N2接口和PLMN信息

ngapIpList: - 192.168.202.128 # 改为你的Host-Only网卡IP servedGuamiList: - plmnId: mcc: "208" mnc: "93" amfId: "cafe00"

smfcfg.yaml- 配置SMF的N3接口

interfaces: - interfaceType: N3 endpoints: - 192.168.202.128

upfcfg.yaml- 配置UPF的GTP-U接口

gtpu: ifList: - addr: 192.168.202.128 type: N3

修改完成后，可以先运行测试脚本验证核心网基本功能：

cd ~/free5gc ./test.sh TestRegistration

4. UERANSIM部署与配置

4.1 编译安装UERANSIM

在第二台机器上安装UERANSIM前，需要先安装一些额外依赖：

sudo apt install -y libsctp-dev lksctp-tools iproute2 sudo snap install cmake --classic

获取源码并编译：

git clone https://github.com/aligungr/UERANSIM cd UERANSIM make

编译过程大约需要5-10分钟，取决于机器性能。如果遇到编译错误，大概率是缺少某些开发库，可以根据错误提示安装对应的-dev包。

4.2 配置gNB和UE

UERANSIM的配置文件在~/UERANSIM/config目录下：

free5gc-gnb.yaml- gNB配置

ngapIp: 192.168.202.130 # gNB的Host-Only网卡IP gtpIp: 192.168.202.130 amfConfigs: - address: 192.168.202.128 # AMF的IP地址

free5gc-ue.yaml- UE配置

supi: 'imsi-208930000000003' mcc: '208' mnc: '93' key: '8baf473f2f8fd09487cccbd7097c6862' op: '8e27b6af0e692e750f32667a3b14605d' opType: 'OP'

特别注意：UE的IMSI、密钥等参数必须与Free5GC WebConsole中配置的订阅信息完全一致，否则注册会失败。

5. 端到端测试与验证

5.1 启动核心网

在第一台机器上启动Free5GC核心网：

cd ~/free5gc ./run.sh

可以另开一个终端启动WebConsole：

cd ~/free5gc/webconsole ./bin/webconsole

然后在浏览器访问http://[你的IP]:5000，使用admin/free5gc登录。在Subscribers页面添加UE订阅信息，参数要与free5gc-ue.yaml中的配置一致。

5.2 启动gNB和UE

在第二台机器上打开三个终端窗口：

窗口1 - 启动gNB：

cd ~/UERANSIM build/nr-gnb -c config/free5gc-gnb.yaml

窗口2 - 启动UE：

cd ~/UERANSIM sudo build/nr-ue -c config/free5gc-ue.yaml

窗口3 - 测试网络连通性：

ping -I uesimtun0 baidu.com

如果一切正常，你应该能看到ping通的结果。这时在WebConsole上也能看到UE的注册状态和会话信息。

5.3 常见问题排查

UE注册失败：
- 检查AMF和gNB的IP配置是否正确
- 确认UE的IMSI等参数与WebConsole中的订阅信息完全一致
- 查看各组件日志中的错误信息

无法ping通外网：

在第一台机器上启用IP转发：

sudo sysctl -w net.ipv4.ip_forward=1 sudo iptables -t nat -A POSTROUTING -o ens33 -j MASQUERADE

确保没有防火墙阻止转发

gNB无法连接AMF：
- 检查两台机器间的网络连通性
- 确认AMF的N2接口IP配置正确
- 使用tcpdump抓包分析

这套环境我已经部署过十几次，每次都能学到新东西。虽然初期配置有点复杂，但一旦跑通，对理解5G网络架构帮助巨大。建议大家在成功搭建基础环境后，可以尝试修改各种参数，观察系统行为变化，这样理解会更深刻。

Free5GC + UERANSIM：从零搭建5G端到端测试环境