Posit Connect

概述

Posit Connect 是一个用于在组织内部安全共享数据产品的发布平台。当你希望在组织内部发布内容而不是在公共互联网上发布时，请使用 Posit Connect。

有几种方法可以将 Quarto 内容发布到 Posit Connect：

使用 quarto publish 命令发布本地渲染的静态内容。
使用 rsconnect-python Python 包或 quarto R 包将用于在 Posit Connect 服务器上渲染的代码发布（例如，用于计划报告）。
使用 Connect 对 Git 支持的内容的支持，当代码被签入 Git 仓库时自动重新发布内容。
使用 Jenkins、Airflow 或 GitHub Actions 等持续集成（CI）服务，渲染并发布到 Connect。

下面将详细介绍每种选项。如果你刚刚开始，我们强烈建议使用第一种方法（quarto publish）。然后，随着你的需求发展，你可以考虑其他更复杂的选择。

发布命令

quarto publish 命令是发布本地渲染内容的最简单方法。从你的项目所在的目录中，执行 quarto publish 命令以发布到 Connect：

终端

quarto publish connect

如果你之前没有发布到 Connect，系统会提示你输入服务器的 URL：

终端

$ quarto publish connect
 ? 服务器 URL: ›

然后，你需要提供一个 Connect API 密钥：

终端

$ quarto publish connect
 ? 服务器 URL: › https://connect.example.com/
 ? API 密钥: ›

认证后，你的内容将被渲染并发布，然后浏览器将打开以查看其在 Connect 上的管理页面。

你之前的发布记录将存储在项目或文档目录中的 _publish.yml 文件中。该文件存储了已发布内容的服务、ID 和 URL。例如：

- source: project
  connect:
    - id: "3bb5f59f-524a-45a5-9508-77e29a1e8bf0"
      url: "https://connect.example.com/content/3bb5f59f-524a-45a5-9508-77e29a1e8bf0/"

账户信息不存储在此文件中，因此适合签入版本控制并与多个发布者共享。

你可以通过提供以下命令行选项来自定义 quarto publish 的行为：

选项	行为
`--no-prompt`	不提示确认发布操作。
`--no-browser`	发布后不打开浏览器。
`--no-render`	发布前不重新渲染。

要发布文档而不是网站或书籍，请提供文档的路径：

终端

quarto publish connect document.qmd

使用代码发布

在前面的示例中，我们在本地渲染内容，然后将其发布到 Connect。然而，在某些情况下，你可能希望将源代码发布到 Connect，然后在服务器上渲染它（例如，创建一个自动更新新数据的计划报告）。

发布代码的工具因你使用的是 Knitr（R）还是 Jupyter（Python）引擎而异，因此我们将在下面分别介绍它们。请注意，在尝试使用代码发布之前，必须在 Connect 服务器上安装 Quarto（这通常由管理员完成，参见 Quarto 安装文档以获取更多详细信息）。

Knitr（R）

quarto R 包包含一组发布函数，你可以使用这些函数将带有 R 代码的 Quarto 项目发布到 Posit Connect。例如，这里我们发布了一个文档和一个网站：

library(quarto)

quarto_publish_doc(
  "document.qmd", 
  server = "rsc.example.com", 
  account = "njones",
  render = "server"
)

quarto_publish_site(
  server = "rsc.example.com", 
  account = "njones",
  render = "server"
)

render = "server" 参数指定了你希望发布代码而不仅仅是内容。

请注意，一旦你首次发布后，可以在不提供显式参数的情况下进行更新：

quarto_publish_site()

有关使用这些函数的更多详细信息，请参阅从 R 发布 Quarto 的文章。

RStudio IDE

如果你使用的是 RStudio IDE，还支持一键发布到 Posit Connect。使用源编辑器或查看器窗格中的发布按钮来发布文档或网站：

请参阅从RStudio IDE发布的Connect文档以获取更多详细信息。

Jupyter (Python)

rsconnect-python Python包提供了一个命令行界面（CLI），您可以使用它将使用Jupyter的Quarto文档和网站发布到Posit Connect。要使用CLI：

首先，安装rsconnect-python包并为发布配置一个Posit Connect服务器：https://docs.rstudio.com/connect/user/connecting-cli/
然后，从您的项目目录中使用rsconnect deploy quarto命令：
```
Terminal
```
```
rsconnect deploy quarto
```

有关使用CLI发布到Connect的更多详细信息，请参阅发布Quarto内容的完整文档。

Notebook插件

