Shlink项目中的Docker镜像版本管理问题解析

在Shlink项目中，近期发现了一个关于Docker镜像版本管理的技术问题。这个问题影响了从4.1.1到4.2.1版本的所有带有roadrunner后缀的镜像。

问题本质

问题的核心在于Docker镜像构建过程中版本号的传递机制。当前实现中存在一个设计缺陷：构建时传递给应用程序的版本号实际上是Docker镜像的标签值，而不是Git仓库中的原始标签值。这种机制导致了版本号可能包含额外的后缀（如roadrunner），最终生成的版本号不再符合标准的SemVer（语义化版本控制）规范。

技术影响

这种版本管理问题会带来几个实际影响：

1. 版本规范破坏：SemVer规范要求版本号必须遵循"主版本号.次版本号.修订号"的格式，可以附加预发布版本信息和构建元数据，但必须以特定方式附加。当前实现可能导致版本号格式不规范。

2. 系统兼容性问题：许多自动化工具和系统（如包管理器、依赖解析工具等）都依赖标准的SemVer格式来正确处理版本号。非标准版本号可能导致这些工具无法正确解析版本信息。

3. 健康检查问题：项目的健康检查端点(/health)返回的版本信息包含了这些后缀，可能影响监控系统的正常工作。

解决方案

项目团队已经通过修改GitHub Actions工作流解决了这个问题。具体修复措施包括：

1. 确保在构建Docker镜像时传递正确的Git标签值作为版本号，而不是使用Docker镜像标签。

2. 在构建过程中对版本号进行规范化处理，确保最终生成的版本号符合SemVer规范。

最佳实践建议

对于类似项目，建议采用以下版本管理策略：

1. 构建时版本注入：在构建过程中明确区分源代码版本和构建产物版本，确保应用程序获取的是原始版本信息。

2. 版本号验证：在CI/CD流程中加入版本号格式验证步骤，确保所有发布的版本都符合SemVer规范。

3. 多阶段构建处理：对于需要添加构建特定后缀的情况，应该在构建过程的最后阶段添加，而不是影响核心版本号。

这个问题的解决体现了Shlink项目对版本管理规范性的重视，也展示了开源项目通过持续改进来提升产品质量的过程。