企业官网建设流程全解析

• 示例工程
• 数据库
• 教程
• 后端

SQL Assessment API 允许用户深度自定义规则集（ruleset）与探针（probe），其中权限需求（Permission Requirement）用于显式声明 probe 运行所需的最低权限，避免因权限不足导致评估过程中途失败。本文基于 sql-server-samples 仓库中 PermissionRequirement.md 的规范，结合仓库内置 ruleset.json 的真实 probe 定义，完整讲解权限需求的名称格式、取值规则、JSON 写法与底层判定机制，帮助你在自定义规则集时准确声明权限并理解跳过行为。

为什么需要声明权限需求

SQL Assessment API 的评估流程由多条规则（rule）驱动，每条规则通过一个或多个 probe 获取数据。默认情况下，只要某个 probe 在执行中抛错，整个评估流程就会立即终止，导致后续所有检查都无法运行，最终得到不完整的结果。

典型场景：下面这个DBMetaInfoprobe 使用DBCC DBINFO读取数据库元数据，该命令要求调用者拥有sysadmin角色权限。如果当前登录用户不是sysadmin，probe 会直接报错并中断整个评估：

"DBMetaInfo": [ { "type": "SQL", "target": { "type": "Database" }, "implementation": { "query": "DBCC DBINFO(@TargetName) WITH TABLERESULTS,NO_INFOMSGS" } } ]

通过在 probe 的requires属性中显式声明前置条件，SQL Assessment API 会在执行查询之前先校验权限；不满足时不会执行查询，所有依赖该 probe 的检查都会被跳过，并仅向用户返回一条警告，而不是中断整个评估：

"DBMetaInfo": [ { "type": "SQL", "target": { "type": "Database" }, "implementation": { "query": "DBCC DBINFO(@TargetName) WITH TABLERESULTS,NO_INFOMSGS" }, "requires": { "role": [ "sysadmin" ] } } ]

关于该机制的完整说明，可参见 Probe requirements 总览 以及 Probe.md 中requires与runFor两个属性的语义定义。

权限需求的名称格式

权限需求（permission requirement）的键名遵循如下格式：

securable_class permission [on securable_name]

各部分含义如下：

关键约定：当安全对象本身是服务器（SERVER）或数据库（DATABASE）时，securable_name部分应当省略，直接写作server permission或database permission形式。

支持的取值范围

权限需求的允许值取决于securable_class对应的安全对象类别。SQL Server 为不同类别定义了各自的权限集合与层次结构：

• 服务器级权限（如ALTER TRACE、ADMINISTER BULK OPERATIONS、VIEW SERVER STATE）：适用于SERVER类；
• 数据库级权限（如SELECT、VIEW DATABASE STATE、ALTER ANY DATABASE）：适用于DATABASE类；
• 对象级权限（如表、视图、存储过程上的SELECT、EXECUTE等）：适用于OBJECT类，此时必须通过on securable_name指明具体对象；
• 其他安全对象类别（如REMOTE SERVICE BINDING）同样遵循对应类别的权限定义。

权限校验的底层依据是 SQL Server 系统函数 sys.fn_my_permissions——该函数返回当前主体（principal）在指定安全对象上实际生效的权限列表，SQL Assessment API 正是基于它来判断 probe 的权限需求是否满足。更完整的权限清单与层次关系可参考 SQL Server 官方文档中的SQL Server Permissions与Permissions Hierarchy两篇资料。

实战示例：原文档与内置规则集的双重印证

服务器级权限：ALTER TRACE

requires的值是一个 JSON 对象，属性名即需求名称，属性值为字符串数组，列出需要校验的权限。下面的声明要求当前用户拥有ALTER TRACE服务器权限：

"requires": { "server permission": [ "ALTER TRACE" ] }

这一写法在仓库内置规则集 ruleset.json 中被真实使用：CountBlackBoxTraces与CountDefaultTraces两个 probe 都通过sys.traces视图查询服务器跟踪信息，而查询该视图需要ALTER TRACE权限，因此它们都在requires中声明了相同权限（见 ruleset.json 第 18412 行）：

"CountBlackBoxTraces": [ { "type": "SQL", "target": { "engineEdition": "SqlServer, ManagedInstance", "version": "[11.0,)" }, "requires": { "server permission": [ "ALTER TRACE" ] }, "implementation": { "query": "SELECT COUNT(id) AS [BlackBoxTraceCount] FROM [sys].[traces] WITH (NOLOCK) WHERE [path] LIKE '%blackbox%.trc' AND status = 1;" } } ]

对象级权限：对 msdb 系统表加 SELECT

当 probe 需要读取某个具体对象（如表、视图）时，使用object permission on <对象名>形式声明。例如读取msdb数据库中的sysalerts表需要SELECT权限：

"requires": { "object permission on [msdb].[dbo].[sysalerts]": [ "SELECT" ] }

