sonarqube管理员指南

sonarqube管理员指南

雷建锋

一、配置项目组合和应用

说明：投资组合和应用程序是企业版SONAR的一部分。

• UI Path : Administration > Configuration > Portfolios
•  Permission : you must have the Global Permission "Administer System" to access this page

         投资组合管理界面允许您同时配置投资组合和应用程序。它分为两或三列。左边是顶级投资组合和应用程序的列表。如果选择了一个投资组合，将显示另外两个列：子投资组合和项目。如果选择应用程序，则只有项目列可用。

         从这里，您可以编辑或删除一个现有的组合或应用程序，或者创建一个新的项目组合或应用程序。

1.       新建组合/应用：使用界面左上角的“Create”按钮打开创建对话框。您需要提供一个名称。您可以选择指定一个描述和key.visibility默认值为public，但是可以选择私有的。私有的投资组合和应用程序只对那些显式授予权限的人可见。

2.       组合：一旦您的组合存在，您就可以使用项目、应用程序和子组合的任意组合填充它。应用程序只填充项目。

3.       添加一个子投资组合：要添加子投资组合，请单击第三列顶部的“Add Portfolio”，然后选择：

l  标准-此选项允许您创建一个新的子项目组合。一旦创建，您可以添加项目、应用程序和更多的子投资组合层

l  本地引用-此选项允许您将现有的投资组合/应用程序作为子组合来引用。一旦添加，它在此处不可编辑，要编辑必须在最左边列中选中。

4.       将项目添加到项目组合中：要将项目直接添加到项目组合或标准子项目组合中，首先在左列中选择项目组合，在中间列中选择子组合(如果需要)。项目选择模式有四种：1）手动-一个个选择项目 2）手动度量-选择手动度量(仅文本度量)，并设置项目在此项目组合中包含的该度量的值 3）所有剩余的项目-选择此选项，以添加所有尚未包括在此项目组合(直接或通过子项目组合)的项目。

5.       计算后：启动计算时，真正的工作是在sonarqube服务器端完成。对于每个组合，创建了一个“后台任务”，您可以通过查看每个组合的可用日志来跟踪管理>项目>后台任务中每个项目的进展情况。

二、自定义度量

         SONARQUBE以自动化的方式收集最多的度量数据，但有一些度量不可能的收集到的，比如：信息无法收集，度量由人计算，等等。不管是什么原因，SONARQUE提供了一种手动注入这些度量的服务，并允许您从其他服务中受益：人工度量服务。输入的手动度量将在项目的下一次分析中选择，然后作为“正常”度量处理。

管理自定义度量：与自动收集的度量一样，手动度量也是根据度量收集的。因此，第一件事是创建要保存度量的度量。为了做到这一点，以系统管理员的身份登录并转到管理>配置>自定义度量：

可以在项目级别和模块级别输入自定义度量值。若要添加度量值，以项目管理员身份登录，需要项目并选择管理>自定义度量值。您将收到一个表，其中包含为每个度量输入的最新度量值：

橙色标记表示自输入手动度量值以来没有运行过分析，因此它不会出现在组件上。从那里，您可以编辑或删除现有的度量值或输入新的度量值。

         无论对自定义度量值采取什么操作，新值都将由组件的下一次分析来选择，并显示在度量值页面中以及其他所有内容中。

三、GIT集成

         使用纯java实现支持Git集成，因此不需要在执行分析的机器上安装git命令行工具。如果项目根目录或其父文件夹中有.git文件夹，将在分析期间自动检测git。否则，可以使用-dsonar.scm.Provider=git强制提供程序。要使这种集成能够收集所需的指责信息(blame information)，就需要一个完整的克隆。如果检测到浅克隆，将记录一个警告，并不会尝试检索错误信息。

jgit是git客户端的纯java实现：https：/

四、Housekeeping

         当您对项目进行新的分析时，以前可用的一些数据将从数据库中清除。例如，前面分析的源代码、目录和文件级别的度量等都会在新分析的末尾自动删除。此外，一些旧的分析快照也会被删除。为什么？嗯，经常分析一个项目以了解其质量的变化是有用的。能够看到几周、几个月、几年的趋势也是有用的。但是当您回顾过去时，您实际上并不需要与项目当前状态相同的详细信息。为了节省空间和提高总体性能，数据库清洁器删除了数据库中的一些行。这是它的默认配置：

