Debian 部署 Jenkins 的常见坑与规避
一 环境与仓库的坑
- 使用过旧的 Java 版本导致启动失败或不兼容，Jenkins 2.357+ 要求 Java 11；建议直接安装 OpenJDK 11（或更高）。验证命令：
java -version。
- 官方 Debian 仓库里的 jenkins 包可能依赖 daemon，在部分 Debian 版本上默认仓库没有该包会报依赖错误；解决方法是先启用 universe 仓库：
sudo add-apt-repository universe，再安装依赖与 Jenkins。
- 导入 GPG 密钥与添加源时，注意区分 LTS 与 Weekly 源，避免装到不稳定版本；导入命令示例：
wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -，源地址示例：deb https://pkg.jenkins.io/debian-stable binary/。
- 系统资源不足会让 Jenkins 运行缓慢或构建失败，建议至少 4GB 内存（生产 8GB+）与 10GB+ 磁盘空间。
二 端口与网络连通的坑
- 默认端口 8080 常被占用（如 Tomcat、Nginx），导致服务起不来；排查命令：
sudo netstat -tuln | grep 8080。修改端口编辑 /etc/default/jenkins，将 JENKINS_PORT="8081" 后重启：sudo systemctl restart jenkins。
- 使用 Agent 时，默认需要开放 50000/tcp（JNLP/agent 通信）；若启用了 UFW，放行端口：
sudo ufw allow 8080/tcp、sudo ufw allow 50000/tcp。
- 云服务器或企业网络可能有安全组/ACL 限制，除本机防火墙外，还需在云平台放行对应端口。
三 权限与安全的坑
- 以 jenkins 系统用户运行时，访问某些目录或执行特权操作会报权限不足；不建议直接给 jenkins 用户 NOPASSWD sudo，应通过精细授权、组权限或代理工具（如
sudo 仅限于特定命令）来最小化授权。
- 初始解锁密码在 /var/lib/jenkins/secrets/initialAdminPassword；首次登录应立即设置强密码并禁用匿名访问。
- 授权策略不要长期使用“登录用户可以做任何事”，建议安装并使用 Role-based Authorization Strategy 或 Matrix Authorization Strategy 做细粒度授权。
四 插件与升级的坑
- 插件冲突/不兼容是常见故障源，升级或重启后 Jenkins 起不来时，可先“禁用所有插件→重启→逐个启用”定位问题插件。
- 升级 Jenkins 或插件后，注意版本兼容性与回滚预案；升级命令：
sudo apt-get update && sudo apt-get upgrade jenkins。
- 尽量少装插件，只保留业务必需项，降低升级风险与攻击面。
五 分布式构建与 Docker 的坑
- 主从（Agent）架构需保证 Master 与 Agent 版本一致、网络互通，并正确配置 SSH 密钥 或 JNLP；在 Manage Jenkins → Manage Nodes and Clouds 中完成节点添加与标签管理。
- 使用 Docker 部署时，映射 8080 与 50000，并谨慎挂载 /var/run/docker.sock；示例：
docker run -u root -d -p 8080:8080 -p 50000:50000 -v jenkins-data:/var/jenkins_home -v /var/run/docker.sock:/var/run/docker.sock jenkins/jenkins:lts。挂载 Docker 套接字带来便利的同时也扩大了容器权限，需配合严格的权限与镜像安全策略。
