基于Helm一键部署云原生5G核心网与无线接入网实战指南-平芜编程栈

1. 项目概述：一键部署云原生5G核心网与无线接入网

如果你正在研究或测试5G网络，尤其是对云原生架构和Kubernetes上的5G部署感兴趣，那么你很可能已经听说过Free5GC和UERANSIM这两个优秀的开源项目。前者提供了一个功能完整的5G核心网实现，后者则是一个强大的5G RAN（无线接入网）和UE（用户设备）模拟器。然而，将它们手动部署到K8s集群中，配置网络、存储、服务发现，并确保各个网元（如AMF、SMF、UPF）能正确通信，是一个相当繁琐且容易出错的过程。这正是Orange开源的towards5gs-helm项目要解决的问题。

简单来说，towards5gs-helm是一套Helm Chart的集合。它的核心价值在于，通过几个简单的Helm命令，就能在Kubernetes集群上“一键式”部署一个完整的、可工作的5G独立组网系统，其中包含了基于Free5GC的5G核心网和基于UERANSIM模拟的无线接入网及用户设备。这极大地降低了5G云原生环境的搭建门槛，无论是用于开发测试、概念验证，还是教学演示，都提供了极大的便利。对于网络工程师、云原生开发者和电信研究人员而言，这个项目是一个快速搭建标准化5G测试环境的绝佳工具。

2. 项目架构与核心组件解析

2.1 整体设计思路：云原生5G的Helm实践

towards5gs-helm项目的设计哲学非常清晰：将复杂的5G系统部署抽象化、模板化。它没有重新发明轮子去编写5G网元，而是作为“胶水”和“编排器”，将成熟的Free5GC和UERANSIM组件，以云原生的方式粘合在一起。

其架构可以理解为两层：

底层组件：即Free5GC和UERANSIM。Free5GC提供了3GPP标准定义的5G核心网控制面和用户面功能，如AMF（接入和移动性管理功能）、SMF（会话管理功能）、UPF（用户面功能）等。UERANSIM则模拟了gNB（5G基站）和UE，用于生成和控制5G空口的信令与数据流量。
上层编排：即本项目提供的Helm Charts。它为每个需要独立部署的5G网元（或一组紧密相关的网元）创建了一个Chart。每个Chart里包含了Kubernetes部署所需的全部清单文件模板，如Deployment、Service、ConfigMap、PersistentVolumeClaim等，并通过Helm的values.yaml文件提供了集中的、可灵活配置的参数入口。

这种设计的优势在于关注点分离。5G协议栈的复杂性由Free5GC和UERANSIM社区负责；而部署、配置管理、服务发现、资源声明等云原生层面的复杂性，则由Helm Chart来封装。用户只需要关心values.yaml中的几个关键配置项，就能控制整个5G系统的行为。

2.2 核心组件与Chart对应关系

要理解如何操作，首先得知道这套系统里有哪些“零件”。towards5gs-helm通常包含以下核心Charts，每个Chart对应一个或多个5G网络功能：

核心网控制面Chart：这通常是一个 umbrella chart（伞状图表）或一组关联的charts，负责部署Free5GC的核心控制面组件。
- AMF：负责终端接入、移动性管理和注册流程。它是UE接入网络后第一个交互的核心网元件。
- SMF：负责会话管理，包括PDU会话的建立、修改和释放，以及为UE分配IP地址。
- UDM/UDR：统一数据管理/存储，管理用户订阅数据。
- AUSF：认证服务器功能，处理用户的认证和授权。
- NSSF：网络切片选择功能。
- NRF：网络仓储功能，这是5G SBA（基于服务的架构）的关键，所有NF（网络功能）都需要向NRF注册，并通过它来发现其他NF。
核心网用户面Chart (UPF)：负责数据包的路由和转发，是用户数据平面的出口和入口。UPF的性能和配置直接影响到数据吞吐量。
RAN模拟Chart (gNB)：基于UERANSIM，模拟一个5G基站。它需要配置与核心网AMF的接口（N2）以及无线参数。
UE模拟Chart (UE)：同样基于UERANSIM，模拟一个或多个5G用户终端。它需要配置SIM卡信息（SUPI/SUCI）、要连接的gNB信息等。

注意：具体的Chart划分可能随着项目版本迭代而变化。有些版本可能将所有核心网控制面组件打包在一个Chart中，有些则可能分开。部署前务必查阅项目文档的docs/目录，这是了解当前版本架构最准确的方式。

2.3 关键依赖与前置条件