1.       对项目来说：1）1天后，每天只保留一次快照。不删除由事件标记的快照。2）在未删除事件标记的快照后，每周只保留一次快照。3）一年后，每月只保留一次快照。不删除由事件标记的快照。4）只有版本事件的快照在2年后保存。不带事件的快照或只有其他事件类型的快照将被删除。5）删除所有超过5年的快照，包括由事件标记的快照。

2.       删除超过三十天的已关闭问题

3.       删除包/目录级别的历史记录

这些设置可以在“管理”>“通用”>“数据库清洁器”中更改。

五、LDAP集成

         您可以通过在$sonarqube_home/conf/sonar.properties文件中配置正确的值来配置LDAP服务器的sonarqube身份验证和授权(包括活动目录的LDAP服务)。主要特点是：

1.       密码检查与外部身份验证

2.       自动同步用户名和电子邮件

3.       用户和组之间关系的自动同步(授权)

4.       能够同时针对外部和内部身份验证系统进行身份验证。如果ldap服务器停机，SONAR内部系统就会出现自动回退

         在第一次身份验证中，如果用户的密码是正确的，那么sonarqube数据库就会自动填充新用户。每次用户登录到sonarqube、用户名、电子邮件和该用户所属的组时，都会在sonarqube数据库中刷新。您也可以选择组成员身份同步，但这不是默认的。

         LDAP配置示例：

# LDAP configuration

# General Configuration

sonar.security.realm=LDAP

ldap.url=ldap://myserver.mycompany.com

ldap.bindDn=my_bind_dn

ldap.bindPassword=my_bind_password

  

# User Configuration

ldap.user.baseDn=ou=Users,dc=mycompany,dc=com

ldap.user.request=(&(objectClass=inetOrgPerson)(uid={login}))

ldap.user.realNameAttribute=cn

ldap.user.emailAttribute=mail

 

# Group Configuration

ldap.group.baseDn=ou=Groups,dc=sonarsource,dc=com

ldap.group.request=(&(objectClass=posixGroup)(memberUid={uid}))

六、管理计算引擎性能

         说明：管理计算机引擎性能的能力可作为企业版的一部分

         如何更快地通过计算引擎队列进行分析？如果分析过程太长，可能需要增加计算引擎(Ce)工作者(worker)的数量(全局管理>项目>后台任务>工作者数量)。有两个情形需要考虑：

1.       慢是因为队列中常常满是挂起的任务

2.       任务要单独花费很长时间来处理

         在情形1中，增加工人人数是有帮助的。在情形2中，应小心评估这点。无论是哪种情况，在考虑增加计算机工程工作者的人数时，都应回答两个问题：

1.       我的基础设施是否允许我增加工人的数量？

2.       我应该在多大程度上增加工人的数量？也就是说，我应该配置多少？

        

         增加工人人数会增加计算引擎所消耗的资源的压力。这些资源是：数据库、磁盘IO、网络、CPU、内存等。其中，只有CPU和内存属于内部计算引擎。

         如果速度慢来自任何外部资源(db、磁盘I/o、网络)，那么增加工作人员的数量实际上会减慢单个报告的处理速度(想象一下两个人同时试图通过一个门)。然而，如果您的慢速度是由大量的个体分析报告造成的，占用计算机引擎工作很长的时间，那么通过添加另一个工作人员可以实现并行处理。但如果你这么做了，你需要看看内部资源。

l  计算机引擎员工(workers)不是CPU密集型的，内存使用完全取决于所分析的项目。有些需要很多内存，有些则不需要很多。但是，如果有多个计算机引擎工作人员，你应该把计算机引擎堆的数量增加一倍。同样的逻辑适用于CPU：如果一个工作人员运行到CPU的百分之Y，那么你应该计划Z工需要CPU的y*z %。

         要准确诊断您的情况，请监视网络延迟、SONAR实例的I/O以及数据库CPU和内存的使用情况，以评估慢度是否主要/仅与外部资源有关。

七、应用市场

管理员可以通过 配置->应用市场来访问应用市场，它是用来更新sonarqube平台的地方。在这里您可以

1、看到当前安装的SOANR版本、已安装的插件、插件是否有更新、其他插件与现有插件的兼容性等

2、发现更新的可用的sonar版本

3、安装新插件以及更新插件，在新插件起作用之前，需要重启服务

另外，若无法连接到互联网，也可以离线安装升级插件：下载插件，然后把插件放到 [sonarqube-home]/extensions/downloads目录，最后重启服务即可。

