Positron Workbench 本地联合开发环境指南:用 `npm run pwb` 一键拉起 Positron 与 Posit Workbench
Positron Workbench 本地联合开发环境指南:用 npm run pwb 一键拉起 Positron 与 Posit Workbench
导读
本指南完整讲解 Positron 仓库内置的本地 QA 环境工具 npm run pwb(docker/environments/wb-local/README.md 为官方文档)。它能在你本机的 Docker 中同时运行 Positron(下一代数据科学 IDE)与 Posit Workbench(原 RStudio Workbench 的服务器发行版),并按你指定的版本组合一键安装、启动、暂停与清理整条技术栈。读完本文,你将掌握版本选择器与非交互式安装、自定义 Positron 构建的替换(--positron-build)、多操作系统测试容器(Ubuntu/Rocky/openSUSE)、受管数据源凭据(Databricks/Snowflake/Azure)、自动停机(TTL)与常见故障排查等完整实战能力,并理解脚本底层(workbench-local.sh、install-workbench.sh 等)的实现原理。
环境概览:一次命令启动的两套产品
npm run pwb 是对 bash docker/environments/wb-local/workbench-local.sh 的 npm 封装(见 package.json)。它编排一套由三个容器组成的 Docker Compose 栈(定义见 docker-compose.workbench.yml):
test:运行 Workbench + Positron 的主容器,默认镜像ghcr.io/posit-dev/positron-ubuntu24:24.18.0,暴露 8787(Workbench)、8080、5900、9323 等端口;postgres:e2e 测试用的 Postgres 数据库(镜像ghcr.io/posit-dev/positron-postgres:24.18.0);connect:Posit Connect 发布服务器(镜像ghcr.io/posit-dev/connect:latest),用于测试内容发布链路。
test 容器以 sleep 循环作为 entrypoint(command: /bin/bash -c "while true; do sleep 3600; done"),Workbench 服务本身由安装脚本写入的 supervisord 管理,而不是容器入口——这是理解“容器已启动但 8787 可能还没通”的关键。
前置条件与首次启动
硬件与系统要求
官方文档给出的最低门槛:Docker Desktop 且配置 8+ CPU、16 GB 内存。可选依赖 fzf(用于方向键选择器,没有时退化为数字编号提示):
brew install fzf # macOS
sudo apt install fzf # Debian/Ubuntu
winget install junegunn.fzf # Windows
conda install -c conda-forge fzf # conda 环境
首次启动四步
-
GitHub 容器仓库登录:首次被提示输入密码时,输入你的 GitHub Personal Access Token(而非 GitHub 密码),该 token 需要
read:packages权限:docker login ghcr.io -u <your_github_username> -
放置许可文件:把
workbench.lic和connect.lic放到docker/environments/wb-local/目录下(connect.lic会被 CR 清洗后挂载到connect/connect.lic,详见后文)。 -
生成
.env:首次运行会从 .env.example 自动复制出.env;若其中WB_PASSWORD未设置,脚本会通过/dev/tty提示你输入。敏感值(如受管凭据)存放在团队 1Password。 -
启动:
npm run pwb
首次运行会弹出两个版本选择器(Positron 与 Workbench),随后完成安装并拉起整个栈。完成后访问 http://localhost:8787,用 user1 登录,密码即 .env 中的 WB_PASSWORD。
认证的底层实现(源码佐证)
脚本并不要求你手动 docker login。wb_ensure_auth(workbench-local.sh 中的函数)会依次:优先使用显式的 GITHUB_TOKEN(环境变量或 .env);否则借用 gh auth login 登录后的 token(gh auth token);再通过 GitHub 的 X-OAuth-Scopes 响应头检查该 token 是否具备 read:packages,缺失时给出针对性修复提示(gh auth refresh -h github.com -s read:packages)。只有在你尚未登录 ghcr.io 时,它才会用该 token 自动执行 docker login ghcr.io——刻意避免覆盖已存在的专用 read:packages PAT。
命令速查表
以下是 npm run pwb 的完整命令参考(npm run pwb -- --help 在终端中输出同样的内容):
| 命令 | 作用 |
|---|---|
npm run pwb |
拉起栈。首次运行:选择版本并安装;已安装:重启并显示状态。可随时安全重跑 |
npm run pwb -- --reinstall |
重新运行选择器并重装,用于切换 Positron / Workbench 版本 |
npm run pwb -- --credentials=<type> |
以受管数据源连接安装:databricks、snowflake 或 azure |
npm run pwb -- --workbench=<release|daily|URL> --positron=<release|daily|TAG> |
跳过版本选择器(无 TTY 时必需:Agent、CI、管道运行) |
npm run pwb -- --positron-build=<run|file> |
用 GitHub Actions 运行产物或本地 tarball 替换官方 Positron 构建 |
npm run pwb -- --vsix=<file> |
为 user1 安装扩展 .vsix,可重复指定 |
npm run pwb -- --ttl N |
设置自动停机时间为 N 分钟;--no-ttl 关闭 |
npm run pwb -- status |
显示容器、已安装版本与 URL |
npm run pwb -- logs [svc] |
跟踪日志:rserver(默认)、connect 或容器名 |
npm run pwb -- shell [svc] |
进入容器 shell:test(默认)、postgres 或 connect |
npm run pwb -- --os=<os> |
测试容器宿主 OS:ubuntu24(默认)、rocky9 或 opensuse15 |
npm run pwb -- stop |
暂停栈(容器停止、卷保留) |
npm run pwb -- down |
拆除栈(移除容器与卷) |
自动停机(Auto-stop)机制
默认情况下,栈会在 60 分钟后自动停止——因为你是通过浏览器工作而非容器,容易忘记关闭它空耗 CPU。其实现位于 wb_schedule_ttl(workbench-local.sh):
- 每次
npm run pwb都会重置计时器(先取消旧定时器再调度新定时器); - 定时器用
nohup挂起一个后台进程,只停止它被调度时对应的那个容器实例(通过docker inspect记录的容器 ID 比对),因此你手动重启后,旧的定时任务不会误杀新实例; - 可用
--ttl N调整分钟数,--no-ttl关闭,或直接在.env中设置WB_TTL_MINUTES。
版本选择器与固定构建
交互式选择
- Positron:先选 Release 或 Daily 频道,再选具体版本。版本列表分别来自
posit-dev/positron的正式 Release(prerelease=false)与posit-dev/positron-builds的构建标签(见wb_list_positron_releases/wb_list_positron_dailies,workbench-local-lib.sh)。 - Workbench:Release 或 Daily 都解析为该频道当前唯一构建(Posit 只发布当前 stable 与当前 daily,与 workbench-nightly CI 一致),或粘贴自定义包 URL 来固定某个具体构建。URL 在安装前会被检查格式、架构与可达性——包括包格式是否匹配目标 OS:比如给
rocky9栈钉一个.deb会在安装前直接拒绝,而不是等到安装时失败。
非交互式运行(CI / Agent / 管道)
选择器从 /dev/tty 读取输入,因此 Agent、cron 或管道运行无法应答。此时必须在命令里显式命名构建:
npm run pwb -- --workbench=daily --positron=release
npm run pwb -- --reinstall --workbench=daily --positron=daily
# 固定精确构建
npm run pwb -- --workbench=https://dl.dailies.rstudio.com/.../rstudio-workbench-...deb --positron=2026.08.0-304
规则:release / daily 解析该频道当前构建,其他值原样使用(--workbench 用包 URL,--positron 用构建标签)。.env 中的 WB_WORKBENCH / WB_POSITRON 效果相同。没有 TTY 且未传这些参数时,运行会停下并提示你该传什么,而不是默默安装列表里第一个构建(wb_menu 中的 read ... </dev/tty 失败即触发该提示)。
需要留意:跑依赖新 Positron 特性的 e2e 套件(例如 Data Connections)时需 --positron=daily;release 构建可能太旧,测试会因找不到 UI 元素而失败,而非真实缺陷。
环境变量兜底
.env 变量与命令行参数等价:WB_WORKBENCH、WB_POSITRON、WB_OS、WB_TTL_MINUTES、WB_PASSWORD、WB_CONTAINER_ARCH 等。命令行参数优先级高于 .env(cmd_up 中显式处理:--os 胜于 .env 胜于 ubuntu24 默认值)。
测试自定义 Positron 构建(--positron-build)
要在一个分支里试用 Workbench,可以把它构建替换掉官方 Positron:
npm run pwb -- --positron-build=<run ID 或 run URL>
npm run pwb -- --positron-build=path/to/positron-workbench-linux-x64-branch.tar.gz
为什么必须由 CI 构建
Workbench 运行的是 Positron 的独立变体——vscode-reh-web-pwb-linux-<arch> 构建,且必须在 Linux 上构建;同时它还需要替换成 Workbench 的许可密钥,否则 Workbench 拒绝接受、每个会话启动即退出。CI 工作流 build-workbench-linux.yml 同时完成这两件事(用 scripts/replace-license.sh 把 remoteLicenseKey.ts 中的默认公钥替换为测试密钥,再执行 npm run gulp vscode-reh-web-pwb-linux-x64)。因此最省事的途径是让 CI 出构建,二选一:
-
在 PR 描述中放
@:workbench,每次 push 都会构建并跑该 lane 的 e2e 测试;或 -
在分支上以仅 Workbench lane 的方式启动全量套件工作流:
gh workflow run test-full-suite.yml --ref <branch> -f run_e2e_linux=false -f run_e2e_windows=false -f run_e2e_browser=false -f run_ext_host_tests=false -f run_e2e_workbench=true
构建任务结束后,把该 run 的 ID 或 URL 传给 --positron-build。后续的 Workbench e2e 测试可以取消——构建已经上传完毕。CI 保留该 artifact 仅 1 天,所以脚本把下载保留在 docker/environments/wb-local/.builds(只保留最新一份),便于在 down 或 --reinstall 后重新应用。run URL 可以指向任意仓库,因此 positron-builds 的 release run 也可用。
替换流程与状态
- 构建被放到安装器放置 Positron 的位置(
positron-server/new或positron-server本身,视是否存在bundled目录而定),status会显示为Positron build; - 它跨
stop与重启保留;--reinstall或down会把官方 Positron 放回去; - 触碰栈之前,脚本会检查下载物是否为该容器架构的 Workbench 构建(
wb_build_tarball_arch依据 tarball 顶层目录名vscode-reh-web-pwb-linux-<arch>与文件名判断); - 若构建仍携带默认许可密钥(通过
wb_default_license_needle从仓库源码 remoteLicenseKey.ts 读取公钥第二行并与out/server-main.js/out/vs/server/node做 grep 比对),脚本会给出警告。
Apple Silicon 上的注意事项
CI 只为 linux-x64 构建 Workbench tarball,因此它无法直接运行在 Apple Silicon 默认获得的 arm64 容器中。把栈切换到模拟的 amd64 容器,在 .env 中添加:
WB_CONTAINER_ARCH=amd64
这会重建容器,所以下一次运行会重新安装,且模拟环境下一切都会变慢(与 --os=opensuse15 的情况相同)。务必把它留在 .env 中而不是单次传入:不带该变量的一次运行会把容器重建回 arm64。反之,positron-builds 的 release run 带有 arm64 构建,无需任何处理。
扩展安装(--vsix)
--vsix=<file> 用 Positron 自己的 CLI 为 user1 安装扩展(与会话内 “Extensions: Install from VSIX” 走同一代码路径:sudo -u user1 -H <positron-server>/bin/positron-server --install-extension),可重复传入安装多个。重载已打开的会话即可生效。
有个值得注意的行为:Positron 构建变更后,其首次会话会重装它捆绑的扩展,若捆绑副本比你的新,会替换掉你装的版本。脚本会在此情况发生时给出警告——先启动一个会话,再执行同样的 --vsix 即可让安装保留下来。
选择测试容器 OS
栈默认运行在 Ubuntu 24 上。传 --os=(或 .env 中设置 WB_OS),即可在其他 e2e lane 覆盖的 OS 上运行同样的 Workbench + Positron 安装:
--os= |
OS | e2e lane | PR tag |
|---|---|---|---|
ubuntu24 |
Ubuntu 24.04 | workbench(默认) |
@:workbench |
ubuntu24 |
Ubuntu 24.04,最新稳定版 Workbench | workbench-stable |
@:workbench-stable |
rocky9 |
Rocky Linux 9 | workbench-rocky |
@:workbench-rocky |
opensuse15 |
openSUSE Leap 15.6 | workbench-suse |
@:workbench-suse |
@:workbench-all 是三条 OS lane(Ubuntu + Rocky + openSUSE)同时覆盖的简写,适合需要全平台验证的改动。它取代那三个 tag 而非叠加——同时带 @:workbench-all 和例如 @:workbench-rocky 的 PR 只会报告 @:workbench-all。它不隐含 @:workbench-stable,后者改变的是 Workbench 版本而非 OS。
npm run pwb -- --os=rocky9 --workbench=daily --positron=daily
npm run pwb -- --os=opensuse15 --workbench=daily --positron=daily
OS 差异的底层处理
OS 之间的差异远不止基础镜像,全部由脚本处理。两个 rpm 系 OS 安装 .rpm 而非用 apt 装 .deb:Rocky 从 feed 的 rhel9 条目用 dnf 安装,openSUSE 从 opensuse15 条目用 zypper 安装。所有 OS 事实(包扩展名、文件名前缀、feed 键中的架构 token、容器镜像、存在哪些架构)都收敛在 wb_os_* 系列辅助函数(workbench-local-lib.sh)中,并有一份纯 bash 编写的离线单元测试 scripts/test/workbench-local-lib-test.sh 用 fixture 数据验证 URL 解析与架构重写逻辑。
值得注意的架构细节:feed 的 key 词汇与文件名词汇不同——rhel9 feed 的 key 把 arm64 写作 arm64,但文件名写作 -aarch64.rpm;stable URL 解析(wb_resolve_stable_url)对 Rocky 的路径段与文件名 token 分别重写(路径 /x86_64→/arm64、文件名 -x86_64.rpm→-aarch64.rpm)。
Workbench 在 supervisord 下运行
无论哪个 OS,安装器都会把 rserver 与会话启动器(session launcher)置于 supervisord 之下(Ubuntu 的 universe 仓库、Rocky 的 EPEL、openSUSE 主仓库提供该包),与 Posit 自己的 Workbench 容器镜像一致。原因是:这些容器没有 systemd,而软件包自带的 SysV init 脚本在容器内看不到自己的进程——stop 曾是静默空操作,restart 会再起一个 rserver 卡死在 “Address already in use” 上。supervisord 按 pid 跟踪子进程,因此常用动词语义准确,且崩溃的 rserver 会自动重启。配置位于 /etc/supervisord.conf,supervisorctl 无需 -c 即可找到(该路径在三套 OS 上都在默认搜索顺序首位):
docker exec test sudo supervisorctl status
docker exec test sudo supervisorctl restart rstudio-server # CI action 与 enforced-settings 测试所做的事
docker exec test sudo supervisorctl start all # npm run pwb 在容器 stop/start 后所做的事
注意:重启 rstudio-launcher 会结束所有正在运行的会话,所以除非你就是要测试 launcher,否则只重启 rstudio-server。
从 install-workbench.sh 的实现可见更多细节:安装器会写一个 rserver-foreground 包装脚本,先等待 launcher 的 socket(/var/run/rstudio-server/rserver-launcher.socket)就绪再执行 rserver --server-daemonize 0,解决 rserver 启动时因 socket 缺失而自我关停的问题;同时为 rstudio-server 程序启用 stopasgroup/killasgroup,让 rserver-http(nginx 前端)与 rserver-monitor 随主进程一起停止,避免孤儿 rserver-http 一直占住 8787 端口。
openSUSE 在 Apple Silicon 上以模拟方式运行
Posit 只为 x86_64 发布 openSUSE 15 的 Workbench 包(daily 与 stable feed 均如此),不像 rhel9 和 noble 有 arm64 构建。因此在 Apple Silicon 上 --os=opensuse15 会把 test 容器强制为 linux/amd64 并在模拟下运行——运行开始时脚本会明确告知。它可用(CI 就是原生这么跑的),但安装与测试会明显慢于另外两个 OS。若请求 arm64 的 openSUSE 构建,会以明确消息快速失败(wb_os_supports_arch 直接拒绝),而不是静默下载 x86 的 rpm。
切换 OS 必然重装
--os 改变 compose 的 image:,Compose 会重建 test 容器,从而清空容器内安装——切换 OS 总是触发重装,运行时会提前告知。本地同时只能运行一个栈,因为 compose 文件钉死了 container_name 与固定主机端口。
栈已存在时,裸 npm run pwb 会停留在当前 OS(“sticky OS”逻辑:读取运行中容器的镜像反推 OS),因此恢复一个 Rocky 栈不会悄悄重建为 Ubuntu。要刻意迁移,请显式传 --os(或设置 WB_OS)。
受管数据源凭据(Managed credentials)
要测试 Positron 的受管数据源连接(Workbench 交给会话的凭据),用 --credentials=<type> 安装。每次安装只配置一种 provider;用 --reinstall --credentials=<type> 切换。
| Type | 配置内容 | 从 .env 读取 |
|---|---|---|
databricks |
/etc/rstudio/databricks.conf + databricks-enabled |
DATABRICKS_URL_、DATABRICKS_CLIENT_ID_ |
snowflake |
/etc/rstudio/snowflake.conf + allow-refresh-snowflake-roles |
SNOWFLAKE_ACCOUNT_、SNOWFLAKE_CLIENT_ID_、SNOWFLAKE_CLIENT_SECRET_ |
azure |
rserver.conf 中的 OpenID 认证 + openid-client-secret + JIT home 目录 |
AZURE_SERVICE_PRINCIPAL_CLIENT_SECRET_ |
操作步骤:
-
把所用 provider 的值填入
docker/environments/wb-local/.env(模板见 .env.example)。每个值都要用单引号包裹——.env由 shell 直接 source,含$、空格或#的密钥会被截断(或直接报错)。名字末尾的下划线本地可省略;裸名(如SNOWFLAKE_ACCOUNT,即 1Password / GitHub secrets 中存储的形式)会被当作别名接受(wb_map_credential_aliases实现;带下划线的正式名优先,因其与 Snowflake/Databricks SDK 自动读取的裸名冲突)。 -
用该 flag 安装:
npm run pwb -- --credentials=snowflake若所选 provider 的变量未设置,安装会快速失败(configure-datasources.sh 对每个 provider 都先检查必需变量,缺失即
exit 1)。
实现细节(configure-datasources.sh):databricks 会从 URL 提取工作区名生成 [workspace] 配置节并追加 databricks-enabled=1;snowflake 生成账户配置节并追加 allow-refresh-snowflake-roles=1;azure 追加 auth-openid=1 等 OpenID 设置、写入 0600 权限的 openid-client-secret,并在 /etc/pam.d/common-session 中加入 pam_mkhomedir.so 以实现首次登录 JIT 创建 home 目录。
服务访问地址
| 服务 | URL | 登录 |
|---|---|---|
| Workbench | http://localhost:8787 | user1 / WB_PASSWORD(来自 docker/environments/wb-local/.env) |
| Connect | http://localhost:3939 | 每次运行 bootstrap 生成 |
Connect 的 API token 由 ensure-connect-token.sh(docker/environments/wb-local/ensure-connect-token.sh)用 rsconnect bootstrap 获取并写入共享卷 /tokens/connect_bootstrap_token,已有则直接复用。
故障排查
首次登录报 "Forbidden"
清除 localhost 域下的 vscode-tkn cookie 后刷新即可。
每个 Positron 会话启动约 35 秒后退出
现象是弹出 “Session Exited” 对话框。检查 launcher 日志中的 checkExited ... [description: End of file]:
docker exec test bash -c 'grep checkExited /var/log/rstudio/launcher/rstudio-local-launcher-*.log | tail -3'
这是 Workbench launcher 放弃了一个仍在运行的会话,并非 Positron 故障。该问题曾出现在 Workbench 2026.10.0-daily+140,在 +190 中消失。裸 npm run pwb 只会恢复已安装的 Workbench 而不会更新它,因此用当前版本重装:
npm run pwb -- --reinstall --workbench=daily --positron=daily
随后重新应用任何 --positron-build。
自定义构建的会话立即退出
会话输出(/var/lib/rstudio-launcher/Local/output/user1/*.stderr)报 Invalid license key; signature is invalid:说明该构建仍带有默认许可密钥。参见上文“测试自定义 Positron 构建”。
同一时间只能有一个栈
因为 container_name: test 被钉死。要对比两个 Workbench 版本,先 down 一个再拉起另一个。
Apple Silicon:Connect 服务慢
Connect 以模拟(amd64)方式运行,启动缓慢,属预期行为。
dependency failed to start: container connect is unhealthy
通常与 Connect 许可有关。Connect 无论如何都会启动,所以检查它认为自己持有什么:
docker exec connect /opt/rstudio-connect/bin/license-manager status
若 "License file status" 为空且显示 Has-Key: No,说明文件根本没被解析,所有请求都会返回 402。CRLF 换行的许可文件正是这种表现(见下文 Windows 一节);缺失或过期的许可同样如此。
Windows 支持细节
该工具支持 Windows x64(与 CI 安装的 amd64 包相同)。命令可在 PowerShell 或 Windows Terminal 中照常运行;脚本本身在 Git Bash 下执行,你无需打开 Git Bash 窗口。
唯一的额外设置步骤是让 npm 指向 Git Bash:
npm config set script-shell "C:\Program Files\Git\bin\bash.exe"
否则 npm 会通过 cmd.exe 运行脚本,其中裸 bash 解析为 C:\Windows\System32\bash.exe——即 WSL 启动器——脚本会跑进一个通常没有可达 Docker daemon、也没有 gh 的 Linux 发行版里。脚本能检测出这种情况并明确告知(wb_check_shell 检查 /proc/version 是否含 microsoft,再验证 docker info 是否可达),而不是以晦涩错误失败。真正配好了 WSL 集成、能触达 Docker 的环境可以正常通过检查。
Windows 上还有两点行为差异:
- 优先使用 PowerShell 或 Windows Terminal,而非 mintty(Git Bash)窗口。
npm run pwb -- shell执行docker exec -it,fzf选择器也需要真正的 Windows 控制台;mintty 不算。 - 许可文件必须是 LF,不能是 CRLF。Connect 拒绝解析 CRLF 许可并永远以 402 应答,rstudio-server 则直接拒绝。现在两者在进入容器时都会做 CR 清洗(脚本与许可文件都经过
sed -i 's/\r$//',Connect 许可在cmd_up中经tr -d '\r'转写后原子替换到connect/connect.lic),因此在 Windows 上保存的许可也能被处理;但若以其他方式触发,参见故障排查。
从源码理解整体工作流
一次 npm run pwb 的完整调用链(workbench-local.sh 的 cmd_up):
- 解析参数(
--reinstall、--ttl、--os、--positron-build、--vsix等); - 检测架构(
wb_detect_arch),并处理 OS 与平台强制(含 Apple Silicon 模拟场景); wb_bootstrap_env从.env.example生成并 source.env,映射凭据别名,必要时从 tty 读取WB_PASSWORD;wb_ensure_auth确保 GitHub 认证与 ghcr.io 登录;- 按需预下载
--positron-build产物并校验架构; - 处理 Connect 的
CONNECT_BOOTSTRAP_SECRETKEY(首次用openssl rand -base64 32生成并持久化到.env)与connect.lic(CR 清洗、原子落盘); docker compose up -d --remove-orphans拉起三容器栈并等待test健康;wb_fetch_scripts把安装器脚本拷入容器并做 CR 清洗、加执行权限;- 已安装且非
--reinstall:wb_ensure_workbench恢复 supervisord 与 rserver,应用自定义构建与 vsix,打印就绪状态,调度 TTL; - 否则
cmd_install:选择 Workbench URL 与 Positron tag → install-workbench.sh 在容器内完成建用户、装 Workbench 包、下载 Positron(positronDownload.sh 从positron-buildsrelease 资产按 tag 与架构取positron-workbench-linux-<arch>-<tag>.tar.gz)、配置数据源、以 supervisord 启动服务。
其中 Workbench 包 URL 的解析(release/daily 频道、arm64 重写、格式/架构/可达性校验)全部收敛在 workbench-local-lib.sh,并被 host 侧选择器、容器内安装器(install-workbench.sh 与 get-latest-wb-url.sh)三处复用,配合 scripts/test/workbench-local-lib-test.sh 的离线测试保证规则一致。
这套环境与仓库 CI 深度同源:Workbench e2e lane 的编排(test-full-suite.yml 中的 build-workbench → e2e-workbench → e2e-workbench-rocky → e2e-workbench-suse → e2e-workbench-stable 串行链)使用的正是同一套 Docker 栈与安装逻辑。因此 npm run pwb 既是本地开发/QA 工具,也是理解 Positron Workbench CI 测试链路的可运行缩影。