openwisp-network-topology 1.0

在生产环境中部署

OpenWISP项目提供了自动化安装程序：OpenWISP项目：ansible-openwisp2。

请确保遵循以下章节中解释的说明：启用网络拓扑模块。

从pypi安装稳定版本

从pypi安装

pip install openwisp-network-topology

安装开发版本

安装tar包

pip install https://github.com/openwisp/openwisp-network-topology/tarball/master

或者您可以使用pip通过git安装

pip install -e git+git://github.com/openwisp/openwisp-network-topology#egg=openwisp-network-topology

如果您想贡献，请安装您克隆的分叉

git clone git@github.com:<your_fork>/openwisp-network-topology.git
cd openwisp-network-topology
python setup.py develop

开发安装

安装sqlite

sudo apt-get install sqlite3 libsqlite3-dev

安装您的分叉库

git clone git://github.com/<your_fork>/openwisp-network-topology
cd openwisp-network-topology/
python setup.py develop

安装测试需求

pip install -r requirements-test.txt

创建数据库

cd tests/
./manage.py migrate
./manage.py createsuperuser

您可以在http://127.0.0.1:8000/admin/访问管理界面。

使用以下命令运行测试

./runtests.py

运行qa测试

./run-qa-checks

设置（集成到现有的Django项目中）

将openwisp_network_topology及其依赖项添加到INSTALLED_APPS

INSTALLED_APPS = [
    # other apps
    'openwisp_network_topology',
    'openwisp_users.accounts',
    'allauth',
    'allauth.account',
    'openwisp_users',
    'rest_framework',
]

将URL添加到您的main urls.py

from django.contrib import admin

urlpatterns = [
    # ... other urls in your project ...
    path('', include('openwisp_network_topology.urls')),
    path('admin/', admin.site.urls),
]

然后运行

./manage.py migrate

创建拓扑

1. 通过转到“网络拓扑”>“拓扑”>“添加拓扑”来创建拓扑对象。

2. 为拓扑提供一个合适的标签。

3. 从下拉菜单中选择拓扑格式。拓扑格式决定了用于处理拓扑数据的解析器。

4. 选择更新此拓扑的策略。

   • 如果您正在使用FETCH策略，则在Url字段中输入获取拓扑数据的URL。

   • 如果您正在使用RECEIVE策略，您将获得发送拓扑数据的URL。RECEIVE策略提供了一个额外的字段过期时间。这可以用于在标记缺失链接为下线时添加延迟。

使用RECEIVE策略发送拓扑数据

1. 复制OpenWISP生成的用于发送拓扑数据的URL。

   例如，在我们的情况下，URL是http://127.0.0.1:8000/api/v1/network-topology/topology/d17e539a-1793-4be2-80a4-c305eca64fd8/receive/?key=cMGsvio8q0L0BGLd5twiFHQOqIEKI423。

2. 创建一个脚本来发送拓扑数据（例如：/opt/send-topology.sh），使用POST方法。以下示例脚本发送OpenVPN的状态日志数据，但相同的代码可以通过替换cat /var/log/openvpn/tun0.stats为返回网络拓扑输出的实际命令，应用到其他格式。

#!/bin/bash

# Get OpenVPN topology data from OpenVPN management interface
cat /var/log/openvpn/tun0.stats |
    # Upload the topology data to OpenWISP
    curl -s -X POST \
        --data-binary @- \
        --header "Content-Type: text/plain" \
        http://127.0.0.1:8000/api/v1/network-topology/topology/d17e539a-1793-4be2-80a4-c305eca64fd8/receive/?key=cMGsvio8q0L0BGLd5twiFHQOqIEKI423

3. 将上一步创建的/opt/send-topology.sh脚本添加到crontab中，以下示例每5分钟发送一次拓扑数据。

# flag script as executable
chmod +x /opt/send-topology.sh
# open crontab
crontab -e

## Add the following line and save

echo */5 * * * * /opt/send-topology.sh