八、通知机制

         每一个分析，sonar都可以通过邮件将结果自动发送给订阅用户；也可以设置延迟发送时间，通过在SONAR_HOME/conf/sonar.properties 文件中设置sonar.notifications.delay属性值实现。设置完成后，需要重启服务后才能生效。

         邮件配置：配置->通用设置->邮件。可以配置邮箱SMTP、端口号、邮箱地址、邮件前缀等等。

九、

         通常，项目是在他们的第一次分析期间创建的，并且永远不会被删除（因为旧的软件永远不会消失）。对于非典型情况，有一个管理项目的页面，它允许您管理项目的存在：配置->项目->管理。

在第一次分析之前，我如何提供一个项目？

         提供一个项目允许您在运行第一个分析之前声明和配置它（定义权限，设置质量概要文件等等），要能够提供项目，您必须登录并获得供应项目的许可。

        在“配置->项目->管理”页面，点击“创建项目”，可以新建一个项目；一旦项目被准备好，您就可以配置它（定义权限、设置质量配置文件等），当您完成配置之后，您可以简单地运行项目的第一个分析。您还可以使用Web API提供和配置项目。

我如何找到供应的项目（还没有分析过）？

         项目管理搜索界面（配置->项目->管理）包括一个开关，允许你将你的搜索结果缩小到只有那些从未被分析过的项目。从那里你可以在这个页面上作为一个集合来处理它们，或者点击单个项目的主页以获得个人的关注和管理。

如何锁定项目的权限（公开或私有）？

         默认情况下，任何新创建的项目都会被认为是“公共的”。这意味着每一个SonarQube用户，无论是否经过认证，都将能够：

l  浏览：访问一个项目，浏览它的度量，问题并执行一些问题编辑（确认/重新/重新打开，分配，评论）

l  查看源代码：查看项目的源代码

         如果您想要确保只有有限的组和用户可以看到项目，那么您需要将其标记为私有。一旦项目是私有的，您就可以定义哪些组和用户可以浏览项目或查看源代码。如果您希望所有新创建的项目都被认为是“私有的”，那么您可以改变管理项目的默认可见性。

如何删除一个项目：项目可以单独从项目的管理页面中删除。有关更多细节，请参见项目设置。要批量删除项目，使用管理项目。在这里，您可以选择要删除的项目。一个被删除的项目已经消失了，没有办法撤销这个操作。

如何找到不再分析的项目？项目管理搜索界面包括一个日期选择器，帮助您找到在指定日期之前分析的所有项目。从这里你可以在这个页面上处理它们作为一个集合，或者点击进入单个项目的主页以获得个人的关注和管理。

十、项目移动（Move）

         项目Move允许您从一个SonarQube实例导出一个项目，并将其导入另一个相同配置的SonarQube实例。要使用项目Move，您必须在源实例中拥有项目的管理权限，并访问两个实例的文件系统。

         什么时候使用项目移动？

l  您想要在企业级创建一个中央SonarQube实例，您希望保留创建在团队级别的N个SONAR实例的历史

l  你的公司正在收购另一家公司，这家公司已经有了一个中心化的SonarQube实例

l  一个应用程序在一个大公司中从一个团队转移到另一个团队，该公司有几个SonarQube实例

先决条件：为了能够导出并加载项目的数据，这两个SonarQube实例必须有：

l  相同的版本

l  相同版本的插件

l  相同的自定义指标

l  相同的自定义规则

如何导出实例？

在源实例:

l  最后一次对项目进行重新分析，以确保它填充了与当前SonarQube安装相对应的数据

l  导航到项目和项目级别，选择管理导入/导出

l  点击Export按钮来生成一个zip文件，其中包含项目的设置和历史（但不是源代码）。注意，如果您需要更改项目的密钥，您必须在执行导出之前执行。

包含所有项目数据的zip文件导出到：$SONAR_SOURCE_HOME/data/governance/project_dumps/export/ under the name .zip

如何导入实例？

在目标实例：

l  拥有“管理系统”和“创建项目”权限的用户，可以使用项目在源实例中使用的相同密钥来管理和提供项目，路径：dministration > Projects > Management

l  配置项目的权限，以及与项目相关的质量配置文件和质量阀

l  将生成的zip文件放入目录中：$SONAR_TARGET_HOME/data/governance/project_dumps/import

l  进入项目的主页并选择Administration > Import / Export

l  点击Import按钮开始导入您的数据

l  源代码不包含在zip文件中。一旦导入完成，就触发一个分析将源文件导入到新的实例中

说明：

l  如果导入成功，zip文件将自动被删除

l  导入已经在目标实例上已经分析过的项目是不可能的