内置规则集中的SysAlertsprobe 正是这一写法（见 ruleset.json 第 18879 行），其查询体直接读取[msdb].[dbo].[sysalerts]，因此需求与实现严格对应：

"SysAlerts": [ { "type": "SQL", "target": { "engineEdition": "SqlServer, ManagedInstance", "version": "[11.0,)" }, "requires": { "object permission on [msdb].[dbo].[sysalerts]": [ "SELECT" ] }, "implementation": { "query": "SELECT DISTINCT severity, message_id FROM [msdb].[dbo].[sysalerts] WITH (NOLOCK)" } } ]

多权限需求：同时声明多个对象权限

requires对象内可以包含多个权限需求键，同一 probe 可同时校验多个对象上的权限。内置规则集中的DeprecatedFeaturesJobsprobe 需要同时读取sysjobs与sysjobsteps两张 msdb 表，因此在requires中并列声明了两项object permission（见 ruleset.json 第 19078 行）：

"requires": { "object permission on [msdb].[dbo].[sysjobs]": [ "SELECT" ], "object permission on [msdb].[dbo].[sysjobsteps]": [ "SELECT" ] }

需要说明的是，权限需求数组中的多项权限按"与"的关系判定——即当前用户必须同时满足数组中声明的全部权限，probe 才会执行；缺少任意一项，probe 都会被跳过并触发警告。

requires 与 runFor 的区别

权限需求只是 probe 需求（Probe Requirements）体系中的一种。与之并列的还有角色（role）、功能特性（feature）与服务（service）三类需求。所有需求的 JSON 形态一致：属性名为需求类型名称，属性值为字符串数组。

更值得关注的是probe 上有两个承载需求的属性，它们在语义上存在关键差异：

runFor适用于"某场景下 probe 本就不该运行、跳过是正常预期"的情况。例如探测数据库镜像端点的 probe 在未启用 HADR（高可用与灾难恢复）的实例上运行没有意义，若用requires声明，每次对非 HADR 实例评估都会冒出警告，反而造成困扰；改用runFor后则静默跳过：

"AGEndpoints": [ { "type": "SQL", "target": { "type": "Server" }, "implementation": { "query": " … " }, "runFor": { "feature": [ "HADR" ] } } ]

内置规则集中AGConfiguration、AGDatabases等 Always On 相关 probe 均采用这一模式（见 ruleset.json 第 19946 行），保证未配置可用性组的实例在评估时不被无关警告打扰。

需求类型速查：role / feature / service

角色需求的 JSON 写法示例（要求用户同时属于bulkadmin与diskadmin角色）：

"requires": { "role": [ "bulkadmin", "diskadmin" ] }

内置规则集中的VLFprobe 即使用role: sysadmin声明需求，因为其查询体执行DBCC LOGINFO（见 ruleset.json 第 18926 行）。

在自定义规则集中落地权限需求

要把权限需求应用到自己的规则集中，只需在自定义 ruleset 的probes部分为对应 probe 添加requires（或runFor）属性。仓库提供了可直接参考的完整自定义样例 MakingCustomChecks_sample.json，其中展示了rules与probes两个顶级节点的完整结构；内置 ruleset.json 与可读版本 DefaultRuleset.csv 则收录了数百条生产级规则的真实写法，可作为命名与取值的最佳实践参考。

在动手编写前建议遵循以下要点：

1. 需求与查询严格对应：probe 查询体访问了哪些安全对象、需要哪些权限，就逐一在requires中声明（对照SysAlerts与DeprecatedFeaturesJobs的写法）；
2. 服务器/数据库级权限省略对象名：server permission、database permission不需要on子句；
3. 对象级权限必须给出完整对象名：建议使用[库].[架构].[对象]形式的多部分名称，避免歧义；
4. 区分 requires 与 runFor：权限不足属于异常场景用requires（保留警告），特性未启用属于正常场景用runFor（静默跳过）；
5. 先评估、后发布：自定义规则集可先通过 PowerShell SqlServer 模块（Install-Module -Name SqlServer -AllowClobber -Force）配合 QuickStart.md 中的Get-SqlInstance -ServerInstance 'localhost' | Invoke-SqlAssessment流程做小范围验证，观察警告与跳过行为是否符合预期。

小结

权限需求是 SQL Assessment API 自定义规则集中最常用的前置校验手段之一：它以securable_class permission [on securable_name]为名称格式，以sys.fn_my_permissions为底层判定依据，配合requires（失败即跳过 + 警告）与runFor（失败即返回空集）两种承载属性，让规则集在最小权限账户、异构实例环境下依然能完整、安静、可预期地完成评估。结合 ruleset.json 中CountBlackBoxTraces、SysAlerts、DeprecatedFeaturesJobs等 probe 的真实声明，你可以在自己的自定义规则集中精确复刻这一模式。

• 示例工程
• 数据库
• 教程
• 后端