支持和版本控制

• 1: 版本控制政策
• 2: 支持的运行时和SDK版本
• 3: 重大变更和弃用
• 4: 报告安全问题
• 5: 预览功能
• 6: Alpha 和 Beta API

1 - 版本控制政策

介绍

Dapr 通过版本控制方案为未来的运行时、API 和组件的变化做好了设计。本主题描述了 API、组件和 Github 仓库的版本控制方案和策略。

版本控制

版本控制是为计算机软件的每个独特状态分配唯一版本名称或版本号的过程。

• 版本控制提供兼容性、明确的变更控制，并处理变更，尤其是重大变更。
• Dapr 力求保持向后兼容性。如果需要重大变更，将会提前宣布。
• 废弃的功能将在多个版本中逐步淘汰，新旧功能将并行工作。

版本控制涉及以下 Dapr 仓库：dapr、CLI、稳定语言 SDK、dashboard、components-contrib、quickstarts、helm-charts 和文档。

Dapr 具有以下版本控制方案：

• Dapr HTTP API 采用 MAJOR.MINOR 版本控制
• Dapr GRPC API 采用 MAJOR 版本控制
• 发布版本（包括 GitHub 仓库中的 dapr、CLI、SDK 和 Helm Chart）采用 MAJOR.MINOR.PATCH 版本控制
• 文档和 Quickstarts 仓库与 Dapr 运行时仓库版本控制一致。
• Dapr 组件 在 components-contrib GitHub 仓库中采用 MAJOR 版本控制。
• Dapr 清单 采用 MAJOR.MINOR 版本控制。这些包括订阅和配置。

请注意，Dapr 的 API、二进制发布（运行时、CLI、SDK）和组件都是相互独立的。

Dapr HTTP API

Dapr HTTP API 根据这些REST API 指南进行版本控制。

根据这些指南；

• 当预期旧版本的弃用时，API 的 MAJOR 版本会递增。任何此类弃用将被通知，并提供升级路径。
• MINOR 版本可能因其他更改而递增。例如，发送到 API 的消息的 JSON 模式的更改。 API 的重大变更定义可以在这里查看。
• 实验性 API 包含一个“alpha”后缀以表示其 alpha 状态。例如 v1.0alpha、v2.0alpha 等。

Dapr 运行时

Dapr 发布使用 MAJOR.MINOR.PATCH 版本控制。例如 1.0.0。阅读支持的发布以了解更多关于发布版本控制的信息。

Helm Charts

helm-charts 仓库中的 Helm charts 与 Dapr 运行时版本一致。Helm charts 用于Kubernetes 部署

语言 SDK、CLI 和 dashboard

Dapr 语言 SDK、CLI 和 dashboard 独立于 Dapr 运行时进行版本控制，并可以在不同的时间表上发布。请参阅此表格以显示 SDK、CLI、dashboard 和运行时版本之间的兼容性。每个新的运行时发布都会列出相应支持的 SDK、CLI 和 Dashboard。

SDK、CLI 和 Dashboard 的版本控制遵循 MAJOR.MINOR.PATCH 格式。当 SDK 中存在非向后兼容的更改时（例如，更改客户端方法的参数），主版本会递增。次版本用于新功能和错误修复，补丁版本在出现错误或安全热修复时递增。

SDK 中的示例和例子与该仓库的版本一致。

组件

组件在 components-contrib 仓库中实现，并遵循 MAJOR 版本控制方案。组件的版本遵循主版本（vX），因为补丁和非破坏性更改会添加到最新的主版本中。当组件接口中存在非向后兼容的更改时，例如更改 State Store 接口中的现有方法，版本会递增。

components-contrib 仓库发布是所有内部组件的统一版本。也就是说，components-contrib 仓库发布的版本由其内部所有组件的模式组成。如果没有组件更改，Dapr 的新版本并不意味着 components-contrib 有新的发布。

注意：组件具有生产使用生命周期状态：Alpha、Beta 和 Stable。这些状态与其版本控制无关。支持的组件表显示了它们的版本和状态。

• state store 组件列表
• pub/sub 组件列表
• binding 组件列表
• secret store 组件列表
• configuration store 组件列表
• lock 组件列表
• cryptography 组件列表
• middleware 组件列表

有关组件版本控制的更多信息，请阅读组件的版本 2 及以后

组件模式

组件 YAML 的版本控制有两种形式：

• 组件清单的版本控制。apiVersion
• 组件实现的版本。.spec.version

组件清单在 .spec.metadata 字段中包含实现的模式，.type 字段表示实现

请参阅下面示例中的注释：

apiVersion: dapr.io/v1alpha1 # <-- 这是组件清单的版本
kind: Component
metadata:
  name: pubsub
spec:
  version: v1 # <-- 这是 pubsub.redis 模式实现的版本
  type: pubsub.redis
  metadata:
  - name: redisHost
    value: redis-master:6379
  - name: redisPassword
    value: general-kenobi

