serve#

要从单个 Python 脚本在 Bokeh 服务器上运行 Bokeh 应用程序，请在命令行中将脚本名称传递给 bokeh serve

bokeh serve app_script.py

默认情况下，Bokeh 应用程序将由 localhost 上默认端口 (5006) 的 Bokeh 服务器提供服务，路径为 /app_script，即：

https://127.0.0.1:5006/app_script

也可以使用 jupyter notebook 运行相同的命令

bokeh serve app_notebook.ipynb

这将生成与 Python 脚本描述的相同结果，并且应用程序将在 localhost 上默认端口 (5006) 提供服务，路径为 /app_notebook

应用程序也可以从目录创建。目录应包含一个 main.py（以及任何其他必需的辅助模块）以及任何其他资产（例如，主题文件）。将目录名称传递给 bokeh serve 以运行应用程序

bokeh serve app_dir

可以一次运行多个应用程序

bokeh serve app_script.py app_dir

如果您想自动打开浏览器以显示 HTML 页面，可以在命令行中传递 --show 选项

bokeh serve app_script.py app_dir --show

这将打开两个页面，分别用于 /app_script 和 /app_dir。

如果您想将命令行参数传递给 Bokeh 应用程序，可以将 --args 选项作为命令行中的最后一个选项传递

bokeh serve app_script.py myapp.py --args foo bar --baz

在 --args 之后的所有内容都将包含在应用程序运行时的 sys.argv 中。在这种情况下，当 myapp.py 执行时，sys.argv 的内容将是 ['myapp.py', 'foo', 'bar', '--baz']，这与标准 Python 对 sys.argv 的期望一致。

请注意，如果提供了多个脚本或目录，它们都将接收由 --args 给出的同一组命令行参数（如果有）。

如果您只有一个应用程序，服务器根目录将重定向到它。否则，您可以在服务器根目录看到所有正在运行的应用程序的索引

https://127.0.0.1:5006/

可以使用 --disable-index 选项禁用此索引，并且可以使用 --disable-index-redirect 选项禁用重定向行为。

运行多个应用程序的另一种方法是使用 glob 表示法来指示应提供与特定模式匹配的所有文件。

bokeh serve *.py

命令行 shell 通常会自动展开 *.py。但是，如果您以编程方式启动 Bokeh 服务器，则带有 glob 的文件名参数可能不会被 shell 展开。在这种情况下，可以使用 --glob 标志使 Bokeh 服务器显式执行 globbing

subprocess.call(["bokeh", "serve", "--glob", "*.py"])

可以使用 --ico-path 选项配置 .ico 文件，Bokeh 服务器将返回 /favicon.ico 的此文件内容

bokeh serve app.py --ico-path=/assets/app.ico

由于浏览器仅查看顶级根目录，因此即使运行多个应用程序，也只能提供一个 .ico 文件。默认情况下，Bokeh 项目徽标作为 favicon.ico 文件返回。

应用程序配置#

Bokeh 服务器可以将底层 tornado 服务器 fork 到多进程中。这在尝试处理多个连接时非常有用，尤其是在需要高计算负载的应用程序上下文中。默认行为是一个进程。使用 0 将自动检测核心数并启动相应数量的进程

bokeh serve app_script.py --num-procs 2

请注意，由于 Tornado 固有的限制，Windows 不支持大于 1 的 --num-procs 值！在这种情况下，请考虑在负载均衡器后面运行多个 Bokeh 服务器实例。

Bokeh 服务器还可以向所有 URL 路径添加可选前缀。这在与“反向代理”设置结合使用时通常很有用。

bokeh serve app_script.py --prefix foobar

然后，应用程序将在以下 URL 下提供服务

https://127.0.0.1:5006/foobar/app_script

如果需要，Bokeh 服务器可以按固定间隔发送 keep-alive ping。要配置此功能，请设置 --keep-alive 选项

bokeh serve app_script.py --keep-alive 10000

该值以毫秒为单位指定。默认的 keep-alive 间隔为 37 秒。给出值 0 以禁用 keep-alive ping。

网络配置#

要控制 Bokeh 服务器侦听的端口，请使用 --port 参数

bokeh serve app_script.py --port 8080

要在任意端口上侦听，请传递 0 作为端口号。实际端口号将在启动时记录。

同样，可以使用 --address 参数指定特定的网络地址。例如

