企业官网建设流程全解析

早上九点半，CI 亮红灯，质量门禁没通过。我打开 SonarQube 一看，新增三十多个问题，其中两个 Blocker 级别。接下来的半小时，团队又进入了熟悉的“分锅”环节：挨个打开 issue，看文件路径，翻 git log 找最近改动的人，猜这是谁的代码，然后在群里喊一句“这个你有空看一下”。三十个问题，这么一轮下来至少折腾个把小时，而且经常猜错——真正写过那段逻辑的人，可能上周已经转去别的模块了。

SonarQube 其实早就有答案了。做完 SCM 集成之后，每一个 issue 都会带上作者信息，也就是根据 git 提交历史推算出来的“最后碰过这一行的人”。这篇文章想说的就是两件事：怎么把 SonarQube 内置的自动分配功能用起来，以及当内置规则满足不了团队的时候，怎么用 API 写一个自定义的分配脚本。适合接手质量门禁的技术负责人、在 CI 里维护 SonarQube 的工程师，以及任何不想每天早上玩“猜猜这是谁写的”的团队。

1. 自动分配到底解决了什么“分锅”问题

1.1 每天早上的手工“分锅会”

先把场景说清楚。SonarQube 扫出来的问题无非几类：Bug、漏洞、坏味道、安全热点。质量门禁挂了以后，团队第一反应不是改代码，而是先确认“这些是谁的”。手工流程通常是这样的：打开 issue 列表，从文件路径猜模块归属，然后切到代码仓库，在 git log 里翻这个文件最近的提交，找到提交人，再对照组织架构确认这个人现在还在不在这个项目里。一个 issue 走完这套流程，快则两三分钟，慢则五分钟。

数据一多就很可怕。假设一次 MR 引入二十个新问题，光“分锅”就要花一个小时。而且人肉判断经常出错，一个公共组件可能是三个人接力改过的，最后提交的人未必是埋雷的人。等真正改的人被找到，都快中午了。我见过有的团队每周五下午专门做一次“分锅会”，把一周积压的问题过一遍，这时间花得是真冤。问题的根源不在于“谁写了这段代码”这件事本身难以判断，而在于我们一直用手工方式去做一个版本管理工具早就记录好的事情——git blame 本身就是答案。

1.2 两条路线：内置开关加脚本兜底

SonarQube 的自动分配大致有两条路线可以走。

第一条是内置的 Automatic Issue Assignment。原理很简单：分析器在做扫描的时候，会对每个文件跑一次基于 SCM 历史的逐行归因，说白了就是它内部做了一次类似 git blame 的操作，把每一行代码对应到最后一个提交者。分析完成后，issue 会带上一个 author 字段，内置分配就是把这个 author 跟 SonarQube 的用户邮箱做匹配，匹配上了就自动指派给那个人。

第二条是 API 脚本路线。内置分配只管“作者是谁就指派给谁”这一件事，但实际研发场景里往往还有别的需求：某个模块有固定 owner、某类历史遗留问题需要按目录归堆、某些提交邮箱和 SonarQube 用户对不上号。这些时候就需要自己拉 issue、自己算归属、再调接口指派。两种路线不是替代关系，我先讲内置的，因为它零成本；再把脚本方案作为兜底补上。

2. 让 SonarQube 先“看明白”提交历史

2.1 SCM 集成的两级配置

自动分配的前提是 SonarQube 得认识你的代码仓库。SCM 集成分为两层，一层是项目里的分析参数，一层是服务端全局配置。

项目里通常写在 sonar-project.properties：

sonar.scm.provider=git sonar.scm.url=scm:git:https://git.example.com/group/project.git

sonar.scm.provider告诉分析器用哪个 SCM 提供器，常见的是 git。sonar.scm.url是为了让 SonarQube 能识别出仓库地址，在服务端配置不够明确的时候做确认。实际上大多数情况下分析环境里已经带了 .git 目录，分析器会自动检测出 SCM 类型，所以这两项不写也能跑，但我习惯显式写出来，因为日志里看得清楚，排查问题省时间。

服务端的全局配置在 Administration → General Settings → SCM。这里主要管的是：是否启用 SCM 集成、选默认提供器、是否需要传凭证。如果你在 CI 里跑扫描，分析环境本身已经 clone 了代码，那分析器直接读 .git 目录就行，服务端几乎不用额外配。有一点要注意：SonarQube 做逐行归因时会调用 JGit 去读提交历史，处理大仓的时候这个操作会有点耗时。第一次分析某个历史很长的项目，扫描时间可能比平时多个一两分钟，这些 SCM 数据会缓存进 SonarQube 的数据库表里，后续增量扫描不会每次都重算全量文件，所以不用太担心性能。

