Bitbucket分支源插件配置为Server仍连Cloud，本地DC连接报401错误

我之前也碰到过这个版本组合的类似问题，核心问题就是插件在配置时容易混淆Bitbucket Server/DC和Cloud的连接逻辑，尤其是旧版本插件的UI配置项不够直观，导致明明选了Server模式，却还是走了Cloud的接口。下面是我整理的排查和解决步骤：

1. 强制指定Bitbucket Server/DC的根URL #

这是最容易忽略的关键点：

• 进入Jenkins项目的源码管理配置，选择Bitbucket后，找到Server Configuration区域（有些旧版本插件可能叫Bitbucket Server）
• 手动填写你的本地Bitbucket DC的根URL，比如http://your-bitbucket-dc-domain:7990或者https://your-bitbucket-dc-domain
• 一定要确认这个URL是Jenkins服务器能正常访问的（可以在Jenkins服务器上用curl http://your-bitbucket-dc-domain:7990测试连通性）

如果这里没填对，插件会默认使用Bitbucket Cloud的API地址，这就是为什么用Cloud凭据会触发另一类错误的原因。

2. 使用正确的凭据类型 #

连接Bitbucket Server/DC不能用Cloud的凭据：

• 对于Bitbucket DC 5.7.1，推荐创建个人访问令牌（在Bitbucket个人设置里生成，勾选仓库读取、项目读取等必要权限）
• 也可以用用户名+密码，但要确保这个用户在Bitbucket DC里有目标仓库的访问权限
• 绝对不要混用Bitbucket Cloud的App Password或者Cloud账号密码，这些在Server/DC环境下是无效的，会直接导致401

3. 验证插件与Bitbucket DC的版本兼容性 #

你使用的Bitbucket Branch Source Plugin 2.2.11是比较旧的版本，需要确认它是否兼容Bitbucket DC 5.7.1：

• 旧版本插件可能对DC 5.x的API支持有缺陷，导致认证失败或者路由错误
• 如果不想升级Jenkins，可以尝试升级插件到兼容的版本（比如查找支持Bitbucket DC 5.x的插件版本，注意要和Jenkins 2.110兼容）

4. 排查401的深层原因 #

如果以上步骤都做了还是401，去Jenkins的系统日志里看详细错误：

• 日志里会显示插件发起请求的具体URL，如果是api.bitbucket.org，说明配置里的Server URL还是没生效，需要重新检查配置
• 如果请求的是你的DC地址但返回401，那大概率是凭据权限不足，或者Bitbucket DC的用户权限设置有问题（比如用户没被添加到目标项目/仓库）

额外注意点 #

• 如果你的Bitbucket DC用了HTTPS，要确保Jenkins信任对应的SSL证书，否则可能出现SSL握手失败，却被插件返回为401错误
• 不要在全局配置和项目配置里混合设置Cloud和Server的参数，项目级的配置优先级更高，但要确保项目配置完全指向Server/DC

内容的提问来源于stack exchange，提问作者JimForTheWin