本地安装Jenkins后如何正确启动服务？

Question

本地安装Jenkins后无法启动服务，是最常见的入门级问题。典型表现为：执行 `java -jar jenkins.war` 后控制台无响应、快速退出，或浏览器访问 `http://localhost:8080` 显示连接被拒绝。根本原因常包括：① Java版本不兼容（Jenkins 2.4+ 要求 JDK 11/17/21，不支持 JDK 8）；② 默认端口8080被占用（如Tomcat、其他Jenkins实例）；③ 启动目录权限不足，导致无法生成 `.jenkins` 工作目录及初始管理员密码文件；④ Windows下双击war包未通过命令行运行，缺少标准输出与交互式初始化流程。此外，若使用系统服务方式安装（如Windows Service或systemd），常因服务配置未指定 `--httpPort=8080` 或 `--prefix=/jenkins` 等关键参数而静默失败。排查需优先检查Java版本（`java -version`）、查看启动日志（尤其首屏输出的`JENKINS_HOME`路径与`Initial Admin Password`位置），并确认端口占用（`netstat -ano | findstr :8080`）。

Answer 1

```html

一、现象层：典型失败表征与第一印象诊断

执行 java -jar jenkins.war 后控制台瞬间闪退、无日志输出；或进程看似运行但 curl -I http://localhost:8080 返回 Connection refused；Windows 用户双击 jenkins.war 仅弹出空白命令窗口后关闭——这些均非“Jenkins崩溃”，而是启动流程在初始化阶段即被阻断。关键信号包括：缺失 JENKINS_HOME 路径打印、无 “Jenkins is fully up and running” 提示、未生成 .jenkins/secrets/initialAdminPassword。

二、环境层：Java 运行时兼容性深度验证

• Jenkins 2.441+（LTS 2.440.1+）强制要求 JDK 11/17/21，明确弃用 JDK 8（JEP 392 已移除 Java EE 模块，而旧版 Jenkins 依赖 JAXB）
• 验证命令：java -version 必须显示 11.0.x、17.0.x 或 21.0.x；若为 1.8.0_xxx，即使能启动也会在加载插件时抛 NoClassDefFoundError: javax/xml/bind/JAXBException
• 进阶检测：java -cp jenkins.war org.jenkinsci.main.modules.sshd.SSHD --version 可绕过主服务验证 JVM 基础兼容性

三、系统层：端口冲突与资源抢占分析

OS	诊断命令	关键字段	典型占用源
Windows	netstat -ano | findstr :8080	PID 列对应进程名	Tomcat、Skype（历史遗留）、另一 Jenkins 实例、IIS Express
Linux/macOS	lsof -i :8080 或 ss -tuln | grep :8080	COMMAND 列	dockerd（容器映射）、node.js dev server、Apache HTTPD Proxy

解决方案：启动时显式指定端口 —— java -jar jenkins.war --httpPort=8081，避免修改系统级服务配置。

四、权限层：工作目录写入能力与安全上下文

若当前用户对启动目录（如 C:\Users\Alice\Downloads 或 /tmp）无写权限，则 Jenkins 无法创建 .jenkins 目录，导致 java.io.IOException: Failed to compute the value for item 'JENKINS_HOME'。Linux 下常见于 root 启动后切换用户；Windows 下表现为 UAC 阻止或 NTFS 权限拒绝。验证方式：mkdir .test && echo test > .test/test.txt && rm -rf .test。修复建议：显式设置 JENKINS_HOME 环境变量指向可写路径，例如：

export JENKINS_HOME=/opt/jenkins-data  # Linux/macOS
set JENKINS_HOME=C:\jenkins-home        # Windows CMD
java -jar jenkins.war

五、架构层：服务化部署的静默失败根因

graph TD
    A[systemd service] --> B{是否指定 --httpPort?}
    B -->|否| C[绑定到随机端口或失败退出]
    B -->|是| D[是否设置 --prefix?]
    D -->|否| E[反向代理 /jenkins 路由失效]
    D -->|是| F[正常启动]
    A --> G{是否配置 Restart=always?}
    G -->|否| H[首次失败后服务状态为 inactive]

Windows Service 安装需使用 jenkins.exe install 并编辑 jenkins.xml，确保 <arguments> 包含 --httpPort=8080 --prefix=/jenkins；systemd 单元文件中 ExecStart 必须完整包含 JVM 参数与 Jenkins 参数，且 RestartSec=10 避免瞬时失败掩盖问题。

六、日志层：启动生命周期关键事件捕获策略

1. 首屏必查三项：JENKINS_HOME=/xxx、Listening on http://0.0.0.0:8080、Initial Admin Password is xxx
2. 若缺失上述任一，立即检查 java -Xlog:gc*,safepoint:file=gc.log:time 是否触发 JVM GC 日志（排除内存不足）
3. Linux 下使用 journalctl -u jenkins -f 实时跟踪 systemd 日志；Windows 下查看 Event Viewer → Windows Logs → Application 中 Jenkins 服务事件
4. 高级技巧：添加 -Djava.util.logging.config.file=logging.properties 自定义日志级别，将 Level=FINE 应用于 hudson.WebAppMain 类

七、验证层：端到端健康检查清单

• ✅ ps aux | grep jenkins 或 tasklist | findstr jenkins 确认进程存在
• ✅ lsof -iTCP:8080 -sTCP:LISTEN 验证端口监听状态
• ✅ curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/login 返回 200 或 302
• ✅ 检查 $JENKINS_HOME/war/WEB-INF/web.xml 中 <session-config> 的 maxInactiveInterval 是否被意外覆盖（影响会话初始化）

```