部署到 Posit Connect
本指南涵盖 Connect 服务器上的 Python、R 与静态内容。 已注册的 Connect Model Context Protocol(MCP)服务器也可以提供发布工具。
根据内容类型与可用工具选择部署路线:
- Python — posit-cli,提供
positCLI,发布在 PyPI 上。其posit connect命令封装了 rsconnect-python。 - R — 指向 Connect 服务器的 R
rsconnect包。 - 已注册的 Connect MCP 服务器 — 当其发布工具支持该内容时,使用其发布工具。
如果用户是在提问("我该怎么做…"、"命令是什么…")而不是要求部署,请根据本指南回答并停止。
最后,报告你部署到了哪台服务器、选择了哪种内容类型、安装了哪些工具,以及做了哪些假设。
阶段 1 — 识别内容
从项目目录中的文件推断语言与框架。常见信号:
| 项目目录中的信号 | 可能的内容 |
| --- | --- |
| app.py | Python Web 应用 — Shiny for Python、Streamlit、Dash、Gradio、Panel 或 Bokeh |
| app.R,或 ui.R + server.R | Shiny for R |
| 包含 plumb() 的 plumber.R / entrypoint.R | Plumber API(R) |
| *.qmd | Quarto 文档 |
| *.Rmd | R Markdown |
| *.ipynb | Jupyter notebook / Voila |
| index.html,或包含 HTML、CSS、JavaScript 或图片文件的目录 | 静态 HTML 站点 |
| manifest.json | 预构建包 — 直接部署,无需猜测框架 |
| 单独的 .py 或 .R — 没有框架导入,旁边也没有 ui.R/server.R/plumber.R/entrypoint.R | 脚本 — 可由 Quarto 渲染、Connect 可调度执行的批处理/ETL 作业 |
确认推断
app.py 中的导入语句指明了框架:
grep -Eo 'import (shiny|streamlit|dash|gradio|panel|bokeh)|from (shiny|streamlit|dash|gradio|panel|bokeh)' app.py
裸的 ASGI 或 WSGI 对象意味着是 fastapi 或 flask。
依赖文件可以确认语言:Python 用 requirements.txt 与 pyproject.toml,R 用 DESCRIPTION 与 renv.lock。
只有当脚本以 front-matter 注释开头时,Quarto 才能渲染脚本:Python 中是围绕 --- 块的 # %% [markdown],R 中是 #' ---。大多数脚本缺少这一块 — 部署前先补上(阶段 5)。
如果内容不明确(同时存在 Python 与 R 文件,或 app.py 中没有可识别的导入),请自行判断,并报告你所做的假设。
阶段 2 — 盘点可用工具
探测环境并建立能力集合:
command -v posit # PATH 中的 posit-cli
command -v rsconnect # PATH 中的 rsconnect-python
command -v uv # uv(安装并运行 Python 工具)
uv tool list 2>/dev/null | grep posit-cli # 通过 uv 安装的 posit-cli
command -v Rscript # 存在 R
Rscript -e 'cat(requireNamespace("rsconnect", quietly=TRUE))' 2>/dev/null # R rsconnect 包
command -v quarto # quarto CLI
command -v git # git
如果存在 uv,Python 内容无需安装步骤。uv tool run --from posit-cli posit ... 会按需获取并运行 CLI。
如果已注册经过认证的 Connect MCP 服务器,请把它的发布工具纳入能力集合。
阶段 3 — 选择路线
将检测到的内容(阶段 1)与你的能力(阶段 2)交叉匹配。
已注册的 Connect MCP 服务器
如果已注册的 Connect MCP 服务器为该内容提供了发布工具,请遵循该服务器给出的指引。 否则,使用下方的发布客户端。
Python 内容
使用 posit-cli。如果 posit 已在 PATH 上:
posit connect deploy <framework> ./my-app
不在 PATH 上但有 uv 时:
uv tool run --from posit-cli posit connect deploy <framework> ./my-app
两种形式的参数完全相同。本指南其余部分使用不带前缀的 posit connect ... 形式。当你使用第二种路线时,在其前面加上 uv tool run --from posit-cli。
posit connect 挂载了完整的 rsconnect 命令集,因此 posit connect <command> 与 rsconnect <command> 接受相同的参数并共享同一批已保存的服务器。如果 rsconnect 在 PATH 上而你无法使用 posit,就用 rsconnect <command> 代替 posit connect <command>。
<framework> 是以下之一:api、bokeh、bundle、dash、fastapi、flask、git、gradio、html、manifest、nodejs、notebook、panel、pyproject、quarto、shiny、streamlit、tensorflow、voila。对于列表之外的内容,posit connect deploy other-content 会打印指引。
框架与参数随安装版本而变,因此请以 posit connect deploy --help 为准,而不是本列表。如果 uv tool run 解析到了陈旧的缓存版本,加 --refresh:uv tool run --refresh --from posit-cli posit ...。
R 内容
使用 R rsconnect 包,通过 Rscript -e '...' 或 R 会话调用:
- Shiny for R、Plumber API 或任何应用目录 →
deployApp() - 单个 R Markdown 或 Quarto 文档 →
deployDoc() - 完整的 R Markdown 或 Quarto 站点 →
deploySite()
如果缺少 Rscript,则通过 posit-cli 使用 manifest.json 部署 R 内容:
- 已存在
manifest.json— 直接部署:posit connect deploy manifest ./manifest.json - 没有 manifest,但其他地方可用 R — 先用
rsconnect::writeManifest()生成一个(见阶段 5)。 - 既没有 R 也没有 manifest — 无法构造有效的 R 包。将此作为阻碍点呈现:询问用户或明确报告。
Quarto 内容
posit connect deploy quarto ./report
带 R 风格的 Quarto(含 R 代码块的 .qmd)需要 R 来渲染。如果缺少 R,把该文档当作 R 内容处理并走 manifest 路线,或者呈现这一缺口。
脚本内容
使用 quarto 框架。先补上 front matter(阶段 5)。
posit connect deploy quarto script.py # Python
rsconnect::deployApp() # R,rsconnect 1.2.2 或更高版本,在脚本所在目录执行
两个命令都会打包目录中的所有文件。一键发布不支持 R 脚本,因此 deployApp() 是 R 的唯一路线。
脚本像 Quarto 文档一样部署,但属于不同的内容类型:.qmd 是供阅读的页面,脚本则是产出输出的作业。
阶段 4 — 确定目标并检查凭据
工具已确定后,弄清要部署到哪台服务器,以及该工具是否已能访问它。这是检查,不是登录。
如果使用发布类 MCP 工具,经过认证的 MCP 连接即为目标。 确认它与用户指定的服务器一致。 如果用户未指定服务器,询问使用哪个目标。 MCP 路线不要检查 CLI 账号或注册服务器。 目标明确后,遵循该服务器的发布指引。
不要在环境中搜索 API 密钥。 不要读取 CONNECT_API_KEY、CONNECT_SERVER、.env 文件、钥匙串条目或任何其他已存储的密钥来挑选目标或注册服务器。仅当用户明确要求时才这样做。存在环境变量不代表要求使用它。
对于 CLI 路线,列出该工具已有的账号。这是唯一需要的 CLI 凭据检查。
posit connect list # Python:已保存的服务器、存储的令牌与默认服务器
Rscript -e 'print(rsconnect::accounts())' # R:已注册的账号
如果工具尚未安装,先在阶段 5 补齐。然后再执行检查。
将结果与用户指定的目标对比。三种结果:
- 有账号与指定目标匹配。 凭据路线可用。不要登录,也不要运行
posit connect add。其余缺口补齐后进入阶段 6。 - 用户未指定目标。 询问他们。列出检查发现的服务器,询问部署到哪一个,或者是否要改用新目标。不要替他们挑选,也不要因为它是唯一保存的服务器就部署过去。
- 目标是新的,或没有账号与其匹配。 这是阶段 5 要解决的缺口。通过浏览器登录注册。
浏览器登录是注册新目标的方式:
posit connect login https://connect.example.com # Python
rsconnect::addServer(url = "https://connect.example.com", name = "myserver") # R
rsconnect::connectUser(server = "myserver")
两种形式都会打开浏览器流程,由用户批准登录,密钥不会经过对话。凭据参考中有细节与常见坑。
阶段 5 — 补齐缺口
当阶段 3 与阶段 4 发现缺口时,先补齐,再把该操作写入报告。
posit 不在 PATH 上。 如果存在 uv,无需安装:
uv tool run --from posit-cli posit connect deploy <framework> ./my-app
如果用户希望持久安装,或 uv tool run 不可行:
uv tool install posit-cli # 或:pip install posit-cli
包名与命令名不同:PyPI 包名是 posit-cli,它提供的命令是 posit。这就是 uv tool run 需要 --from posit-cli 的原因。之后要更新,运行 uv tool upgrade posit-cli。
缺少 R rsconnect 包,但存在 Rscript。 从 Posit Package Manager(P3M)安装,它提供预编译的 Linux 二进制包。二进制安装比源码构建快得多,且不需要 -dev 系统库。二进制包需要两样东西:__linux__/<codename> 仓库地址和标识平台的 HTTPUserAgent。没有用户代理时,P3M 会回退到源码。
export P3M="https://packagemanager.posit.co/cran/__linux__/$(. /etc/os-release && echo "$VERSION_CODENAME")/latest"
Rscript -e '
options(HTTPUserAgent = sprintf("R/%s R (%s)", getRversion(),
paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))
install.packages("rsconnect", repos = Sys.getenv("P3M"))
'
P3M 为常见发行版的 x86_64 提供二进制包。在 arm64 或不受支持的发行版上,P3M 会回退到源码。结果依然正确,只是更慢,且需要常规的 -dev 库与编译器。仅在 P3M 不可达时才使用 https://cloud.r-project.org(CRAN 源码)。
R 内容缺少 manifest.json,但 R 可用。 生成它:
Rscript -e 'rsconnect::writeManifest()'
posit-cli 会为 Python 内容生成:
posit connect write-manifest <framework> ./my-app
如果 R 无法直接部署,再用 posit-cli 部署该 manifest。
脚本缺少 front matter。 在文件顶部补上最小块。Connect 从 title 读取内容标题,所以要写成描述性的。
Python:
# %% [markdown]
# ---
# title: "Data processing script"
# ---
R:
#' ---
#' title: "Data processing script"
#' ---
目标缺少 CLI 账号。 现在通过浏览器登录注册:Python 用 posit connect login,R 用 rsconnect::addServer() 与 rsconnect::connectUser()。凭据参考中有细节与常见坑。不要退而求其次去用环境中的 API 密钥。如果浏览器流程不可用,报告并停止。
依赖。 rsconnect 与 posit-cli 会扫描代码并为所需包版本做快照,因此很少需要手工列清单。Python 内容需要 requirements.txt。对于 R,内容自身用到的包必须已在本地安装,rsconnect 才能检测到 — Plumber API 用 plumber,Shiny 应用用 shiny。缺少的包从上文同一个 P3M 仓库安装。
阶段 6 — 部署并处理失败
探明实际可用的命令面(Python)
框架与参数在不同版本间会变化,帮助文本才是权威来源:
posit --version # 你实际运行的 posit-cli 版本
posit connect deploy --help # 可部署的每个框架
posit connect deploy <framework> --help # 单个框架的参数
posit connect version 报告的是 Connect 服务器的版本,不是 CLI 的版本。
部署
对于 Python,用阶段 3 选定的框架运行 posit connect deploy <framework> <dir>。manifest 框架接受的是 manifest 文件而非目录。
容易忽略的参数:-t/--title、-N/--new(强制新建部署而不是更新已记录的部署)、-a/--app-id <id>(显式指定既有条目,与 --new 互斥)、-E NAME=VALUE(设置环境变量,可重复)、--draft(发布前继续提供旧的包)。
对于 R,调用阶段 3 选定的函数。传入 appTitle,避免内容以目录名命名。
脚本部署会打包整个目录。如果目录中还有脚本用不到的文件,收窄选择范围:在 Python 中点名文件(posit connect deploy quarto script.py helper.py data.csv),或在 R 中传入 appFiles(rsconnect::deployApp(appFiles = c("_quarto.yml", "script.R")))。含 _quarto.yml 的目录是 Quarto 项目 — 用 posit connect deploy quarto . 整体部署。
部署时找不到 posit
可能已安装但不在当前 shell 的 PATH 上。IDE 启动的终端与已激活的虚拟环境都会导致这种情况。按阶段 5 所述回退到 uv tool run,并带 --from posit-cli。
部署前检查(可选)
部署前确认目标可达且凭据有效:
posit connect details -n myserver
部署失败时
Python:
- 认证错误 — 用
posit connect list确认目标,然后重新运行posit connect login。仅当用户让你使用既有密钥时才传-s/-k。 -n/--name ... cannot be specified in conjunction with ... -s/--server (from ENVIRONMENT)— 设置了CONNECT_SERVER且你又传了-n。运行unset CONNECT_SERVER并保留-n。凭据参考解释了为什么选择这个方向。CONNECT_API_KEY可以保留。The requirements file 'requirements.txt' does not exist— Python 内容需要该文件。创建它,用--requirements-file指向另一个文件,或用--force-generate生成。最后一个选项运行pip freeze,可能锁定得过严。- 自签名 TLS — 使用
-i/--insecure或-c/--cacert <file>。设置CONNECT_INSECURE或CONNECT_CA_CERTIFICATE可全局生效。 - 参数被拒或框架未知 — 重新检查
posit --version并重新阅读posit connect deploy <framework> --help。已安装版本通常比你使用的参数更旧。 - 部署后的脚本渲染为空或损坏 — 服务器缺少 Quarto 1.4+、Jupyter(Python 脚本)或
rmarkdown(R 脚本)。部署本身已成功,不要重试。报告缺失的服务器依赖。
R:
- "No account" 或认证错误 — 运行
rsconnect::accounts()。如果为空,重新运行rsconnect::addServer(),然后connectUser()或connectApiUser()。确认你用的是服务器函数而不是connectCloudUser()。 Found multiple accounts. Please disambiguate by setting server and/or account— 关联了多个账号。在部署调用中显式传入account =与server =。交互式 R 会话会显示菜单,这会让无头运行卡住。- 部署函数用错 — 目录与应用用
deployApp(),单个文档用deployDoc(),站点用deploySite()。 - 自签名 TLS — 通过
curl选项传入 CA 包,或带证书添加服务器。快速测试时可设置options(rsconnect.check.certificate = FALSE)。 - 绝对路径警告 — 硬编码绝对路径的文件不会阻止部署,但最好改为相对项目目录的路径。
凭据参考
针对阶段 4 未找到账号的目标,如何注册。如果已有账号与目标匹配,则无需以下任何操作。
首选浏览器登录。其下的 API 密钥路线只适用于一种情况:用户明确告诉你使用一个已存在的密钥,位于环境变量或凭据存储中。不要自行寻找密钥,也绝不要向用户索要。API 密钥不应出现在对话中。
Python(posit-cli)
- OAuth 登录(交互式)。 默认路线。每台服务器一次浏览器流程。令牌保存在操作系统钥匙串或本地凭据存储中,并自动刷新。
posit connect login https://connect.example.com posit connect login https://connect.example.com --use-device-code # 无头模式 - 已保存的 API 密钥昵称。 仅当用户要求走密钥路线时。保存一次,之后用
-n/--name选择。
服务器可以设为默认值,当命令既不传posit connect add -n myserver -s https://connect.example.com -k <api-key> posit connect list # 确认已保存的内容-n也不传-s时使用。add只在传--set-default时才设置默认;login会设置默认,除非传--no-set-default。之后可用posit connect server set-default -n <name>更改。CONNECT_SERVER仍然优先于默认值。 - 环境变量。 仅当用户要求使用时。posit-cli 直接读取它们,适用于无需管理状态的无头或自动化运行。
export CONNECT_SERVER=https://connect.example.com export CONNECT_API_KEY=... # 在整个 `posit connect` 命令面生效 - 临时参数,加在部署命令上:
-s <url> -k <api-key>。同样的前提,并从用户指定的变量读取密钥,而不要直接写出。
共享凭据参数:-n/--name(已保存的服务器)、-s/--server(环境变量 CONNECT_SERVER)、-k/--api-key(环境变量 CONNECT_API_KEY)、-i/--insecure(环境变量 CONNECT_INSECURE,用于自签名 TLS)、-c/--cacert <file>(环境变量 CONNECT_CA_CERTIFICATE)。
-n与CONNECT_SERVER不能同时生效。posit-cli 会拒绝把已保存服务器名(-n/--name)与服务器地址组合的命令,包括来自环境变量的地址:-n/--name (from COMMANDLINE) cannot be specified in conjunction with options -s/--server (from ENVIRONMENT)。只有服务器存在冲突。
CONNECT_API_KEY、CONNECT_INSECURE与CONNECT_CA_CERTIFICATE可以与-n并存而不报错,因为密钥不在排除范围内。-n dogfood加上导出的CONNECT_API_KEY是有效命令。必须去掉的是CONNECT_SERVER。按请求所指来选择,而不是按碰巧导出了什么:
- 请求点名了已保存的服务器("部署到 dogfood")— 使用
-n dogfood并在该命令中unset CONNECT_SERVER。反方向解决冲突更糟:CONNECT_SERVER可能指向完全不同的地方,因此去掉-n保留它会部署到用户没有要求的服务器。- 请求未点名服务器,即典型的无头运行 — 让
CONNECT_SERVER与CONNECT_API_KEY提供目标,并用posit connect deploy <framework> <dir>部署。
CONNECT_SERVER不是机密。不确定它指向哪台服务器时可以打印出来,并在报告中写明你部署到的服务器。
R(rsconnect)
先以本地昵称注册服务器,再针对它注册用户:
library(rsconnect)
# 1. 服务器(每台服务器一次;名称是本地昵称)
rsconnect::addServer(url = "https://connect.example.com", name = "myserver")
# 2a. 交互式 — 在浏览器中批准,无需经手密钥
rsconnect::connectUser(server = "myserver")
# 2b. 或非交互式(CI),仅当用户要求走密钥路线时
rsconnect::connectApiUser(
server = "myserver",
account = "your-username",
apiKey = Sys.getenv("CONNECT_API_KEY")
)
connectCloudUser() 针对的是 Connect Cloud,这是另一项服务,因此对 Connect 服务器无效。这里请使用 connectUser() 或 connectApiUser()。
登录路线不可用时
报告并停止。写明你尝试注册的服务器以及哪个登录命令失败了。不要到环境、.env 文件或凭据存储中搜索密钥来填补缺口,也不要向用户索要密钥。下一步由用户决定。

Scan to join WeChat group