在挥舞Helm这把“利器”之前，你需要确保“战场”（环境）已经准备就绪。以下是必须满足的前置条件：

一个可用的Kubernetes集群：可以是本地的Minikube、Kind、K3s，也可以是云厂商的托管集群（如EKS, AKS, GKE）。集群版本建议在1.20及以上。
Helm CLI工具：需要在你的本地机器上安装Helm 3.x版本。
集群网络配置：这是最大的挑战之一。5G网元之间通过特定的端口通信（例如，AMF的N2接口端口38412，NRF的80端口等）。你需要确保：
- Kubernetes的CNI（容器网络接口）插件工作正常，Pod间可以互通。
- 如果gNB模拟器（运行在Pod中）需要与外部物理测试设备通信，可能需要配置HostNetwork或特定的网络策略。
- 核心网组件间的服务发现依赖于Kubernetes Service。Chart会创建对应的Service，确保其类型（ClusterIP/NodePort/LoadBalancer）符合你的访问需求。
存储：像UDM/UDR这样的组件可能需要持久化存储来保存用户数据。Chart中通常会定义PVC（持久卷声明），你需要确保集群中有可用的StorageClass，或者根据实际情况修改values.yaml中的存储配置。
镜像拉取：确保你的K8s集群节点能够从Docker Hub或项目指定的容器镜像仓库拉取Free5GC和UERANSIM的镜像。有时可能需要预先拉取或配置镜像仓库密钥。

3. 实战部署：从零搭建5G测试环境

理论说得再多，不如动手一试。下面我们以一个典型的部署流程为例，展示如何使用towards5gs-helm在本地Kind集群中搭建一套完整的5G SA（独立组网）测试环境。

3.1 环境准备与集群初始化

首先，我们在本地创建一个Kind集群。选择Kind是因为它轻量、快速，非常适合本地开发和测试。

# 1. 安装Kind (如果尚未安装) # 参考 https://kind.sigs.k8s.io/docs/user/quick-start/#installation # 2. 创建一个名为`5g-test`的集群，配置文件允许端口映射以便后续访问 cat > kind-cluster.yaml <<EOF kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane extraPortMappings: - containerPort: 30080 # 用于映射NRF的HTTP服务 hostPort: 30080 protocol: TCP - containerPort: 30443 # 用于映射NRF的HTTPS服务（如启用） hostPort: 30443 protocol: TCP # 可以根据需要添加更多端口映射，例如给UPF的GTP-U端口(2152) EOF kind create cluster --name 5g-test --config kind-cluster.yaml # 3. 验证集群 kubectl cluster-info --context kind-5g-test kubectl get nodes

接下来，安装Helm。这里假设你已经安装了Helm 3。

# 添加 towards5gs 的 Helm仓库 helm repo add towards5gs https://raw.githubusercontent.com/Orange-OpenSource/towards5gs-helm/main/repo/ helm repo update # 搜索仓库，查看有哪些可用的Charts helm search repo towards5gs

执行helm search repo后，你可能会看到类似towards5gs/free5gc，towards5gs/ueransim这样的Chart名称。具体的名称需要以实际搜索结果为准。

3.2 配置与部署核心网（Free5GC）

部署的核心是配置values.yaml文件。我们首先部署核心网。通常项目会提供一个覆盖默认配置的values.yaml示例。你需要先获取它。

# 假设核心网Chart名为 towards5gs/free5gc # 1. 拉取Chart到本地，以便查看和修改values helm pull towards5gs/free5gc --untar cd free5gc

现在，重点来了：修改values.yaml。以下是一些必须检查和可能修改的关键配置项，这些是部署成功的核心：

# 示例：values.yaml 关键部分 global: # 镜像仓库和标签，确保使用稳定版本 repository: free5gc tag: "v3.2.1" # 请查阅项目文档，使用推荐的版本 # NRF配置，它是服务注册与发现的中心 nrf: enabled: true service: type: NodePort # 在本地测试时，为了方便外部访问，可以设为NodePort nodePort: 30080 # 对应Kind配置中映射的端口 # NRF需要被其他所有NF访问，确保其Service名称和端口配置正确 config: sbi: port: 80 scheme: http # 测试环境通常用http，生产环境考虑https # AMF配置 amf: enabled: true config: nrfUri: http://free5gc-nrf:80 # 这是K8s Service DNS，指向NRF服务 sbi: port: 29518 ngap: port: 38412 # N2接口端口，gNB将连接到此 # SMF配置 smf: enabled: true config: nrfUri: http://free5gc-nrf:80 upf: # 指定UPF的地址，可以是Service名或IP - addr: free5gc-upf # 这是UPF的K8s Service名称 dnn: - dnn: internet cidr: 60.60.0.0/16 # 为UE分配的IP地址池 # UPF配置 upf: enabled: true config: gtpu: addr: 10.244.0.0 # UPF自身的GTP-U地址，需与Pod网络匹配 dnn: - dnn: internet cidr: 60.60.0.0/16 nat: enable # UPF通常需要特权模式来操作网络命名空间和加载内核模块 securityContext: privileged: true # 如果UPF需要高性能数据面，可能需要使用hostNetwork或SR-IOV # networkType: hostNetwork

