Dapr 版本发布说明编写指南：以 release notes 模板为核心的升级实战与源码印证-开发者社区

Dapr 版本发布说明编写指南：以 release notes 模板为核心的升级实战与源码印证

【免费下载链接】daprDapr is a portable runtime for building distributed applications across cloud and edge, combining event-driven architecture with workflow orchestration.项目地址: https://gitcode.com/GitHub_Trending/da/dapr

Dapr 项目在每个版本发布时都会在 docs/release_notes 目录下沉淀一份结构化的版本发布说明，其骨架由 docs/release_notes/template.md 统一定义。本文以该模板为绝对主线，逐段拆解"发布公告—鸣谢—变更清单—升级指南—破坏性变更—弃用通知"的撰写规范，并对其中承载的自托管升级、Kubernetes 零停机升级（CLI 与 Helm 双路径）、全新安装、安装后验证、降级回滚等操作逐条展开，同时结合当前仓库的 Helm Chart、daprd 命令行选项等源码证据，帮助读者既掌握 Dapr 版本发布说明的写作骨架，也能把其中的升级命令真正落地到自己的环境中。

一、模板定位：一份发布说明的统一骨架

template.md是 Dapr 所有版本发布说明的母版。当前仓库中从 v0.1.0.md 到 v1.18.4.md 的一百多份发布说明，无论功能多寡，都遵循同一套章节骨架：

章节	作用
`# Dapr $dapr_version`	版本标题与发布引言，宣布版本、致谢贡献者
`Highlights`	提炼本次发布最重要的特性（可含 ASCII 结构图与 YAML 配置示例）
`## Acknowledgements`	感谢参与发布的贡献者与组织
`## New in this release`	按 Runtime / CLI / Components / 各 SDK / Docs 等维度列出变更清单
`## Upgrading to Dapr $dapr_version`	本地与 Kubernetes 两套升级/安装/验证步骤
`## Breaking Changes`	升级前必须评审的破坏性变更
`## Deprecation Notices`	已弃用但仍可用的功能与替代方案

模板大量使用$dapr_version、$warnings、$dapr_contributors、$dapr_changes、$dapr_breaking_changes、$dapr_deprecation_notices等占位符，由发布流水线在生成时替换为真实内容。这也解释了为什么仓库根目录 RELEASE.md 只保留一行指向发布流程的外部指引——具体的"产出物长什么样"全部由这份模板约束。

二、发布公告与 Highlights：让读者一眼抓住重点

模板开篇即宣布版本号，并引导新用户通过 Dapr 官方文档熟悉项目。紧接着的**Highlights**是整份发布说明的"电梯演讲"，模板要求在这里呈现：

本次发布最核心的主题（例如 1.18 是"Workflows 安全、持久化与规模"主题）；
需要用户注意的警告（$warnings占位符，例如升级前必须关注的密钥算法变更）；
指向本仓库内对应章节的锚点链接（如"见Upgrading to Dapr $dapr_version一节"）。

以仓库中实际发布的 v1.18.0.md 为例，其 Highlights 就包含了可复用的写作范式：

关键特性配图：Workflow 历史签名链用 ASCII 框图说明Signature 0 → Signature 1 → Signature 2的prevDigest链式结构；
关键配置配 YAML：Workflow 并发上限直接给出可复制的配置片段（globalMaxConcurrentWorkflowInvocations、workflowConcurrencyLimits等）；
升级预警前置：在正文开头即用提示块点明"本版本包含若干破坏性变更"，并给出降级下限（1.17.7）这一关键操作约束。

写作时遵循的原则是：Highlights 不罗列 PR 编号，只回答"这个版本为什么值得升级"；详细的 PR 清单全部下沉到## New in this release按仓库维度归档。

三、Acknowledgements 与 New in this release：变更清单的组织方式

## Acknowledgements部分用于感谢所有贡献者（$dapr_contributors占位符），模板同时用+++++注释块提示维护者手动补充对参与综合测试等工作的个人与组织的致谢。

## New in this release则按仓库维度展开变更清单，从 v1.0.0.md 开始就确立了这一惯例：

Dapr Runtime：核心运行时功能（如二进制 CloudEvent 支持、访问列表 URL 规范化）；
Dapr CLI：命令行能力与参数一致性调整；
Components：各组件（state / pubsub / bindings / secretstores）的问题修复与特性；
各语言 SDK（.NET / Go / Java / Python / JS / Rust / C++）；
Documentation / Quickstarts / Test Infrastructure。

