一、功能简介
密钥级密钥网络访问限制是访问密钥网络访问限制策略的一种配置级别，针对指定 SecretId 单独配置访问来源限制，仅对该 SecretId 生效。本文介绍密钥级网络访问限制的使用限制、配置步骤，以及新上线的 COS/CLS 网络限制能力。
说明：
项目 | 说明 |
策略类型 | 密钥级密钥网络访问限制。 |
配置维度 | 指定 SecretId 单独配置。 |
生效范围 | 仅对该 SecretId 生效。 |
优先级 | 高于账号级策略，已配置密钥级策略的密钥，不再校验账号级策略。 |
支持产品 | 腾讯云 API 通用网络限制（公网 IP / 专有网络 VPC），以及对象存储 COS、日志服务 CLS 网络限制。 |
二、使用限制
限制项 | 说明 |
单个密钥可配置策略数量 | 最多9条 |
公网策略数量 | 最多1条 |
专有网络策略数量 | 与总策略数量共享，最多8条 |
单条策略内 IP 数量 | 最多50个 IP 或 IP 段 |
支持格式 | IPv4、IPv6、IPv4 CIDR 段，例如 10.0.0.0/16 |
三、配置前准备
（一）梳理可信网络来源
1. 账号级密钥网络访问限制开启后，将影响当前账号下所有未配置密钥级策略的永久访问密钥。配置前，请先梳理可信网络来源，避免遗漏正常业务调用地址。建议按以下方式检查：
检查项 | 说明 |
操作审计记录 |  |
云上资源出口 | 确认 CVM、容器服务、NAT 网关、负载均衡等资源的公网出口 IP 或内网地址段 |
办公网和 VPN 出口 | 确认企业办公网、VPN、堡垒机等访问出口 IP |
自动化任务来源 | 确认 CI/CD、运维脚本、定时任务、监控系统等自动化调用来源 |
第三方系统来源 | 确认外部系统、合作方系统或 SaaS 服务的固定出口 IP |
动态 IP 场景 | 对弹性扩缩容、Serverless、容器等动态来源，建议统一通过固定 NAT 出口访问 |
（二）选择访问域名
配置网络访问限制策略时，请根据限制类型选择正确的 API 访问域名：
限制类型 | 限制类型 | 访问域名要求 |
限制公网 IP | 配置允许访问的公网 IP 或 IP 段 | 使用公网域名访问腾讯云 API，无需访问 internal 域名 |
限制内网 IP | 配置允许访问的内网 IP 或 IP 段，并选择对应 VPC ID | 需使用 internal 域名访问腾讯云 API |
如果业务需要通过公网来源调用腾讯云 API，请配置公网策略，并使用公网域名访问。
如果业务需要通过 VPC 内网来源调用腾讯云 API，请配置专有网络策略，并通过 internal 域名访问。否则，请求可能无法命中对应的网络访问限制策略。
四、配置步骤
1. 登录 访问管理 CAM 控制台。
2. 在左侧导航栏选择访问密钥 > API 密钥管理，进入 API 密钥管理页面，单击密钥网络限制。
说明：
您也可以在左侧导航栏选择用户列表，单击目标子用户名称，进入用户详情页面，再选择 API 密钥页签，进入 API 密钥页面。
3. 在密钥网络限制页面，开启密钥级访问限制，开启后当前密钥访问将受本策略管控。
说明：
您也可以在此页面关闭密钥级访问限制，关闭后该密钥不受密钥级策略约束。
4. 在密钥网络限制页面，按需配置以下策略：
公网策略（最多1条）：填入允许调用的公网 IP 或 CIDR。若启用策略但未填写任何公网 IP，系统将拒绝所有来自公网的请求。
专有网络策略（最多8条）：从下拉框选择 VPC ID（登录态下会自动拉取 VPC 列表；若账号无 VPC 查询权限，可手动输入，系统不对 VPC ID 的存在性做二次校验），并填入该 VPC 内允许访问的 IP 段，每行最多50个 IP。
5. 确认无误后，单击确认。
6. 在确认窗口中，输入提示内容以二次确认，单击开启。
五、COS/CLS 网络限制
针对对象存储 COS、日志服务 CLS 的网络访问限制能力已在密钥级上线。开启后，密钥对 COS/CLS 的调用同样受 IP/VPC 白名单控制。
支持范围与默认策略
项目 | 说明 |
支持级别 | 本次仅密钥级密钥网络访问限制支持 COS/CLS 网络限制； 账号级与主账号暂不支持。 |
作用维度 | 子用户（子账号）维度 ：对该子用户下所有已配置密钥级网络限制的密钥生效。 |
默认策略 | 新创建的密钥，或未开启过密钥网络访问限制功能的子用户， 默认开启 COS/CLS 网络限制。 |
历史用户 | 已开启密钥网络访问限制功能的历史用户，需 主动开启 COS/CLS 网络限制后方可生效。 |
开启 COS/CLS 网络限制
1. 进入 API 密钥管理 页面，单击开启 COS/CLS 网络限制。
2. 在弹窗中查看开启 COS/CLS 网络限制说明与风险提示，确认完成后，勾选我确认 COS/CLS 调用 IP 并已加入白名单（必勾），并在下方输入子用户 UIN。
注意：
开启后，本子账号下所有已配置密钥级网络限制的密钥，其 COS/CLS 限制将一并纳入各自配置的 IP/VPC 白名单控制。
提交后，预计 10~15 分钟内全网生效。
若现有 IP/VPC 列表未覆盖其 COS/CLS 实际调用 IP，该密钥对应的业务将被立即拦截。
请确认已通过操作审计日志、COS/CLS 日志，核查最近 30 天 COS/CLS 调用源 IP，并已加入“公网限制策略”或“专有网络限制策略”。
3. 单击确认提交配置。
关闭 COS/CLS 网络限制（可选）
1. 进入 API 密钥管理 页面，单击关闭 COS/CLS 网络限制。
2. 在弹窗中查看关闭 COS/CLS 网络限制说明与风险提示，确认完成后，在下方输入子用户 UIN。
注意：
关闭后，子账号下所有已配置密钥级网络限制的密钥，对 COS/CLS 的访问将恢复为无限制状态，不再受 IP/VPC 的限制策略控制。
各密钥已配置的 IP/VPC 限制保持不变，不受本次关闭影响。
提交后 10~15 分钟内全网生效，期间 COS/CLS 限制将逐步失效，在此之前的调用仍受限。
3. 单击确认提交配置。
五、注意事项
密钥级策略与账号级策略为替代关系：已配置密钥级策略的密钥，仅按密钥级策略校验，账号级策略不再对其生效。
如果开启策略但未配置对应的允许来源，可能导致相关来源的 API 请求被拒绝。例如，仅配置 VPC 策略而未配置公网策略时，公网来源请求可能被拒绝。
修改策略后，全网生效可能存在分钟级延迟。建议在业务低峰期进行配置变更。
不建议频繁修改同一密钥对应的网络访问限制策略，避免因策略缓存尚未更新导致业务调用结果不符合预期。
开启 COS/CLS 网络限制前，务必核查最近 30 天 COS/CLS 调用源 IP 并加入白名单，避免业务被立即拦截。
COS/CLS 网络限制在子用户维度统一开启或关闭；账号级与主账号暂不支持 COS/CLS 网络限制。
六、常见问题
（一）如何确认自己的业务调用属于"公网"还是"专有网络"？
若调用方走公网 Endpoint，来源 IP 为出口公网 IP 或 NAT 网关上的 EIP，属于公网调用，请配置公网策略。
若调用方走 VPC 内网 Endpoint，来源 IP 为 VPC 内部 IP，属于专有网络调用，请配置对应 VPC 策略。
云产品之间互相调用（例如 SCF 调用 COS）的来源 IP 可能是云产品内部地址，此类跨云产品调用推荐优先使用角色扮演（Role + 临时密钥），而不是永久密钥。
（二）API 调用被拒绝时如何排查？
请按以下顺序排查：
1. 确认请求中使用的 SecretId。
2. 检查该 SecretId 是否配置了密钥级密钥网络访问限制。
3. 如果已配置，请检查请求来源是否命中密钥级策略；如果未配置，请检查账号级密钥网络访问限制是否开启，以及请求来源是否命中账号级策略。
4. 通过操作审计查询实际来源 IP，并与策略中配置的 IP 或 IP 段进行比对。
（三）策略提交后多久生效？
提交成功到全局生效之间存在分钟级延迟（COS/CLS 网络限制开启或关闭为 10~15 分钟内全网生效）。期间旧策略与新策略都可能命中，请避开业务高峰进行变更。
（四）临时密钥（STS Token）会受该策略限制吗？
不会。本功能仅对永久密钥（SecretId/SecretKey）生效。如需对临时密钥做更细粒度的控制，请在 CAM 策略语法中使用 qcs:ip 条件键。
（五）如何开通密钥级网络访问限制？
（六）如何判断我的子用户是否默认开启了 COS/CLS 网络限制？
进入 API 密钥管理 页面，页面按钮展示为关闭 COS/CLS 网络限制，则说明已默认开启了 COS/CLS 网络限制。
新创建的密钥，或未开启过密钥网络访问限制功能的子用户，默认为开启状态；已开启过密钥网络访问限制功能的历史用户，需主动开启后生效。
（七）开启 COS/CLS 网络限制后，会影响子账号下哪些密钥？
仅影响该子账号下已配置密钥级网络限制的密钥：这些密钥的 COS/CLS 调用将一并纳入各自已配置的 IP/VPC 白名单控制。未配置密钥级网络限制的密钥不受影响。
（八）开启 COS/CLS 网络限制前，如何核查实际调用源 IP？
请通过操作审计日志、COS/CLS 日志，检索最近 30 天 COS/CLS 调用记录并统计来源 IP，确认这些 IP 已加入对应密钥的公网限制策略或专有网络限制策略。若白名单未覆盖实际调用 IP，开启后相关业务将被立即拦截。
（九）主账号可以使用 COS/CLS 网络限制吗？
暂不支持。COS/CLS 网络限制仅在密钥级支持，且作用维度为子用户（子账号），主账号与账号级配置均暂不支持。
（十）关闭 COS/CLS 网络限制后，已配置的 IP/VPC 策略会丢失吗？
不会。关闭后，子账号下所有已配置密钥级网络限制的密钥，对 COS/CLS 的访问恢复为无限制状态，但各密钥已配置的 IP/VPC 限制保持不变，不受本次关闭影响。关闭操作同样存在 10~15 分钟全网生效过渡期，期间 COS/CLS 限制逐步失效。
（十一）专有网络策略中的 VPC ID 如何填写？系统会校验 VPC 是否存在吗？
进入 API 密钥管理 页面，单击密钥网络限制，进入密钥网络限制页面，单击专有网络策略模块的添加专有网络策略，在下拉框选择 VPC ID（登录态下会自动拉取 VPC 列表）；若账号无 VPC 查询权限，可手动输入 VPC ID，系统不对 VPC ID 的存在性做二次校验，请自行确认填写正确。另外，使用专有网络策略时，调用方需通过 internal 域名访问腾讯云 API，否则请求可能无法命中对应的网络访问限制策略。