十一、质量配置文件

         质量配置文件服务是SonarQube的核心，因为它是您通过定义规则集来定义您的需求的地方（例如：方法不应该有大于15的复杂度）。理想情况下，所有的项目都将以相同的配置文件来衡量，但这并不总是可行的。例如，你可能会发现：

l  不同的应用程序用不同的技术来实现（例如，在构建线程或非线程Java应用程序时可能应用不同的编码规则）。

l  您希望确保对某些应用程序的需求更强（例如，内部框架）

         这就是为什么您可以定义尽可能多的质量配置文件，尽管建议尽可能少的质量配置文件，以确保您公司的项目的一致性。要管理质量配置文件，请转到质量配置文件（顶部栏），在那里您可以找到按语言分组的配置文件。

         每个语言插件都有一个预定义的内置配置文件（通常称为“sonar way”），这样您就可以非常快速地开始使用SonarQube分析。这就是为什么当你安装一个新的语言插件时，至少会有一个质量配置文件可供你使用。每种语言都必须有一个默认配置文件（标记为默认标记）。与特定配置件没有显式关联的项目将使用该语言的缺省配置文件分析。

         当从一个新安装开始时，很容易使用sonar way作为默认配置文件，因为它包含了所有通常适用于大多数项目的规则。但是作为一个最佳实践，您应该创建一个新的概要文件（您可以通过复制声纳的内容来填充它）并使用它。为什么?首先，因为sonar way 的配置文件是不可编辑的，所以你无法根据你的需要定制它。同样，这也可以让你把sonar way作为基准，在你对它进行修改的时候，你可以追踪你自己的个人资料（你会这样做的）。另外，sonar way通常会随着插件的每一个新版本更新，以添加规则，有时还会调整规则。任何从内置的sonar way继承的配置文件都将在同一时间自动更新。

HOW TO DOS:

        

ü  如何将质量配置文件的管理委派给其他人？

默认情况下，只有具有“管理质量配置文件”权限的用户才能编辑质量配置文件，但是在大型组织中，不需要授予权限来更改所有质量配置文件，这可能是不可取的。这就是为什么你也可以授权用户/组编辑一个个人的质量档案，例如，Swift档案的管理可以委托给一组Swift专家，对COBOL也是一样的。这个权限的授权只能由已经拥有“管理质量概要”权限的人来执行，或者在概要文件上有单独的编辑权限，这样就可以授予额外的权限。授予个人权限的接口可以在概要文件详细页面上找到。

ü  如何把规则从一个配置文件复制到另一个配置文件？

            很多时候，人们想要从一个基于内置配置文件的配置文件中工作，而不需要实际使用内置的配置文件。在这种情况下，最简单的方法是使用原始配置文件，我们称它为源文件，在质量配置文件中。从这里开始，在规则页面上点击查看源代码的总数量，然后在源代码的规则范围内进行预先的搜索。使用批量激活来在你的目标配置文件中改变源的规则。

ü  如何知道配置文件中发生了什么变化？

         当SonarQube注意到一个分析是用一个与之前的分析不同的方式进行的，质量配置事件添加到项目的事件日志。要查看概要文件中的更改，导航到配置文件 (Quality Profiles > [ Profile Name ]), 然后选择更新日志。这可以帮助您了解概要文件的变化如何影响分析中提出的问题。

         此外，每次使用内置的配置文件（由分析人员直接提供的配置文件）更新时，通过电子邮件通知具有高质量配置管理权限的用户。这些更新只能由分析器更新引起。

ü  如何从一个SonarQube实例复制一个配置文件到另一个实例？

         在源实例上使用Back up特性将概要文件导出到XML文件。在目标实例上使用Restore Profile特性来导入文件。请注意，该特性存在一些限制： - Make it possible to back up and restore customizations of rules OPEN

ü  如何对项目应用一组核心规则和附加规则？

         假设您的公司有一个所有团队都必须遵循的最小编码规则集，但是您想要添加特定规则用于特定项目。这些规则对你的团队是有好处的，但对其他人来说是无关的，甚至是误导。这种情况需要继承。建立一个基本的配置文件，我们用你的核心规则来命名它为Root。一旦它被创建，您就可以改变父类从根继承，然后添加您丢失的规则。

ü  如何确保我的非默认配置文件在一个项目中使用？

         每种语言的一个配置文件都标记为缺省值。除非有其他的干预，所有使用该语言的项目都将使用该配置文件进行分析。要让一个项目由非默认配置文件进行分析，从质量配置文件（Quality Profiles）开始，然后单击目标配置文件，然后管理哪些项目被显式地分配给配置文件。