每条变更条目遵循**ADDED** / **FIXED** / **RESOLVED** / **REMOVED** / **SECURITY**的动词前缀规范，并尽量附带 issue/PR 编号以便追溯。补丁版本（如 v1.18.4.md）则退化为更精简的"问题—影响—根因—解决方案"四段式，每条 bug fix 独立成节，方便用户按标题快速定位自己是否受影响。

四、升级指南（一）：本地机器 / 自托管模式

模板给出自托管（self-hosted）环境下的标准升级三步曲，这是dapr run本地开发模式升级的官方路径。

1. 卸载旧版本

dapr uninstall --all

模板特别注明该命令的副作用：会删除默认的$HOME/.dapr目录、二进制文件，以及dapr_redis、dapr_placement、dapr_zipkin三个容器；Linux 用户若docker命令需要 sudo，则需以sudo执行。

2. 安装新版本 CLI 并初始化指定版本运行时

先获取最新版daprCLI 二进制并放入PATH，然后：

dapr init --runtime-version=$dapr_version

--runtime-version是模板强调的关键参数：它保证 CLI 与运行时（daprd）版本对齐，避免出现"CLI 是新的、runtime 是旧的"的错位状态。RC 预发布版本尤其需要显式指定该参数。

3. 验证版本

$ dapr --version CLI version: $dapr_version Runtime version: $dapr_version

只有CLI version与Runtime version同时指向目标版本，才算升级完成。

五、升级指南（二）：Kubernetes 零停机升级

模板明确声明：在 Kubernetes 上可以通过Helm 3与Dapr CLI两种方式执行零停机升级。零停机的前提是控制平面组件具备 HA 配置——这可以从仓库的 charts/dapr/values.yaml 得到印证：global.ha.enabled默认关闭，开启后replicaCount: 3、topologyKey: topology.kubernetes.io/zone，并支持podAntiAffinityPolicy在preferredDuringSchedulingIgnoredDuringExecution（软反亲和，默认）与requiredDuringSchedulingIgnoredDuringExecution（硬反亲和）之间切换。

使用 CLI 升级

dapr upgrade --runtime-version $dapr_version -k

高可用模式升级：

dapr upgrade --runtime-version $dapr_version --enable-ha=true -k

--enable-ha=true对应 Chart 中的global.ha.enabled；从 v1.18.0.md 的发布说明可知，placement 与 scheduler 两个 StatefulSet 还额外支持硬反亲和策略，通过global.ha.podAntiAffinityPolicy与global.ha.topologyKey组合控制副本分布域。

使用 Helm 升级

helm repo add dapr https://dapr.github.io/helm-charts/ helm repo update helm upgrade dapr dapr/dapr --version $dapr_version --namespace=dapr-system --wait

--wait确保 Helm 等待所有 Pod 就绪后才返回。两种方式执行完毕后，都建议用dapr status -k检查控制平面健康状态。

全新安装到集群

模板同时给出 Helm 与 CLI 两条全新安装路径：

# 方式一：Helm 3 helm repo add dapr https://dapr.github.io/helm-charts/ helm repo update kubectl create namespace dapr-system helm install dapr dapr/dapr --version $dapr_version --namespace dapr-system --wait

# 方式二：Dapr CLI dapr init --runtime-version=$dapr_version -k

仓库中 charts/dapr/Chart.yaml 展示了dapr/dapr这个 Helm Chart 的真实组成——它聚合了dapr_rbac、dapr_operator、dapr_placement、dapr_sidecar_injector、dapr_sentry、dapr_scheduler、dapr_config七个子 Chart，这与安装完成后dapr status -k输出的控制平面组件一一对应。

安装后验证与 sidecar 滚动重启

$ dapr status -k NAME NAMESPACE HEALTHY STATUS REPLICAS VERSION AGE CREATED dapr-sidecar-injector dapr-system True Running 1 $dapr_version 15s ... dapr-sentry dapr-system True Running 1 $dapr_version 15s ... dapr-operator dapr-system True Running 1 $dapr_version 15s ... dapr-placement dapr-system True Running 1 $dapr_version 15s ...

从 v1.18.0.md 的实际输出可以看到，现代版本还会包含dapr-scheduler（与 Chart 中的dapr_scheduler子 Chart 对应）。模板反复强调一条铁律：

Make sure your deployments are restarted to pick the latest version of the Dapr sidecar.

即控制平面升级完成后，必须对业务 Deployment 执行滚动重启，让注入的 sidecar 跟随新版本：

kubectl rollout restart deploy/<deployment-name>

降级与回滚：升级指南的镜像章节

v1.18.0.md 在模板骨架之外新增了## Downgrading to Earlier Versions章节，是"升级指南"的镜像——它证明一份完整的发布说明还应当覆盖回滚路径。该章节给出：

