free5gc/ueransim

UERANSIM 5G网络模拟器镜像文档

镜像概述

UERANSIM是一个基于Docker容器化的开源5G网络模拟工具，旨在提供符合3GPP标准的5G用户设备(UE)和核心网功能的完整模拟环境。该镜像封装了UERANSIM项目的核心组件，允许用户快速部署和配置5G网络模拟环境，适用于5G协议开发、网络功能测试、教学研究等场景，无需依赖实际5G硬件设备。

核心功能与特性

核心网组件支持

• 接入和移动管理功能(AMF)：负责UE的注册、认证、移动性管理和会话管理协调
• 会话管理功能(SMF)：处理会话建立、修改和释放，管理用户面路径
• 用户面功能(UPF)：负责用户数据的路由和转发，支持QoS处理
• 网络切片选择功能(NSSF)：支持5G网络切片的选择和管理

用户设备(UE)模拟

• 支持多UE并发模拟，模拟真实用户设备的接入、移动和数据传输行为
• 实现NR（新无线电）协议栈，包括物理层、MAC层、RLC层和PDCP层的基本功能
• 支持多种接入场景，如初始接入、切换、会话建立等

标准兼容性

• 符合3GPP TS 23.501、TS 23.502等核心网规范
• 支持5G NR接入网协议（3GPP TS 38系列）
• 兼容5G核心网的非独立组网(NSA)和独立组网(SA)架构

网络模拟能力

• 支持自定义网络拓扑配置，可灵活部署核心网组件和UE
• 提供网络流量监控和日志输出，便于调试和分析
• 支持与外部网络功能或模拟器的集成（如eNodeB、gNodeB模拟器）

使用场景

5G协议开发与调试

• 开发人员可基于模拟环境验证5G核心网协议实现，快速定位协议交互问题
• 测试新功能（如网络切片、QoS策略）在不同场景下的表现

网络功能测试

• 对5G核心网网元（AMF、SMF等）的功能正确性进行自动化测试
• 模拟极端场景（如高并发UE接入、切换频繁）下的网络稳定性

教学与研究

• 高校和研究机构用于5G网络原理教学，直观展示5G网络架构和协议流程
• 研究5G网络性能优化、资源调度算法等课题的实验平台

产品预研与演示

• 在产品开发早期构建原型环境，验证产品与5G网络的兼容性
• 向客户演示5G应用场景（如工业物联网、AR/VR）的网络支持能力

使用方法与配置说明

前提条件

• 安装Docker Engine (20.10+) 和Docker Compose (v2+)
• 主机需支持IPv6（部分核心网功能依赖）
• 至少2GB内存和20GB磁盘空间

获取镜像

UERANSIM Docker镜像可通过以下方式获取：

从Docker Hub拉取（若官方提供）

bash
docker pull aligungr/ueransim:latest

自行构建镜像

从GitHub仓库克隆源码并构建：

bash
git clone https://github.com/aligungr/UERANSIM.git
cd UERANSIM
docker build -t ueransim:local .

基本使用流程

1. 准备配置文件

UERANSIM通过配置文件定义核心网组件和UE的参数。需创建配置目录并挂载到容器中，示例配置文件可从项目仓库获取：

bash
mkdir -p ueransim/config
git clone https://github.com/aligungr/UERANSIM.git
cp -r UERANSIM/config/* ueransim/config/

2. 启动5G核心网组件

使用Docker Compose部署核心网组件（推荐），创建docker-compose.yml：

yaml
version: '3'
services:
  amf:
    image: ueransim:local
    command: ./build/amf -c /config/amf.yaml
    volumes:
      - ./ueransim/config:/config
    network_mode: host  # 核心网组件需使用主机网络以确保端口映射正确
    restart: unless-stopped

  smf:
    image: ueransim:local
    command: ./build/smf -c /config/smf.yaml
    volumes:
      - ./ueransim/config:/config
    network_mode: host
    restart: unless-stopped

  upf:
    image: ueransim:local
    command: ./build/upf -c /config/upf.yaml
    volumes:
      - ./ueransim/config:/config
    network_mode: host
    cap_add:
      - NET_ADMIN  # UPF需要网络管理权限以配置路由和TUN接口
    restart: unless-stopped

启动核心网：

bash
docker-compose up -d

3. 启动UE模拟器

在另一个终端启动UE，连接到已部署的核心网：

bash
docker run -it --rm --network host \
  -v ./ueransim/config:/config \
  ueransim:local \
  ./build/ue -c /config/ue.yaml

配置参数说明

核心网配置文件（以amf.yaml为例）

关键配置项：

• plmn_list：运营商PLMN信息（MCC+MNC）
• served_guami：AMF的GUAMI（全球唯一AMF ID）
• tac：跟踪区域码
• ngap_ip_addresses：AMF的NGAP接口IP地址
• security：认证和加密算法配置

UE配置文件（ue.yaml）

关键配置项：

• supi：用户永久标识符（如imsi-208930000000001）
• plmn：目标PLMN（MCC+MNC）
• key：用户认证密钥
• opc：OPc值（用于认证）
• gnb_search_list：要搜索的gNodeB列表（IP和端口）

日志与监控

核心网组件和UE的日志默认输出到容器标准输出，可通过以下命令查看：

bash
# 查看AMF日志
docker-compose logs -f amf

# 查看UE日志
docker logs -f <ue_container_id>

停止与清理

bash
# 停止核心网组件
docker-compose down

# 删除容器和镜像（如需）
docker rm -f $(docker ps -aq --filter ancestor=ueransim:local)
docker rmi ueransim:local