Jenkins不支持原生集群，其“集群”实为Master-Slave或Controller-Agent架构，通过单主节点调度多Agent分担负载、隔离环境；多主Active-Active模式官方不支持，易致数据冲突；Agent可选Java（需JRE）、SSH（轻量免Java）或Docker（动态无状态）三类，混用可行但需在Web界面统一配置；主节点需开放8080和50000端口，Agent只需出向连通主节点50000端口；连不上常见原因包括URL写localhost、CSRF未适配、时间偏差超5分钟或SSH密钥未正确配对。
Jenkins 本身不提供原生集群模式，所谓“集群”实际是主从（Master-Slave）或控制器-代理（Controller-Agent）架构，靠分布式节点分担构建负载、隔离环境、提升可用性。部署的关键不是装多个 Jenkins 实例，而是让一个主节点调度多个独立运行的 Agent 节点 —— 这些 Agent 可以是物理机、虚拟机或容器，只要能连上主节点并执行命令即可。
为什么不能直接装多个 Jenkins 主服务？
Jenkins 主服务（Controller）状态强依赖 /var/lib/jenkins 目录下的配置、插件、作业定义和构建历史。多个 Controller 同时写入同一份数据会引发冲突、元数据损坏甚至任务丢失。官方明确不支持多主 Active-Active 模式。所谓“高可用”，必须通过外部手段（如反向代理 + 主备切换 + 共享存储同步）实现，成本高、运维复杂，远不如用单 Controller + 多 Agent 稳定可靠。
Agent 节点必须用 Java 吗？
不是。Jenkins Agent 分为三类，选型直接影响部署复杂度：
-
Java Agent（
agent.jar）：需目标节点安装匹配版本的 JRE（推荐 Java 17），启动后通过 JNLP 协议连接主节点；适合长期稳定运行的 Linux/Windows 服务器，但 Java 环境要手动维护 - SSH Agent：主节点通过 SSH 密钥直连远程机器执行命令；无需在目标节点装 Java 或 Jenkins 组件，只要 openssh-server 和基础工具（git、maven、docker 等）就绪即可；最轻量，推荐用于大多数 Linux Agent 场景
-
Docker Agent（Pipeline 中动态拉起）：在 Pipeline 脚本里用
agent { docker 'node:18' }声明，由主节点调用 Docker API 创建临时容器执行任务；完全隔离、无状态，但要求主节点所在机器装有 Docker 且有权限操作/var/run/docker.sock
混用没问题，比如核心编译用 SSH Agent，前端构建用 Docker Agent，关键点在于：Agent 类型一旦选定，就在 Jenkins Web 界面的 Manage Jenkins → Manage Agents 里固定配置，不要在 Pipeline 里反复切换类型导致调试困难。
主节点端口冲突和防火墙怎么处理？
主节点默认监听 8080（HTTP）和 50000（Agent 连接端口），这两个端口必须通：
- 云服务器（阿里云/腾讯云等）：安全组里放行
8080和50000入方向 TCP 流量，不是只开8080 - 本地服务器或虚拟机：若用 firewalld，执行
firewall-cmd --permanent --add-port=8080/tcp和firewall-cmd --permanent --add-port=50000/tcp，再firewall-cmd --reload - 如果主节点已跑 Tomcat 或其他服务占了
8080，改 Jenkins 端口：编辑/etc/sysconfig/jenkins（RHEL/CentOS）或/etc/default/jenkins（Debian/Ubuntu），修改JENKINS_PORT="8081"，重启服务 - Agent 节点只需能出站访问主节点的
50000端口（或 JNLP URL），不需要开放入方向端口
Agent 节点连不上主节点的常见原因
报错类似 Connection refused 或 Failed to connect to master，优先检查这几点：
- Agent 配置里的主节点 URL 写的是
http://localhost:8080—— 这在 Agent 本机解析失败，必须用主节点真实 IP 或可 DNS 解析的域名，例如http://192.168.1.100:8080 - 主节点启用了 CSRF 保护（默认开启），而 Agent 使用旧版
agent.jar或未正确传入-jnlpUrl参数；确保用 Jenkins Web 页面生成的完整启动命令，包含-secret和-jnlpUrl - Agent 节点时间与主节点偏差超过 5 分钟（影响 JWT Token 验证），执行
timedatectl set-ntp true同步时间 - SSH Agent 的密钥没配对：主节点添加的 SSH 凭据（Credentials）必须对应 Agent 节点
~/.ssh/authorized_keys里已导入的公钥，且 Agent 节点sshd_config中PubkeyAuthentication yes已启用
真正麻烦的从来不是装多少个节点，而是让每个 Agent 稳定、可审计地连上主节点并复用已有工具链。别急着堆机器，先确保一台 Agent 能干净地跑通 Maven 编译 + Git Clone + Docker 构建全流程，再批量复制。
