干 DevOps 这行也有十年了我给团队搭过 Jenkins 集群也用过 GitLab CI但这两年最顺手、综合成本最低的一套自动化构建组合反而是 GitHub Actions SonarQube 主机部署。这篇文章是《DevOps 实战指南》的第十篇就拿一个真实的 Java 项目当例子把整个过程讲清楚代码推到 GitHub 之后如何自动完成编译、跑测试、做 SonarQube 质量扫描再把构建好的产物推到远程主机上重启服务。无论你是刚接触 CI/CD 的初级开发者还是已经在公司维护流水线的同学这套方案都可以直接复制唯一的前提是你愿意花一下午把环境文档读完。1. 方案整体设计为什么是 GitHub Actions SonarQube 主机部署1.1 这套组合解决的核心问题先说清楚项目管理乱、提交频繁、部署靠手工这三个问题在中小 Java 团队里基本上是连体婴儿。代码合并到主干之后开发同学手动在服务器上 pull 代码、打包、重启偶尔漏掉一条命令轻则部署版本不对重则把测试库搞挂。GitHub Actions 要解决的是“自动化执行”的问题SonarQube 要解决的是“代码质量把关”的问题主机部署要解决的是“最终如何上线”的问题。三者串联起来就形成了一条从提交到交付的自动流水线。这里有个容易忽略的点为什么把质量扫描放在构建流程中间而不是最后因为mvn package能保证编译通过、单元测试通过但保证不了代码质量。SonarQube 扫描出问题后在流水线里直接 fail比代码合入主干之后靠 Code Review 再去追要省事得多。尤其团队里人员流动时质量门禁是一个不会说话的守门员它不跟人讲情面只看数据。1.2 为什么不做 Docker / K8s每次聊 CI/CD 方案都有人问都这几年了怎么还往主机上部署其实答案很简单场景决定了工具。对于单体服务、两三个 Java 服务的团队Docker 容器化虽然也简单但引入容器之后你还要面对镜像仓库、网络策略、磁盘空间、容器日志收集这些问题再往上走 K8s学习成本和运维成本是真实存在的对一个小团队来说可能形成反噬。主机部署的核心优势是直观产物是一个 jar/war目标是一个目录中间隔着一层 SSH。出问题的时候登录服务器一查就能定位。而容器化部署的优势是复现性、隔离性和弹性但这些优势在服务量不大的情况下并不明显。所以我一直建议只有当你发现主机部署开始频繁污染环境、多应用互相影响、或者需要横向扩容时再引入容器化。在那之前别让技术复杂度超过业务复杂度。1.3 完整流水线长什么样把整条链路拆开大概是七个环节触发 - 检出代码 - 编译与单元测试 - SonarQube 静态扫描 - 上传构建产物 - 推送到远程主机 - 执行部署脚本重启服务。触发我们选用“推送 main 分支 手动触发”两种模式。推送 main 触发保证主干每次更新都能被验证手动触发留给运维同学有时候你只想补跑一次扫描或者想在不改代码的情况下重新部署workflow_dispatch 按钮非常有用。检出代码交给官方 actions/checkoutJava 环境用 actions/setup-java 配置 JDK 17构建工具选 Maven。这里有一个细节SonarQube 的扫描插件需要在 pom.xml 里提前声明否则 mvn sonar:sonar 会提示找不到插件。后面我会给出具体配置。2. 环境准备SonarQube 服务器与目标主机初始化2.1 用 Docker 把 SonarQube 跑起来SonarQube 有两种装法一种是直接下载社区版压缩包依赖系统里的 JDK 运行另一种是 Docker 方式官方镜像自带了运行所需的 JDK只需在后端挂一个 PostgreSQL 数据库。我推荐后者因为升级、回滚、数据备份都简单很多。机器配置建议至少 4 核 8G低于这个配置扫描稍微大一点的项目就会明显卡顿。docker-compose.yml 大致长这样version: 3 services: sonarqube: image: sonarqube:10.5.0-community container_name: sonarqube ports: - 9000:9000 environment: - SONAR_JDBC_URLjdbc:postgresql://db:5432/sonar - SONAR_JDBC_USERNAMEsonar - SONAR_JDBC_PASSWORDsonar volumes: - sonar_data:/opt/sonarqube/data - sonar_ext:/opt/sonarqube/extensions - sonar_logs:/opt/sonarqube/logs depends_on: - db db: image: postgres:13 container_name: sonar-db environment: - POSTGRES_USERsonar - POSTGRES_PASSWORDsonar - POSTGRES_DBsonar volumes: - db_data:/var/lib/postgresql/data volumes: sonar_data: sonar_ext: sonar_logs: db_data:第一次启动大概需要等一到两分钟因为 SonarQube 要做数据库迁移、初始数据初始化。启动完成后浏览器访问http://服务器IP:9000默认管理员账号是admin初始密码也是admin登录后会强制要求重置。这一步千万别跳过不然后面用默认密码对接自动化容易出安全问题。这里补充一个容易踩的坑SonarQube 的 data、extensions、logs 目录权限要求归属 UID 1000如果宿主机上目录权限不对容器启动后会报写入失败之类的错误。用默认的 named volume 一般没有这种问题但如果你自己挂载宿主机目录记得先chown -R 1000:1000一下。2.2 创建扫描项目和访问令牌SonarQube 启动后在“项目”页面新建一个项目项目标识建议用一个有规律的 key比如demo-java-service。这个 key 后面会原样传进 Maven 命令里。新建完项目之后在页面右上角头像下面进入“我的账号”切到“安全”Tab生成一个 Global Token。这个 Token 是自动化扫描的凭证权限等价于你的账号所以一定要放进 GitHub 的 secrets不要写死在 pom.xml 或 workflow 文件里。生成 Token 的界面现在叫“令牌”选类型时选 Global Analysis Token 即可。它不限项目使用如果担心泄露影响面太大也可以回到项目内部生成项目级 Token。个人经验是一个服务一个项目级 Token 更可控回收时不至于影响其他项目。2.3 目标主机的部署环境初始化部署主机的环境按照我们的技术栈需要准备四样东西JDK 17、部署账号、应用目录、以及一个可用的日志目录。因为我这里的安全底线是“尽量少用 root 跑应用”所以单独建一个app用户。sudo useradd -m -s /bin/bash app sudo mkdir -p /opt/app/releases sudo mkdir -p /opt/app/logs sudo chown -R app:app /opt/appJava 环境可以用 apt 装也可以直接下载 Temurin 的压缩包解压到/usr/local/jdk-17。不要只装 JDK 不配置JAVA_HOME部署脚本里如果写死相对路径换机器就得改脚本。export JAVA_HOME/usr/local/jdk-17 export PATH$JAVA_HOME/bin:$PATH另外目标主机上要生成一个专门给 GitHub Actions 用的 SSH 密钥对。公钥放进~/.ssh/authorized_keys私钥放进 GitHub Actions secrets。注意这台服务器上如果有现成的 Jenkins 或其他自动化工具的密钥尽量别复用独立管理一个 CI 专用密钥出问题的时候吊销范围更清楚。3. GitHub Actions 流水线实现3.1 工作流文件的基本骨架GitHub Actions 的流水线定义放在.github/workflows/目录下文件名可以叫ci.yml或deploy.yml。一个流水线文件由name、on触发条件、jobs任务三大部分组成。我在实际项目中喜欢先把骨架搭出来再填充步骤避免一上来就写一堆脚本导致排查困难。name: Java CI/CD on: push: branches: [main] workflow_dispatch: jobs: build-scan: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 ... deploy: needs: [build-scan] runs-on: ubuntu-latest steps: ...触发条件这里有个小技巧push.branches精确到 main同时不排除带 tag 的分支推送。如果你希望“打版本 tag 后发布到生产环境”可以再加一个tags: [v*]的触发。不过我常用的做法是 main 分支对应测试环境打 tag 手动确认之后再部署生产一个 workflow 文件里通过环境变量控制目标服务器即可。3.2 构建与质量扫描步骤构建步骤的核心是三个拉代码、配置 JDK、执行 Maven。JDK 版本一定和开发环境保持一致否则会出现编译目标版本不一致的问题。比如项目用 JDK 17 编译服务器上却是 JDK 8跑起来直接报UnsupportedClassVersionError。Actions 里配置如下- uses: actions/checkoutv4 - name: Set up JDK 17 uses: actions/setup-javav4 with: distribution: temurin java-version: 17 cache: mavencache: maven是很多人忽略的加速点。它会把本地 Maven 仓库缓存成 Actions 的缓存键第二次构建的依赖下载时间能省下大半。如果你发现流水线每次构建都很慢先检查一下这个参数有没有配上。扫描前pom.xml 里需要配置两处JaCoCo 插件用于生成覆盖率报告SonarQube 扫描用的 sonar-maven-plugin。不配 JaCoCoSonarQube 里覆盖率指标永远显示 0。SonarQube 插件一般建议在pluginManagement里固定版本避免 Maven 拉取不稳定版本导致构建失败。properties sonar.coverage.jacoco.xmlReportPathstarget/site/jacoco/jacoco.xml/sonar.coverage.jacoco.xmlReportPaths /properties build plugins plugin groupIdorg.jacoco/groupId artifactIdjacoco-maven-plugin/artifactId version0.8.12/version executions execution goals goalprepare-agent/goal goalreport/goal /goals /execution /executions /plugin plugin groupIdorg.sonarsource.scanner.maven/groupId artifactIdsonar-maven-plugin/artifactId version3.11.0.3922/version /plugin /plugins /build然后是构建和扫描动作。我这里先用mvn clean verify再单独执行mvn sonar:sonar。为什么要分两步而不是直接在verify后面加sonar:sonar串起来因为我想让测试报告和覆盖率报告先生成完毕再让 SonarQube 读取。如果一条命令连跑Maven 生命周期顺序上会有时快时慢的诡异问题分开写更稳。- name: Build and run tests run: mvn clean verify - name: Run SonarQube analysis env: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }} run: | mvn sonar:sonar \ -Dsonar.token$SONAR_TOKEN \ -Dsonar.host.url$SONAR_HOST_URL \ -Dsonar.projectKeydemo-java-service3.3 制品传递与远程部署构建产物在 GitHub Actions 的 runner 上生成后默认不会自动带到下一个 job。我们需要先通过actions/upload-artifact把target/*.jar存到 Actions 的临时存储里再在 deploy job 里用actions/download-artifact拉出来。这一步隔离了构建和部署好处是构建失败就不会走到部署另一个 job 部署失败也不至于搞得构建缓存一团乱。上传和下载的配置- name: Upload artifact uses: actions/upload-artifactv4 with: name: java-service-jar path: target/*.jar retention-days: 3 jobs: deploy: needs: [build-scan] steps: - name: Download artifact uses: actions/download-artifactv4 with: name: java-service-jar path: ./target然后把 jar 推到主机。我推荐用appleboy/scp-action推文件配 ssh-action 执行远程命令两个 action 组合起来比较成熟不用手写 ssh 命令处理 host key 校验问题。- name: Push jar to server uses: appleboy/scp-actionv0.1.7 with: host: ${{ secrets.DEPLOY_HOST }} username: ${{ secrets.DEPLOY_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} port: 22 source: target/*.jar target: /opt/app/incoming strip_components: 1 - name: Execute deploy script uses: appleboy/ssh-actionv1.0.3 with: host: ${{ secrets.DEPLOY_HOST }} username: ${{ secrets.DEPLOY_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} port: 22 script: | ls -l /opt/app/incoming/ /opt/app/scripts/deploy.sh注意strip_components: 1。因为下载产物时它默认会在./target下重新生成一层目录名不剥离的话推上去就变成/opt/app/incoming/target/app-service.jar很容易把部署脚本的路径判断搞乱。3.4 密钥管理与安全细节GitHub 仓库的 Settings - Secrets and variables - Actions 里需要配置以下 secretsSecret 名称用途取值建议SONAR_TOKENSonarQube 扫描凭证项目级 TokenSONAR_HOST_URLSonarQube 服务地址http://sonar.example.com:9000DEPLOY_HOST目标主机 IP固定 IP 或域名DEPLOY_USER部署账号appSSH_PRIVATE_KEYCI 专用私钥私钥全文注意保留换行这里我有几句过来人的提醒。第一SONAR_HOST_URL写 http:// 还是 https:// 都可以但要保证 GitHub runner 能访问到。如果 SonarQube 部署在公司内网而 Actions 跑在公网你需要先打通网络访问限制否则扫描永远连接超时。第二SSH 私钥建议用ssh-keygen -t ed25519生成把公钥追加到 authorized_keys私钥配置到 secret。不要用密码登录部署一来密码会暴露在命令行参数里二来一旦账户密码被改所有自动化直接瘫痪。4. SonarQube 质量门禁与规则调优4.1 质量门禁怎么定才合理SonarQube 默认自带一个质量门禁Quality Gate规则是覆盖率不低于 80%、Bug 和漏洞不能有新增、安全热点需要人工确认、重复率不高于 3%。对于一个从零开始治理的项目这个门禁偏理想化。把门禁设得太高流水线天天红开发者会觉得“反正是改不过来的关掉算了”治理就成了一句空话。我自己的经验是分阶段调整。第一周用默认门禁观察把新增问题压到零第二周开始要求覆盖率任务不下降第三周再渐进式把重复率阈值收紧。具体指标可以参考我常用的这套指标初始值三个月目标新增 Bug00新增漏洞00新增安全热点待确认0测试覆盖率不做硬性要求新增代码 ≥ 60%重复代码比例≤ 5%≤ 3%这套配置在公司内部落地时团队成员抵触情绪小很多因为每次改门禁都给了一周缓冲期。硬生生把 80% 门槛压下来团队可能直接绕开扫描重新把代码塞到 GitHub那就本末倒置了。4.2 增量分析与增量问题SonarQube 默认做全量分析但如果你的项目已有几十万行存量代码全量扫描会把门禁卡在历史问题上导致新功能提不上去。这时候要利用增量分析的思路。一个最直接的做法把存量代码作为基线只对本次新改动的代码做门禁判定。实现方式是在扫描命令里传入基线日期或版本号。比如mvn sonar:sonar -Dsonar.projectDate$(git log -1 --format%ci --before2024-01-01) ...不过说实话这个参数配置起来有点绕我更喜欢在 SonarQube UI 里直接调整“新增代码”的窗口周期。默认是“自上一次分析以来”也就是增量窗口。你只要保证每次 PR 合入主干前都跑过一次扫描新增代码的问题就会单独被检测出来老代码的问题继续被记录但不会导致门禁失败。这里有个容易误解的点SonarQube 并不是“只扫增量代码”它是全量扫描、显示时区分“新增问题”和“存量问题”。门禁默认也是分两块的New code和Overall code。我实际维护项目时总体冗余问题不会阻塞合并只有新增问题才真正卡住流水线。4.3 扫描报告里最该看什么扫描结束后SonarQube 会把报告直接回传给流水线同时你也可以在 Web 界面上查看详情。很多人的习惯是“扫完看个总分就完事”我建议重新分配关注重心。排在第一位的一定是 Security 和 Reliability也就是漏洞和 Bug这两类问题是可确定性修复的优先级最高其次是 Security Hotspots这个需要人工判断比如硬编码密钥的检测机器只负责标记风险是否真的有问题要人来看最后才是坏味道、复杂度这一类代码可维护性问题它们不会立刻引发故障但会影响长期迭代效率。举一个实际例子SonarQube 报了一个synchronized可能引发死锁的 Bug如果不去细看就直接合并可能在并发高峰期出现线程卡死。这类问题虽然概率低但一旦生产发生就是大事。而复杂度高的方法往往靠 Code Review 也能发现放在门禁里反而容易让团队疲劳。所以我的建议是高分不等于高质量低分却往往意味着交付风险把有限的精力花在漏洞和 Bug 上。5. 主机部署细节从制品到可服务5.1 部署目录与软链设计部署到主机上最怕的是什么是手里只有一份“最新版”想回退却发现旧版本已经被覆盖。所以我一律建议用“版本目录 软链接”的结构。/opt/app/ ├── incoming/ │ └── app-service.jar ├── releases/ │ ├── 20240401-1015/ │ │ └── app-service.jar │ └── 20240402-1420/ │ └── app-service.jar ├── logs/ │ └── app.log ├── scripts/ │ ├── deploy.sh │ ├── start.sh │ ├── stop.sh │ └── rollback.sh └── current - /opt/app/releases/20240402-1420current是一个软链接脚本统一读这个路径启动服务。每次部署时新的 jar 先放到 incoming 中转目录由部署脚本移动到 releases 下的新版本目录更新软链指向新目录然后重启服务。如果要回退只需把软链指向上一个版本再重启即可。整个切换过程不删除旧文件保留最近 5 到 10 个版本磁盘一般不会出问题。5.2 启动、停止与回滚脚本部署脚本的核心逻辑其实很简单找到旧进程 PID 并停掉把 incoming 里的 jar 落位到 releases 版本目录更新软链再启动新进程。杀进程我一般不用pkill -f app-service这种模糊匹配因为很容易误杀其他同名应用。更稳的办法是通过 PID 文件pidfile管理。部署脚本 deploy.sh 示例#!/bin/bash set -euo pipefail APP_HOME/opt/app APP_NAMEapp-service SOURCE_JAR$APP_HOME/incoming/$APP_NAME.jar VERSION_DIR$APP_HOME/releases/$(date %Y%m%d-%H%M%S) mkdir -p $VERSION_DIR mv $SOURCE_JAR $VERSION_DIR/$APP_NAME.jar ln -sfn $VERSION_DIR $APP_HOME/current cd $APP_HOME/releases ls -t | tail -n 11 | xargs -r rm -rf $APP_HOME/scripts/stop.sh sleep 2 $APP_HOME/scripts/start.sh启动脚本 start.sh 示例#!/bin/bash APP_NAMEapp-service APP_HOME/opt/app CURRENT_JAR$APP_HOME/current/$APP_NAME.jar PID_FILE$APP_HOME/$APP_NAME.pid if [ -f $PID_FILE ] kill -0 $(cat $PID_FILE) 2/dev/null; then echo App is already running, pid$(cat $PID_FILE) exit 1 fi nohup java -jar $CURRENT_JAR \ --spring.profiles.activeprod \ $APP_HOME/logs/app.log 21 echo $! $PID_FILE sleep 5 if ! kill -0 $(cat $PID_FILE) 2/dev/null; then echo App failed to start, check logs/app.log exit 1 fi for i in $(seq 1 30); do if curl -fs http://127.0.0.1:8080/actuator/health | grep -q status:UP; then echo Health check passed exit 0 fi sleep 1 done echo Health check failed, app is about to shutdown kill $(cat $PID_FILE) exit 1停止脚本 stop.sh#!/bin/bash APP_NAMEapp-service APP_HOME/opt/app PID_FILE$APP_HOME/$APP_NAME.pid if [ ! -f $PID_FILE ]; then echo No pid file found exit 0 fi PID$(cat $PID_FILE) if kill -0 $PID 2/dev/null; then kill $PID sleep 5 if kill -0 $PID 2/dev/null; then kill -9 $PID fi fi rm -f $PID_FILE echo App stopped这里要特别强调一点启动后一定要做健康检查而不是只检查进程存在。进程在但端口没起来、数据库连不上这些都是生产里常见的假启动。Spring Boot 应用可以依赖 Actuator 暴露 health 端点部署脚本里轮询/actuator/health返回UP才算真正成功。如果检查 30 秒还是失败就把进程杀掉并抛出异常流水线就会标红避免“假部署成功”。回滚脚本逻辑也很简单就是改软链#!/bin/bash # 用法: ./rollback.sh 版本目录名 set -euo pipefail ROLLBACK_VERSION$1 ln -sfn /opt/app/releases/$ROLLBACK_VERSION /opt/app/current /opt/app/scripts/stop.sh sleep 2 /opt/app/scripts/start.sh5.3 systemd 托管与开机自启如果目标主机重启我们当然希望服务自动起来。只靠 nohup 启动的进程扛不住这种场景。更稳的方案是写一个 systemd service。[Unit] DescriptionApp Service Afternetwork.target [Service] Userapp Groupapp WorkingDirectory/opt/app EnvironmentFile/opt/app/conf/app.env ExecStart/usr/local/jdk-17/bin/java -jar /opt/app/current/app-service.jar Restartalways RestartSec10 [Install] WantedBymulti-user.target然后执行systemctl daemon-reload systemctl enable app-service。这样部署脚本里就不再用 nohup直接使用systemctl restart app-service即可。要注意我的 start.sh 里用 PID 文件的方式适合起步阶段一旦上了 systemd就要把 PID 和进程管理的职责交给 systemd脚本里不要再保留 nohup 启动那套否则两个管理器会互相打架。使用 systemd 还需要处理权限问题。如果部署账号是 app默认systemctl restart app-service需要 root 权限。可以给 app 用户配置受限的 sudoers只允许它操作这个服务app ALL(root) NOPASSWD: /bin/systemctl restart app-service, /bin/systemctl stop app-service, /bin/systemctl start app-service同时把 deploy.sh 里的start.sh / stop.sh替换成sudo systemctl restart app-service。这样既能享受 systemd 的守护和开机自启又不至于把 root 权限整个交出去。6. 踩坑实录高频问题与排查方法6.1 高频问题速查表我把实际在这套组合上碰过的问题整理成了表格方便你按图索骥现象常见原因处理办法Actions 运行报 host key verification failedrunner 首次连接目标主机没记录指纹提前用 ssh-keyscan 将主机指纹写入 known_hosts或在 ssh-action 中设置 known_hosts 参数mvn 编译报“源发行版 17 需要目标发行版 17”Maven 默认 JDK 与项目编译 target 不一致用 setup-java 明确指定 JDK 17并在 pom.xml 固定 maven.compiler.releaseSonarQube 覆盖率一直为 0缺少 JaCoCo 报告或报告路径不对检查 target/site/jacoco/jacoco.xml 是否存在并核对 sonar.coverage.jacoco.xmlReportPathsSonarQube 扫描返回 token 无效项目 key 与项目 Token 不匹配在 SonarQube 项目页复制新 Token 并重新配置 secretscp 推上去文件权限不对默认 umask 导致文件不属于 app 用户push 后执行 chown app:app /opt/app/incoming/*.jar端口被占用服务起不来上一版本进程没杀干净用 ss -lntp | grep 8080 找到旧 PID 并 kill部署成功了但服务访问 404启动参数或 profile 环境不对检查 logs/app.log 和 Spring profile 配置重新部署时 jar 还在 incoming 目录上一次部署脚本执行到一半失败在 deploy.sh 开始处清空 incoming避免旧文件混淆6.2 几条血泪经验最后分享几条我在实际维护中真正用上的经验。第一GitHub Actions 的免费工时对私有仓库是每天给一定额度对一个不频繁改动的小项目完全够用但别把跑测试的重任务全塞进去。Maven 依赖缓存、并发级别、保留天数都要控制否则一个仓库多几个 workflow额度很快就见底了。第二SonarQube 的升级要谨慎。社区版从 9.x 升到 10.x数据库迁移和权限模型都有变化如果在生产环境里跑着扫描最好先在另一台机器上验证一遍再动。我吃过一次亏升级后所有扫描都报Unsupported operation最后只能回滚快照。第三务必把所有状态信息暴露在流水线日志里。构建产物文件名、部署目标、启动日志、健康检查结果这些信息看似细节但排查线上问题时能省好几个小时。GitHub Actions 的日志可以搜索部署脚本里多打几行 echo比事后盲目猜原因高效得多。第四主机部署的幂等性比速度重要。同一个版本重复部署两次结果应该完全一致不能因为某个文件已存在就报错。部署脚本里尽量用set -euo pipefail任何一个步骤失败就停止后续避免半部署状态。这套组合我前后跑了快两年GitHub 负责编排SonarQube 负责质量主机负责承载三层各司其职几乎没有出现过一次因为流程互相干扰导致的线上事故。如果你正准备给自己的 Java 项目搭一套自动化构建完全可以直接照这个思路走先把主链路跑通再把门禁调严质量治理这事急不得。