实操心得：在本地测试时，最常遇到的问题就是网络连通性。务必理解：
Pod间通信：所有核心网组件（AMF, SMF, NRF等）的Pod必须在同一个K8s网络内，能通过Service名称（如free5gc-nrf）互相解析和访问。这是K8s Service和CoreDNS默认提供的。
gNB到AMF的N2连接：gNB模拟器（也是一个Pod）需要能访问到AMF Service的nodePort（如果AMF Service是NodePort类型）或者ClusterIP（如果gNB Pod在集群内）。在Kind中，由于gNB Pod也在集群内，使用ClusterIP即可，地址就是free5gc-amf和端口38412。
UPF的数据面：UPF是数据出口。如果UE模拟器也在集群内，数据流能在集群网络内闭环。如果你希望UE的数据能访问外部互联网（例如，从UE Podping 8.8.8.8），则需要配置UPF的NAT和路由，并且确保UPF Pod所在的节点有到外网的路由。这通常更复杂，初期测试可以只关注信令连通性。

配置完成后，开始部署：

# 回到Chart所在目录的上一级 cd .. # 安装Release，命名为 my-5g-core helm install my-5g-core ./free5gc -f ./free5gc/values.yaml --namespace free5gc --create-namespace

部署后，密切观察Pod状态：

kubectl get pods -n free5gc -w

等待所有Pod都进入Running状态。如果有Pod启动失败，使用kubectl logs -n free5gc <pod-name>查看日志，错误信息是排查问题的关键。

3.3 配置与部署无线接入网及UE模拟器（UERANSIM）

核心网运行起来后，接下来部署RAN和UE。同样，先拉取Chart并配置。

helm pull towards5gs/ueransim --untar cd ueransim

修改values.yaml。这里的配置必须与上一步的核心网配置对齐。

# 示例：ueransim values.yaml 关键部分 global: repository: ueransim tag: "latest" # 建议指定一个稳定版本标签 # gNB模拟器配置 gnb: enabled: true replicaCount: 1 config: # 关键！指向AMF的地址。如果AMF Service类型为ClusterIP，则使用K8s Service名。 amfConfigs: - address: free5gc-amf.free5gc.svc.cluster.local # 完整的Service DNS port: 38412 # gNB的本地配置 linkIp: 10.244.0.0 # gNB的GTP-U地址，需与Pod IP在同一网段 ngapIp: 10.244.0.0 # gNB的N2接口地址 gtpIp: 10.244.0.0 # 小区ID、频段等无线参数（模拟用） tac: 1 mcc: "001" mnc: "01" # UE模拟器配置 ue: enabled: true replicaCount: 1 config: # 关键！指向gNB的地址。由于gNB和UE可能在同一Pod或不同Pod，需要配置正确。 gnbSearchList: - address: <gnb-service-name> # 例如 ueransim-gnb.ueransim.svc.cluster.local # UE的SIM卡信息，必须与核心网UDM中配置的订阅数据匹配 supis: - imsi: "001010000000001" # 国际移动用户识别码 key: "465B5CE8B199B49FAA5F0A2EE238A6BC" # 认证密钥 op: "E8ED289DEBA952E4283B54E88E6183CA" # 运营商代码 opType: "OP" # 或 "OPC" amf: "8000" sqn: "000000000000" # 默认的DNN（数据网络名称），需与SMF中配置的一致 defaultDnn: "internet"

注意事项：imsi、key、op这些认证参数是重中之重。它们必须与核心网UDM/UDR中预置的订阅数据完全一致，否则UE无法通过认证。在Free5GC中，这些数据通常通过一个初始化的配置文件或数据库脚本注入。towards5gs-helm的Free5GC Chart可能会包含一个初始化Job来加载这些数据，你需要确认其使用的默认值，并确保UERANSIM的配置与之匹配。

部署UERANSIM：

cd .. helm install my-5g-ran ./ueransim -f ./ueransim/values.yaml --namespace ueransim --create-namespace