2.2 浅克隆是 SCM 数据缺失的头号原因

这块是实操里翻车最多的地方，我单独拎出来说。很多 CI 平台默认 checkout 的时候只拉最近一次提交，也就是 shallow clone，常见的形式是--depth 1或者 fetch-depth 设为 1。这种模式下，本地的 git 历史里只有最新一个 commit，SonarQube 想 blame 也没有足够历史，最后所有文件的 SCM 归因都是空的。

症状非常典型：分析日志里能看到 SCM 提供器被检测出来，文件也扫了，但 issue 的 author 字段是空的，界面里也点不出“最后一次修改的人”。如果在日志里看到类似 history 只有 1 条 commit 的记录，基本就是浅克隆没跑。

解决办法是在 CI 的 checkout 阶段把历史拉全。以通用的流水线配置为例，把 fetch-depth 设为 0，等效于拉全部历史；已经浅克隆的仓库可以补一条git fetch --unshallow。有些团队的仓库特别大，会觉得拉全历史很费时间，但从我的经验看，这个成本是值得的，因为 SCM 归因一旦缺失，后面所有自动化分配都无从谈起。真要是仓库大到拉历史难以忍受，再考虑只给 SonarQube 扫描这个独立 job 保留一个完整 clone，其他编译 job 继续用浅克隆。

2.3 提交邮箱标准化

内置执自动分配的逻辑是拿 SCM 的作者邮箱去匹配 SonarQube 用户邮箱。这就意味着提交代码时用的 git 邮箱必须和 SonarQube 里的用户邮箱一致，否则匹配不上，分配失败。

常见两种情况。一种是同一个开发者本地有几台电脑，某台机器上 git config 的 user.email 写得是私人邮箱，push 上去之后 SonarQube 拿着这个邮箱根本找不到对应用户。另一种是新人入职的时候 SonarQube 账号邮箱没更新，代码从老账号提交，新账号收不到任何 issue。这些属于脏数据问题，最有效的治理手段就是在仓库里压一条提交规范：git config user.email必须写在某个固定域名下，和公司账号体系一致；同时让 SonarQube 用户在创建的时候就从这个邮箱体系里同步过来。

检查一个人的提交邮箱很简单，git log -1 --pretty="%an <%ae>"。如果是历史仓库实在没法整改，那就在脚本方案里维护一张“旧邮箱到新用户”的映射表，这个问题后面再细说。

3. 内置方案：Automatic Issue Assignment 实战

3.1 项目设置里的三样关键配置

内置分配功能在项目设置里可以找到，路径大致是 Project Settings → General Settings → Issues → Automatic Issue Assignment。不同版本的界面布局略有差异，但核心配置就是三样。

第一，总开关。把 Automatic Issue Assignment 这个选项打开，SonarQube 才会在分析完成后尝试做分配。

第二，分配依据。这里选择“按 SCM 作者分配”，也就是说 issue 最终指派给谁，取决于该 issue 对应代码行的最后提交者。有些版本还提供基于邮件通知的分配方式，那是另外一套逻辑，走的是 commit 通知邮件解析，我在实际项目中基本不用，SCM 作者这种方式更直接。

第三，作者邮箱白名单。把团队成员的提交邮箱填进去，逗号分隔。只有出现在这个名单里的作者邮箱才会被尝试匹配用户然后自动分配，陌生邮箱扫出来的 issue 会保持未分配状态。这个白名单其实是个安全阀，防止外部贡献者或者机器人提交的代码自动分到某个人头上。

做完这三步，不需要改分析参数，下次扫描完就会生效。要强调一点：自动分配是按扫描批次来做的，已经存在于库里的历史 issue 不会因为配置开启而批量补齐，它只管“开配置之后的扫描”新产生的分配动作。如果想处理存量，后面脚本方案里有思路。

3.2 验证自动分配到底有没有生效

配置这种东西，配完必须验证，不然心里没底。我的做法是在一个测试项目里走一遍完整流程。

先在一个分支上故意引入一个能被 SonarQube 扫出来的坏味道，比如方法里留一个没用的局部变量，或者写个空方法。等扫描跑完，进 issue 列表，找到刚才那个问题，重点看两处：一处是 issue 详情里的 Author 字段，看是不是你自己；另一处是 Assignee 字段，看是不是已经自动填上了你的名字。

想看更细的数据，可以拉 API 确认。拿你自己项目的 token 调一下：

curl -u YOUR_TOKEN: \ 'http://sonar.example.com/api/issues/search?projectKeys=demo&statuses=OPEN&ps=20' \ | jq '.issues[] | {key, message, author, assignee}'

