跳转至

初始化 wis2box

学习目标

完成本次实践课程后，您将能够：

  • 运行 wis2box-create-config.py 脚本以创建初始配置
  • 启动 wis2box 并检查其组件状态
  • 查看 wis2box-api 的内容
  • 访问 wis2box-webapp
  • 使用 MQTT Explorer 连接到本地 wis2box-broker

Note

当前培训材料基于 wis2box-release 1.3.0。

如果您在本地培训课程之外运行此培训，请参阅 accessing-your-student-vm 了解如何下载和安装 wis2box 软件栈的说明。

准备工作

使用您的用户名和密码登录指定的虚拟机，并确保您处于 wis2box 目录中：

cd ~/wis2box

创建初始配置

创建 wis2box 的初始配置需要：

  • 一个包含配置参数的环境文件 wis2box.env
  • 主机上的一个目录，用于在主机和 wis2box 容器之间共享，由环境变量 WIS2BOX_HOST_DATADIR 定义

可以使用 wis2box-create-config.py 脚本来创建您的 wis2box 的初始配置。

脚本会向您提出一系列问题，以帮助设置配置。

脚本完成后，您可以查看并更新配置文件。

运行以下命令启动脚本：

python3 wis2box-create-config.py

wis2box-host-data 目录

脚本会要求您输入用于 WIS2BOX_HOST_DATADIR 环境变量的目录。

请注意，您需要定义该目录的完整路径。

例如，如果您的用户名是 username，目录的完整路径为 /home/username/wis2box-data：

username@student-vm-username:~/wis2box$ python3 wis2box-create-config.py
Please enter the directory to be used for WIS2BOX_HOST_DATADIR:
/home/username/wis2box-data
The directory to be used for WIS2BOX_HOST_DATADIR will be set to:
    /home/username/wis2box-data
Is this correct? (y/n/exit)
y
The directory /home/username/wis2box-data has been created.

wis2box URL

接下来，您需要输入 wis2box 的 URL。此 URL 将用于访问 wis2box 的 Web 应用程序、API 和用户界面。

请使用 http://<your-hostname-or-ip> 作为 URL。

Please enter the URL of the wis2box:
 For local testing the URL is http://localhost
 To enable remote access, the URL should point to the public IP address or domain name of the server hosting the wis2box.
http://username.training.wis2dev.io
The URL of the wis2box will be set to:
  http://username.training.wis2dev.io
Is this correct? (y/n/exit)

WEBAPP、STORAGE 和 BROKER 密码

当提示输入 WIS2BOX_WEBAPP_PASSWORD、WIS2BOX_STORAGE_PASSWORD 和 WIS2BOX_BROKER_PASSWORD 时，您可以选择随机生成密码或自行定义。

无需担心记住这些密码，它们会存储在 wis2box.env 文件中，位于您的 wis2box 目录中。

检查 wis2box.env

脚本完成后，请检查当前目录中的 wis2box.env 文件内容：

cat ~/wis2box/wis2box.env

或者通过 WinSCP 检查文件内容。

Question

wis2box.env 文件中 WISBOX_BASEMAP_URL 的值是什么？

点击查看答案

WIS2BOX_BASEMAP_URL 的默认值是 https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png。

此 URL 指向 OpenStreetMap 瓦片服务器。如果您希望使用其他地图提供商，可以将此 URL 更改为指向其他瓦片服务器。

Question

wis2box.env 文件中 WIS2BOX_STORAGE_DATA_RETENTION_DAYS 环境变量的值是什么？

点击查看答案

WIS2BOX_STORAGE_DATA_RETENTION_DAYS 的默认值是 30 天。如果需要，您可以将此值更改为其他天数。

wis2box-management 容器每天运行一个 cronjob，删除 wis2box-public 存储桶和 API 后端中超过 WIS2BOX_STORAGE_DATA_RETENTION_DAYS 定义天数的数据：

0 0 * * * su wis2box -c "wis2box data clean --days=$WIS2BOX_STORAGE_DATA_RETENTION_DAYS"

Note

wis2box.env 文件包含定义 wis2box 配置的环境变量。有关更多信息，请参阅 wis2box-documentation。

除非您确定所做的更改，否则不要编辑 wis2box.env 文件。不正确的更改可能导致您的 wis2box 无法正常工作。

