企业官网建设流程全解析

用 Docker 搭建 SonarQube 服务，听起来不过是拉镜像、起容器、开端口这几件事，但真正跑起来之后你会发现，启动日志里能住进一个排障专家。SonarQube 是干嘛的？它就是一个代码体检平台，静态扫描出代码里的缺陷、漏洞、坏味道、重复代码和覆盖率变化，再把这些指标聚合成质量门禁，让“代码健不健康”从一种感觉变成一组可以量化的数据。这篇内容适合刚接触代码扫描、想快速搭一套自用或团队用服务的人，也适合那些用 Docker 装了好几次、每次都卡在启动阶段的老哥们。我会把自己踩过的坑、试过的方案、最后稳定运行的配置完整写一遍，尽量让每一步都有据可循。

1. 为什么我推荐用 Docker 搭 SonarQube

1.1 代码质量平台不是玩具，是团队基础设施

很多人第一次接触 SonarQube 是在本地 IDE 里装插件跑一下，扫完看一眼报告就关了。这其实浪费了它最核心的能力：持续累积的代码质量趋势。一次扫描发现 20 个问题没什么指导意义，但“这个月新增了 35 个坏味道、测试覆盖率从上个版本掉了 6 个百分点”才是需要介入的信号。把扫描结果沉淀在一个团队共用的服务上，配合质量门禁，才能让代码规范从“口头要求”变成“硬性关卡”。

不少开发团队会把它放到 CI 流水线里，每次提交代码自动触发扫描，不通过就直接在流水线里标红。这种用法对部署的稳定性要求很高，服务不能三天两头挂掉，数据不能随便丢。所以我的建议是：从一开始就用 Docker 部署，把所有外部依赖（数据库、配置、插件目录）都做成明确的卷，之后不管是迁移服务器还是升级版本，都能在很短的时间内恢复。

1.2 版本选型：别看见新版就冲，LTS 才是安全牌

SonarQube 的版本迭代节奏很快，目前比较受关注的两个大版本是 9.9 LTS 和 10.x 系列。9.9 LTS 是很多运维和开发团队仍在生产环境使用的版本，它的插件兼容性、Sonar Scanner 版本兼容性、中文汉化包的匹配度都已经过市场验证，运行相对稳定。10.x 系列确实带来了很多新功能和更现代的架构，但它对内嵌 Elasticsearch 的版本要求更高，资源占用也更大，而且社区版的中文插件经常出现版本错位的问题。

如果你只是个人使用或者团队内部跑代码扫描，我非常建议直接用 9.9 LTS 版本对应的 Docker 镜像。这样后续搜索资料、找插件、抄配置的时候，大部分网上的案例都能直接用。社区版已经覆盖了包括 Java、C/C++、C#、Python、JavaScript、TypeScript 等在内的主流语言，对于日常项目足够用了。只有在需要企业级功能——比如针对更多语言的高级规则、分支分析等——才需要考虑商业版本授权，但这不是一般团队起步阶段该纠结的事。

1.3 Docker 方式相比裸机安装到底省在哪、坑在哪

裸装 SonarQube 的前提是准备 Java 运行环境、PostgreSQL 数据库、SonarQube 本体，再加上它内嵌的 Elasticsearch，任何一个组件版本没对齐都可能导致启动失败。Docker 化把这些组件封装成了可复用的产物，镜像拉下来之后，真正需要定义的只有环境变量、卷、端口和少量内核参数，最大的优势是“可复现性”。测试机上跑通之后，到生产机上去执行同一份 compose 配置，结果是一致的。

但 Docker 化并不是没有代价。SonarQube 的官方镜像里内嵌了一个 Elasticsearch，它对宿主机内核参数 vm.max_map_count 有硬性要求，低于 262144 的时候容器里的 ES 会直接起不来。另外，官方镜像默认不是以 root 用户运行，如果映射的卷目录权限不对，启动时就会出现 Permission denied，这个问题在 Linux 服务器上尤其常见。所以我在后文会重点讲两个前置项：内核参数调整、卷目录属主设置。这两个问题搞定了，部署就成功了一大半。

2. 部署前设计：版本、数据库与目录规划

2.1 数据库直接选 PostgreSQL，别在 H2 上将就

SonarQube 社区版官方支持的数据库是 PostgreSQL，9.9 LTS 版本对应 PostgreSQL 12 到 14 系列都比较稳妥。Docker 部署时，我建议直接把 PostgreSQL 也用容器跑起来，跟 SonarQube 放在同一个 Docker 网络中，通过服务名互相访问，避免在主机的 localhost 端口上绕来绕去。