返回值里author来自 SCM 归因，assignee是实际指派人。如果你看到author有值但assignee是空的，那基本就是邮箱匹配没对上，去查 SonarQube 用户设置里的邮箱是不是和提交邮箱一致。我一般用这个 API 输出做交接收尾，比截图有说服力。

3.3 内置方案的边界

内置方案能覆盖七八成场景，但它有三个绕不开的边界。

第一个是它只认“最后碰过这一行的人”。代码被大面积格式化、重命名提交之后，最后提交者可能是做重构的人而不是埋雷的人。这个问题理论上存在，但实际影响没有想象中大，尤其是你只关心“新代码问题”的时候——质量问题通常集中在新提交的代码上，谁新写的谁负责，归因是比较准的。

第二个是它不支持模块归属。操作端到端项目的时候，公共基础库的问题最后提交者可能在业务组，但真正应该去改的人是基础库的 owner。内置分配做不到这种业务规则，必须靠脚本。

第三个是白名单之外的作者永远不会被分配，你不填邮箱，它就静默跳过。这不是 bug，是一个提醒：团队里有人的邮箱没进白名单，他产出的是问题就一直在池子里没人管。所以配置完之后，最好隔一两周拉一次“未分配 issue”清单看看，把漏网之鱼补上。

4. 脚本方案：用 API 把分配规则握在自己手里

4.1 需要脚本介入的常见场景

内置方案解决“按作者分锅”，但真实团队的诉求往往更复杂。我整理了自己经历过的三种场景。

场景一，按模块 owner 分。项目按核心网关、业务后端、前端管理台分成几个小组，每个组有固定负责人，公共组件的问题很难说清该谁改。这时候我希望分配规则是：先从 SCM 作者找，找不到或者作者已经离职，就按文件路径前缀匹配模块 owner。

场景二，存量问题清洗。内置方案只管新扫描，但历史积累的三四百个未分配 issue 还躺在那里。想一次性按同样规则把它们分出去，就必须脚本批量跑。

场景三，账户体系不一致。公司里提交代码用的邮箱前缀和 SonarQube 登录名对不上，内置匹配一直失败。脚本里维护映射表，把旧邮箱映射到正确的用户，问题当场解决。

这三个场景的共同点是都要求“分配规则自己说了算”，那就得用 API。

4.2 三个 API 端点串起整个流程

实现自动分配脚本其实只需要三个操作：查问题、查用户、改问题归属。

查问题用/api/issues/search。按项目 key 过滤，指定状态为未关闭，分页拉下来。返回的每条 issue 里有几个关键字段：key用于后续指派，author是 SCM 归因出来的作者邮箱，assignee是当前指派人，component是文件路径。脚本里要做的判断全都围绕这几个字段展开。

查用户用/api/users/search。这个接口可以拉出用户列表，把邮箱和登录名对应起来。注意分页，一次最多返回 500 条，需要循环拉完。如果需要更高的权限才能查全量，那就给 CI 里用的服务账号开对应权限，或者只拉一个固定用户组。

改归属用/api/issues/assign。POST 请求，带 issue 的 key 和要指派给的用户登录名。接口调用很轻，不存在事务性问题，失败重试即可。

这三个端点串起来的流程就是：拉未分配 issue 列表 → 解析每个人的 author → 用邮箱映射到登录名 → 调用 assign 接口指派。整体就是一个 100 行以内的脚本。

4.3 一个可以直接改的分配脚本

下面这个脚本我拆过很多次了，实际部署时只要改四个变量：服务端地址、token、项目 key、邮箱映射表。Python 3 加 requests 就够了。

import requests BASE = "http://sonar.example.com" # 你的 SonarQube 地址 TOKEN = "你的sonar用户token" HEADERS = {"Authorization": f"Bearer {TOKEN}"} PROJECT_KEY = "my_platform" # 兜底映射：提交邮箱 -> SonarQube 登录名 # 适用于内置匹配不上的历史邮箱，可留空 EMAIL_TO_LOGIN = { "old.dev@example.com": "dev.zhang", } def fetch_open_issues(project_key): issues, page = [], 1 while True: params = { "projectKeys": project_key, "statuses": "OPEN,CONFIRMED,REOPENED", "ps": 100, "p": page, } r = requests.get(f"{BASE}/api/issues/search", params=params, headers=HEADERS, timeout=30) r.raise_for_status() data = r.json() issues.extend(data["issues"]) page += 1 if page > (data["total"] + 99) // 100: break return issues def build_user_map(): mapping, page = {}, 1 while True: params = {"ps": 500, "p": page} r = requests.get(f"{BASE}/api/users/search", params=params, headers=HEADERS, timeout=30) r.raise_for_status() users = r.json().get("users", []) for u in users: email = (u.get("email") or "").strip().lower() if email: mapping[email] = u["login"] page += 1 if len(users) < 500: break mapping.update(EMAIL_TO_LOGIN) return mapping def assign_issue(issue_key, login): params = {"issue": issue_key, "assignee": login} r = requests.post(f"{BASE}/api/issues/assign", params=params, headers=HEADERS, timeout=15) r.raise_for_status() user_map = build_user_map() unassigned = [it for it in fetch_open_issues(PROJECT_KEY) if not it.get("assignee")] for issue in unassigned: author = (issue.get("author") or "").strip().lower() login = user_map.get(author) if not login: print(f"skip {issue['key']} author={author or 'none'}") continue assign_issue(issue["key"], login) print(f"assigned {issue['key']} -> {login}")