请勿与任何人共享您的 wis2box.env 文件内容，因为其中包含敏感信息，例如密码。

启动 wis2box

确保您位于包含 wis2box 软件栈定义文件的目录中：

cd ~/wis2box

使用以下命令启动 wis2box：

python3 wis2box-ctl.py start

首次运行此命令时，您会看到以下输出：

No docker-compose.images-*.yml files found, creating one
Current version=Undefined, latest version=1.3.0
Would you like to update ? (y/n/exit)

选择 y，脚本将创建文件 docker-compose.images-1.3.0.yml，下载所需的 Docker 镜像并启动服务。

根据您的网络连接速度，下载镜像可能需要一些时间。此步骤仅在首次启动 wis2box 时需要完成。

使用以下命令检查状态：

python3 wis2box-ctl.py status

重复运行此命令，直到所有服务都启动并运行。

wis2box 和 Docker

wis2box 作为一组由 docker-compose 管理的 Docker 容器运行。

服务定义在 ~/wis2box/ 目录中的各种 docker-compose*.yml 文件中。

Python 脚本 wis2box-ctl.py 用于运行底层的 Docker Compose 命令，以控制 wis2box 服务。

您无需了解 Docker 容器的详细信息即可运行 wis2box 软件栈，但可以查看 docker-compose*.yml 文件以了解服务的定义。如果您有兴趣了解更多关于 Docker 的信息，可以参考 Docker 文档。

要登录到 wis2box-management 容器，请使用以下命令：

python3 wis2box-ctl.py login

注意，登录后您的提示符会发生变化，表明您现在处于 wis2box-management 容器中：

root@025381da3c40:/home/wis2box#

在 wis2box-management 容器中，您可以运行各种命令来管理您的 wis2box，例如：

  • wis2box auth add-token --path processes/wis2box：为 processes/wis2box 端点创建授权令牌
  • wis2box data clean --days=<number-of-days>：清理 wis2box-public 存储桶中超过指定天数的数据

要退出容器并返回主机，请使用以下命令：

exit

运行以下命令查看主机上运行的 Docker 容器：

docker ps --format "table {{.Names}} \t{{.Status}} \t{{.Image}}"

您应该看到以下容器正在运行：

NAMES                     STATUS                         IMAGE
nginx                     Up 56 seconds                  nginx:1.30.1-alpine
mqtt_metrics_collector    Up 58 seconds                  ghcr.io/world-meteorological-organization/wis2box-mqtt-metrics-collector:1.3.0
wis2box-auth              Up 59 seconds                  ghcr.io/world-meteorological-organization/wis2box-auth:1.3.0
wis2box-ui                Up About a minute              ghcr.io/world-meteorological-organization/wis2box-ui:1.3.0
wis2box-management        Up About a minute              ghcr.io/world-meteorological-organization/wis2box-management:1.3.0
wis2box-minio             Up 2 minutes (healthy)         ghcr.io/world-meteorological-organization/wis2box-minio:latest
wis2box-api               Up About a minute (healthy)    ghcr.io/world-meteorological-organization/wis2box-api:1.3.0
elasticsearch             Up 2 minutes (healthy)         docker.elastic.co/elasticsearch/elasticsearch:8.6.2
grafana                   Up 2 minutes                   grafana/grafana-oss:12.4.2
loki                      Up 2 minutes                   grafana/loki:2.4.1
elasticsearch-exporter    Up 2 minutes                   quay.io/prometheuscommunity/elasticsearch-exporter:latest
prometheus                Up 2 minutes                   prom/prometheus:v2.37.0
mosquitto                 Up 2 minutes                   ghcr.io/world-meteorological-organization/wis2box-broker:1.3.0
wis2box-webapp            Up 2 minutes (healthy)         ghcr.io/world-meteorological-organization/wis2box-webapp:1.3.0

这些容器是 wis2box 软件栈的一部分，提供运行 wis2box 所需的各种服务。

运行以下命令以查看主机机器上运行的 Docker 卷：

docker volume ls

您应该会看到以下卷：

  • wis2box_project_auth-data
  • wis2box_project_es-data
  • wis2box_project_minio-data
  • wis2box_project_prometheus-data
  • wis2box_project_loki-data
  • wis2box_project_mosquitto-config