bokeh serve app_script.py --address 0.0.0.0

将使 Bokeh 服务器侦听所有可用的网络地址。

默认情况下，不允许跨站点连接到 Bokeh 服务器 websocket。您可以通过使用 BOKEH_ALLOW_WS_ORIGIN 环境变量或 --allow-websocket-origin 选项指定其他主机来启用源自这些主机的 websocket 连接

bokeh serve app_script.py --allow-websocket-origin foo.com:8081

可以通过多次添加 --allow-websocket-origin 选项来指定多个允许的 websocket 源，并向 BOKEH_ALLOW_WS_ORIGIN 提供以逗号分隔的主机列表

要让 Bokeh 服务器使用 X-Real-Ip、X-Forwarded-For、X-Scheme、X-Forwarded-Proto 标头（如果提供）覆盖所有请求的远程 IP 和 URI 方案/协议，请设置 --use-xheaders 选项

bokeh serve app_script.py --use-xheaders

当在 SSL 终止的反向代理后面运行 Bokeh 服务器时，通常需要这样做。

警告

不建议在直接面向 Internet 的 Bokeh 服务器上设置此选项。

Bokeh 服务器还可以通过指定 PEM 格式的单个文件的路径来直接终止 SSL 连接，该文件包含证书以及建立证书真实性所需的任意数量的 CA 证书

bokeh serve --ssl-certfile /path/to/cert.pem

或者，也可以通过设置环境变量 BOKEH_SSL_CERTFILE 来提供路径。

如果私钥单独存储，则可以通过设置 --ssl-keyfile 命令行参数或设置 BOKEH_SSL_KEYFILE 环境变量来提供其位置。如果私钥需要密码，则应通过设置 BOKEH_SSL_PASSWORD 环境变量来提供密码。

会话 ID 选项#

通常，连接到 Bokeh 服务器的每个浏览器选项卡都将具有自己的会话 ID。当服务器生成 ID 时，它将使其在密码学上无法猜测。这可以防止用户访问彼此的会话。

为了控制谁可以使用 Bokeh 应用程序，服务器可以使用密钥对会话 ID 进行签名并拒绝“编造”的会话名称。有三种模式，由 --session-ids 参数控制

bokeh serve app_script.py --session-ids signed

可用模式为：unsigned、signed 或 external-signed

在 unsigned 模式下，服务器将接受在 URL 中提供给它的任何会话 ID。例如，https://127.0.0.1/app_script?bokeh-session-id=foo 将创建一个会话 foo。在 unsigned 模式下，如果未在 URL 中使用 ?bokeh-session-id= 提供会话 ID，服务器仍将生成一个在密码学上无法猜测的 ID。但是，服务器允许客户端创建可猜测或有意共享的会话（如果他们愿意）。

unsigned 模式在服务器在本地运行以进行开发时最有用，例如，您可以让多个进程访问固定的会话名称，例如 default。unsigned 模式也很方便，因为无需生成或配置密钥。

在 signed 模式下，会话 ID 必须采用特殊格式并使用密钥签名。尝试使用无效会话 ID 使用应用程序将失败，但是如果没有提供 ?bokeh-session-id= 参数，服务器将生成一个新的签名会话 ID。signed 模式的结果是仅允许安全会话 ID，但任何人都可以连接到服务器。

在 external-signed 模式下，会话 ID 必须签名，但服务器本身不会生成会话 ID；将需要 ?bokeh-session-id= 参数。要使用此模式，外部进程（例如另一个 Web 应用程序）将使用函数 bokeh.util.token.generate_session_id() 来创建有效的会话 ID。外部进程和 Bokeh 服务器必须共享相同的 BOKEH_SECRET_KEY 环境变量。

如果您希望另一个进程对 Bokeh 服务器的访问进行身份验证，则 external-signed 模式很有用。如果某人被允许使用 Bokeh 应用程序，您将为其生成会话 ID，然后使用该有效的会话 ID 将其重定向到 Bokeh 服务器。如果您没有为某人生成会话 ID，则他们无法从 Bokeh 服务器加载应用程序。

在 signed 和 external-signed 模式下，密钥必须保密；拥有密钥的任何人都能够生成有效的会话 ID。

密钥应在 BOKEH_SECRET_KEY 环境变量中设置，并且应是一个密码学上随机的字符串，至少具有 256 位（32 字节）的熵。bokeh secret 命令可以生成新的密钥。

