云原生CI/CDDevOps后端【免费下载链接】pipelineA cloud-native Pipeline resource.项目地址https://gitcode.com/gh_mirrors/pipelin/pipeline点击查看免费下载本文是一份面向 Go 开发者的迁移指南围绕 Azure 官方 Go SDK 中密钥管理模块从旧的keyvault包迁移到新一代azkeys模块的完整过程展开。文章以仓库内 azkeys/MIGRATION.md 为骨架结合 azkeys 模块源码 中的客户端实现、常量定义与模型结构帮助读者掌握新旧 API 的核心差异、认证模型的变化、代码改写方法以及迁移后的错误处理与日志排查手段最终能够将现有 Key Vault 密钥操作代码平滑升级到azkeys。一、迁移背景Key Vault 模块为何拆分在过去Azure Key Vault 的所有操作都集中在单一包中。对于 Go 语言这个包是github.com/Azure/azure-sdk-for-go/services/keyvault/version/keyvault这种一个包管所有的设计把密钥keys、机密secrets、证书certificates三类资源的管理接口全部揉在一起随着 API 演进包体积、依赖关系和迭代节奏都难以控制。新一代 SDK 将 Key Vault API 拆分为相互独立的模块密钥管理github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys即本仓库 vendor 中对应的 azkeys 目录用于创建、存储和控制数据加密密钥的访问证书管理azcertificates负责 SSL/TLS 证书的创建、管理与部署机密管理azsecrets用于安全存储令牌、密码、API Key 等机密信息托管 HSM 管理azadmin提供基于角色的访问控制RBAC、设置以及保管库级别的备份/恢复能力。本文聚焦密钥操作的迁移即从旧keyvault包切换到azkeys模块。注意变化远不止模块名。正如 MIGRATION 指南所指出的部分类型名和方法名发生了改变并且所有新模块统一使用 azidentity 可以看到本仓库 vendored 的azkeys版本为v1.5.0对应 Key Vault API 服务版本2025-07-01见 CHANGELOG.md。二、新旧 API 核心差异速览新旧两代模块在客户端构造、认证方式和 URL 传递方式上有本质区别这是迁移中需要最先适应的部分维度旧keyvault模块新azkeys模块认证方式创建keyvault.BaseClient后手动挂载Authorizer先用azidentity创建凭证Credential再以此构造客户端URL 传递每次调用方法时传入vaultURL参数构造客户端时一次性传入方法调用不再携带 URL指针参数大量使用取地址构造指针统一使用azcore/to.Ptr()等辅助函数模块划分单一包涵盖所有资源keys / secrets / certificates 分模块返回类型newBundle 直接解引用Response结构 响应中的Key字段错误处理传统错误统一返回*azcore.ResponseError认证模型的变化从 Authorizer 到 Credential旧版代码的典型做法是先实例化一个空的keyvault.BaseClient再从环境变量构建Authorizer挂载到客户端上。新版则遵循 azcore 的统一设计任何azcore.TokenCredential都可以直接传给azkeys.NewClient认证策略在客户端内部自动装配开发者无需关心 Authorizer 的挂载细节。Key Vault URL 的传递时机旧 API 中vaultURL是每个方法的入参如CreateKey(ctx, vaultURL, name, params)新 API 中 URL 只在NewClient(vaultURL, cred, nil)构造时传入一次之后所有方法调用CreateKey、GetKey、DeleteKey等都只需给出密钥名与版本等资源定位参数。从 client.go 的Client结构可以看出vaultBaseUrl被保存在客户端内部// Client - The key vault client performs cryptographic key operations and vault operations against the Key Vault service. // Dont use this type directly, use a constructor function instead. type Client struct { internal *azcore.Client vaultBaseUrl string }所有请求都在内部通过runtime.JoinPaths(client.vaultBaseUrl, urlPath)拼接出完整 URL见backupKeyCreateRequest等私有方法对外部调用者完全透明。三、代码对照创建密钥的两种写法MIGRATION 指南给出了新旧模块创建密钥的完整对照代码这是迁移时最直接的参照。旧keyvault模块创建密钥import ( context fmt github.com/Azure/azure-sdk-for-go/profiles/latest/keyvault/keyvault kvauth github.com/Azure/azure-sdk-for-go/services/keyvault/auth ) func main() { vaultURL : https://TODO: your vault name.vault.azure.net authorizer, err : kvauth.NewAuthorizerFromEnvironment() if err ! nil { // TODO: handle error } basicClient : keyvault.New() basicClient.Authorizer authorizer fmt.Println(\ncreating a key in keyvault:) keyParams : keyvault.KeyCreateParameters{ Curve: keyvault.P256, Kty: keyvault.EC, } newBundle, err : basicClient.CreateKey(context.TODO(), vaultURL, key name, keyParams) if err ! nil { // TODO: handle error } fmt.Println(added/updated: *newBundle.JSONWebKey.Kid) }这段旧代码的问题显而易见认证靠手动挂载AuthorizerCreateKey每次调用都要重复传入vaultURL返回的newBundle需要层层解引用newBundle.JSONWebKey.Kid才能拿到密钥标识。新azkeys模块创建密钥package main import ( context fmt github.com/Azure/azure-sdk-for-go/sdk/azcore/to github.com/Azure/azure-sdk-for-go/sdk/azidentity github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys ) func main() { vaultURL : https://TODO: your vault name.vault.azure.net cred, err : azidentity.NewDefaultAzureCredential(nil) if err ! nil { // TODO: handle error } client, err : azkeys.NewClient(vaultURL, cred, nil) if err ! nil { // TODO: handle error } keyParams : azkeys.CreateKeyParameters{ Curve: to.Ptr(azkeys.CurveNameP256K), Kty: to.Ptr(azkeys.KeyTypeEC), } resp, err : client.CreateKey(context.TODO(), key name, keyParams, nil) if err ! nil { // TODO: handle error } fmt.Println(*resp.Key.KID) }对照可见几个关键变化认证前置先用azidentity.NewDefaultAzureCredential(nil)创建凭证再传给NewClient客户端一次构造vaultURL只出现一次指针语义统一keyvault.P256变为to.Ptr(azkeys.CurveNameP256K)keyvault.EC变为to.Ptr(azkeys.KeyTypeEC)返回结构扁平化响应中的密钥 ID 通过resp.Key.KID直接访问。从源码看CreateKeyParameters是azkeys中创建密钥的标准请求模型见 models.go其字段包括字段类型说明Kty*KeyType必填。要创建的密钥类型Curve*CurveName椭圆曲线名称仅 EC 类型KeyAttributes*KeyAttributes密钥管理属性启用状态、过期时间等KeyOps[]*KeyOperation允许的 JWK 操作encrypt、decrypt、sign 等KeySize*int32密钥位长如 RSA 的 2048、3072 或 4096PublicExponent*int32RSA 公钥指数ReleasePolicy*KeyReleasePolicy密钥可导出策略Tagsmap[string]*string应用自定义元数据键值对四、深入源码azkeys 客户端的认证与构造机制迁移不只是替换 import 路径理解新客户端的内部构造机制有助于排查认证类问题。azkeys的客户端构造函数位于手写文件 custom_client.go生成代码目录中标注 this file contains handwritten additions to the generated code。NewClient 的实现要点func NewClient(vaultURL string, credential azcore.TokenCredential, options *ClientOptions) (*Client, error) { if options nil { options ClientOptions{} } authPolicy : internal.NewKeyVaultChallengePolicy( credential, internal.KeyVaultChallengePolicyOptions{ DisableChallengeResourceVerification: options.DisableChallengeResourceVerification, }, ) azcoreClient, err : azcore.NewClient(moduleName, version, runtime.PipelineOptions{ APIVersion: runtime.APIVersionOptions{ Location: runtime.APIVersionLocationQueryParam, Name: api-version, }, PerRetry: []policy.Policy{authPolicy}, Tracing: runtime.TracingOptions{ Namespace: Microsoft.KeyVault, }, }, options.ClientOptions) if err ! nil { return nil, err } return Client{vaultBaseUrl: vaultURL, internal: azcoreClient}, nil }从中可以提取出以下迁移相关的关键事实Key Vault 挑战认证策略Challenge Policyazkeys通过internal.NewKeyVaultChallengePolicy实现 Key Vault 特有的 401 挑战认证流程。这与普通 Azure 资源不同——Key Vault 会返回认证挑战客户端需据此从正确租户获取令牌。ClientOptions.DisableChallengeResourceVerification该选项控制是否要求认证挑战中的资源与 Key Vault / 托管 HSM 域名匹配。默认启用校验以增强安全性仅在特殊网络/代理场景下才考虑关闭。API 版本管理管道中通过api-version查询参数传递 API 版本runtime.APIVersionLocationQueryParam当前仓库对应服务版本为2025-07-01。自azkeys v1.3.0起见 CHANGELOG用户还可以通过ClientOptions.APIVersion覆盖默认版本。链路追踪所有操作以Microsoft.KeyVault命名空间生成 trace便于接入 OpenTelemetry。客户端提供的能力面从 client.go 导出的方法可见迁移后你将获得远比旧包更完整、更现代的密钥操作能力生命周期管理CreateKey、GetKey、DeleteKey、GetDeletedKey、ImportKey、BackupKey备份导出受保护形式的密钥仅用于跨保管库恢复且受地理边界限制密码学操作Encrypt、Decrypt、Sign、Verify、WrapKey、UnwrapKey批量枚举NewListKeyPropertiesPager、NewListKeyPropertiesVersionsPager、NewListDeletedKeyPropertiesPager基于runtime.Pager实现分页遍历轮换与高级能力GetKeyRotationPolicy、UpdateKeyRotationPolicy、GetRandomBytes从保管库获取随机字节、GetKeyAttestation密钥证明自 v1.4.0-beta.1 引入。每个方法都遵循统一的模式注入操作名与 span、构造请求、执行管道、用runtime.HasStatusCode检查状态码并在失败时返回*azcore.ResponseError。五、类型与常量对照迁移中容易踩的坑旧包中的类型命名如KeyCreateParameters、P256、EC在新模块中全部重新命名。以仓库内 constants.go 为准对照关系如下密钥类型KeyType新常量值说明KeyTypeECEC椭圆曲线密钥KeyTypeECHSMEC-HSM私钥存储在 HSM 中的椭圆曲线密钥KeyTypeOctoct八位字节序列对称密钥KeyTypeOctHSMoct-HSM私钥存储在 HSM 中的对称密钥KeyTypeRSARSARSA 密钥KeyTypeRSAHSMRSA-HSM私钥存储在 HSM 中的 RSA 密钥椭圆曲线名称CurveName新常量值对应标准CurveNameP256P-256NIST P-256即 SECG SECP256R1CurveNameP256KP-256KSECG SECP256K1CurveNameP384P-384NIST P-384SECG SECP384R1CurveNameP521P-521NIST P-521SECG SECP521R1密钥操作KeyOperation新模块用类型化常量替代旧版的字符串拼接KeyOperationEncrypt、KeyOperationDecrypt、KeyOperationSign、KeyOperationVerify、KeyOperationWrapKey、KeyOperationUnwrapKey、KeyOperationImport。加密算法EncryptionAlgorithm值得特别注意的是新模块在算法命名上明确区分了推荐与不推荐的算法。例如EncryptionAlgorithmRSA15RSA1_5和EncryptionAlgorithmRSAOAEPRSA-OAEP基于 SHA-1在源码注释中都被标注为[Not recommended]官方建议使用EncryptionAlgorithmRSAOAEP256RSA-OAEP-256基于 SHA-256等更强的算法。迁移时如果旧代码使用了 RSA1_5 或 RSA-OAEP应借此机会评估升级到更强算法。签名算法SignatureAlgorithm对应 ECDSA / RSASSA-PSS / HMAC 系列如SignatureAlgorithmES256P-256 SHA-256、SignatureAlgorithmRS256、SignatureAlgorithmPS256、SignatureAlgorithmHS256等详见 constants.go。六、完整迁移步骤从零改写一个密钥操作程序综合 MIGRATION 指南与 azkeys README一次完整的迁移通常包含以下步骤。第 1 步安装依赖go get github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys go get github.com/Azure/azure-sdk-for-go/sdk/azidentityazidentity用于 Azure Active DirectoryEntra ID认证。前提条件包括一个 Azure 订阅、一个已创建的 Key Vault可通过 Azure Portal 或 Azure CLI 创建以及受支持的 Go 版本Azure SDK 支持最近两个 Go 大版本。第 2 步替换 import 路径将旧包引用替换为import ( github.com/Azure/azure-sdk-for-go/sdk/azidentity github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys )旧包中kvauth github.com/Azure/azure-sdk-for-go/services/keyvault/auth这类认证辅助包整体移除认证职责移交azidentity。第 3 步构造凭证与客户端cred, err : azidentity.NewDefaultAzureCredential(nil) if err ! nil { // TODO: handle error } client, err : azkeys.NewClient(https://TODO: your vault name.vault.azure.net, cred, nil) if err ! nil { // TODO: handle error }DefaultAzureCredential在本地开发与生产环境均可工作生产环境推荐使用托管身份Managed Identity。NewClient接受任意azidentity凭证类型。第 4 步改写业务调用逐一替换旧调用。以创建密钥为例除第三节展示的基础用法外还可以按需补充属性keyParams : azkeys.CreateKeyParameters{ Kty: to.Ptr(azkeys.KeyTypeRSA), KeySize: to.Ptr(int32(2048)), KeyOps: []*azkeys.KeyOperation{ to.Ptr(azkeys.KeyOperationEncrypt), to.Ptr(azkeys.KeyOperationDecrypt), }, Tags: map[string]*string{ purpose: to.Ptr(migration-demo), }, } resp, err : client.CreateKey(context.TODO(), my-key, keyParams, nil) if err ! nil { // TODO: handle error } fmt.Println(key id:, *resp.Key.KID)读取与删除的迁移同样直接// 读取密钥version 传空字符串表示当前版本 getResp, err : client.GetKey(context.TODO(), my-key, , nil) // 删除密钥 delResp, err : client.DeleteKey(context.TODO(), my-key, nil)第 5 步处理返回结构与指针语义迁移中最常见的编译错误来自指针语义的变化。新 SDK 统一使用azcore/to.Ptr构造指针、*解引用不再依赖旧包中导出的Type模式。返回值也从裸 bundle 结构变为xxxResponse 结构业务代码中的字段访问路径如newBundle.JSONWebKey.Kid→resp.Key.KID需要同步调整。七、迁移后的错误处理、日志与调试错误处理统一捕获*azcore.ResponseError新 SDK 中所有发起 HTTP 请求的方法在失败时都返回*azcore.ResponseError其中包含错误详情和 Key Vault 的原始响应import github.com/Azure/azure-sdk-for-go/sdk/azcore resp, err : client.GetKey(context.Background(), keyName, nil) if err ! nil { var httpErr *azcore.ResponseError if errors.As(err, httpErr) { // TODO: investigate httpErr } else { // TODO: not an HTTP error } }日志AZURE_SDK_GO_LOGGING与azcore/logazkeys复用azcore的日志实现。开启全部 Azure SDK 模块日志可设置环境变量AZURE_SDK_GO_LOGGINGall默认输出到 stderr。如需精细化控制可用azcore/log包例如只记录 HTTP 请求与响应事件并打印到 stdoutimport azlog github.com/Azure/azure-sdk-for-go/sdk/azcore/log // Print log events to stdout azlog.SetListener(func(cls azlog.Event, msg string) { fmt.Println(msg) }) // Includes only requests and responses in logs azlog.SetEvents(azlog.EventRequest, azlog.EventResponse)访问原始http.Response若需要检查 Key Vault 返回的原始 HTTP 响应可通过runtime.WithCaptureResponse在 context 中捕获import github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime var response *http.Response ctx : runtime.WithCaptureResponse(context.TODO(), response) _, err client.GetKey(ctx, keyName, nil) if err ! nil { // TODO: handle error } // TODO: do something with response八、迁移核对清单完成迁移后建议对照以下清单逐项自检import 路径已全部切换到sdk/security/keyvault/azkeys旧services/keyvault/.../keyvault与keyvault/auth包已移除认证已改为azidentity凭证 NewClient(vaultURL, cred, nil)构造方法调用中不再出现vaultURL参数指针构造统一使用to.Ptr(...)类型常量已替换为新命名如keyvault.EC→azkeys.KeyTypeECkeyvault.P256→azkeys.CurveNameP256/P256K返回值访问路径已适配新 Response 结构如resp.Key.KID加密算法已评估是否需从 RSA1_5 / RSA-OAEP 升级到 RSA-OAEP-256错误处理统一使用errors.As(err, httpErr)识别*azcore.ResponseError若依赖托管 HSM 或密钥轮换能力确认所用azkeys版本本仓库为 v1.5.0服务版本2025-07-01包含所需操作。相关资源迁移指南原文azkeys/MIGRATION.md模块使用说明与排障azkeys/README.md、azkeys/TROUBLESHOOTING.md客户端源码与手写扩展client.go、custom_client.go类型与常量定义constants.go、models.go版本演进记录CHANGELOG.md赞分享云原生CI/CDDevOps后端【免费下载链接】pipelineA cloud-native Pipeline resource.项目地址https://gitcode.com/gh_mirrors/pipelin/pipeline点击查看免费下载相关推荐Agentic Skills 实战用 TypeScript 在 Azure Key Vault 中安全管理密钥azure-keyvault-secrets-tsAgentic Skills 实战用 TypeScript 在 Azure Key Vault 中安全管理密钥azure keyvault secretsAI 技能AI 插件Azure Key Vault Keys Java SDK 密钥管理实战从密钥创建到加解密、签名与轮换agentic-awesome-skillsAzure Key Vault Keys Java SDK 密钥管理实战从密钥创建到加解密、签名与轮换agentic awesome skills 本指南AI 技能AI 插件Azure Key Vault Python SDK 实战指南在 agentic-awesome-skills 中安全管理密钥、加密键与证书Azure Key Vault Python SDK 实战指南在 agentic awesome skills 中安全管理密钥、加密键与证书 导读 本文以 aAI 技能AI 插件上一篇5分钟上手Monocypher从安装到实现XChaCha20-Poly1305加密的快速教程下一篇Sentinel gRPC Adapter 接入指南用拦截器为 gRPC 服务一键开启流控防护创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考