组件清单版本

组件 YAML 清单的版本为 dapr.io/v1alpha1。

组件实现版本

组件实现的版本由示例中的 .spec.version 字段确定。.spec.version 字段在模式实例中是必需的，如果不存在，该组件将无法加载。在 Dapr 1.0.0 发布时，所有组件都标记为 v1。组件实现版本仅在非向后兼容更改时递增。

组件弃用

组件的弃用将在两个（2）版本之前宣布。组件的弃用会导致组件版本的主版本更新。经过 2 个版本后，该组件将从 Dapr 运行时中注销，尝试加载它将抛出致命异常。

组件的弃用和移除将在发布说明中宣布。

Quickstarts 和示例

Quickstarts 仓库中的 Quickstarts 与运行时版本一致，其中相应版本的表格位于示例仓库的首页。用户应仅使用与正在运行的运行时版本相对应的 Quickstarts。

Samples 仓库中的示例根据示例维护者的情况逐个版本控制。与运行时发布（多个版本之前）非常不一致或超过 1 年未维护的示例将被移除。

相关链接

• 阅读支持的发布
• 阅读重大变更和弃用政策

2 - 支持的运行时和SDK版本

介绍

本主题详细介绍了Dapr版本的支持策略、升级策略，以及在所有Dapr代码库（如运行时、CLI、SDK等）中如何传达弃用和重大更改的信息，适用于1.x及以上版本。

Dapr版本采用MAJOR.MINOR.PATCH的版本号格式。例如，1.0.0。

支持的版本指的是：

• 如果版本存在关键问题，例如主线中断或安全问题，将发布修补程序。每个问题都根据具体情况进行评估。
• 对支持的版本进行问题调查。如果版本不再受支持，您需要升级到较新的版本以确定问题是否仍然存在。

从1.8.0版本开始，Dapr支持三个版本：当前版本和之前的两个版本。通常这些是MINOR版本更新。这意味着支持版本的动态窗口会向前移动，您有责任保持这些支持版本的最新状态。如果您使用较旧版本的Dapr，可能需要进行中间升级以达到支持的版本。

在major.minor版本发布之间至少有13周（3个月）的时间，给用户至少9个月的时间从不支持的版本进行升级。有关发布过程的更多详细信息，请阅读发布周期和节奏。

补丁支持适用于当前和之前的支持版本。

构建变体

Dapr的sidecar镜像被发布到GitHub容器注册表和Docker注册表。默认镜像包含所有组件。从1.11版本开始，Dapr还提供了仅包含稳定组件的sidecar镜像变体。

• 默认sidecar镜像：daprio/daprd:<version>或ghcr.io/dapr/daprd:<version>（例如ghcr.io/dapr/daprd:1.11.1）
• 稳定组件的sidecar镜像：daprio/daprd:<version>-stablecomponents或ghcr.io/dapr/daprd:<version>-stablecomponents（例如ghcr.io/dapr/daprd:1.11.1-stablecomponents）

在Kubernetes上，可以通过dapr.io/sidecar-image注释覆盖应用程序部署资源的sidecar镜像。有关更多信息，请参阅Dapr的参数和注释。如果未指定，则使用默认的’daprio/daprd:latest’镜像。

了解更多关于Dapr组件的认证生命周期。

支持的版本

下表显示了已一起测试并形成“打包”发布的Dapr版本。任何其他版本组合都不受支持。

SDK兼容性

SDK和运行时承诺除了安全问题所需的更改外，不会有重大更改。如果需要，所有重大更改都会在发布说明中宣布。

SDK和运行时的前向兼容性
较新的Dapr SDK支持最新版本的Dapr运行时和之前的两个版本（N-2）。

SDK和运行时的后向兼容性
对于新的Dapr运行时，当前的SDK版本和之前的两个版本（N-2）都受到支持。

升级路径

在运行时1.0版本发布后，可能会出现需要通过额外版本显式升级以达到目标的情况。例如，从v1.0升级到v1.2可能需要经过v1.1。

下表显示了Dapr运行时的测试升级路径。任何其他升级组合都没有经过测试。

有关升级的一般指导可以在selfhost模式和Kubernetes部署中找到。最好查看目标版本的发布说明以获得具体指导。

在托管平台上升级

Dapr可以支持多个生产托管平台。在1.0版本发布时，支持的两个平台是Kubernetes和物理机。有关Kubernetes升级，请参阅Kubernetes上的生产指南

依赖项的支持版本

以下是最新版本的Dapr（v1.15.5）已测试的软件列表。

相关链接

• 阅读版本控制策略
• 阅读重大更改和弃用策略

3 - 重大变更和弃用

重大变更

重大变更是指对以下内容的修改，这些修改可能导致现有的第三方应用程序或脚本在升级到下一个稳定的小版本的 Dapr 工件（如 SDK、CLI、runtime 等）后出现编译错误或运行时问题：