4. 完成上述步骤后，您应该会看到节点和链接自动创建，您可以从拓扑更改页面的管理员页面查看网络拓扑图（您需要在页面的右上角点击“查看拓扑图”按钮），或者，也可以在URL /topology/topology/<TOPOLOGY-UUID>/找到非管理员可视化页面。

update_topology

在管理员中添加拓扑URL（暴露网络拓扑的文件）后，可以使用update_topology管理命令收集数据并开始对网络图进行操作。

./manage.py update_topology

管理命令接受一个--label参数，将用于在拓扑标签中搜索，例如。

./manage.py update_topology --label mytopology

save_snapshot

可以使用save_snapshot管理命令保存拓扑图数据，这可以在将来某个时间点用于查看网络拓扑图。

./manage.py save_snapshot

管理命令接受一个--label参数，将用于在拓扑标签中搜索，例如。

./manage.py save_snapshot --label mytopology

upgrade_from_django_netjsongraph

如果您是从django-netjsongraph升级到openwisp-network-topology，有一个简单的迁移脚本可以将您的拓扑、用户和组导入到openwisp-network-topology实例中。

./manage.py upgrade_from_django_netjsongraph

管理命令接受一个--backup参数，您可以将备份文件的位置传递给它，默认情况下它会在tests/目录下查找，例如。

./manage.py upgrade_from_django_netjsongraph --backup /home/user/django_netjsongraph/

管理命令接受另一个参数--organization，如果您想将数据导入到特定的组织中，您可以提供其UUID，默认情况下数据将添加到找到的第一个组织，例如。

./manage.py upgrade_from_django_netjsongraph --organization 900856da-c89a-412d-8fee-45a9c763ca0b

注意：您可以按照教程迁移数据库从django-netjsongraph。

create_device_nodes

此管理命令可以用于在已启用与OpenWISP Controller集成的现有系统中创建初始DeviceNode关系，其中数据库中已存在一些设备和拓扑对象。

./manage.py create_device_nodes

FETCH策略

拓扑数据将从URL获取。

当某些链路不再检测到时，它们将立即标记为“down”。

RECEIVE策略

拓扑数据直接从网络的一个或多个节点发送。

收集器等待接收POST HTTP请求的有效负载中的数据；当收到此类请求时，它首先将请求的key参数与Topology的key进行比较。

如果请求被授权，收集器将继续更新拓扑。

如果数据只从一个节点发送，强烈建议将Topology实例的expiration_time设置为0（秒），这样系统的工作方式与FETCH策略类似，唯一的区别是数据由一个节点发送而不是由收集器收集。

如果数据来自多个节点，您必须将Topology实例的expiration_time设置为略高于节点发送拓扑的间隔的值，这样只有当链路一段时间内未被检测到时，链路才会被标记为“down”。这种机制允许在网络被分割成几个部分的情况下可视化拓扑，缺点是检测下线的链路将花费更多时间。

OPENWISP_NETWORK_TOPOLOGY_PARSERS

其他自定义netdiff解析器。

OPENWISP_NETWORK_TOPOLOGY_SIGNALS

表示在初始化时导入的Python模块的字符串。

用于加载Django信号或定义自定义行为。

OPENWISP_NETWORK_TOPOLOGY_TIMEOUT

获取拓扑URL的超时时间。

OPENWISP_NETWORK_TOPOLOGY_LINK_EXPIRATION

如果一个链路已断开超过这个数字的天数，它将被update_topology管理命令删除。

将此设置为False将禁用此功能。

OPENWISP_NETWORK_TOPOLOGY_VISUALIZER_CSS

可视化器CSS文件的路径。允许根据用户的偏好自定义CSS。

OPENWISP_NETWORK_TOPOLOGY_NODE_EXPIRATION

如果一个节点自指定天数以来未被修改，并且没有链路，它将被update_topology管理命令删除。这取决于是否启用了OPENWISP_NETWORK_TOPOLOGY_LINK_EXPIRATION。将False替换为整数以启用此功能。