很多人一开始为了省事尝试 SonarQube 内置的 H2 数据库，这是官方唯一“开箱即用”的嵌入式库，但官方文档也明确说明 H2 只适合评估场景，不建议用于生产环境。原因很简单：H2 的性能、并发能力和备份恢复工具链都比 PostgreSQL 差一截，而且随着扫描历史和指标数据的增长，H2 文件会变成难以收拾的黑洞。既然生产使用就老老实实配 PostgreSQL，其实也就是在 compose 里多定义一个服务的事。

2.2 卷目录映射与用户权限规划

SonarQube 官方镜像内部使用的用户 uid 是 999，如果你在宿主机上手工创建了一个目录并赋给了 root 或者其他用户，容器内进程是没有权限写入的。这个坑我遇到过不下三次，表面的现象是容器启动后很快退出，docker logs 里看到一堆 “Permission denied” 或者 Elasticsearch 创建临时文件失败的报错。

我习惯的做法是把数据分三类：一类是 SonarQube 配置和插件，映射到sonarqube_conf和sonarqube_extensions；一类是扫描结果和索引数据，映射到sonarqube_data；还有一类是 PostgreSQL 的数据文件，映射到postgresql_data。挂载前先执行mkdir -p创建目录，然后chown -R 999:999把属主改成 uid 999，再启动容器，基本就不会出权限问题了。如果你是普通用户自己测试，用 Docker 命名卷其实也可以，因为 Docker 会自动帮你处理属主，但后续想直接查看数据文件就稍微麻烦点。

2.3 三个容易忽略的部署前置条件

第一个是要宿主机支持并修改内核参数 vm.max_map_count。Elasticsearch 官方要求这个值至少是 262144，SonarQube 内嵌的 ES 同样受此约束。临时生效只需要执行sysctl -w vm.max_map_count=262144，永久生效需要在/etc/sysctl.conf里加一行vm.max_map_count=262144，然后sysctl -p让它立即加载。

第二个是内存要够。SonarQube 的 JVM 加上 Elasticsearch，跑起来之后实测内存占用少说 2GB 起步，项目扫描频繁的时候会更高。我给小团队用的时候，服务器内存至少预留 4GB 给这两个容器，否则会出现 OOM 导致容器退出。Docker 的-m参数可以限制内存，但我不建议给 SonarQube 卡一个很小上限，它内部进程多，限制太死反而会异常退出。

第三个是端口规划。SonarQube 默认监听 9000 端口，PostgreSQL 监听 5432。如果你宿主机已经有很多服务，一定要提前确认 9000 没有被占用。另外，PostgreSQL 容器只需要在内部网络中被 SonarQube 访问，不需要把 5432 端口暴露到宿主机，除非你有外部管理工具的连接需求。

3. 实操部署：compose、启动与首登配置

3.1 编写 docker-compose.yml 的核心思路

与其一条条 docker run 命令串行执行，我更推荐直接写一个 docker-compose.yml 文件，把 SonarQube 和 PostgreSQL 定义成两个服务。这样做的好处是启动、停止、查看日志都有统一的方式，而且可以通过环境变量把数据库连接信息一次性写清楚。

下面是经过我实际改过的配置结构，分成网络、卷、postgres 服务、sonarqube 服务四块。我解释一下几个关键点：

version: "3.8" services: postgres: image: postgres:13-alpine container_name: sonar-postgres environment: POSTGRES_USER: sonar POSTGRES_PASSWORD: sonarpass POSTGRES_DB: sonar TZ: "Asia/Shanghai" volumes: - postgresql_data:/var/lib/postgresql/data networks: - sonar-network healthcheck: test: ["CMD-SHELL", "pg_isready -U sonar"] interval: 10s timeout: 5s retries: 5 sonarqube: image: sonarqube:9.9.2-community container_name: sonarqube depends_on: postgres: condition: service_healthy environment: SONAR_JDBC_URL: jdbc:postgresql://postgres:5432/sonar SONAR_JDBC_USERNAME: sonar SONAR_JDBC_PASSWORD: sonarpass TZ: "Asia/Shanghai" volumes: - sonarqube_conf:/opt/sonarqube/conf - sonarqube_data:/opt/sonarqube/data - sonarqube_logs:/opt/sonarqube/logs - sonarqube_extensions:/opt/sonarqube/extensions ports: - "9000:9000" networks: - sonar-network volumes: sonarqube_conf: sonarqube_data: sonarqube_logs: sonarqube_extensions: postgresql_data: networks: sonar-network: driver: bridge

