SimAdmin

SimAdmin - SIM/eSIM 中枢

** 重磅更新：SimAdminHub 多设备集中管理功能现已上线** · 了解详情

SimAdmin 是一套面向 Debian 蜂窝 CPE、随身 WiFi、软路由类设备的 SIM/eSIM、蜂窝网络、短信、DDNS 和系统状态管理系统。

当前项目由 Rust 后端和 React 前端组成：

• 后端：Rust + Axum + zbus，主要通过 ModemManager D-Bus 接口管理 modem，并在部分场景使用 mmcli、qmicli 或 AT 直连兜底。
• 前端：React + Vite + Material UI，提供仪表盘、SIM 卡管理、蜂窝网络、设备网络、短信管理、通知中心、自动化中心和 OTA 更新页面。
• 部署形态：后端二进制同进程托管前端 SPA，默认安装到 /opt/simadmin，通过 systemd 运行。
• 发布架构：提供 aarch64-unknown-linux-musl、armv7-unknown-linux-musleabihf 与 x86_64-unknown-linux-musl 三种静态构建，安装脚本会按设备架构选择。ARMv7 MVP 暂不包含 lpac/eSIM。

健康检查整体按支持 ModemManager 的 Linux 蜂窝设备组织，不同 modem 固件、内核、ModemManager 版本暴露的能力不同，具体功能以实际设备为准。

文档导航

• 安装与部署指南：设备一键安装/卸载、后台默认访问地址及首次管理员密码设置。
• 版本更新记录：历史版本详细的更新说明日志。
• ⚙️ 运行环境与系统管理：目标设备硬件与依赖指令要求、默认安装路径、eSIM 管理机制、systemd 服务维护及数据持久化。
• ️ 开发者指南：项目工程结构、前端与后端开发编译、OTA 构建、ADB 部署调试及 D-Bus 接口说明。
• REST API 接口文档：详细的 REST API 路由映射表、请求/响应报文规约与 Bruno API 调试集合。

社区交流

⚠️ 温馨提示：群聊仅限日常讨论、技术交流及经验分享，问题反馈、新需求请提交 Issues。

  QQ 群
  TG 群组

界面预览

仪表盘

SIM 卡

eSIM 管理

蜂窝网络

WLAN

短信

通知中心 - 通知渠道

通知中心 - 通知规则

通知中心 - 设备状态规则

通知中心 - 通知日志

自动化中心

基本配置

安全设置

数据备份

数据恢复

资料库与快照

OTA 更新

仪表盘 - 深色模式

核心功能

Web 管理页面

后端能力

• 单管理员密码登录，支持首次设置、会话 Cookie、受保护 API 拦截和 SSH 本机恢复。
• 设备信息、SIM 信息、网络注册信息读取。
• 数据连接开关和漫游策略持久化。
• 飞行模式控制。
• 数据备份与恢复：支持系统配置、短信、通知等 10 类组件打包归档、校验导入、定期清理、自动备份调度及导入前快照一键回滚。
• 基带重启流程和进度查询。
• 数据连接 watchdog，每 15 秒检查连接状态、iptables 规则数量和 modem 可用性；检测到宿主机防火墙规则时仅记录诊断日志，不自动清空规则。
• ModemManager 丢失时触发 mmcli --scan-modems，连续失败后重启 ModemManager。
• 安装时补齐并启动 ModemManager / NetworkManager，清理历史 wwan* unmanaged 配置，并重新触发 udev modem 候选识别。
• 设备侧 WLAN 客户端连接管理，通过 NetworkManager/nmcli 扫描和连接无线局域网，WLAN 在线时优先作为设备默认出口。
• 原生 DDNS 同步，支持腾讯云 DNSPod、阿里云 AliDNS 和 Cloudflare，支持 IPv4/IPv6 独立配置、API/网卡取 IP 和变更/失败事件通知；默认通过网卡取 IP，可切换为内置多接口 API fallback。
• 短信发送、接收监听、SQLite 持久化和多渠道通知转发。
• 自动化中心双轨任务调度引擎：支持在后台并行执行自动化任务，提供定点定时（周几 + 具体时间，如每周二 03:00）和间隔周期（按分钟/小时/天，如每 180 天）调度模式。
• 多种自动化动作支持：支持重启基带、安全重启系统（支持延时）和发送短信（支持随机延迟、自动生成随机字符防止拦截、发送失败自动重试）。
• 自动化事件通知与运行日志管理：任务执行后写入本地 SQLite 日志表（支持关键词检索、日期筛选、手动/自动清理策略），并可将执行结果（成功/失败）作为事件实时推送至通知通道。
• APN 列表读取和 APN 修改。
• 运营商列表、扫描、手动注册、自动注册。
• eSIM 模式下按需调用 lpac 管理实体 eUICC SIM 卡 Profiles；普通 SIM 模式下不调用 eSIM 能力。
• 安装脚本按设备架构自动准备带 QMI APDU 后端的私有 lpac，并校验 qmi / curl 驱动能力；OTA 包本身不绑定 lpac 架构或版本。ARMv7 MVP 暂不安装或调用 lpac，并在前端隐藏工作模式与 eSIM 管理入口。
• ARMv7 MVP 以 QMI 为已验证 modem 路径；MBIM 和短信能力不在首个候选版本的声明范围内。
• OTA 上传、在线下载、校验、替换二进制和前端资源。

免责声明

本项目会直接操作蜂窝 modem、SIM 注册、数据拨号、APN、频段、飞行模式、NetworkManager、systemd 服务、系统重启和 OTA 文件替换；iptables/ip6tables 仅用于只读网络诊断，不会自动清空宿主机防火墙规则。

请仅在你拥有控制权的设备上使用。错误配置可能导致断网、无法注册网络、SIM 漫游计费、设备需要手动恢复，甚至 OTA 后服务无法启动。任何使用本项目造成的后果由使用者自行承担。

部分接口受硬件和 ModemManager 能力限制：

• 频段锁定依赖 ModemManager 暴露的 SupportedBands / CurrentBands / SetCurrentBands。
• 小区锁定当前为后端内存态展示，不会下发真实硬件锁小区命令。

开源协议声明

本项目采用 GNU General Public License v3.0 (GPLv3) 开源协议。

你可以：

• 自由使用、研究、修改本软件。
• 分发本软件副本。
• 分发修改后的版本。

但你必须：

1. 保留版权声明和许可证声明。
2. 分发本软件或修改版本时，以 GPLv3 协议公开完整源代码。
3. 基于本项目的衍生作品继续使用 GPLv3 协议。
4. 明确标注修改内容和修改日期。
5. 分发时附带完整 GPLv3 许可证文本。

严禁将本项目或其衍生版本闭源后作为专有软件分发。

️ 鸣谢

贡献者

感谢大家为 SimAdmin 项目的关注和贡献！如果你也希望为 SimAdmin 做出贡献，请查阅 贡献指南。

代码贡献者

特别贡献者

参考项目

• project-cpe
• SmsForwarder
• ddns-go
• lpac