OPENWISP_NETWORK_TOPOLOGY_API_URLCONF

使用urlconf选项更改接收API URL以指向另一个模块，例如：myapp.urls。

OPENWISP_NETWORK_TOPOLOGY_API_BASEURL

如果您在另一个域上有单独的openwisp-network-topology实例，您可以使用此选项更改URL的基础，这将使您能够将所有API URL指向您的openwisp-network-topology API服务器域，例如：值：https://mytopology.myapp.com。

OPENWISP_NETWORK_TOPOLOGY_API_AUTH_REQUIRED

当启用时，API 端点将仅允许具有管理其所属组织对象的必要权限的认证用户访问。

实时文档

在/api/v1/docs/处的通用实时API文档（遵循OpenAPI规范）。

可浏览的Web界面

此外，在浏览器中直接打开以下端点之一将显示Django-REST-Framework的可浏览API界面，这使得查找每个端点的详细信息更加容易。

端点列表

详细的说明包含在每个点的实时文档和可浏览网页中，因此这里我们只提供可用的端点列表，如需更多信息，请打开浏览器中的端点URL。

GET /api/v1/network-topology/topology/

/api/v1/network-topology/topology/?organization=371791ec-e3fe-4c9a-8972-3e8b882416f6&strategy=fetch

GET /api/v1/network-topology/topology/?include_unpublished=true

POST /api/v1/network-topology/topology/

GET /api/v1/network-topology/topology/{id}/

GET /api/v1/network-topology/topology/{id}/?include_unpublished=true

PUT /api/v1/network-topology/topology/{id}/

PATCH /api/v1/network-topology/topology/{id}/

DELETE /api/v1/network-topology/topology/{id}/

GET /api/v1/network-topology/topology/{id}/history/?date=2020-08-08

POST /api/v1/network-topology/topology/{id}/receive/

GET /api/v1/network-topology/link/

/api/v1/network-topology/link/?status=down&topology=7fce01bd-29c0-48b1-8fce-0508f2d75d36

POST /api/v1/network-topology/link/

GET /api/v1/network-topology/link/{id}/

PUT /api/v1/network-topology/link/{id}/

PATCH /api/v1/network-topology/link/{id}/

DELETE /api/v1/network-topology/link/{id}/

GET /api/v1/network-topology/node/

/api/v1/network-topology/node/?organization=371791ec-e3fe-4c9a-8972-3e8b882416f6&topology=7fce01bd-29c0-48b1-8fce-0508f2d75d36

POST /api/v1/network-topology/node/

GET /api/v1/network-topology/node/{id}/

PUT /api/v1/network-topology/node/{id}/

PATCH /api/v1/network-topology/node/{id}/

DELETE /api/v1/network-topology/node/{id}/

示例：覆盖<script>标签

以下是更改传递给netjsongraph.js的javascript选项的逐步指南，请记住将<project_path>替换为您项目的绝对文件系统路径。

步骤1：在<project_path>/templates/netjsongraph中创建一个目录

步骤2：打开您的settings.py并编辑TEMPLATES['DIRS']设置，使其看起来像以下示例

# settings.py
TEMPLATES = [
    {
        'DIRS': [os.path.join(BASE_DIR, 'templates')],
        # ... all other lines have been omitted for brevity ...
    }
]

步骤3：在新的<project_path>/templates/netjsongraph/目录中创建一个名为netjsongraph-script.html的新文件，例如

