jupyterhub-announcement

这是一个用于JupyterHub的通告服务，您可以通过JupyterHub风格的UI进行管理。您可以使用它与您的hub用户沟通状态、即将到来的停机或分享新闻。它允许您发布当前通告，并按倒序显示以前的通告。它提供了一个REST API钩子，您可以使用它将最新的通告直接发布到JupyterHub本身（使用自定义模板）。即使用户未登录，通告也是可见的。

需求

• jupyterhub
• html-sanitizer
• aiofiles

安装

pip install jupyterhub-announcement

如何配置它

您可以将此服务作为hub管理的服务或外部服务运行。以下是一个hub管理的服务示例配置，您可以将其放置在JupyterHub配置文件中

c.JupyterHub.services = [
    {
        'name': 'announcement',
        'url': 'http://127.0.0.1:8888',
        'command': ["python", "-m", "jupyterhub_announcement"]
    }
]

以下是将它设置为外部服务的配置，例如，在另一个名为announcement的Docker容器中

import os
c.JupyterHub.services = [
    {
        'name': 'announcement',
        'url': 'http://announcement:8888',
        'api_token': os.environ["ANNOUNCEMENT_JUPYTERHUB_API_TOKEN"]
    }
]

您必须在此处指定hub和通告服务共享的API令牌。从JupyterHub 2.0开始，您将需要通过适当的定义c.JupyterHub.load_roles来设置用户访问。请参阅hub管理的服务示例了解如何进行。

服务还有一个自己的配置文件，默认情况下是announcement_config.py。配置文本可以使用--generate-config选项生成。

如果您正在运行启用内部SSL的hub，您可能想要利用SSL选项设置。

如何使用它

它实际运行时看起来是什么样子？启动hub。以管理员用户身份登录，然后转到

https://:8000/services/announcement/

您应该看到

您现在将看到之前相同的页面，但会看到一个文本框。请输入一条消息。请注意，您的输入将被清理。出于安全考虑，一些HTML标签，如“<iframe>”或“<script>”将被自动删除。

这将成为最新公告。

在中心，用户将看到发布的公告。

如果您输入一条空消息，则清除该消息并将其降级为以前的公告。

继续添加更多。然后注销。现在使用一个非管理员测试用户登录。指向公告页面，您将看到友好的管理员发送给您的所有这些精彩沟通。

再次注销并查看。即使您已注销，您也可以看到它们。

REST端点

• /services/announcement/latest - 获取最新公告作为JSON对象。
• /services/announcement/list - 获取最新N条公告作为JSON对象列表。
  • 要设置N，您需要在配置中设置default_limit。
  • 要覆盖默认限制，请使用以下URL参数/services/announcement/list?limit=2

如果自定义页面模板，您可以调用服务以获取来自中心的公告。用户可能喜欢这种方式。如果没有最新公告或尚未发布公告，将返回空公告。

以下是如何在自定义模板中使用REST端点的更多详细信息。此示例扩展了JupyterHub page.html模板，以对公告服务进行小的AJAX调用。要使其工作，您必须

1. 在中心可以访问的地方创建一个目录，例如使用/opt/templates。
2. 将模板添加到/opt/templates/page.html
3. 最后，在JupyterHub配置文件中设置c.JupyterHub.template_paths = ["/opt/templates"]。

注意第一行，说明我们正在扩展模板。

{% extends "templates/page.html" %}
{% block announcement %}
<div class="container announcement"></div>
{% endblock %}

{% block script %}
{{ super() }}
<script>
$.get("/services/announcement/latest", function(data) {
  var announcement = data["announcement"];
  if(announcement) {
    $(".announcement").html(`<div class="panel panel-warning">
      <div class="panel-heading">
        <h3 class="panel-title">Announcement</h3>
      </div>
      <div class="panel-body text-center announcement">
        ${announcement}
      </div>       
    </div>`);
  }
});
</script>
{% endblock %}

小心 到目前为止，应该很清楚，您想确保管理员是可信赖的！

使用React

以下示例使用react组件以bootstrap toast的形式显示最后N条公告（见下文图片）。

固定消息

配置中有一个钩子，允许您在所有公告上方添加自定义消息。此消息的好用途是包括指向更通用的系统状态或每日消息（MOTD）页面的链接。

公告有效期

公告将在队列中保留，直到配置的某些天数。之后，它们将自动清除。默认情况下，公告在队列中保留一周。

持久化公告

默认情况下，该服务不执行任何操作以持久化公告。您可以通过指定AnnouncementQueue对象的persist_path来更改此行为。如果设置了此选项，则服务将在启动时读取此文件，并尝试使用其内容初始化队列。如果设置了但文件不存在，则没关系，队列将从空开始。在更新时，文件将被覆盖以反映队列的当前状态。这样，如果服务重新启动，则不会丢失旧公告。持久化文件是JSON。请确保此文件的安全访问！