Golang Docker Client构建失败401未授权：Harbor API2.0适配求助

问题背景 #

以下Golang代码在Harbor API 1.9.0环境下可正常执行镜像构建，但切换至Harbor API 2.0后出现401 Unauthorized错误，已确认用户名密码正确，查阅Docker Registry Token认证相关文档后仍未解决。

原代码 #

cli, err := client.NewClientWithOpts(client.WithVersion("1.40"))
if err != nil {
    return "", err
}
defer cli.Close()

authConfig := types.AuthConfig{
    Username: "xxx",
    Password: "xxx",
}

buildCtx, _ := archive.TarWithOptions("./", &archive.TarOptions{
    ExcludePatterns: []string{".git"},
})

plain := "plain"
buildOpts := types.ImageBuildOptions{
    Version: types.BuilderBuildKit,
    Tags:    []string{image},
    BuildArgs: map[string]*string{
        "progress": &plain,
    },
    AuthConfigs: map[string]types.AuthConfig{
        f.CONFIG.HARBOR.Url: authConfig,
    },
}

ctxWithTimeout, _ := context.WithTimeout(context.TODO(), time.Second*1800)
buildResponse, err := cli.ImageBuild(ctxWithTimeout, buildCtx, buildOpts)
if err != nil {
    return "", err
}

问题原因及解决方案 #

Harbor 2.0对认证机制做了调整，可从以下几点排查修复：

• API版本兼容性
  Harbor 2.0对应的Docker API版本建议使用1.41+，原代码指定的1.40存在兼容性问题。修改客户端初始化代码：

  cli, err := client.NewClientWithOpts(client.WithVersion("1.41"))
  

• AuthConfigs域名格式修正
  Harbor 2.0要求AuthConfigs中的key必须是不带http/https前缀的纯域名（如harbor.example.com），若原配置的f.CONFIG.HARBOR.Url包含协议前缀，会导致认证匹配失败。修改方式：

  import "net/url"
  // 解析并提取纯域名
  u, _ := url.Parse(f.CONFIG.HARBOR.Url)
  authHost := u.Host
  
  buildOpts := types.ImageBuildOptions{
      // 保留其他配置
      AuthConfigs: map[string]types.AuthConfig{
          authHost: authConfig,
      },
  }
  

• BuildKit认证传递优化
  使用BuildKit构建时，可预先通过Docker客户端登录Harbor，避免在ImageBuildOptions中重复配置认证信息：

  // 预先登录Harbor
  _, err = cli.RegistryLogin(context.TODO(), authConfig)
  if err != nil {
      return "", err
  }
  

• Harbor项目权限校验
  确认当前用户对目标镜像所在的Harbor项目拥有推送权限，Harbor 2.0对项目权限管控更严格，无推送权限即使账号密码正确也会返回401。

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