身份验证选项#

可以配置 Bokeh 服务器，使其仅在存在经过正确身份验证的用户的情况下才允许连接。这可以通过在命令行中提供实现必要函数的模块的路径来完成

bokeh serve --auth-module=/path/to/auth.py

或通过设置 BOKEH_AUTH_MODULE 环境变量。

该模块必须包含以下两个函数之一，这些函数将返回当前用户（或 None）

def get_user(request_handler):
    pass

async def get_user_async(request_handler):
    pass

该函数传递 Tornado RequestHandler，并且可以检查 Cookie 或请求标头以确定经过身份验证的用户。如果没有有效的经过身份验证的用户，这些函数应返回 None。

此外，该模块必须指定将未经过身份验证的用户重定向到哪里。它必须包含以下任一项

  • 模块属性 login_url 和（可选）LoginHandler 类

  • 用于 get_login_url 的函数定义

login_url = "..."

class LoginHandler(RequestHandler):
    pass

def get_login_url(request_handler):
    pass

当给出相对 login_url 时，还可以提供可选的 LoginHandler 类，并且它将自动作为路由安装在 Bokeh 服务器上。

get_login_url 函数在登录 URL 必须根据请求或 Cookie 等变化的情况下很有用。当定义 get_url_function 时，无法指定 LoginHandler。

与登录选项类似，可选的 logout_url 和 LogoutHandler 值可以定义用于注销用户的端点。

如果未提供身份验证模块，则将假定为默认用户，并且访问 Bokeh 服务器端点不需要身份验证。

警告

将执行身份验证模块的内容！

Bokeh 还可以启用 Tornado 的 XFRF Cookie 保护的使用。要启用此功能，请使用 --enable-xsrf-cookies 选项，或设置环境变量 BOKEH_XSRF_COOKIES=yes。如果启用此设置，则必须正确地检测自定义或登录处理程序上的任何 PUT、POST 或 DELETE 操作才能起作用。通常，这意味着将 xsrf_form_html() 模块添加到 HTML 表单提交模板。有关完整详细信息，请参阅

会话过期选项#

要配置检查未使用会话的频率，请设置 --check-unused-sessions 选项

bokeh serve app_script.py --check-unused-sessions 10000

该值以毫秒为单位指定。检查未使用会话的默认间隔为 17 秒。仅接受正整数值。

要配置未使用会话持续的时间，请设置 --unused-session-lifetime 选项

bokeh serve app_script.py --unused-session-lifetime 60000

该值以毫秒为单位指定。未使用会话的默认生存期间隔为 15 秒。仅接受正整数值。

诊断选项#

可以使用 --log-level 参数控制日志记录级别

bokeh serve app_script.py --log-level debug

可用的日志级别为：trace、debug、info、warning、error 或 critical

可以使用 --log-format 参数控制日志格式

bokeh serve app_script.py --log-format "%(levelname)s: %(message)s"

默认日志格式为 "%(asctime)s %(message)s"

要控制统计日志的写入频率，请设置 --stats-log-frequency 选项

bokeh serve app_script.py --stats-log-frequency 30000

该值以毫秒为单位指定。记录统计信息的默认间隔为 15 秒。仅接受正整数值。

Bokeh 还可以选择记录进程内存使用情况。此功能需要安装可选的 psutil 软件包。要启用内存日志记录，请设置 --mem-log-frequency 选项

bokeh serve app_script.py --mem-log-frequency 30000

该值以毫秒为单位指定。记录统计信息的默认间隔为 0（禁用）。仅接受正整数值。

class Serve(parser: ArgumentParser)[来源]#

启动 Bokeh 服务器的子命令。

customize_applications(args: Namespace, applications: dict[str, Any]) → dict[str, Any][来源]#

允许子类自定义 applications。

应该修改并返回 applications 字典的副本。

customize_kwargs(args: Namespace, server_kwargs: dict[str, Any]) → dict[str, Any][来源]#

允许子类自定义 server_kwargs。

应该修改并返回 server_kwargs 字典的副本。

customize_server(server: Server) → Server[来源]#

允许子类自定义 server。

应该对服务器应用修改并包装它或返回相同的实例。

invoke(args: Namespace) → None[来源]#
name: ClassVar[str] = 'serve'#

此子命令的名称