ü  如何确保在我的配置文件中已经获得所有相关的新规则？

         每次发布一个语言插件更新时，都会添加新的规则，但是它们不会自动出现在你的个人资料中，除非你使用的是内置的配置文件，比如sonar way。

         如果你没有使用内置的配置文件，你可以将你的个人资料与内置的概要文件进行比较，以查看你丢失的新默认规则；另一种选择是进入规则空间，并使用Available Since 搜索项，查看自从升级相关插件以来，该平台添加了哪些规则。

ü  如何比较两个配置文件？

         从质量配置（Quality Profiles）页面开始，单击您想要比较的概要文件，然后使用 Actions > Compare接口来选择第二个概要文件，并查看其中的区别。

ü  如何确保我的配置文件中没有已弃用的的规则？

         规则接口本身的弃用规则部分是您的第一个警告，即配置文件包含已弃用的规则。这个粉红色背景部分给出了当前在profiles中活动的弃用规则的总数，以及每个配置文件的弃用计数的分解。这里的一个点击将带您到规则页面来编辑所讨论的配置文件。

         另外，你可以在一个配置文件中执行规则搜索（手动或通过从质量配置页进行点击），并使用状态规则搜索面将列表缩小到需要注意的列表。

十二、安全

         SonarQube有一个完整的机制来管理安全性（认证+授权）。配置安全性允许您覆盖两个主要情况：

1.       管理组件、信息等的访问权限

2.       为用户启用SonarQube定制（通知等）

下面是一些安全限制的例子，您可以通过在SonarQube中配置安全性来执行这些限制：

1.       通过在访问任何页面之前强制认证，从而确保SonarQube实例的安全

2.       使一个给定的项目对匿名用户不可见

3.       限制对给定组用户的项目访问

4.       将项目源代码的访问限制为给定的一组用户

5.       定义谁可以管理一个项目（设置排除模式，为该项目调整插件配置，等等）

6.       定义谁可以管理SonarQube实例

有关如何配置内置安全机制的详细说明，请浏览和。

身份验证和授权也可以委托给外部系统：

1.       LDAP或Active Directory-

2.       Crowd-

3.       GitHub - 

4.       Bitbucket - 

安全性的另一个方面是对诸如密码等设置的加密。SonarQube提供了一种内置的机制。

十三、服务器日志管理

服务器端日志是由设定的属性控制的：$SONARQUBE_HOME/conf/sonar.properties.

4个日志文件被创建：每个 SonarQube进程。

日志级别

服务器端日志级别可以通过sonar.log.level 属性进行定制，支持的值是:

·        INFO (默认)

·        DEBUG - for advanced logs

·        TRACE - 显示高级日志和所有SQL和 Elasticsearch请求。TRACE级别的日志记录减慢了服务器环境的速度，应该只用于跟踪web请求性能问题。

服务器端日志级别可以通过以下属性更精确地调整SonarQube服务器的4个进程：

·        sonar.log.level.app: for the Main process of SonarQube (aka WrapperSimpleApp, the bootstrapper process starting the 3 others) 

·        sonar.log.level.web: for the WebServer

·        sonar.log.level.ce: for the ComputeEngineServer

·        sonar.log.level.es: for the SearchServer

日志滚动Log Rotation

      要控制日志滚动，请使用 sonar.log.rollingPolicy

·        time:[value] -基于时间的滚动。例如，使用时间：yyyy-MM-dd用于每日滚动，以及时间：yyyy-MM每月滚动.

·        size:[value] -基于对大小的滚动。例如, size:10MB.

·        none -没有滚动。通常，当日志由像logrotate这样的外部系统处理时，就会使用这种方法。

sonar.log.max文件是要保存的文件的最大数量。如果 sonar.log.rollingPolicy=none，则这个属性被忽略。

十四、Sonar DB复制工具

这个工具的目标是帮助您从一个DB供应商到另一个供应商的迁移过程。让我们假设您曾经在Oracle上运行SonarQube实例，您想要迁移到MySQL，而不会丢失所有的历史分析。

详见：

十五、SVN集成

         支持的SVN版本是1.6.x到1.9.x。

         如果在项目的根目录中有一个.SVN文件夹，则在分析期间自动检测SVN。否则，您可以在命令行上使用 -Dsonar.scm.provider=svn 来强制提供。

以上内容翻译至：

                   （全文完）