<!-- <project_path>/templates/netjsongraph/netjsongraph-script.html -->
<script>
    window.__njg_el__ = window.__njg_el__ || "body";
    window.__njg_default_url__ = "{{ graph_url }}";
    window.loadNetJsonGraph = function(graph){
        graph = graph || window.__njg_default_url__;
        d3.select("svg").remove();
        d3.select(".njg-overlay").remove();
        d3.select(".njg-metadata").remove();
        return d3.netJsonGraph(graph, {
            el: window.__njg_el__,
            // customizations of netjsongraph.js
            linkClassProperty: "status",
            defaultStyle: false,
            labelDy: "-1.4em",
            circleRadius: 8,
            charge: -100,
            gravity: 0.3,
            linkDistance: 100,
            linkStrength: 0.2,
        });
    };
    window.graph = window.loadNetJsonGraph();
    window.initTopologyHistory(jQuery);
</script>

1. 初始化您的自定义模块

你需要做的第一件事是创建一个新的django应用，该应用将包含你自定义的openwisp-network-topology版本。

django应用不过是python包（一组python脚本），在以下示例中我们将此django应用命名为sample_network_topology，但你可以按自己的意愿命名。

django-admin startapp sample_network_topology

如果你使用与openwisp-controller的集成，你可能需要扩展集成应用，如果需要的话。

django-admin startapp sample_integration_device

请注意，上述命令必须从存在于你的PYTHON_PATH中的目录调用，这样你就可以将结果导入到你的项目中。

现在你需要将sample_network_topology添加到你的settings.py中的INSTALLED_APPS，同时确保已经移除了openwisp_network_topology。

INSTALLED_APPS = [
    # ... other apps ...
    'openwisp_utils.admin_theme',
    # all-auth
    'django.contrib.sites',
    'openwisp_users.accounts',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    # (optional) openwisp_controller - required only if you are using the integration app
    'openwisp_controller.pki',
    'openwisp_controller.config',
    'reversion',
    'sortedm2m',
    # network topology
    # 'sample_network_topology' <-- uncomment and replace with your app-name here
    # (optional) required only if you need to extend the integration app
    # 'sample_integration_device' <-- uncomment and replace with your integration-app-name here
    'openwisp_users',
    # admin
    'django.contrib.admin',
    # rest framework
    'rest_framework',
]

有关如何与django项目和django应用一起工作的更多信息，请参阅django文档。

2. 安装openwisp-network-topology

安装（并将openwisp-network-topology添加到项目需求中）

pip install openwisp-network-topology

3. 添加EXTENDED_APPS

将以下内容添加到你的settings.py

EXTENDED_APPS = ('openwisp_network_topology',)

4. 添加openwisp_utils.staticfiles.DependencyFinder

将openwisp_utils.staticfiles.DependencyFinder添加到你的settings.py中的STATICFILES_FINDERS

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'openwisp_utils.staticfiles.DependencyFinder',
]

5. 添加openwisp_utils.loaders.DependencyLoader

将openwisp_utils.loaders.DependencyLoader添加到你的settings.py中的TEMPLATES

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
                'openwisp_utils.loaders.DependencyLoader',
            ],
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    }
]

6. 继承AppConfig类

请参考测试项目中的示例应用中的以下文件

• sample_network_topology/__init__.py.

• sample_network_topology/apps.py.

有关与openwisp-controller集成的信息，请参阅

• sample_integration_device/__init__.py.

• sample_integration_device/apps.py.

你必须在你自己的项目中复制并适应这些代码。

有关AppConfig概念的更多信息，请参阅django文档中的“Applications”部分。

7. 创建您的自定义模型

请参考测试项目中使用的示例应用模型文件sample_app models file。

你必须在你自己的项目中复制并适应这些代码。

注意：有关如何使用、扩展或开发模型的疑问，请参阅django文档中的“Models”部分。

8. 添加交换器配置

一旦创建了模型，请将以下内容添加到你的settings.py

# Setting models for swapper module
TOPOLOGY_LINK_MODEL = 'sample_network_topology.Link'
TOPOLOGY_NODE_MODEL = 'sample_network_topology.Node'
TOPOLOGY_SNAPSHOT_MODEL = 'sample_network_topology.Snapshot'
TOPOLOGY_TOPOLOGY_MODEL = 'sample_network_topology.Topology'
# if you use the integration with OpenWISP Controller and/or OpenWISP Monitoring
TOPOLOGY_DEVICE_DEVICENODE_MODEL = 'sample_integration_device.DeviceNode'