再次观察Pod状态，确保gNB和UE的Pod都正常运行。

3.4 验证端到端连接

部署完成后，如何验证整个5G系统工作正常呢？一个完整的信令流程包括：UE注册到网络、建立PDU会话、然后进行数据传输。我们可以通过查看日志和发送测试流量来验证。

查看gNB日志，确认N2接口连接建立：
```
kubectl logs -n ueransim deployment/ueransim-gnb -f
```
你希望看到类似Connection established for AMF [...]或NG Setup procedure is successful的消息。
查看UE日志，确认注册和会话建立：
```
kubectl logs -n ueransim deployment/ueransim-ue -f
```
成功的日志会显示Registration is successful和PDU session establishment is successful，并会打印出分配给UE的IP地址（例如60.60.0.1）。

在UE Pod内进行网络测试：

# 进入UE Pod的shell kubectl exec -n ueransim -it deployment/ueransim-ue -- /bin/bash # 尝试ping SMF配置的IP池网关或一个外部地址（如果UPF配置了NAT和外部路由） ping 60.60.0.254 # 假设这是SMF/UPF分配的网关地址 # 或者尝试curl一个内部测试服务（如果部署了的话）

如果ping通，说明从UE到UPF的用户面数据通道已经建立成功。

4. 深度配置调优与生产环境考量

一键部署让测试变得简单，但要用于更严肃的开发或预生产环境，就需要深入了解和调整配置。towards5gs-helm的价值在于它提供了这个调优的入口。

4.1 网络配置的进阶调整

服务暴露方式：在测试中我们用了ClusterIP或NodePort。在生产中，对于需要被集群外网元（如真实的RAN设备）访问的服务（如AMF的N2接口），可能需要使用LoadBalancer类型，并配合云提供商的负载均衡器，或者使用Ingress控制器（对于HTTP接口如NRF）。
网络策略：使用Kubernetes NetworkPolicy来实施最小权限原则。例如，只允许ueransim命名空间下的Pod访问free5gc命名空间中AMF的N2端口，增强安全性。
多网络接口：在性能要求高的场景，UPF的数据面可能需要独占一个物理网络接口。这可以通过K8s的MultusCNI插件实现，为UPF Pod附加额外的网络接口。

4.2 资源管理与弹性伸缩

5G网元对资源的需求不同。在values.yaml中，你可以为每个组件单独配置资源请求和限制。

# 以AMF为例 amf: resources: requests: memory: "512Mi" cpu: "500m" limits: memory: "1Gi" cpu: "1000m"

对于控制面组件（AMF, SMF），你可以利用Kubernetes HPA（水平Pod自动伸缩）基于CPU/内存或自定义指标（如每秒注册请求数）进行自动扩缩容。这需要部署Metrics Server和可能自定义的适配器。

4.3 持久化与高可用

数据持久化：UDM/UDR中的用户数据、NSSF的切片选择策略等可能需要持久化存储。确保Chart中配置的PVC模板使用的是可靠的StorageClass，如云盘或本地SSD。
```
udr: persistence: enabled: true storageClass: "ssd-sc" size: 10Gi
```
高可用部署：通过设置replicaCount: 2或更多，可以为无状态组件（如AMF、SMF）部署多个副本。同时，需要确保这些组件是无状态的，或者将其状态外部化到数据库（如UDM使用MongoDB/Redis）。对于有状态组件，如数据库，需要考虑使用StatefulSet和集群化方案。

4.4 监控与可观测性

云原生5G的运维离不开监控。你需要为这套系统集成监控栈。

日志收集：部署如Fluentd、Fluent Bit或Filebeat作为DaemonSet，将每个Pod的日志收集到中心化的日志系统（如Elasticsearch）中，方便检索和分析信令流程。
指标暴露与收集：Free5GC和UERANSIM组件可能通过HTTP端点暴露Prometheus格式的指标。你需要在Deployment中配置相应的注解，以便Prometheus Operator自动发现和抓取。
```
# 在values.yaml的组件配置中添加 prometheus: enabled: true port: 8080 # 假设组件指标暴露在8080端口 path: /metrics
```
然后，使用Grafana绘制仪表盘，监控核心网元的关键指标，如注册成功率、会话建立成功率、信令面延迟、用户面吞吐量等。
分布式追踪：对于复杂的端到端问题排查，可以集成Jaeger或Zipkin，在5G信令流程中注入追踪上下文，可视化整个呼叫流程在各个网元中的耗时。

5. 常见问题排查与实战技巧