这里最重要的两件事：第一，SONAR_JDBC_URL里的主机名写的是postgres，而不是localhost，因为两个服务在同一个 Docker 网络里，是通过服务名互相解析的；第二，depends_on配合 PostgreSQL 的 healthcheck，等数据库真正就绪后再启动 SonarQube，避免两个容器同时启动时 SonarQube 抢跑导致数据库连接失败。

3.2 启动流程与容器状态观察

配置写好后，执行docker compose up -d即可，首次启动需要拉取镜像，时间取决于网络环境。启动完成后不要急着打开 Web 页面，先用docker compose ps看一下容器状态，再用docker logs sonarqube观察初始化日志。

第一次启动时 SonarQube 要建索引、初始化数据库结构、加载插件，这个阶段往往需要 1 到 3 分钟。日志里如果能看到 “SonarQube is up” 或者类似表示 Web Server 已启动的记录，说明基本成功了。此时浏览器访问http://服务器IP:9000，应该能看到登录页面。如果一直停留在“正在初始化”的画面，多半是 Elasticsearch 没有起来，后续的排查章节会专门讲。

补充一个细节：官方镜像里 Tomcat 和 ES 都在同一个进程组中，如果宿主机的内存不足以让 ES 和 JVM 同时跑起来，你会在日志里看到 ES 退出的记录，但容器本身可能并没有直接退出。这时候不能只看容器状态，必须结合日志里的关键字判断。

3.3 首次登录、修改默认口令与基础配置

第一次打开登录页，默认账号是admin，默认密码也是admin。这个默认口令是公开的，强烈建议登录后立即修改，不要拖。SonarQube 会强制要求你设置新密码，并且新密码不能和默认密码一样。

登录进去之后，我建议先做三件基础配置：第一，进入 My Account -> Security，生成一个用于后续扫描的 Token，避免在命令行里直接暴露密码；第二，进入 Administration -> General Settings，设置服务器的基础 URL 和邮件通知配置，如果暂时不配邮件可以先跳过，但基础 URL 最好填成团队实际访问的地址；第三，检查一下默认 Quality Gate 规则，后续接入项目时你会用到它。

在 9.9 版本里，页面本身是英文界面，中文汉化需要通过插件完成。我特意把汉化单独放到后面的问题章节，因为这不是一个简单安装步骤，版本匹配问题会让不少人折腾很久。

4. 接入项目扫描：从 Token 到第一份报告

4.1 创建项目和分析令牌

服务能登录之后，核心场景就是把自己的项目接进来。SonarQube 的项目概念很简单：每个被扫描的代码库对应一个项目 Key，这个 Key 是全局唯一标识。项目 Key 的命名我建议用“组织名-应用名”的格式，比如demo-team-blog-service，这样在平台上看到 Key 就能直接判断出是哪个业务。

在 “Projects -> Create Project” 里填好项目 Key 和展示名称，下一步会让你选择用什么方式扫描，直接按网页的提示生成一个 Token。Token 是扫描时代替密码的凭证，建议缩小权限范围，只给这个项目对应的角色。把 Token 复制下来存好，因为它通常只在生成那一刻完整展示，之后再想查看就只能重新生成了。

4.2 配置 sonar-scanner 与项目属性文件

扫描器用的是官方提供的 sonar-scanner-cli，它负责读取项目代码，分析后把结果推送到服务器。安装 sonar-scanner 的方式不同系统略有差异，下载对应平台的安装包解压后，把bin目录加入 PATH 即可。命令行里执行sonar-scanner --version可以看到安装是否成功。

在待扫描的代码根目录下创建sonar-project.properties，这是扫描器的配置文件。写法如下：

sonar.projectKey=demo-team-blog-service sonar.projectName=blog-service sonar.projectVersion=1.0 sonar.sources=src sonar.java.binaries=target/classes sonar.sourceEncoding=UTF-8

对于 Java 项目，sonar.java.binaries非常重要，必须指向编译产物目录，否则很多类型推断类规则跑不出来。对于前端项目，把sonar.sources指向src或者对应的源码目录，同时可以指定排除node_modules。配置完成后，执行：

sonar-scanner \ -Dsonar.host.url=http://服务器IP:9000 \ -Dsonar.login=这里填你的Token

扫描过程会在终端打印进度，遇到问题会直接给出 ERROR 提示。扫描完成后，到服务器上看对应项目页面，报告已经生成。

4.3 看懂报告和质量门禁

第一次看到 SonarQube 报告的人，很容易被满屏的颜色和指标吓到。其实核心就五个指标：Bug、Vulnerability、Security Hotspot、Code Smell、Coverage，另外还有一个去重率指标叫做 Duplicated Lines。它的质量门禁默认是 “Quality Gate Passed”，翻译过来就是：当前代码是否允许合入/发布。如果有阻塞性问题，Quality Gate 会显示红色，这种情况在 CI 流水线里会阻断发布。