用步骤1中选择的名称替换sample_network_topology

9. 创建数据库迁移

创建并应用数据库迁移

./manage.py makemigrations
./manage.py migrate

有关更多信息，请参阅django文档中的“Migrations”部分。

10. 创建管理员

参考示例应用的admin.py文件。

为了对管理员进行更改，您可以采取以下两种主要方式，具体说明如下。

注意：有关django管理员如何工作或如何定制的更多信息，请参阅django文档中的“django admin网站”部分。

from openwisp_network_topology.admin import TopologyAdmin, LinkAdmin, NodeAdmin

# TopologyAdmin.list_display.insert(1, 'my_custom_field') <-- your custom change example
# LinkAdmin.list_display.insert(1, 'my_custom_field') <-- your custom change example
# NodeAdmin.list_display.insert(1, 'my_custom_field') <-- your custom change example

from django.contrib import admin
from swapper import load_model

from openwisp_network_topology.admin import (
    TopologyAdmin as BaseTopologyAdmin,
    LinkAdmin as BaseLinkAdmin,
    NodeAdmin as BaseNodeAdmin
)

Node = load_model('topology', 'Node')
Link = load_model('topology', 'Link')
Topology = load_model('topology', 'Topology')

admin.site.unregister(Topology)
admin.site.unregister(Link)
admin.site.unregister(Node)

@admin.register(Topology, TopologyAdmin)
class TopologyAdmin(BaseTopologyAdmin):
    # add your changes here

@admin.register(Link, LinkAdmin)
class LinkAdmin(BaseLinkAdmin):
    # add your changes here

@admin.register(Node, NodeAdmin)
class NodeAdmin(BaseNodeAdmin):
    # add your changes here

11. 创建根URL配置

请根据您的项目需求阅读并复制

The following can be used to register all the urls in your
``urls.py``.

# If you've extended visualizer views (discussed below).
# Import visualizer views & function to add it.
# from openwisp_network_topology.utils import get_visualizer_urls
# from .sample_network_topology.visualizer import views

urlpatterns = [
    # If you've extended visualizer views (discussed below).
    # Add visualizer views in urls.py
    # path('topology/', include(get_visualizer_urls(views))),
    path('', include('openwisp_network_topology.urls')),
    path('admin/', admin.site.urls),
]

有关django中URL配置的更多信息，请参阅django文档中的“URL分发器”部分。

12. 设置API URL

您需要在您的应用中创建一个名为api/urls.py（文件的名称和路径必须匹配）的文件，其中包含以下内容

from openwisp_network_topology.api import views
# When you want to modify views, please change views location
# from . import views
from openwisp_network_topology.utils import get_api_urls

urlpatterns = get_api_urls(views)

13. 扩展管理命令

要扩展管理命令，请在sample_network_topology/management/commands目录中创建目录和两个文件

• save_snapshot.py

• update_topology.py

14. 导入自动化测试

当基于此模块开发自定义应用程序时，导入并运行基本测试也是一个好主意，这样您可以确保您引入的更改不会破坏openwisp-network-topology的一些现有功能。

请参阅示例应用程序的tests.py文件。

如果您需要添加破坏性更改，可以覆盖基类中定义的测试来测试您自己的行为。

对于测试，您还需要扩展固件，您可以将文件openwisp_network_topology/fixtures/test_users.json复制到您的示例应用程序的fixtures/目录中。

现在，您可以使用以下命令运行测试

# the --parallel flag is optional
./manage.py test --parallel sample_network_topology

用步骤1中选择的名称替换sample_network_topology

有关django中自动测试的更多信息，请参阅“Django中的测试”。

其他可继承和扩展的基本类

以下步骤不是必需的，而是为了更高级的定制。