serve#

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

bokeh serve app_script.py

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

https://127.0.0.1:5006/app_script

也可以使用 Jupyter Notebook 运行相同的命令

bokeh serve app_notebook.ipynb

这将生成与 Python 脚本中描述的相同结果，并且应用程序将在默认端口 (5006) 上的 localhost 提供服务，路径为 /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']，这与 sys.argv 的标准 Python 期望一致。

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

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

https://127.0.0.1:5006/

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

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

bokeh serve *.py

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

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 服务器分叉到多进程中。这在尝试处理多个连接时非常有用，尤其是在需要高计算负载的应用程序的上下文中。默认行为是一个进程。使用 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 服务器可以以固定的间隔发送保持活动 ping。要配置此功能，请设置 --keep-alive 选项

bokeh serve app_script.py --keep-alive 10000

该值以毫秒为单位指定。默认保持活动间隔为 37 秒。提供值 0 以禁用保持活动 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 选项并向 BOKEH_ALLOW_WS_ORIGIN 提供以逗号分隔的主机列表来指定多个允许的 websocket 来源

要使 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 格式的单个文件路径（其中包含证书以及建立证书真实性所需的任何数量的 CA 证书）来直接终止 SSL 连接

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 模式下，如果会话 ID 未在 URL 中使用 ?bokeh-session-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 环境变量。

external-signed 模式在您希望另一个进程对 Bokeh 服务器的访问进行身份验证时很有用。如果某人被允许使用 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)[source]#

启动 Bokeh 服务器的子命令。

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

允许子类自定义 applications。

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

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

允许子类自定义 server_kwargs。

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

customize_server(server: Server) → Server[source]#

允许子类自定义 server。

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

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

此子命令的名称