如果您使用的是经典的Jupyter Notebook，您可以安装rsconnect-jupyter笔记本插件，以启用Jupyter笔记本的一键发布功能：

首先，按照rsconnect-jupyter的用户指南中的说明安装插件。
然后，点击您希望发布的笔记本中的发布按钮。系统会提示您配置一个Connect服务器，然后会显示一个发布对话框：

有关使用插件的完整文档，请参阅发布Jupyter笔记本的文章。

从Git发布

内容可以直接从远程Git仓库部署到Posit Connect。内容将自动从关联的远程Git仓库获取并重新部署。这允许与以Git为中心的工作流和持续部署自动化集成。

为了将Git支持的内容部署到Posit Connect，您需要遵循两个步骤：

创建并提交一个清单文件（这包括渲染您的内容所需的R或Python依赖项信息）
将Posit Connect链接到Git仓库

请注意，在尝试从Git发布之前，必须在Connect服务器上安装Quarto（这通常由管理员完成，有关更多详细信息，请参阅Quarto安装文档）。

创建清单

有关创建清单并将它们检入到您的仓库的完整详细信息，请参阅Connect文档中的Git支持的内容。为了给您一个大致的概念，以下是一些为Knitr和Jupyter项目创建清单的示例代码：

# 为Knitr项目编写清单
install.packages("rsconnect") # 如果需要
rsconnect::writeManifest()

Terminal

# 为Jupyter笔记本编写清单
pip install rsconnect-python # 如果需要
rsconnect write-manifest notebook MyNotebook.ipynb

有关创建清单的完整详细信息，请参阅Git支持的内容的文档。

连接仓库

Connect用户必须至少拥有publisher角色，才能从Git仓库创建新内容。

在内容页面上，顶部附近有一个标记为发布的按钮。点击此按钮将展开一个菜单，其中包含一个名为“从Git导入”的选项，点击它可以启动一个新的内容向导。

系统会提示您提供仓库URL、要发布的分支以及要发布的目标目录（例如，包含您的manifest.json的目录）。

有关将Git仓库连接到Connect的完整详细信息，请参阅Git支持的内容的文档。

持续集成

您还可以使用Jenkins、Airflow或GitHub Actions等持续集成（CI）服务部署Quarto内容。在大多数情况下，这将涉及编写quarto publish命令的脚本，但在GitHub Actions的情况下，您可以利用标准的Quarto发布操作。

当从CI服务发布到Connect时，您需要考虑是否希望直接在CI服务器上执行您的Python或R代码，或者是否希望利用之前冻结的执行结果。我们将首先探讨这种可能性，然后继续讨论如何从CI发布。

冻结计算

根据你的运行时需求（包、数据库凭证等）的复杂程度，你可能会发现将Python和R代码的执行限制在具有所需软件和凭证的本地环境中更为方便。

为了确保 R、Python 和 Julia 代码仅在本地执行，请通过在 _quarto.yml 中添加以下内容，配置您的项目以使用 Quarto 的冻结功能：

_quarto.yml

execute:
  freeze: auto

现在，完全重新渲染您的站点：

Terminal

quarto render

如果您在项目中有可执行代码，您会注意到在项目的顶层创建了一个 _freeze 目录。此目录存储计算结果，并应将其提交到版本控制中。每当你更改包含可执行代码的 .qmd 文件时，它将在下一次渲染时自动重新运行，并且更新后的计算结果将存储在 _freeze 中。

如果你希望CI发布执行项目中包含的所有Python和R代码，你需要确保CI服务器上安装了这些工具的必要版本（以及任何所需的包）。如何做到这一点超出了本文的范围——要了解更多关于保存和恢复依赖项的信息，请参阅关于虚拟环境的文章。

发布命令

你可以通过脚本化quarto publish命令，使用任何CI服务将Quarto内容发布到Connect。为此，你需要确保Connect服务器地址和凭证在CI服务器上作为环境变量可用。

变量	描述
`CONNECT_SERVER`	Posit Connect服务器的地址（例如，`https://connect.example.com`）。
`CONNECT_API_KEY`	Posit Connect的API密钥

此外，你还需要指定要更新的目标内容的ID。这通常从发布期间保存到项目目录中的_publish.yml文件中提取。例如：

_publish.yml

- source: project
  connect:
    - id: 4f2ffc46-24b0-4cc7-a854-c5eb671e0dd7
      url: 'https://connect.example.com/content/4f2ffc46-24b0-4cc7-a854-c5eb671e0dd7/'

假设你有一个如上的_publish.yml，你可以使用以下命令从CI发布到Connect：

Terminal