几个细节值得说一下。分页循环必须处理 total 和 ps 的关系，否则项目一多就只分到前一百个。用户列表接口每次最多 500 条，所以我拿列表长度判断是否还有下一页。author字段可能为空，脚本里做了兼容，空作者直接跳过而不是报错，因为有些文件确实没有 SCM 归因。

第一次跑的时候强烈建议先加一个 dry-run 模式，只打印“会把谁分给谁”，确认规则没问题再真正调 assign 接口。改接口是幂等的，重复指派不会产生副作用，但手动确认一遍比事后撤销要省心得多。

4.4 按模块归属兜底分配

我在项目里把脚本扩展了一下，加了一层模块归属兜底。规则是这样的：优先按 SCM 作者分配；如果作者匹配不上，就按文件路径前缀找模块 owner；再找不到就保持未分配。

路径归属用一张简单的列表就能描述：

PATH_OWNERS = [ ("backend-gateway/src/main/java", "gateway_owner@example.com"), ("frontend/packages/admin", "admin_fe_owner@example.com"), ("common/", "platform_owner@example.com"), ] def owner_by_path(component): for prefix, email in PATH_OWNERS: if component.startswith(prefix): return email return None

注意路径匹配的顺序，公共前缀要放在靠后的位置，更具体的模块路径放前面，不然common/会把所有匹配都抢走。这种写法对按 Git 仓库或者库名分包的项目特别管用，配合 SCM 作者匹配，整个分配脚本就能覆盖几乎所有未分配 issue。

部署方式我一般放在 CI 流水线里，SonarQube 扫描成功后紧接着跑一个 stage。如果团队还残留一堆历史存量，就在服务器上用 crontab 每周固定时间跑一次全量脚本，配合干跑日志看看有没有异常。时间上不用担心，拉几百条 issue、调用几百次 assign 接口，一分钟内肯定能跑完。

5. 常见问题与避坑速查

自动分配这块的坑我基本都踩过一遍，整理成了一张速查表，大家可以直接对照排查。

除了这些技术问题，还有一个非常容易出现误判的情况：一个方法被改过很多次，SonarQube 记录的 author 是最后一次提交的人。这种情况在存量 issue 上特别容易引发争议。我的建议是分配的时候把“最后提交者”理解成“当前最有义务处理的人”，而不是“唯一责任人”。代码是团队资产，自动分配只是让事情有个明确的推进出口，不是为了考古挖坟。

另外一个实用的提醒：分配脚本跑在 CI 里的时候，用专用账号的 token，不要用某个同事的私人 token。私人 token 可能因为人员离职、权限调整而失效，会让流水线突然红掉。给脚本建一个服务账号，token 到期了也好统一换。

6. 我的一些实操体会

自动分配这件事，技术上真的不复杂，难的是让团队接受“机器分的锅比人分的准”。我最初只在一个试点项目上开了内置开关，试行一个月后发现一个很有意思的现象：以前大家看到未分配 issue 的第一反应是“这又不是我的”，开了自动分配之后，issue 直接出现在自己的待办里，反而没人扯皮了，因为改动归属在提交代码的那一刻就已经被 git 记录下来了，争论也没用。

还有一个额外的收获：为了让自动分配更准确，团队开始认真对待提交粒度。以前一个提交塞五个文件的改动，现在还养成了一次提交只做一件事的习惯，不然 blame 出来的归属会乱。提交信息规范一些，git log 可读性上去之后，不只 SonarQube 分配准，日常 review 和回溯排查都顺了很多。

如果你们团队正准备做这件事，我的建议是分三步走：先开内置自动分配并统一邮箱，跑两周看看未分配率降到多少；再用脚本把模块归属规则补上，处理掉存量池子；最后把每周的未分配清单和按人统计的报告发到工作群，让分配结果形成闭环。越往后你会发现，真正重要的不是“分锅”这个动作本身，而是每一条代码都有了明确的 owner，问题有处可去，改动有迹可循。