jhsingle-native-proxy

将任意Web应用包装起来，以便在JupyterHub设置中替代jupyter-singleuser使用。

在JupyterHub中，这允许与jupyter-server-proxy类似的操作，但它还移除了Jupyter笔记本本身，因此直接与任意Web服务一起工作。

基于JUPYTERHUB_*环境变量强制执行OAuth身份验证。

该项目用于ContainDS仪表板，这是一个用户友好的方式，在JupyterHub中启动可共享的仪表板形式的Jupyter笔记本。也适用于Streamlit和其他可视化框架。

安装和运行

使用pip进行安装。

pip install jhsingle-native-proxy

启动过程在命令行中指定，例如一个streamlit Web应用

jhsingle-native-proxy streamlit hello

默认情况下，jhsingle-native-proxy服务器将在端口8888上监听，并将流量转发到端口8500。

但通常需要告诉jhsingle-native-proxy端过程将运行的端口，也许还需要告诉端过程你希望它使用的端口（你可以使用替换变量{port}）。

注意使用--来向jhsingle-native-proxy指示命令行选项的结束。然后第三方命令行本身可以包含以破折号开头的选项。另一种选择是使用替换{--}

jhsingle-native-proxy -- streamlit hello --server.port {port} --server.headless True --server.enableCORS False

要使用不同的端口运行jhsingle-native-proxy本身，请使用

jhsingle-native-proxy --port 8000 streamlit hello

要在端口8000上运行jhsingle-native-proxy，并在端口8505上运行端过程

jhsingle-native-proxy --port 8000 --destport 8505 -- streamlit hello --server.port {port} --server.headless True --server.enableCORS False

使用JUPYTERHUB_SERVICE_PREFIX环境变量来指定要监听的URL的第一部分（然后在转发前将其删除）。例如，JUPYTERHUB_SERVICE_PREFIX=/user/dan将意味着对http://localhost:8888/user/dan/something的请求将转发到http://localhost:8500/something

您还可以指定 --ip 0.0.0.0 作为监听地址。

以下示例中，我们使用 {--} 代替要运行的命令，以便我们可以将 --ip 指定给 jhsingle-native-proxy 而不是运行的命令。

jhsingle-native-proxy --port 8000 --destport 8505 streamlit hello {--}server.port {port} {--}server.headless True {--}server.enableCORS False --ip 0.0.0.0

类似地，可以使用 {-}m 来表示最终命令中的 -m。

看看这个示例

在子文件夹 URL 上运行 voila，例如 /user/dan/

python -m jhsingle_native_proxy.main --destport 0 voila ./Presentation.ipynb {--}port={port} {--}no-browser {--}Voila.server_url=/ {--}Voila.base_url={base_url}/ {--}debug

上面的 'destport 0' 指令告诉 jhsingle-native-proxy 在哪个随机空闲端口上运行子进程（Voila），并且当然会将它作为 {port} 替换到 Voila 命令行中，以便它知道要监听哪个端口。默认情况下，destport 0 已经是默认值。

或者，指定 presentation_path 作为替代，而不是硬编码，这在您的包装代码中有时更容易。

python -m jhsingle_native_proxy.main --destport 0 voila {presentation_path} {--}port={port} {--}no-browser {--}Voila.server_url=/ {--}Voila.base_url={base_url}/ {--}debug --presentation_path=./Presentation.ipynb

此外，如果提供了 presentation_path，还有两个额外的替代变量可用：presentation_dirname 和 presentation_basename。这些是通过在 presentation_path 上使用 Python 的 os.path.dirname 和 os.path.basename 函数计算得出的。

身份验证

上面的示例都假设将强制执行 OAuth，如 JUPYTERHUB_* 环境变量所规定。

可以通过 authtype 标志指定替代方案。

与默认设置相同

jhsingle-native-proxy --authtype=oauth streamlit hello

根本不需要身份验证

jhsingle-native-proxy --authtype=none streamlit hello

指定授权用户

JUPYTERHUB_USER 和 JUPYTERHUB_GROUP 环境变量可以像任何 JupyterHub 单个服务器典型情况一样使用，来指定 JupyterHub 的用户/组，这些用户/组应该通过 OAuth 允许访问。还有一个额外的自定义环境变量 JUPYTERHUB_ANYONE，可以设置为 1 以允许任何已认证的用户访问。（即任何在 JupyterHub 上有账户的人）

额外参数

--request-timeout=300 指定了在代理正常请求时等待底层子进程返回的秒数。默认为 300。

命令参数中的 {origin_host} 将被替换为发送到 jhsingle-native-proxy 服务器的任何请求中看到的第一个 'host'。

--last-activity-interval=300 指定以秒为单位多长时间更新 hub，以提供通过代理的任何流量最后通过的时间（默认为 300）。指定 0 以从不更新。--force-keep-alive 或 --no-force-keep-alive：前者（默认）确保即使没有活动，hub 也会通知最近的活动 - 仅当 last-activity-interval 不是 0 时才有效。

--ready-check-path（默认为 /）用于更改用于通过 HTTP 请求轮询以检查就绪状态的子进程的 URL。

--repo - 在运行子进程之前使用 git 检出存储库

--repofolder - 存储库内容要包含的文件夹的路径（如果需要，将创建该文件夹）

--forward-user-info - 将包含 JupyterHub 用户信息的 JSON 编码字符串的 X-CDSDASHBOARDS-JH-USER HTTP 标头转发到底层进程

--query-user-info - 在调用底层进程时添加名为 CDSDASHBOARDS_JH_USER 的 GET 查询参数，其中包含 JupyterHub 用户信息作为 JSON 编码字符串

