Harbor登录失败？可能是这个加密版本问题（附详细排查步骤）

Harbor登录失败？可能是这个加密版本问题（附详细排查步骤）

最近在帮几个团队迁移和升级他们的私有镜像仓库时，遇到一个挺有意思的“坑”：明明密码记得清清楚楚，但就是死活登录不进Harbor的管理界面。界面友好地提示“用户名或密码错误”，让人一度怀疑自己的记忆力是不是出了问题。这种问题在Harbor版本升级、从旧版本迁移数据，或者在某些特定配置变更后，出现的概率不低。折腾半天，最后发现根源往往不在密码本身，而在于一个后台的、不太起眼的设置——密码加密版本。对于负责基础设施运维的工程师和日常使用Harbor的开发者来说，遇到这种“灵异”登录故障，如果不知道从何下手，确实会浪费不少时间。今天，我们就来彻底拆解这个问题，不仅告诉你如何“救火”，更帮你理解背后的原理，做到举一反三。

1. 理解Harbor的认证机制与加密版本

要解决问题，先得知道问题从哪来。Harbor作为一个企业级镜像仓库，其用户认证信息（用户名、密码）并非明文存储，这是基本的安全要求。这些信息被保存在其内置的PostgreSQL数据库中。当你尝试登录时，Harbor Core服务会将你输入的密码，经过一套特定的算法处理，然后与数据库中存储的密文进行比对。

这套算法的核心就是哈希（Hash）函数。Harbor历史上主要支持两种哈希算法：

• SHA-1：一种较早期的哈希算法。在Harbor较旧的版本（例如v1.x早期）中，这是默认或常用的密码加密方式。
• SHA-256：一种更安全、抗碰撞能力更强的哈希算法。随着安全标准的提升，新版本的Harbor逐渐转向使用SHA-256作为默认或推荐的加密方式。

这里的关键在于 password_version 这个字段。它在数据库的 harbor_user 表中，明确记录了该用户密码是使用哪种算法进行哈希的。当Harbor Core服务验证密码时，它会读取这个版本号，然后使用对应的算法来处理你输入的密码。如果数据库里标记的是 sha256，但Core服务尝试用 sha1 的方式去验证，那么计算出来的哈希值必然对不上，登录也就失败了。

那么，什么情况下会导致这种“版本错配”呢？

1. 版本升级或迁移：从使用SHA-1的旧版本Harbor升级到默认使用SHA-256的新版本时，如果用户数据迁移过程中，password_version 字段没有正确更新，就会导致错配。
2. 手动修改或导入数据：通过数据库工具直接操作用户表，修改了密码字段但忘了同步更新 password_version。
3. 配置不一致：在某些定制化部署或配置中，不同服务组件关于加密算法的配置可能被意外修改。

为了更清晰地对比这两种算法在Harbor上下文中的差异，我们可以看下面这个表格：