OpenWISP 介绍与选型指南
OpenWISP 定位、模块构成、许可与版本节奏，并与 Ubiquiti UISP、MikroTik CAPsMAN、LibreNMS、NetBox 做量化选型对比，数据取自 2026-10-28 官方站点与代码仓库。
OpenWISP 介绍与选型指南
目标：在正式部署前弄清 OpenWISP 的定位、模块构成、许可与版本节奏，并把它与 Ubiquiti UISP、MikroTik CAPsMAN、LibreNMS、NetBox 放在同一张量化表里比较，给出可执行的选型结论。本文为联网溯源篇，全部数据来自官方站点与代码仓库，查询日期 2026-10-28，不含本地安装实测；部署与命令细节分别见 《OpenWISP 1.3.2 Ubuntu 22.04 安装指南》 与 《OpenWISP 1.3.2 常用 CLI 与运维命令详解》。
一、环境信息
本文是认知与选型文档，不产生本机安装结果，环境信息记录的是取证环境与数据口径：
- 操作系统：Ubuntu 22.04.5 LTS（取证终端，仅用于访问官方站点与仓库）
- 查询日期：2026-10-28（所有版本号、星数、发版日期均以该日快照为准）
- 版本数据源：PyPI JSON API
https://pypi.org/pypi/openwisp-controller/json、GitHub Releases Atomhttps://github.com/openwisp/openwisp-controller/releases.atom - 星数数据源：shields.io 徽章
https://img.shields.io/github/stars/openwisp/openwisp-controller（避免直连 GitHub API 触发限流） - 许可数据源：仓库内
LICENSE文件原文、PyPI 分类器（License :: OSI Approved :: GNU General Public License v3 (GPLv3)） - 文档数据源：官方文档站
https://openwisp.io/docs/stable/（站点标题显示 OpenWISP 26.09 documentation） - 对比对象数据源：LibreNMS/NetBox 各自 Releases Atom 与 LICENSE、MikroTik RouterOS 手册、Ubiquiti UISP 官网
- 版本口径：PyPI 上
openwisp-controller的最新稳定版为 1.3.2，发布时间 2026-10-23T21:56:02（UTC）
💡 说明：OpenWISP 是“套件名”，
openwisp-controller只是其中负责设备与配置管理的核心模块。套件文档站采用 26.09 这类年月版本号，而各 Python 包仍用 1.x 语义化版本，两者不是同一套编号，选购与升级时不要混淆。
二、软件概述
OpenWISP 是一套面向网络运维团队的开源网络管理平台，核心能力是把大量 OpenWrt 设备纳入统一台账，用模板批量生成配置并下发，同时提供设备地图、拓扑、监控、RADIUS 认证、固件升级等周边模块。它由意大利 OpenWISP 团队发起，代码托管在 GitHub 组织 openwisp 下，采用 GPLv3 许可。
关键身份信息（2026-10-28 实查）：
| 维度 | 取值 | 取证位置 |
|---|---|---|
| PyPI 包名 | openwisp-controller | pypi.org/pypi/openwisp-controller/json |
| 最新稳定版 | 1.3.2（2026-10-23） | PyPI info.version、Releases Atom |
| 上一版本 | 1.3.1（2026-10-15）、1.3.0（2026-09-03） | Releases Atom |
| 许可 | GNU GPL v3 | 仓库 LICENSE 第 5–6 行 “GNU GENERAL PUBLIC LICENSE Version 3” |
| 开发状态 | Production/Stable | PyPI 分类器 Development Status :: 5 - Production/Stable |
| 技术栈 | Python + Django，PostgreSQL/PostGIS、Redis、Celery、Channels | PyPI 依赖清单、官方文档 Settings |
| GitHub 星数 | 792 | shields.io github/stars 徽章 |
| 套件文档版本 | 26.09（/docs/stable/ 当前指向） | openwisp.io 文档站页脚标题 |
| 运行依赖下限 | Python ≥ 3.10（官方开发文档 Dependencies 节） | openwisp.io/docs/stable/controller/developer/installation.html |
发版节奏方面，Releases Atom 显示的近一年节奏为：1.2.0（2025-10-24）→ 1.2.1（2026-03-04）→ 1.2.2（2026-03-06）→ 1.2.3（2026-04-09）→ 1.3.0（2026-09-03）→ 1.3.1（2026-10-15）→ 1.3.2（2026-10-23）。可见它不是固定月更，而是“小步快跑 + 季度级次版本”的混合节奏：1.3.0 之后两周内连续两次补丁，说明维护者对回归问题响应较快。
💡 技术拓展：网络管理类开源项目常见三种治理形态——单一大版本长期维护（如 NetBox 的 4.x 系列）、年月滚动发布（如 LibreNMS 26.10）、模块化多包独立发版（OpenWISP）。前者升级路径清晰但新特性慢，中者节奏稳定但需频繁跟进，后者模块可裁剪但版本矩阵复杂。OpenWISP 属于第三种，选型时要同时锁定
openwisp-controller与openwisp-utils、openwisp-users等配套包的版本。
三、核心架构
OpenWISP 不是单体应用，而是“一个 Django 核心 + 一组可选模块 + 一类设备侧代理”的组合。官方文档侧栏把模块划分为 Users、Controller、Monitoring、Network Topology、Firmware Upgrader、RADIUS、WiFi Login Pages、IPAM、Notifications、Utils 与 OpenWrt Agents。
服务端数据流可以概括为四步：
- 纳管：设备在 Controller 中登记，记录名称、MAC、组织、位置、连接凭据（SSH 或 SNMP）。
- 建模：用 netjsonconfig 的 NetJSON 结构描述设备配置，模板（Template）通过变量（Context）复用到多台设备。
- 渲染与下发：Celery 后台任务把模板渲染成设备可识别的 UCI 配置，通过 SSH 推送并触发设备重载。
- 回流：设备上报配置状态、最后 IP、监控指标，进入仪表盘、地图与拓扑视图。
组件职责与依赖关系如下表，选型时应按“必需 / 增强”两档裁剪：
| 组件 | 角色 | 必需性 | 关键依赖 |
|---|---|---|---|
| openwisp-controller | 设备台账、配置模板、批量下发、VPN 服务端管理 | 必需 | PostgreSQL/PostGIS、Redis、Celery |
| openwisp-users | 多组织（Organization）与角色权限 | 必需 | Django auth、allauth |
| openwisp-utils | 后台主题、菜单、REST API 基础设施 | 必需 | Django REST Framework |
| openwisp-notifications | 站内与邮件通知 | 推荐 | WebSocket（Channels） |
| openwisp-ipam | 子网与 IP 地址分配 | 可选 | PostGIS |
| openwisp-radius | 热点与 WPA-Enterprise 认证、流量记账 | 可选 | FreeRADIUS、Redis |
| openwisp-monitoring | 指标采集与图表 | 可选 | 时序数据源、SNMP |
| openwisp-network-topology | 链路拓扑可视化 | 可选 | 拓扑数据采集 |
| openwisp-firmware-upgrader | 固件批量升级 | 可选 | 设备侧代理 |
| OpenWrt 代理 | 设备侧上报与执行 | 视场景 | OpenWrt 固件 |
💡 技术拓展：设备配置下发有三类主流实现——SSH 直连执行（OpenWISP 默认，兼容广、需设备开放 SSH）、厂商私有控制器协议（UISP、CAPsMAN，体验好但绑定单一厂商）、声明式代理拉取（设备侧定时向服务端取配置，适合 NAT 后设备）。OpenWISP 同时支持 SSH 直连与 OpenWrt 代理上报，本文所述方案采用其默认 SSH 连接器。
四、功能特性
按官方模块划分，逐项说明能力边界与实际价值：
- 设备与配置管理：设备分组、标签、组织隔离；配置模板支持变量与条件片段；变更记录基于 django-reversion，可回滚。
- 批量推送与状态回执：配置变更后由 Celery 异步推送，设备返回成功/失败状态，失败可重试；官方文档 “Device Configuration Status” 一节描述了状态机。
- VPN 服务端编排：内置 OpenVPN、WireGuard、VXLAN over WireGuard、ZeroTier 四种后端（
OPENWISP_CONTROLLER_VPN_BACKENDS默认值），可为设备自动签发客户端配置。 - 证书与 PKI：基于 django-x509 管理 CA 与证书，用于 VPN 与设备身份。
- 地理视图：基于 GeoDjango/PostGIS 与 Leaflet，设备可标注位置、楼层平面图，支持按组织划分地理设置。
- IPAM：子网划分、IP 分配与子网分片规则（subnet division），适合大规模地址规划。
- RADIUS 与热点：独立模块 openwisp-radius 提供 REST API，供 FreeRADIUS 的
rlm_rest调用，实现用户认证、记账、CoA 与验证码登录页。 - 监控与拓扑：openwisp-monitoring 采集指标并绘图，openwisp-network-topology 展示链路关系，二者均为可选增强。
- REST/WebSocket API：基于 DRF 的
/api/v1/接口与 Channels 提供的 WebSocket 通知，便于与自有系统集成。 - 多组织隔离：同一套平台可服务多个客户或部门，权限按组织边界收敛。
功能强项集中在“OpenWrt 设备 + 配置模板 + 批量下发 + 认证计费”这条主线上；对非 OpenWrt 设备，Controller 主要通过 SSH/SNMP 连接器执行有限命令，不能像对待 OpenWrt 那样做全量配置渲染。
五、快速开始
OpenWISP 官方现在主推三条落地路径，均收录于文档站 installers.html：Ansible 安装器、基于 Kubernetes 的部署路径、以及面向开发者的手工安装。下面给出各路径的官方入口与“跑通判据”，命令取自官方文档原文，本文未在本机执行（A1 篇只做溯源）。
路径一：Ansible 安装器（官方推荐的生产路径）
官方文档 “Ansible OpenWISP” 章节给出系统要求、角色变量与启用模块的步骤，典型流程为：
git clone https://github.com/openwisp/openwisp-ansible.git
cd openwisp-ansible
ansible-playbook playbooks/openwisp.yml
判据：Playbook 执行结束后，浏览器能打开 https://<域名>/admin/ 并出现 OpenWISP 登录页。Ansible 角色会一并部署数据库、缓存、应用服务器与反向代理，适合“一次装好、长期运维”的团队。
路径二：Kubernetes 部署
官方文档站提供 Kubernetes 形态的部署说明（installers 目录下），适合已有集群、希望用声明式方式管理实例的环境。判据与手工安装一致：/admin/ 可登录、后台能创建组织与设备。该路径需要自行准备 PostgreSQL/PostGIS 与 Redis 的可用端点。
路径三：手工 pip 安装（可控性最高）
官方开发文档给出的最小命令序列为 pip install openwisp-controller，随后在 Django 项目中加入应用、配置数据库并执行迁移。判据是 manage.py check 输出 System check identified no issues (0 silenced).。这条路径的完整实测（含 PostGIS、Redis、uWSGI、Nginx、systemd）见 《OpenWISP 1.3.2 Ubuntu 22.04 安装指南》，其中每个命令都附有真实回显。
三条路径的差异不在功能，而在“谁替你维护配置”：
| 路径 | 适合团队 | 可控性 | 升级成本 |
|---|---|---|---|
| Ansible 安装器 | 有 Ansible 经验、追求标准化 | 中（角色变量可覆盖） | 低（重跑 Playbook） |
| Kubernetes | 已有集群、平台工程团队 | 高 | 中（需维护清单与存储） |
| 手工 pip | 需要深度定制 settings、无自动化工具 | 最高 | 高（逐项维护） |
六、适用场景与限制
适用场景（按优先级）
- WISP/园区多站点 OpenWrt 网络：几十到上千台 OpenWrt 设备需要统一 SSID、防火墙、VPN 策略，OpenWISP 的模板 + 变量 + 批量推送正好覆盖。
- 需要认证与计费的公共无线：RADIUS 模块 + 登录页 + 会话限制，适合酒店、校园、社区网络。
- 混合厂商但以 OpenWrt 为主的网络：通过 SSH/SNMP 连接器纳入非 OpenWrt 设备做监控与命令执行，配置管理仍以 OpenWrt 为主。
- 需要地理可视化与资产台账：PostGIS + Leaflet 的地图视图、IPAM 的地址规划，适合跨区域运维。
限制与代价
- 生态绑定明显：配置渲染依赖 netjsonconfig 的 OpenWrt/OpenWISP 后端，Cisco IOS、华为 VRP 等闭源系统无法获得同等配置管理能力。
- 运维门槛是 Django：需要理解 settings.py、迁移、Celery、WSGI 服务器与反向代理，纯网络工程师上手需要时间。
- 高可用需自建：平台本身不提供集群编排，数据库与 Redis 的高可用要按各自产品方案另行设计。
- 地理编码依赖外网：地址转坐标调用外部地理编码服务，隔离网络中会退化为按经纬度手工标注（安装篇实测记录了这一告警）。
- 商业支持付费：社区支持通过邮件列表与 Issue 进行，SLA 级支持需购买官方商业支持。
七、同类选型对比
把 OpenWISP 与四个常被拿来比较的产品放在同一口径下（版本与许可均为 2026-10-28 实查）：
| 维度 | OpenWISP 1.3.2 | Ubiquiti UISP | MikroTik CAPsMAN | LibreNMS 26.10.2 | NetBox 4.7.4 |
|---|---|---|---|---|---|
| 许可 | GPLv3 | 专有免费（闭源） | RouterOS 专有（随设备授权） | GPLv3 | Apache-2.0 |
| 最新版本/日期 | 1.3.2 / 2026-10-23 | 官网未公开版本号，滚动更新 | 随 RouterOS v7 发布 | 26.10.2 / 2026-10-21 | 4.7.4 / 2026-10-27 |
| 发版节奏 | 季度级次版本 + 两周内补丁 | 平台滚动 | 跟随 RouterOS | 月度（26.10.0 于 2026-10-19） | 约双周 |
| GitHub 星数 | 792 | 不开源 | 不开源 | 约 5k | 未在徽章取值 |
| 设备配置下发 | 模板渲染 + SSH/代理推送 | 厂商设备统一配置 | 仅 MikroTik AP | 不做配置下发 | 不做配置下发 |
| 无线控制器 | 通过 OpenWrt 配置模板 | 内置（UniFi/UISP 设备） | 内置（CAPsMAN） | 无 | 无 |
| 多厂商支持 | OpenWrt 深度 + SSH/SNMP 广度 | 仅 Ubiquiti | 仅 MikroTik | 广（SNMP 为主） | 广（建模为主） |
| RADIUS/计费 | 独立模块 + FreeRADIUS | 内置 | 支持（RouterOS 侧） | 无 | 无 |
| 地理地图 | 内置（PostGIS + Leaflet） | 内置 | 无 | 有地图插件 | 无原生地图 |
| REST API | 有（DRF） | 有 | RouterOS API | 有 | 有（成熟） |
| 部署形态 | Ansible / Kubernetes / 手工 | 厂商安装包 | 路由器内置 | 手工/自动化脚本 | 手工/Kubernetes |
| 典型规模 | 数十至数千台 OpenWrt | 中小型 WISP | 单站点至多站点 MikroTik | 数百至数万台 | 资产规模不限 |
表格解读与选型建议：
- 要“管配置”而不只是“看状态”：只有 OpenWISP 与两个厂商控制器能下发配置。UISP 与 CAPsMAN 体验更顺滑，但只在自家设备上成立；OpenWISP 的代价是要自己维护模板与连接凭据。
- 要“多厂商监控台账”：LibreNMS 胜在协议覆盖与告警成熟，NetBox 胜在资产建模与 IPAM/DCIM 的规范性；两者都不做配置下发。
- 要“认证计费 + 热点”：OpenWISP 的 RADIUS 模块是开源方案里少见的完整实现；UISP 内置但绑定生态。
- 要“最低运维成本”：如果全网都是 Ubiquiti 或 MikroTik，直接用厂商控制器更省人力；混合厂商且以 OpenWrt 为主时，OpenWISP 的通用性才体现价值。
“如果…则…”速查：
- 如果网络里 OpenWrt 占比超过一半，且需要批量改 SSID/防火墙/VPN → 选 OpenWISP。
- 如果全部是 UniFi/UISP 设备，且团队没有 Django 运维能力 → 选 UISP。
- 如果只要无线集中管理、设备全是 MikroTik → 选 CAPsMAN。
- 如果只需要 SNMP 监控与告警，不需要改配置 → 选 LibreNMS。
- 如果核心诉求是资产台账、IPAM、机房与链路建模 → 选 NetBox。
- 如果既要资产建模又要配置下发 → OpenWISP + NetBox 组合，用 NetBox 做“真相源”，OpenWISP 做执行面。
八、常见问题与排障
Q1：OpenWISP 和 OpenWrt 是什么关系？
OpenWrt 是设备侧固件，OpenWISP 是服务端管理平台。二者通过 SSH 连接器与 OpenWrt 代理协作；OpenWISP 也支持 OpenWISP 1.x 固件后端（netjsonconfig.OpenWisp），但新部署一般选 OpenWrt 后端。
Q2：为什么文档站版本是 26.09，而 PyPI 是 1.3.2？
文档站按套件年月归档，/docs/stable/ 当前指向 26.09；PyPI 上各模块独立语义化版本。升级时应以 PyPI 包版本为准，文档站用于查配置项与操作流程。
Q3：安装时 geocode.arcgis.com 报 Network is unreachable 正常吗？
这是地址地理编码检查在隔离网络中无法访问外部服务导致的告警，不影响平台启动与登录，只影响“按地址自动定位”。安装篇实测中该告警会在 manage.py check --deploy 阶段出现，处理方式是在设备里手工填经纬度，或为服务器放通该域名。
Q4：SpatiaLite 与 PostGIS 怎么选？
官方开发文档默认用 SpatiaLite（便于单机跑测试），生产环境推荐 PostgreSQL + PostGIS。若沿用 SpatiaLite 又缺少系统库，会报 Unable to load the SpatiaLite library extension，需设置 SPATIALITE_LIBRARY_PATH。本文后续安装篇采用 PostGIS。
Q5：能否只装 Controller 不装 RADIUS/监控？
可以。Controller、Users、Utils、Notifications 构成最小可用集；RADIUS、监控、拓扑、固件升级都是独立 Python 包，按需加入 INSTALLED_APPS 与依赖服务即可。
九、参考链接
- OpenWISP 官网：
https://openwisp.org/ - 官方文档站（26.09）：
https://openwisp.io/docs/stable/ - 安装器总览：
https://openwisp.io/docs/stable/installers.html - Controller 开发安装与依赖：
https://openwisp.io/docs/stable/controller/developer/installation.html - Controller 配置项：
https://openwisp.io/docs/stable/controller/user/settings.html - RADIUS 配置项：
https://openwisp.io/docs/stable/radius/user/settings.html - PyPI 包页：
https://pypi.org/project/openwisp-controller/ - GitHub 仓库与 Releases：
https://github.com/openwisp/openwisp-controller/releases - LibreNMS Releases：
https://github.com/librenms/librenms/releases - NetBox Releases：
https://github.com/netbox-community/netbox/releases - MikroTik CAPsMAN 手册：
https://manual.mikrotik.com/docs/wireless/wifi/capsman/ - Ubiquiti UISP：
https://uisp.ui.com/
站内延伸阅读：《OpenWISP 1.3.2 Ubuntu 22.04 安装指南》、《OpenWISP 1.3.2 配置参数详解》、《OpenWISP 1.3.2 常用 CLI 与运维命令详解》。