企业官网建设流程全解析

MDD Sim Gateway eSIM 管理实战：lpac 与 eUICC 配置文件切换完整教程

MDD Sim Gateway 是一个自托管的 SIM/eSIM 网关，可以把物理 SIM 和 eSIM 变成自己可控的 VoWiFi 通话、短信与数据通道。本文聚焦其中的eSIM 管理功能：如何安装 lpac 工具读取 eUICC 芯片、下载新的 eSIM 配置文件，以及一键切换 eUICC Profile 而不中断服务。全程只需浏览器操作，无需手动敲 APDU 命令。

为什么需要 lpac 管理 eUICC？

普通手机里"添加 eSIM"点几下就完成，但背后其实跑着一整套 GSMA 标准流程：向 SM-DP+ 服务器请求、双向认证、下载 Profile 包、安装到 eUICC 安全元件。MDD Sim Gateway 用 lpac 这套 LPA（Local Profile Assistant）工具完成了同样的事，好处是：

• 不依赖手机：把 eSIM 插进 USB 读卡器（或蜂窝模块的虚拟卡槽），网关替你完成整个流程；
• 不碰密钥：鉴权全部在卡内完成，网关不读取、不保存任何运营商密钥；
• 支持双安全元件：对 ESTKme Max / Plus+ 这类双 SE 卡（control/app/estkme.py），可以显式选择把 Profile 装到 SE1 还是 SE2。

准备工作：装好 lpac 并插入 eUICC

1. 获取网关

git clone https://gitcode.com/gh_mirrors/md/mdd-sim-gateway cd mdd-sim-gateway sudo ./install.sh install

安装完成后访问https://<网关地址>:8443（全容器部署为https://<主机地址>:10443）。

2. 构建 lpac 二进制

eSIM 功能依赖本地的 lpac 二进制，首次使用需要执行：

sudo ./install.sh build-lpac

该命令会下载 lpac 源码、打上仓库自带的 patches/lpac/ 兼容性补丁（修复上游 PC/SC 读卡器选择问题），然后编译到数据目录。之后在 Web 界面的 eSIM 页面，"Chip" 卡片会提示 lpac 是否可用——如果显示 "lpac is not installed"，说明这一步漏了。

3. 插入 eUICC 卡

把 eUICC 卡插进USB PC/SC 读卡器，或放进支持虚拟卡槽的蜂窝模块。在"设备"页确认读卡器已被识别：

第一步：读取 eUICC 芯片信息

进入左侧菜单的eSIM页（源码：webui/src/views/Esim.jsx），按下面顺序操作：

1. 在顶部Reader下拉框选择插入 eUICC 的读卡器；
2. 点击Load按钮，网关会通过 lpac 读取芯片信息；
3. 读取成功后，"Chip" 卡片会显示EID（eUICC 唯一标识）、Default SM-DP+地址、Free NVM剩余存储空间和用于下载的 IMEI。

⚠️ 注意：lpac 需要独占访问读卡器。如果这张卡上有一条 VoWiFi 线路正在运行，点击 Load 前界面会先提示"停止线路再读取"。这是正常的保护机制。

读取结果会被缓存到网关的esim-chip-cache.json，之后打开 eSIM 页会直接显示上次的 Profile 列表，不必每次切换都停线路重新读卡。

第二步：下载新的 eSIM 配置文件

在 eSIM 页点击Download eSIM按钮，弹窗支持两种方式：

如果是双 SE 卡，弹窗顶部会让你先选装到哪个 eUICC（SE），并显示每个 SE 的剩余空间。IMEI 字段会预填当前读卡器对应线路的 IMEI，一般保持默认即可。

点击Download后，界面会用 9 步进度条实时展示下载流水线：读取 SM-DP+ 地址 → 获取挑战码 → 双向认证 → Profile 预览 → 下载安装（对应 webui/src/views/Esim.jsx 中的步骤定义）。下载走 WebSocket 推送进度（control/app/main.py），中途可以点Cancel取消。

核心操作：一键切换 eUICC 配置文件

这是整个 eSIM 管理里最实用的功能。Profile 列表里每条配置显示Enabled / Disabled状态徽标，操作按钮：

• Enable（启用）：把该 Profile 切换为活动状态；
• Disable（停用）：停用当前活动 Profile；
• Rename（重命名）：给 Profile 起个昵称，方便区分运营商；
• Delete（删除）：从 eUICC 中永久移除。

切换时的自动化流程

以蜂窝模块上的 eSIM 为例，点击Enable后，后端会按 main.py 中的api_esim_enable逻辑执行：

1. 如果该读卡器上有线路正在运行，界面会提示"停止线路后继续"，确认后先停线路；
2. lpac 向 eUICC 发送启用指令（GSMA SGP.22 流程），同时自动处理 SGP.22 通知；
3. 模块的虚拟卡槽需要短暂重启以刷新新 ICCID（main.py 中的恢复逻辑）；
4. 新 Profile 对应的线路自动重新拉起，VoWiFi 恢复工作。

整个"停线 → 切卡 → 起线"过程是编排好的，你只需要点一个按钮。如果切换成功但线路恢复异常，界面会明确提示"已切换，但线路未能自动启动"，而不是让你误以为没生效。

💡 小贴士：给 Profile 起昵称（Rename）后，列表优先显示昵称。多运营商卡强烈建议先命名再切换。

通知（Notifications）处理

eUICC 里可能有运营商下发的待处理通知（如远程下发的 Profile 变更）。eSIM 页底部Notifications卡片列出所有待处理项，可以逐条Send处理，或点Process all一键全部处理。每次 Profile 变更后网关也会自动执行一次通知处理（auto_process_notifications，可在设置中关闭）。

常见问题排查

完整问题排查见 docs/TROUBLESHOOTING.md。

小结

MDD Sim Gateway 把 eSIM 管理中繁琐的 LPAC 操作收敛到了浏览器里三个动作：Load 读卡、Download 下载 Profile、Enable 一键切换。配合 lpac 的 9 步可视化下载进度和双 SE 支持，普通用户也能安全地管理 eUICC 上的多运营商配置文件，而不需要任何命令行基础。相关代码集中在 control/app/lpa.py（lpac 封装）、control/app/main.py（eSIM API）和 webui/src/views/Esim.jsx（界面），想深入了解 SGP.22 细节的可以顺着这几处源码读起。