Jenkins agent 连接失败主因是 master 未启用 JNLP 协议，需勾选“Allow TCP port for inbound agents”；Pipeline 拉取私有 Git 应用 credentialsId 配置 SSH 凭据；部署需用目标用户免密 SSH 执行 rsync 与 systemctl；docker build 失败因 agent 用户未加入 docker 组或未挂载 socket。
为什么 Jenkins 在 Linux 上跑不起来 agent 连接？
多数人卡在第一步：Jenkins master 装好了，但 jenkins-agent 启动后立刻断连，日志里反复出现 Connection refused 或 Failed to connect to master。根本原因不是权限或防火墙，而是默认配置下 Jenkins master 没开启 JNLP 代理协议支持。
实操建议：
- 进 Jenkins 管理界面 →
Manage Jenkins→Security→ 勾选Agents下的Allow TCP port for inbound agents（别只改端口数字，必须勾选） - 确认
jenkins-agent.jar启动时用的是-jnlpUrl而非-url（后者是旧版 Web UI 连接方式，已弃用） - Linux 上运行 agent 的用户不能是
root（Jenkins 默认禁用），用sudo -u jenkins java -jar jenkins-agent.jar ...更稳妥
如何让 pipeline 正确拉取私有 Git 仓库代码？
git clone 在 pipeline 中失败，常见报错是 Permission denied (publickey) 或 fatal: could not read Username —— 这说明凭证没进对上下文。Jenkins 的凭据（Credentials）不会自动透传到 shell 执行环境，尤其当用 sh 步骤调用 git 命令时。
实操建议：
- 不要在
sh里手动写git clone https://user:token@github.com/...，Token 明文暴露且易过期 - 在 pipeline 中用
checkout scm或显式指定credentialsId：checkout([ $class: 'GitSCM', branches: [[name: '*/main']], doGenerateSubmoduleConfigurations: false, extensions: [], userRemoteConfigs: [[ url: 'git@github.com:org/repo.git', credentialsId: 'ssh-key-id-in-jenkins' ]] ]) - SSH 凭据必须是 Jenkins 管理界面中添加的
SSH Username with private key类型，且私钥不能带密码（Jenkins 不支持交互式解密）
构建后怎么把二进制包安全推到远程 Linux 服务器？
很多人用 scp 或 rsync 直接推，结果遇到权限混乱、路径不存在、SELinux 拦截等问题。关键不是“能不能传”，而是“谁在传、传到哪、以什么身份落地”。
Linux AI 服务器 — 将 Linux 服务器转换为本地 AI 推理集群。使用 systemd、NVIDIA CUDA 实现无头 Linux AI，零 GUI 开销。
实操建议：
- 远程目标机器上提前建好部署用户（如
deploy），并配置免密 SSH 登录（用 Jenkins agent 所在机器的公钥） - 别在
sh里写sudo rsync—— Jenkins agent 通常没配NOPASSWD，会卡住；改用部署用户自己的家目录做中转，再用chown+systemctl restart完成服务切换 - 推荐用
ssh单行命令组合，避免中间状态残留：sh "ssh deploy@prod-server 'mkdir -p /opt/myapp/releases/\${BUILD_ID} && rsync -av --delete ./target/app.jar deploy@prod-server:/opt/myapp/releases/\${BUILD_ID}/ && ln -sfn /opt/myapp/releases/\${BUILD_ID} /opt/myapp/current && systemctl restart myapp.service'"
为什么 pipeline 中 docker build 总提示 Cannot connect to the Docker daemon？
Jenkins agent 进程默认不在 docker 用户组里，即使宿主机装了 Docker，sh 'docker build' 也会因 socket 权限被拒。这不是 Docker 服务没启，而是 Unix socket 文件（/var/run/docker.sock）的属组访问控制生效了。
实操建议：
- 把运行 agent 的用户加进
docker组：sudo usermod -aG docker jenkins，然后重启 agent 进程（不是 reload） - 如果用容器化 agent（比如
jenkins/inbound-agent镜像），必须挂载/var/run/docker.sock:/var/run/docker.sock，且镜像内用户 UID 要匹配宿主机docker组 GID - 避免在 pipeline 里用
docker login存凭据 —— 改用 Jenkins 的Docker Server Credentials插件绑定 registry 凭据，再通过withDockerRegistry块调用
整个链路最易被忽略的点：Jenkins agent 的工作目录权限、远程服务器上部署用户的 $HOME/.ssh/known_hosts 是否预置了目标主机指纹、以及所有 shell 步骤里的路径是否都用了绝对路径（pwd 在 pipeline 中不可靠）。这些细节不提前压平，流水线会在看似无关的环节突然静默失败。