--ready-timeout - 检查进程在启动时运行的时间段整数超时（默认为 10）。如果您的进程在启动后一段时间内无法在 --ready-check-path 返回任何内容，请增加此值。注意，一旦准备就绪，进程必须在 1 秒内返回其 HTTP 响应。注意，此参数与 --request-timeout 不同，后者适用于正常操作期间单个 HTTP 代理调用（而不仅仅是启动时）。

--websocket-max-message-size - 允许连接到底层进程的 WebSocket 连接的消息大小（默认依赖于 tornado 库的默认值）。

--progressive - 从底层服务中刷新缓冲区，每当出现数据块时（这对于更快地看到 Voila 的结果很有用）

变更日志

v0.8.3 发布于 2024 年 9 月 25 日

• Aiohttp 连接器和超时的新选项：aiohttp-no-ssl-connector 和 aiohttp-request-timeout。感谢 aditipate。

v0.8.2 发布于 2023 年 11 月 30 日

• 通过Tornado实现更好的日志输出。感谢aditipate。

v0.8.1版本发布于2023年6月13日

• 锁定simpervisor版本，以避免与1.0版本冲突。感谢dangercrow。

v0.8.0版本发布于2021年11月8日

• 修改以支持JupyterHub 2（如果没有设置--port，则从JUPYTERHUB_SERVICE_URL环境变量检测端口）

v0.7.6版本发布于2021年4月20日

• 新增命令行选项--ready-timeout和--websocket-max-message-size

v0.7.3版本发布于2021年4月9日

• 新增命令行选项--progressive，以便在底层服务中出现块时从底层服务刷新缓冲区（这对于更快地看到Voila的结果很有用）
• 当运行JUPYTERHUB_BASE_URL为/时，oauth_callback URL现在可访问

v0.7.1版本发布于2021年2月22日

• 新增命令行选项--query-user-info，将CDSDASHBOARDS_JH_USER GET查询参数添加到底层服务的http请求中。

v0.7.0版本发布于2021年2月12日

• 新增命令行选项--forward-user-info，将X-CDSDASHBOARDS-JH-USER头添加到底层服务的http请求中。该头部的值是一个包含kind、name、admin、groups字段的JSON编码字典，如果可用，则为已登录的JupyterHub用户的这些字段。

v0.6.1版本发布于2021年1月6日

• 要求simpervisor >= 0.4，以确保Python 3.9兼容。

v0.6.0版本发布于2020年11月20日

• 默认显示INFO级别的日志，包括子进程的输出（使用--no-logs关闭）问题 #7
• 根据来源将子进程的日志写入不同的级别（stderr -> 错误，stdout -> 信息）
• 处理并截断长子进程日志，而不是抛出错误 cdsdashboards问题 #44
• 使用git repo源时，处理分支签出与之前签出的分支切换时的不同

v0.5.6版本发布于2020年9月18日

• 在传递给子命令之前，始终将presentation_path转换为基于CWD的绝对路径。

v0.5.5版本发布于2020年9月10日

• 也接受前缀的URL编码等效的URL，并重定向到URL的常规版本。

v0.5.4版本发布于2020年9月3日

• 当指定时，将工作文件夹更改为repofolder

v0.5.2版本发布于2020年8月17日

• 要求tornado 6.0.4+

v0.5.1版本发布于2020年8月17日

• 修复以确保同时打开两个websockets，以避免写入尚未打开的websocket。

v0.5.0版本发布于2020年8月17日

• 在连接客户端之前，先打开底层进程的websocket。这确保了可以将任何其他GET头传递回客户端。（Streamlit XSRF问题的修复。）

v0.4.3版本发布于2020年7月30日

• 添加了--allow-root选项（目前忽略），以避免通常将此标志传递给jupyter-singleuser时出错

v0.4.2版本发布于2020年7月23日

• 通过指定--conda-env选项在运行子进程之前切换到Conda环境

v0.4.1版本发布于2020年7月20日

• 修复，因为当输出太多时，子进程有时会被阻塞

v0.4.0版本发布于2020年7月15日

• 添加了repo和repofolder可选参数

v0.3.2版本发布于2020年6月25日

v0.3.1版本发布于2020年6月18日

• 如果未提供，将presentation_path默认设置为空字符串（''），以避免错误

v0.3.0版本发布于2020年6月17日

• 可以将presentation_path作为命令行参数提供，成为替换变量。
• 当提供presentation_path时，也提供了presentation_basename和presentation_dirname。

v0.2.0版本发布于2020年6月11日

• 改进了websocket处理（子协议）
• 添加{origin_host}变量

v0.1.3版本发布于2020年6月1日

• 已将请求超时添加到代理调用中，默认设置为300秒（之前httpclient的默认值为20秒）。

v0.1.2版本发布于2020年5月29日。

• 现在允许使用单个破折号占位符，例如 {-}m 在最终子进程命令中转换为 -m。

开发安装

git clone https://github.com/ideonate/jhsingle-native-proxy.git
cd jhsingle-native-proxy

pip install -e .

在Python中直接运行： python -m jhsingle_native_proxy.main <命令行剩余部分>

测试git拉取器

python -m jhsingle_native_proxy.main --authtype=none --destport=0 --port=8888 voila ./sincosfolder/Presentation.ipynb {--}port={port} {--}no-browser {--}Voila.server_url=/ {--}Voila.base_url={base_url}/ --repo=https://github.com/danlester/binder-sincos --repofolder=sincosfolder