• 代码行为
• 架构
• 默认配置值
• 命令行参数
• 发布的指标
• Kubernetes 资源模板
• 公开访问的 API
• 公开可见的 SDK 接口、方法、类或属性

以下情况可以立即应用重大变更：

• 版本未达到 1.0.0 的项目
• 预览功能
• Alpha API
• SDK 中的预览或 Alpha 接口、类、方法或属性
• 处于 Alpha 或 Beta 阶段的 Dapr 组件
• github.com/dapr/components-contrib 的接口
• 文档和博客中的 URL
• 例外情况，需要修复关键错误或安全漏洞。

应用重大变更的流程

应用重大变更需要遵循以下流程：

1. 弃用通知必须作为发布的一部分进行发布。
2. 重大变更将在弃用公告发布后的两个版本后生效。
   • 例如，功能 X 在 1.0.0 版本说明中宣布弃用，然后将在 1.2.0 中移除。

弃用

弃用可以应用于：

1. API，包括 alpha API
2. 预览功能
3. 组件
4. CLI
5. 可能导致安全漏洞的功能

弃用信息会在发布说明中名为“弃用”的部分中列出，说明：

• 当前弃用的功能将在未来某个版本中不再受支持。例如，发布 x.y.z。这至少是在两个版本之前。
• 在发布说明中记录用户需要采取的任何步骤以修改其代码、操作等（如果适用）。

在宣布未来的重大变更后，该变更将在 2 个版本或 6 个月后生效，以较长者为准。弃用的功能应响应警告，但除此之外不执行任何操作。

已宣布的弃用

相关链接

• 阅读 版本政策
• 阅读 支持的发布

4 - 报告安全问题

Dapr 项目和维护者将安全性视为操作和设计软件的核心关注点。从 Dapr 二进制文件到 GitHub 发布流程，我们采取了多种措施以确保用户应用程序和数据的安全。有关 Dapr 安全功能的更多信息，请访问安全页面。

涵盖的存储库和问题

提到“Dapr 中的安全漏洞”时，指的是dapr GitHub 组织下任何存储库中的安全问题。

此报告流程仅适用于 Dapr 项目本身的安全问题，不适用于使用 Dapr 的应用程序或不影响安全性的问题。

如果问题无法通过对上述涵盖的存储库之一的更改来解决，建议在适当的存储库中创建 GitHub 问题或在 Discord 中提出问题。

**如果您不确定，**请谨慎行事，在通过 GitHub、Discord 或其他渠道提出问题之前，使用报告流程进行联系。

明确不涵盖：漏洞扫描器报告

我们不接受仅仅是从漏洞扫描工具复制粘贴输出的报告，除非已经专门确认工具报告的漏洞确实存在于 Dapr 中，包括 CLI、Dapr SDKs、components-contrib 存储库或 Dapr 组织下的任何其他存储库。

我们也使用这些工具，并根据它们的输出采取行动。然而，当这些报告被发送到我们的安全邮件列表时，通常是误报，因为这些工具往往只检查库的存在，而不考虑库在上下文中的使用方式。

如果我们收到的报告似乎只是来自扫描器的漏洞列表，我们保留忽略它的权利。

这尤其适用于工具生成的漏洞标识符不是公开可见或以某种方式是专有的情况。我们可以查找 CVE 或其他公开可用的标识符以获取更多详细信息，但不能对专有标识符执行相同操作。

安全联系人

有权阅读您的安全报告的人列在maintainers.md中。

报告流程

1. 用英语描述问题，最好附上一些示例配置或代码，以便重现问题。解释为什么您认为这是 Dapr 中的安全问题。
2. 将这些信息放入电子邮件中。使用描述性标题。
3. 发送电子邮件至Security (security@dapr.io)

响应

响应时间可能会受到周末、假期、休息或时区差异的影响。尽管如此，维护者团队会尽快回复，理想情况下在 3 个工作日内。

如果团队得出结论认为报告的问题确实是 Dapr 项目中的安全漏洞，至少两名维护者团队成员会尽快讨论下一步，理想情况下在 24 小时内。

一旦团队决定报告是真实漏洞，团队中的一名成员会回复报告者，确认问题并建立披露时间表，应该尽快进行。

分类、响应、修补和公告应在 30 天内完成。

5 - 预览功能

Dapr 的预览功能在首次发布时被视为实验性功能。

要使用运行时的预览功能，必须在 Dapr 的应用程序配置中通过预览设置功能进行显式选择加入。有关更多信息，请参阅如何启用预览功能。

对于 CLI，不需要显式选择加入，只需使用首次提供该功能的版本即可。

当前预览功能

6 - Alpha 和 Beta API

Alpha API

Beta API

当前没有 Beta API。

相关链接

了解有关 Alpha、Beta 和稳定生命周期阶段的更多信息。