Docker Compose启动SonarQube并集成GitLab CI是轻量高复用的代码质检方案，核心为SonarQube与PostgreSQL双容器协同，配合sonar-scanner-cli镜像在CI中执行带质量门禁的扫描。
用 Docker Compose 启动 SonarQube，再通过 GitLab CI 触发扫描，是目前最轻量、可复用性最强的代码质检接入方式。关键不在于堆功能，而在于服务能稳、配置能对、扫描能准。
用 Compose 快速拉起可用的 SonarQube 服务
核心是两个容器协同：SonarQube 主体 + PostgreSQL 数据库存储分析数据。推荐使用官方 lts-community 镜像，稳定且免费。
- 确保宿主机已设置系统参数：
sysctl -w vm.max_map_count=524288和sysctl -w fs.file-max=131072，否则 Elasticsearch 内嵌组件会启动失败 - docker-compose.yml 中数据库连接地址写成
db:5432（不是 localhost），因容器间通信走内部网络 - 务必挂载
/opt/sonarqube/data和/opt/sonarqube/extensions到宿主机目录或命名卷，避免重启后插件丢失、规则重置 - 首次启动后访问
http://localhost:9000，默认账号密码均为 admin/admin，登录后立即修改密码
在 GitLab CI 中集成 SonarScanner 执行扫描
不需要在 GitLab Runner 上装 Java 或 Maven，直接用官方 sonarsource/sonar-scanner-cli 镜像即可完成分析。
- 在
.gitlab-ci.yml中定义 job，指定镜像、挂载项目源码，并传入 SonarQube 地址和 token - token 在 SonarQube → 用户头像 → My Account → Security → Generate Tokens 创建，权限仅需“Execute Analysis”
- 关键参数示例：
sonar.host.url=http://host.docker.internal:9000（GitLab Runner 在 Docker 中运行时）或http://sonarqube:9000（Runner 与 SonarQube 同属一个 docker network） - Java 项目建议加
sonar.java.binaries=target/classes；前端项目可加sonar.javascript.lcov.reportPaths=coverage/lcov.info
让质量门禁真正生效，不止于“跑完就了事”
扫描结果默认只存进 SonarQube 页面，要让它影响 CI 流程，得靠 Quality Gate。
- 进入 SonarQube → Administration → Configuration → Quality Gates，确认默认 gate（如 “Sonar way”）已启用
- 在 CI job 中追加参数：
-Dsonar.qualitygate.wait=true，这样 job 会阻塞等待门禁结果 - 若门禁失败（例如覆盖率低于 70%、新代码漏洞数 > 0），job 将自动失败，GitLab 合并请求界面会标红提示
- 建议在项目根目录放
sonar-project.properties统一管理 key、name、sources 等配置，比全写在 CI 脚本里更清晰
常见卡点与绕过思路
不是所有问题都要重装，多数是网络、权限或路径错位导致。
-
“Connection refused” 错误：检查 GitLab Runner 是否和 sonarqube 容器在同一个自定义 network（如
sonarnet），不能依赖默认 bridge -
“Unable to connect to database”：确认 PostgreSQL 容器先于 SonarQube 启动（用
depends_on），且SONAR_JDBC_URL中的 host 名与 service 名一致 -
扫描没报 bug，但页面显示“0 issues”：查看日志中是否提示
Excluded sources，常因sonar.sources路径写错或文件权限不足（如 runner 用户无权读src/main/java） - 中文乱码或界面无中文插件：进入 SonarQube Marketplace 搜索安装 “Chinese Pack”，重启容器生效