即使按照指南操作，在部署和运行过程中也难免会遇到问题。下面是一些我实践中遇到的典型问题及解决思路。

5.1 Pod启动失败类问题

问题现象：Pod处于CrashLoopBackOff或Error状态。
排查步骤：
1. 查看Pod日志：kubectl logs -n <namespace> <pod-name>。这是第一手信息。
2. 常见原因1：镜像拉取失败。错误信息包含ErrImagePull或ImagePullBackOff。检查镜像名称和标签是否正确，网络是否通畅，是否需要配置镜像仓库密钥（imagePullSecrets）。
3. 常见原因2：配置错误。日志中可能明确提示“配置文件解析错误”、“找不到NRF地址”、“数据库连接失败”。此时需仔细核对values.yaml中对应组件的配置，特别是连接其他服务的地址、端口和认证信息。一个黄金法则是：确保所有指向其他服务的地址，在Pod内部网络中是可达的。多用<service-name>.<namespace>.svc.cluster.local这种完整的K8s DNS名称。
4. 常见原因3：权限不足。例如UPF需要特权模式来加载gtp内核模块。如果Chart中未配置privileged: true，UPF Pod会启动失败。检查Pod的securityContext配置。

5.2 网络连通性类问题

问题现象：gNB日志显示无法连接AMF，或者UE注册失败。
排查步骤：
1. 从Pod内部进行网络诊断：
```
# 进入gNB Pod kubectl exec -n ueransim -it deployment/ueransim-gnb -- /bin/sh # 尝试解析AMF的Service名 nslookup free5gc-amf.free5gc.svc.cluster.local # 尝试telnet到AMF的N2端口 telnet free5gc-amf.free5gc.svc.cluster.local 38412
```
  如果解析失败，检查CoreDNS服务是否正常。如果连接失败，检查AMF的Service和Deployment配置，确认端口是否正确暴露，以及Pod是否健康（kubectl describe svc -n free5gc free5gc-amf）。
2. 检查防火墙/网络策略：如果是云环境，检查安全组规则。在K8s集群内，检查是否有NetworkPolicy阻断了必要的流量。
3. 验证NRF服务发现：许多组件依赖NRF。确保NRF服务正常运行，并且其他组件（如AMF、SMF）配置的nrfUri是正确的。可以尝试直接访问NRF的HTTP API（curl http://free5gc-nrf.free5gc.svc.cluster.local/nnrf-nfm/v1/nf-instances）查看已注册的网络功能。

5.3 认证与会话建立失败

问题现象：UE日志显示“Authentication Failure”或“PDU Session Establishment Rejected”。
排查步骤：
1. 核对认证参数：这是最高频的错误源。逐字核对UE配置中的imsi、key、op、opType、amf、sqn，与核心网UDM中预置的订阅数据完全一致。注意key和op是十六进制字符串，区分大小写。
2. 检查DNN配置：UE请求的DNN（如internet）必须在SMF的配置列表中，并且相关的UPF配置需要匹配。
3. 查看核心网组件日志：当UE发起注册时，依次查看AMF、AUSF、UDM的日志，看错误具体发生在哪个环节。AMF日志会显示接收到的UE标识；AUSF日志会显示认证流程；UDM日志会显示查询订阅数据的情况。

5.4 性能与资源问题

问题现象：系统运行一段时间后响应变慢，或Pod被重启。
排查步骤：
1. 监控资源使用率：使用kubectl top pods -n <namespace>查看CPU和内存使用情况。如果接近或超过limit，可能导致Pod被OOM Kill或CPU限流。
2. 调整资源配额：根据监控结果，适当调整values.yaml中的resources.requests和resources.limits。
3. 检查外部依赖：如果使用了外部数据库（如MongoDB for UDR），检查数据库的性能和连接数是否成为瓶颈。

5.5 版本兼容性问题

问题：Chart版本、Free5GC镜像版本、UERANSIM镜像版本之间可能存在API或配置不兼容。
建议：始终参考towards5gs-helm项目官方文档或Chart内的README.md，使用其明确测试过的版本组合。在升级任何一个组件时，做好回滚准备。

最后，善用kubectl describe pod和kubectl get events --all-namespaces命令，它们能提供Pod调度、镜像拉取、存储挂载等层面的综合信息，是排查复杂问题的利器。部署云原生5G系统是一个涉及多层面知识的实践，耐心和细致的日志分析是成功的关键。这个项目为我们提供了一个极佳的起点和标准化框架，让开发者能更专注于5G业务逻辑本身，而非基础设施的泥沼。