StarModel invitation
← Back to skills
extension
Category: OtherAPI key required

应用部署发布管理

将 Python 与 R 项目内容部署或发布到 Connect 服务器,覆盖交互式应用、仪表盘、Web API、渲染文档与预构建包等内容类型,自动检测项目语言与框架,选择合适的部署工具与命令,核对目标服务器与账号凭据,补齐依赖与环境缺口,并在部署失败时定位原因给出修复方向,最终报告部署目标、内容类型与所做假设,避免凭空猜测命令参数导致发布出错。Use when 用户需要将应用、文档或 API 部署发布到 Connect 服务器时使用。Triggers include 部署、发布、rsconnect、重新部署、内容上线如需完整版,请淘宝搜索店铺「AI灵匣」

personAuthor: u_1ea983achubenterprise
<!-- 维护者说明:请仅在 posit-dev/connect 中编辑本技能。 下游副本会由同步工作流覆盖。 -->

部署到 Posit Connect

本指南涵盖 Connect 服务器上的 Python、R 与静态内容。 已注册的 Connect Model Context Protocol(MCP)服务器也可以提供发布工具。

根据内容类型与可用工具选择部署路线:

  • Python — posit-cli,提供 posit CLI,发布在 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)

  1. OAuth 登录(交互式)。 默认路线。每台服务器一次浏览器流程。令牌保存在操作系统钥匙串或本地凭据存储中,并自动刷新。
    posit connect login https://connect.example.com
    posit connect login https://connect.example.com --use-device-code   # 无头模式
    
  2. 已保存的 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 仍然优先于默认值。
  3. 环境变量。 仅当用户要求使用时。posit-cli 直接读取它们,适用于无需管理状态的无头或自动化运行。
    export CONNECT_SERVER=https://connect.example.com
    export CONNECT_API_KEY=...        # 在整个 `posit connect` 命令面生效
    
  4. 临时参数,加在部署命令上:-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 文件或凭据存储中搜索密钥来填补缺口,也不要向用户索要密钥。下一步由用户决定。