export CONNECT_SERVER=https://connect.example.com/
export CONNECT_API_KEY=7C0947A852D8
quarto publish connect

或者，如果你没有_publish.yml文件，可以在命令行上指定ID，如下所示：

Terminal

quarto publish connect --id 4f2ffc46-24b0-4cc7-a854-c5eb671e0dd7

GitHub Actions

如果你的CI服务是GitHub Actions，那么你可以利用Quarto的标准发布操作来自动部署到Connect。

服务器凭证

在创建发布操作之前，你需要确保你的仓库具有发布到Connect所需的凭证。你可以按如下方式操作：

如果你还没有，请从必要的Connect服务器创建一个Posit Connect的API密钥，然后将其复制到剪贴板。
将Connect API密钥添加到仓库的action Secrets（可在仓库的Settings中访问）。你会在右上角看到一个New repository secret按钮：

点击按钮并将步骤1中的API密钥作为名为CONNECT_API_KEY的秘密添加：

发布操作

要设置你的发布操作，请在你的仓库中创建一个.github/workflows/publish.yml文件。如果你正在冻结计算（即不在操作中运行Python或R代码），那么文件将如下所示：

.github/workflows/publish.yml

on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Render and Publish 
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: connect
          CONNECT_SERVER: https://connect.example.com
          CONNECT_API_KEY: ${{ secrets.CONNECT_API_KEY }}

一旦你推送了更新后的仓库（包括发布操作和_freeze目录）到GitHub，你的操作将在此及后续提交中运行，自动渲染并发布到Connect。

执行代码

如果你愿意，你还可以配置GitHub Actions在渲染过程中执行Python或R代码。虽然这可能看起来是最佳方法，但请考虑在GitHub Actions等CI服务中执行代码时所施加的要求：

你需要在CI环境中重新构建所有依赖项（R、Python或Julia以及所需包的正确版本）。
如果你的代码需要任何特殊权限（例如数据库或网络访问），这些权限也需要存在于CI服务器上。
你的项目可能包含一些难以再次轻松执行的文档（例如几年前使用旧版本包的博客文章）。这些文档可能需要单独启用freeze以防止在CI上执行。

先决条件

确保代码能在GitHub Action中执行的最佳方式是使用虚拟环境，如venv或renv与你的项目结合（下面我们将为每种方式提供示例操作）。如果你不熟悉使用这些工具，请查看关于使用虚拟环境与Quarto的文章以了解更多信息。

一旦你决定在GitHub Action中执行代码，你可以从你的_quarto.yml配置中移除上述的freeze: auto。请注意，如果你想对某些文档或目录有选择地使用freeze，这仍然是可能的（对于目录，在目录中创建一个_metadata.yml文件并在其中指定你的freeze配置——这是Quarto对博客项目posts文件夹的默认操作）。

示例：使用venv的Jupyter

以下是一个完整的GitHub Action示例，它安装Python、Jupyter以及从requirements.txt中的包依赖项，然后执行代码并将输出渲染到Connect：

.github/workflows/publish.yml

on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        
      - name: Install Python and Dependencies
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
          cache: 'pip'
      - run: pip install jupyter
      - run: pip install -r requirements.txt
      
      - name: Render and Publish 
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: connect
          CONNECT_SERVER: https://connect.example.com
          CONNECT_API_KEY: ${{ secrets.CONNECT_API_KEY }}

示例：使用renv的Knitr

以下是一个完整的GitHub Action示例，它安装R以及从renv.lock中的包依赖项，然后执行代码并将输出渲染到Connect：

.github/workflows/publish.yml

on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        
      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.2.0'
      
      - name: Install R Dependencies 
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1
      
      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: connect
          CONNECT_SERVER: https://connect.example.com
          CONNECT_API_KEY: ${{ secrets.CONNECT_API_KEY }}

附加选项

在一个更大的GitHub仓库中可能存在一个Quarto项目，而该Quarto项目并不位于顶级目录中。在这种情况下，向publish操作的调用中添加一个path输入。例如：

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: connect
    path: subdirectory-to-use
    CONNECT_SERVER: https://connect.example.com
    CONNECT_API_KEY: ${{ secrets.CONNECT_API_KEY }}

默认情况下，quarto publish会在发布前重新渲染你的项目。然而，如果你将渲染后的输出存储在版本控制中，你不需要GitHub Action重新渲染项目。在这种情况下，向publish操作添加选项render: false：

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: connect
    render: false
    CONNECT_SERVER: https://connect.example.com
    CONNECT_API_KEY: ${{ secrets.CONNECT_API_KEY }}