兼容性矩阵：1.18 → 1.17.7+ 安全；1.18 → 1.17.6 及更早版本会导致 Sentry 启动崩溃（无法解析 Ed25519 密钥类型的 trust bundle）；1.17.6 及更早 → 1.18 安全；
安全回滚路径：先回滚到 1.17.7，待dapr status -k恢复健康后再继续降级；
具体命令：helm history dapr -n dapr-system查看历史修订，helm rollback dapr <REVISION> -n dapr-system --wait回滚，或helm upgrade dapr dapr/dapr --version 1.17.7 --namespace dapr-system --wait固定目标版本。

六、Breaking Changes 与 Deprecation Notices：升级前的必读清单

模板的收尾两章是升级安全的重要保障。

Breaking Changes

v1.18.0.md 的 Breaking Changes 用> [!warning]提示块开篇，逐条列出会影响现有部署的变更，例如：

WorkflowsRemoteActivityReminder默认开启：跨应用工作流活动结果默认改由 Scheduler reminders 投递；
HotReload 默认开启：组件、Subscription、MCPServer、Configuration、HTTPEndpoint、Resiliency、WorkflowAccessPolicy 默认支持热重载，可通过在 DaprConfiguration的spec.features中将其enabled: false恢复旧行为；
工作流实例 ID 复用语义变更：创建与活跃实例同 ID 的工作流现在直接返回冲突错误，而非静默覆盖；
服务调用剥离逐跳（hop-by-hop）HTTP 头（符合 RFC 7230）；
降级下限锁定为 1.17.7。

写作规范上，每条破坏性变更都应同时给出影响描述与迁移指引，并附 issue/PR 编号供用户追溯。

Deprecation Notices

弃用通知与破坏性变更的区别在于：被弃用的功能当前仍然可用，但已不推荐，且有明确的替代方案与移除时间表。同样以 v1.18.0 为例：

工作流实例 ID 复用能力移除（可通过 purge API 或保留策略释放实例 ID）；
Java SDK 最低版本提升到 Java 17，invokeMethodAPI 弃用，改用DaprClient.invokeHttpClient(appId)；
.NET SDK 的InvokeMethodAsync系列标记为[Obsolete]；
JS SDK 工作流方法改名（get→getWorkflowState等），旧名称作为弃用别名保留至 Dapr 1.20。

模板之所以强制保留这两个章节，是为了让用户在升级前能一次性评估"我的部署会不会被破坏、我依赖的功能还能用多久"。

七、从模板到源码：升级参数背后的实现印证

模板与发布说明中出现的命令行参数，都能在仓库源码中找到对应实现，这为"按文档操作"提供了底层依据。

以--max-body-size为例：发布说明中提及工作流历史载荷超过该限制会被优雅置为STALLED。查看 cmd/daprd/options/options.go 可以看到它定义为字符串选项maxBodySize，默认值由 pkg/runtime/config.go 中的DefaultMaxRequestBodySize = 4 << 20（即 4 MiB）决定，并在解析时：

将旧的--dapr-http-max-request-size标记为已废弃（提示改用--max-body-size）；
当--max-body-size显式传入时优先采用，并通过resource.ParseQuantity支持400（无单位）与400Mi（带单位）两种写法——cmd/daprd/options/options_test.go 中的测试用例专门覆盖了这两种解析路径。

这说明发布说明中的每一条"注意"（如--max-body-size默认 4 MiB、超出会触发工作流 STALLED 而非整条流中断）背后都有对应的源码常量与单元测试支撑，文档、实现与测试三者相互印证。

八、小结：如何基于模板产出一份合格发布说明

综合模板与仓库中一百余份实际发布说明，可以归纳出一份合格的 Dapr 发布说明应当满足的检查清单：

结构完整：公告/Highlights → Acknowledgements → New in this release → 升级指南 → Breaking Changes → Deprecation Notices，缺一不可；
升级路径可执行：自托管（dapr uninstall --all→dapr init --runtime-version→dapr --version）与 Kubernetes（CLIdapr upgrade/ Helmhelm upgrade，含全新安装与dapr status -k验证、kubectl rollout restart滚动重启）两条路径的命令必须原样可复制；
变更可追溯：每条变更带动词前缀与 issue/PR 编号；
风险前置：破坏性变更、弃用通知、降级下限必须在升级前醒目呈现，必要时附兼容性矩阵；
有源码与测试背书：文档中的默认值、参数行为与仓库实现（如 cmd/daprd/options/options.go、charts/dapr/values.yaml）保持一致。