BTCPay Server 发布全流程实战指南：从dotnet format到 Docker 镜像与 GitHub Release 的完整检查清单
【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source & self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver
BTCPay Server 是免费、开源、可自托管的 Bitcoin 支付处理器，其版本发布涉及代码规范检查、翻译同步、版本号管理、GPG 签名验证、Docker 多架构镜像构建与 Release 文档撰写等多项工作。本文以仓库根目录下的 RELEASE-CHECKLIST.md 为骨架，逐条拆解 BTCPay Server 维护者创建新版本时的七步发布检查清单，并结合仓库内的版本文件、发布脚本、CI 工作流与测试代码，给出每条检查项背后的实现原理与可执行的验证方法。读完本文，你将掌握从本地提交到 Docker 镜像上线的完整发布操作链路。
发布清单总览：七步定位一次完整 Release
BTCPay Server 的发布清单（RELEASE-CHECKLIST.md）篇幅精炼但覆盖了发布链路的全部关键环节。按执行顺序整理如下：
| 步骤 | 操作 | 涉及文件/命令 | 目的 |
|---|---|---|---|
| 1 | 对解决方案运行dotnet format | btcpayserver.sln | 统一代码风格，消除格式差异 |
| 2 | 运行PullTransifexTranslations测试 | BTCPayServer.Tests/UtilitiesTests.cs | 从 Transifex 拉取最新翻译并回写本地语言包 |
| 3 | 在 CHANGELOG.md 撰写新版本变更日志 | Changelog.md | 沉淀每个版本的特性、修复与破坏性变更 |
| 4 | 在Build/Version.csproj中提升版本号 | Build/Version.csproj | 定义本次发布的版本标识 |
| 5 | 确保提交使用 GPG 签名（不要通过 GitHub UI 合并 PR） | .github/scripts/verify-signed-commit.sh | 保证发布提交来源可信 |
| 6 | 运行publish-docker.ps1 | publish-docker.ps1 | 打标签、推送 master 分支，触发 CI 构建镜像 |
| 7 | CI 构建完成后，将新版本 changelog 复制到 GitHub Release | .github/workflows/release.yml | 在 GitHub Release 页面呈现发布说明 |
其中步骤 1 至 5 发生在本地准备阶段，步骤 6 是触发点，步骤 7 由 CI 流水线承接后半程（多架构镜像构建、签名校验），最后由维护者在 GitHub Release 页面补充说明。下面逐条展开。
步骤 1：运行dotnet format统一代码风格
发布前的第一件事是对整个解决方案执行格式化检查：
dotnet format该命令会基于仓库根目录的btcpayserver.sln遍历所有项目（BTCPayServer、BTCPayServer.Abstractions、BTCPayServer.Client、BTCPayServer.Common、BTCPayServer.Data、BTCPayServer.Rating、BTCPayServer.PluginPacker、BTCPayServer.Tests 等）。仓库中还存在一份 BTCPayServer.ruleset，用于定义代码分析规则（例如禁用或提升特定警告的严重级别），dotnet format会尊重解决方案级别的.editorconfig与规则集配置。
为什么要放在发布第一步？因为一旦发布分支确定，后续任何代码风格漂移都会进入历史记录，且格式不一致会增加代码审查（包括安全审查）的噪音。在打发布标签之前先格式化，可以保证发布提交与 CI 签名校验使用的提交是同一份"干净"的代码。
步骤 2：运行PullTransifexTranslations测试同步翻译
BTCPay Server 的界面文案托管在 Transifex 翻译平台上，发布前需要把社区贡献的翻译同步回仓库。清单中的检查项对应的是测试项目里的一个工具型测试：
- 测试方法：
PullTransifexTranslations，位于 BTCPayServer.Tests/UtilitiesTests.cs - 测试特性：
[FactWithSecret("TransifexAPIToken")]，意味着该测试需要名为TransifexAPIToken的密钥才能运行
从源码看（BTCPayServer.Tests/UtilitiesTests.cs），该测试的核心逻辑是：
- 读取英文基准翻译（
JsonTranslation.GetTranslation("en")）； - 通过 Transifex 客户端获取语言列表与资源字符串；
- 用最新的英文源串刷新
en语言包并保存； - 对每个非英文语言，将 Transifex 上的翻译写回对应的 JSON 语言文件并保存（遇到网络异常会重试）。
需要说明的是，该方法对应的源代码注释还给出了使用前提：先在 Transifex 官网的用户设置页生成 API Token，然后执行：
dotnet user-secrets set TransifexAPIToken <youapitoken>翻译落盘的目标目录为BTCPayServer/wwwroot/locales与BTCPayServer/wwwroot/locales/checkout（仓库中wwwroot/locales下已有 48 个*.json语言文件，即这些文件的更新来源）。此外源码中还包含 Transifex 语言代码与 JSON 语言文件代码的映射逻辑（如zh_CN→zh-SP、ne_NP→np-NP），说明不同平台的语言标识并不总是一一对应。
步骤 3：在 CHANGELOG.md 中撰写变更日志
发布前需要在 Changelog.md 顶部为本次版本新增一节。从仓库现状看，BTCPay Server 的 changelog 有成熟的书写惯例：
- 每节以版本号开头（如
## 2.4.3、## 2.4.2）； - 若为安全修复版本，会显著标注（如 2.4.3 写明"security release"，2.4.2 写明修复了正在被积极利用的严重漏洞，并建议同时升级 NBXplorer 到 2.6.10）；
- 变更内容按类别分组：
Breaking change、New features、Fixes、Improvements； - 每条变更附 Pull Request 编号（
#7492等）与贡献者 @用户名，便于追溯。
由于步骤 7 会直接把 changelog 复制到 GitHub Release 页面，这一步的撰写质量直接决定发布说明的可读性。建议在发布前把合并到发布分支的所有 PR 逐个核对，确保没有遗漏任何用户可见的变更。
步骤 4：在Build/Version.csproj中提升版本号
版本号集中定义在仓库根目录的 Build/Version.csproj 中，当前仓库内容为：
<Project> <PropertyGroup> <Version>2.4.3</Version> </PropertyGroup> </Project>发布新版本时只需更新<Version>节点的值。这个文件是发布链路的"版本唯一真源"：
- Dockerfile 在构建阶段会单独复制
Build/Version.csproj，随后执行dotnet publish -p:GitCommit=${GIT_COMMIT}，把编译时的 Git 提交哈希注入程序集； - 运行时，BTCPayServerEnvironment 通过读取
AssemblyInformationalVersionAttribute获取带 Git 提交信息的版本号（GetInformationalVersion），并在页面页脚展示© BTCPay Server v{Version}（见同文件第 79 行附近）。
也就是说，Build/Version.csproj里的版本号既影响 Docker 镜像标签，也会被编译进程序集，成为运行实例自报版本、诊断问题的依据。提升版本号时应与 CHANGELOG 的版本保持一致，避免出现"代码是 2.4.3，镜像标签却是 2.4.2"的错位。
步骤 5：使用 GPG 签名提交（不要通过 GitHub UI 合并 PR）
清单明确要求：发布提交必须用 GPG 签名，且不要通过 GitHub UI 的合并按钮合入 PR。这条约束的目的是让发布提交的来源可被密码学验证。
仓库中的 CI 在构建 Docker 镜像之前会执行签名校验脚本 .github/scripts/verify-signed-commit.sh，其核心逻辑是：
- 导入仓库维护者的 GPG 公钥（
.github/scripts/*.asc，仓库内置了nicolasdorier.asc、rockstardev.asc、Kukks.asc等维护者公钥）； - 用
git log -1 --format="%G?" HEAD检查最新提交的签名状态； - 仅当状态为
G（良好签名）或U（签名者未在本地密钥环中被信任，但签名本身有效）时通过校验，否则直接退出并以失败告终； - 通过后执行
git log -1 --show-signature输出签名详情。
因此，发布前的最后一步提交应使用类似命令完成签名提交：
git commit -S -m "Release v2.4.3"若本地 Git 尚未配置签名密钥，需要先在密钥管理中生成 GPG 密钥并配置user.signingkey。脚本存在的意义在于：即便 CI 的 push 权限或密钥被滥用，至少可以保证被打包进 Docker 镜像的那次提交确实出自持有维护者私钥的人。
步骤 6：运行publish-docker.ps1触发发布
发布动作由 PowerShell 脚本 publish-docker.ps1 完成，完整脚本逻辑如下：
param( [string]$suffix ) if ($suffix) { $suffix = "-$suffix" } $ver = [regex]::Match((Get-Content Build/Version.csproj), '<Version>([^<]+)<').Groups[1].Value git tag -a "v$ver$suffix" -m "$ver$suffix" git checkout master git push origin "v$ver$suffix" --force逐行解读其作用：
- 可选参数
$suffix：用于附加预发布后缀（例如传rc1会得到标签v2.4.3-rc1），不带参数则生成正式版本标签； - 用正则从
Build/Version.csproj中提取<Version>节点的值，保证标签版本与代码版本严格一致； git tag -a "v$ver$suffix"创建带注释的注解标签（annotated tag），并附上标签消息；- 切换到
master分支并执行git push origin "v$ver$suffix" --force推送标签。
注意脚本使用了--force强制推送标签，因此执行前务必确认本地 master 与远端一致、标签版本号正确，避免覆盖线上已存在的同名标签。
步骤 7：CI 构建镜像并同步 GitHub Release 说明
推送标签后，GitHub Actions 工作流 .github/workflows/release.yml 会响应push事件中标签以v*开头的推送，自动接管后续流程。该工作流包含三个任务：
1. 触发文档构建（trigger_docs_build）：调用btcpayserver-doc仓库的 build_docs 事件，让官方文档随新版本同步重建。
2. 发布前检查（release_checks）：运行.github/scripts/run-tests.sh "PreReleaseCheck=PreReleaseCheck"，脚本 .github/scripts/run-tests.sh 会基于BTCPayServer.Tests/docker-compose.altcoins.yml编排测试环境（含 pull 重试逻辑，最多重试 10 次、每次间隔 5 秒），通过测试过滤器PreReleaseCheck=PreReleaseCheck执行预发布检查用例，超时上限为 120 分钟。
3. 插件兼容性检查（plugin_compatibility）：在 .NET SDK 容器中执行.github/scripts/check-btcpay-plugin-compat.sh，验证新版本与既有 BTCPay 插件的兼容性。
4. Docker 镜像构建与推送（docker，依赖 release_checks）：
- 先运行
verify-signed-commit.sh验证发布提交的 GPG 签名（即步骤 5 的自动化落地）； - 使用
docker buildx同时构建linux/amd64、linux/arm64、linux/arm/v7三个架构的镜像； - 镜像标签取标签去掉前缀
v后的版本（LATEST_TAG="${GITHUB_REF_NAME#v}"，即v2.4.3→2.4.3），并推送到 Docker Hub。
构建使用的 Dockerfile 采用两阶段构建：先基于mcr.microsoft.com/dotnet/sdk镜像还原依赖并执行dotnet publish（传入GIT_COMMIT构建参数），再基于mcr.microsoft.com/dotnet/aspnet运行时镜像拷贝产物，设置BTCPAY_DATADIR=/datadir数据卷与docker-entrypoint.sh入口，最终通过docker compose或docker run部署。
当所有镜像在 CI 中构建完成后，维护者需要把 Changelog.md 中新版本那一节的全文复制到 GitHub 的 Release 页面，作为该版本的正式发布说明（即清单第 7 条）。此时一次完整的 BTCPay Server 发布流程即告结束。
发布后的自查清单
结合 CI 行为与发布脚本，维护者在发布完成后可以按以下顺序复核：
- 版本一致性：
Build/Version.csproj中的<Version>、git 标签v2.4.3、Docker 镜像标签2.4.3、Changelog 标题## 2.4.3四处必须完全一致； - 签名有效性：本地执行
git log -1 --show-signature，确认 HEAD 提交的 GPG 签名有效；CI 的verify-signed-commit.sh会以G/U状态作为硬性门槛； - 翻译与格式：
PullTransifexTranslations测试已把最新翻译写回wwwroot/locales，且dotnet format后无未提交的格式变更； - 镜像架构齐全：确认
amd64、arm64、arm/v7三个平台镜像均已推送到 Docker Hub，方便各类服务器（x86 云主机、ARM 单板机等）拉取； - Release 说明完备：GitHub Release 页面已包含完整 changelog，安全修复类版本应在显著位置提示升级建议。
遵循这份清单，BTCPay Server 的每次发布都能保持"代码规范 → 翻译同步 → 变更记录 → 版本提升 → 签名验证 → 镜像构建 → 说明发布"的完整闭环，既保证了发布产物的可追溯性，也降低了安全回归与版本错配的风险。
【免费下载链接】btcpayserverAccept Bitcoin payments. Free, open-source & self-hosted, Bitcoin payment processor.项目地址: https://gitcode.com/GitHub_Trending/bt/btcpayserver
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