以及一些由各种容器使用的匿名卷。

以 wis2box_project_ 开头的卷用于存储 wis2box 软件栈中各种服务的持久数据。

wis2box API

wis2box 包含一个 API（应用程序编程接口），提供数据访问和交互式可视化、数据转换及发布的处理功能。

打开一个新标签页并导航到页面 http://YOUR-HOST/oapi。

wis2box-api.png

这是 wis2box API 的主页（通过 wis2box-api 容器运行）。

Question

当前有哪些集合可用？

点击查看答案

要查看 API 当前可用的集合，请点击 View the collections in this service：

wis2box-api-collections.png

当前可用的集合如下：

  • 站点
  • 数据通知
  • 发现元数据

Question

已发布了多少条数据通知？

点击查看答案

点击 "Data notifications"，然后点击 Browse through the items of "Data Notifications"。

您会注意到页面显示 "No items"，因为尚未发布任何数据通知。

wis2box webapp

打开一个网页浏览器并访问页面 http://YOUR-HOST/wis2box-webapp。

您会看到一个弹窗要求输入用户名和密码。使用默认用户名 wis2box-user 和在 wis2box.env 文件中定义的 WIS2BOX_WEBAPP_PASSWORD，然后点击 "Sign in"：

Note

检查您的 wis2box.env 文件以获取 WIS2BOX_WEBAPP_PASSWORD 的值。您可以使用以下命令检查此环境变量的值：

cat ~/wis2box/wis2box.env | grep WIS2BOX_WEBAPP_PASSWORD

登录后，将鼠标移到左侧菜单以查看 wis2box Web 应用程序中的可用选项：

wis2box-webapp-menu.png

这是 wis2box Web 应用程序，您可以通过它与您的 wis2box 进行交互：

  • 创建和管理数据集
  • 更新/审查您的站点元数据
  • 使用 FM-12 synop 表单上传手动观测数据
  • 监控在您的 wis2box-broker 上发布的通知

我们将在后续课程中使用此 Web 应用程序。

wis2box-broker

在您的计算机上打开 MQTT Explorer，并准备一个新连接以连接到您的 broker（通过 wis2box-broker 容器运行）。

点击 + 添加一个新连接：

mqtt-explorer-new-connection.png

您可以点击 'ADVANCED' 按钮并验证您已订阅以下主题：

  • #
  • $SYS/#

mqtt-explorer-topics.png

Note

# 主题是一个通配符订阅，它会订阅 broker 上发布的所有主题。

发布在 $SYS 主题下的消息是由 mosquitto 服务本身发布的系统消息。

使用以下连接详情，确保将 <your-host> 替换为您的主机名，将 <WIS2BOX_BROKER_PASSWORD> 替换为您 wis2box.env 文件中的值：

  • 协议: mqtt://
  • 主机: <your-host>
  • 端口: 1883
  • 用户名: wis2box
  • 密码: <WIS2BOX_BROKER_PASSWORD>

Note

您可以检查您的 wis2box.env 文件以获取 WIS2BOX_BROKER_PASSWORD 的值。您可以使用以下命令检查此环境变量的值：

cat ~/wis2box/wis2box.env | grep WIS2BOX_BROKER_PASSWORD

请注意，这是您的 内部 broker 密码，Global Broker 将使用不同的（只读）凭据订阅您的 broker。切勿与任何人共享此密码。

确保点击 "SAVE" 保存您的连接详情。

然后点击 "CONNECT" 连接到您的 wis2box-broker。

mqtt-explorer-wis2box-broker-port1883.png

连接后，您将看到您的 broker 在 $SYS 主题下发布的内部 mosquitto 统计信息：

mqtt-explorer-sys-topic.png

同样的连接也可以通过 WebSockets 使用 MQTT 在端口 80 上实现，连接详情如下：

mqtt-explorer-wis2box-broker-websockets.png

结论

恭喜！

在本次实践课程中，您学习了如何：

  • 运行 wis2box-create-config.py 脚本以创建初始配置
  • 启动 wis2box 并检查其组件状态
  • 在浏览器中访问 wis2box-webapp 和 wis2box-API
  • 使用 MQTT Explorer 连接到学生虚拟机上的 MQTT broker

```