govpf/sonar-scanner

Docker Sonar Scanner 镜像文档

一、镜像概述和主要用途

概述

Docker Sonar Scanner 镜像是基于 Sonar Scanner 工具构建的容器化解决方案，集成了代码质量分析所需的运行环境及依赖，可直接在容器中执行代码扫描任务，无需在本地或服务器手动安装 Sonar Scanner。

主要用途

用于对源代码进行自动化质量检测与安全分析，支持将扫描结果上传至 SonarQube 服务器进行集中展示、报告生成及问题追踪，帮助开发团队持续监控代码质量、发现潜在缺陷（如 bug、漏洞、代码异味等）并优化代码规范。

二、核心功能和特性

1. 多语言支持：兼容 Java、Python、JavaScript、C/C++、Go、Ruby 等 20+ 编程语言的代码扫描。
2. 与 SonarQube 无缝集成：支持连接远程或本地 SonarQube 服务器，自动上传扫描结果并关联项目数据。
3. 轻量化设计：基于 Alpine 或 Debian 基础镜像构建，镜像体积小，启动速度快，资源占用低。
4. 灵活配置：支持通过环境变量、命令行参数或配置文件自定义扫描规则、项目信息、分析范围等参数。
5. 跨平台兼容：可在任何支持 Docker 的环境（Linux、Windows、macOS）中运行，无需适配底层操作系统。

三、使用场景和适用范围

使用场景

1. CI/CD 流水线集成：在 Jenkins、GitLab CI、GitHub Actions 等持续集成/部署流程中嵌入，作为代码合并或发布前的质量门禁（如“扫描未通过则阻断构建”）。
2. 本地开发环境：开发人员在提交代码前，通过容器快速执行本地扫描，提前发现问题。
3. 自动化测试流程：与单元测试、集成测试联动，将代码质量指标（如测试覆盖率、重复率）纳入测试报告。
4. 批量项目扫描：对多项目代码库进行定期批量扫描，生成团队级代码质量趋势报告。

适用范围

• 开发团队：需持续监控代码质量的中小型至大型研发团队。
• 项目类型：支持各类源代码项目（如应用程序、库、微服务等）。
• 环境要求：需配合 SonarQube 服务器使用（需提前部署 SonarQube 服务并确保网络连通性）。

四、详细使用方法和配置说明

1. 前置条件

• 已部署 SonarQube 服务器（需获取服务器地址及访问令牌）。
• 本地或目标环境已安装 Docker 或 Docker Compose。

2. 环境变量配置

扫描任务需通过环境变量指定核心参数，常用变量如下：

3. 基础使用（docker run 命令）

通过 docker run 直接启动容器，挂载本地代码目录并指定环境变量：

bash
docker run --rm \
  -e SONAR_HOST_URL="http://sonarqube-server:9000" \
  -e SONAR_TOKEN="your-sonarqube-token" \
  -e SONAR_PROJECT_KEY="my-project-key" \
  -v /path/to/local/code:/app \  # 挂载本地代码目录到容器内 /app（扫描目标目录）
  sonar-scanner:latest \
  -Dsonar.sources=/app \  # 指定容器内待扫描代码路径（需与挂载路径对应）
  -Dsonar.java.binaries=/app/target/classes  # （Java 项目可选）指定编译后的 class 文件路径

说明：

• /path/to/local/code 需替换为本地源代码根目录的绝对路径；
• 额外扫描参数（如排除目录、自定义规则集）可通过 -D参数名=值 形式追加（参考 https://docs.sonarqube.org/latest/analysis/analysis-parameters/%EF%BC%89%E3%80%82

4. Docker Compose 配置示例

若需与 SonarQube 服务器联动部署（如本地测试环境），可通过 docker-compose.yml 定义多容器服务：

yaml
version: '3.8'

services:
  # SonarQube 服务器（若已独立部署，可删除此服务）
  sonarqube:
    image: docker.xuanyuan.run/sonarqube:latest
    ports:
      - "9000:9000"
    environment:
      - SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
    networks:
      - sonar-network

  # Sonar Scanner 服务（执行扫描任务）
  sonar-scanner:
    image: docker.xuanyuan.run/sonar-scanner:latest
    depends_on:
      - sonarqube
    environment:
      - SONAR_HOST_URL=http://sonarqube:9000  # 连接同一网络中的 SonarQube 服务
      - SONAR_TOKEN=your-sonarqube-token
      - SONAR_PROJECT_KEY=my-project-key
      - SONAR_PROJECT_NAME=My Application
      - SONAR_PROJECT_VERSION=1.0.0
    volumes:
      - /path/to/local/code:/app  # 挂载本地代码到容器内 /app
    command: -Dsonar.sources=/app -Dsonar.exclusions=**/node_modules/**  # 排除 node_modules 目录
    networks:
      - sonar-network

networks:
  sonar-network:
    driver: bridge

volumes:
  sonarqube_data:
  sonarqube_extensions:

启动命令：

bash
docker-compose up sonar-scanner  # 仅启动扫描服务（依赖 SonarQube 服务）

5. 配置文件方式（sonar-project.properties）

若扫描参数较多，可在代码根目录创建 sonar-project.properties 配置文件，容器启动时自动读取：

properties
# sonar-project.properties（放置于 /path/to/local/code 目录下）
sonar.projectKey=my-project-key
sonar.projectName=My Application
sonar.projectVersion=1.0.0
sonar.sources=.  # 相对路径（容器内代码目录，即 /app）
sonar.host.url=http://sonarqube:9000
sonar.login=your-sonarqube-token  # 也可通过环境变量 SONAR_TOKEN 传入，优先级更高
sonar.exclusions=**/*.test.js,**/vendor/**  # 排除测试文件及第三方依赖
sonar.javascript.eslint.reportPaths=eslint-report.json  # 集成 ESLint 报告（可选）

使用配置文件启动容器：

bash
docker run --rm \
  -v /path/to/local/code:/app \  # 配置文件需在此目录下
  sonar-scanner:latest

五、常见问题与注意事项

1. 权限问题：若扫描时提示“无法读取文件”，需确保本地代码目录权限允许容器访问（可通过 chmod -R 755 /path/to/local/code 调整）。
2. 网络连通性：容器需能访问 SONAR_HOST_URL 指向的 SonarQube 服务器（若使用 Docker Compose，需确保服务在同一网络内）。
3. 内存限制：大型项目扫描可能因内存不足失败，可通过 SONAR_SCANNER_OPTS="-Xmx1024m" 增加 JVM 内存。
4. 语言支持：部分语言（如 C/C++、.NET）需 SonarQube 服务器安装对应插件，否则扫描结果可能不完整。

六、镜像更新记录

• 最近推送时间：2025-09-23 13:33（UTC+8）