建议团队初期不要把质量门禁卡得太死，先抓 “新增代码覆盖率低于 80% 不允许合入” 这类最关键的规则，让团队逐步适应，再慢慢把坏味道的阈值收严。自动化扫描的目的是帮团队发现问题，而不是一开始就造成交付阻塞。

5. 踩坑实录：部署与使用中反复出现的五个问题

5.1 启动即失败：vm.max_map_count 过低

这是 SonarQube 用 Docker 部署时最典型的启动失败原因之一。日志里会出现类似 “max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]” 的提示。解决方案就是博客前面提到的，在宿主机上执行sysctl -w vm.max_map_count=262144，并在/etc/sysctl.conf中持久化配置，然后重启 Docker 或直接重启容器。

需要注意的是，这个参数是针对宿主机的，不是容器内部变量。你进入容器执行sysctl -w vm.max_map_count=262144虽然也能看到值变化，但容器重启后又会回到较低值，正确做法永远是在宿主机上改。

5.2 汉化插件版本错位

9.9 LTS 版本的汉化方案相对成熟，在 Administration -> Marketplace 中搜索 Chinese Pack 就能找到对应插件，安装之后重启服务即可。但在 10.x 版本上，社区汉化插件的更新经常落后于官方版本，装上去后页面可能回到英文，甚至出现插件加载失败。

我个人的建议是：如果没有特别强的中文界面需求，直接用英文界面问题不大，索纳丘布（SonarQube）的操作路径就那几条。坚持要中文的话，用 9.9 LTS 版本是一个更稳的组合。

5.3 卷目录权限问题导致的 Permission denied

前面提过官方镜像内部 uid 是 999，如果挂载的目录属主不是 999，启动时就会失败。日志里的表现可能是 “Error creating temp file” 或者 “Could not create directory”，这很容易被误判成磁盘空间不足，实际却是权限问题。

排查方法是docker inspect sonarqube | grep -A5 Uid查看容器内用户信息，或者直接看挂载目录的属主。临时解决方案就是chown -R 999:999 /path/to/data，但要注意，如果目录里已经存在之前实例的数据，修改属主时不要同时改掉不该改的父目录，避免影响宿主机其他服务。

5.4 内存与磁盘占用持续变高

跑了一段时间后，SonarQube 的容器内存和磁盘占用会持续上升。内存这块主要是 Elasticsearch 的查询缓存和 JVM 堆，在容器启动参数里添加-Xms和-Xmx可以控制，但调太小会影响操作响应速度，建议保持 2GB 左右。磁盘这块主要是扫描历史的存储，包括每次扫描产生的报告快照和索引数据，可以通过 Administration -> Projects -> Deletion 清理旧项目，或者在系统设置里调整分析历史保留天数。

实际使用中，如果服务器磁盘比较紧张，我会把 SonarQube 的数据卷单独挂到容量更大的分区上，并且监控容器的日志大小，避免docker logs文件无限膨胀。长期运行后建议定期执行docker system prune清理用不到的镜像层。

5.5 端口暴露与访问安全

SonarQube 默认只监听 9000 端口，如果你直接把服务器 IP 的 9000 端口暴露到公网，很容易被扫描到弱口令或其他风险。登录界面的默认账号如果没改，安全风险是很高的。我的建议是：如果服务只给内部团队用，就不要把端口裸奔到公网，配合反向代理只开放 443，并启用 HTTPS。如果团队规模小、访问人数少，至少也要做好防火墙规则，限制访问来源 IP。

另外，SonarQube 里的用户权限模型要注意不要给到全局管理员，普通使用者给到项目级别的 Browse 和 Execute Analysis 权限即可。这样即使某个人的账号泄露，也不会影响整个质量平台的配置。

6. 最后沉淀下来的几点体会

搭过几次之后，我最大的体会是：SonarQube 不是一个装上就不管的服务，它需要持续的版本管理和使用习惯培养。第一次部署花了一下午，主要卡在内核参数和汉化插件上；第二次部署只花了十几分钟，因为把 compose 文件、环境变量和卷规划记成了模板。所以给正准备动手的同学留几个建议：尽量用 LTS 版本镜像；目录挂载前先处理权限；数据库用 PostgreSQL 而不是临时库；Token 权限尽可能缩小；扫描器写进 CI 而不是靠人肉手动跑。另一个小技巧是把每次升级前的数据和插件目录做一次快照，这样即使新版有问题，也可以快速回退到能用的状态。这套服务跑稳之后，你会发现自己对项目的代码健康状况有了完全不同的掌控感。