Jenkins JNLP Agent with Python 镜像文档

1. 镜像概述和主要用途

Jenkins JNLP Agent with Python 是一个基于 JNLP（Java Network Launch Protocol）协议的 Jenkins 代理（Agent）镜像，内置 Python 运行环境。该镜像用于在 Jenkins 分布式架构中作为工作节点（Agent），接收并执行来自 Jenkins Master 的构建任务，特别适用于需要 Python 环境的 CI/CD 流程。

2. 核心功能和特性

• JNLP 协议支持：通过 JNLP 协议与 Jenkins Master 建立安全连接，无需暴露 Agent 端口。
• 内置 Python 环境：预安装 Python 解释器及基础依赖（具体版本取决于镜像标签，如 3.9、3.10 等）。
• 轻量级设计：基于 Alpine 或 Debian 精简基础镜像，减少资源占用。
• 灵活配置：支持自定义 Agent 名称、工作目录、连接参数等。
• 兼容性：与 Jenkins Master 2.303+ 版本兼容，支持最新的 Agent 协议。

3. 使用场景和适用范围

适用场景

• 执行 Python 脚本或 Python 项目的构建、测试、部署任务。
• 运行依赖 Python 的自动化测试（如 Selenium、Pytest 等）。
• 在 Jenkins 分布式架构中分担构建负载，提高任务执行效率。
• 需要隔离 Python 环境的多版本项目构建（通过不同标签的镜像区分 Python 版本）。

适用范围

• Jenkins 分布式部署环境（Master-Agent 架构）。
• 需要 Python 环境的 CI/CD 流程（如 Django、Flask 项目，Python 数据分析任务等）。
• 容器化部署的 Jenkins Agent 节点。

4. 使用方法和配置说明

4.1 镜像拉取

从 Docker Hub 拉取镜像（根据需要指定 Python 版本标签，默认标签为 latest）：

docker pull jenkins/jnlp-agent-python:3.9  # Python 3.9 版本
docker pull jenkins/jnlp-agent-python:latest  # 最新版本

4.2 启动 Agent（docker run）

通过 docker run 命令启动 Agent，需指定 Jenkins Master 地址、JNLP 连接密钥及 Agent 名称：

docker run -d \
  --name jenkins-python-agent \
  -e JENKINS_URL="[***]" \  # Jenkins Master URL
  -e JNLP_SECRET="your-jnlp-secret" \  # Agent 连接密钥（从 Jenkins Master 获取）
  -e AGENT_NAME="python-agent-01" \  # Agent 名称（需在 Jenkins 中唯一）
  -e AGENT_WORKDIR="/home/jenkins/agent" \  # 工作目录（可选，默认 /home/jenkins/agent）
  -v /var/run/docker.sock:/var/run/docker.sock \  # 如需在 Agent 中使用 Docker（可选）
  -v jenkins-agent-workdir:/home/jenkins/agent \  # 持久化工作目录（可选）
  jenkins/jnlp-agent-python:3.9

4.3 Jenkins 中配置 JNLP Agent

1. 在 Jenkins Master 中创建 Agent：

   • 进入 Jenkins 管理页面 → 系统管理 → 节点管理 → 新建节点。
   • 输入 Agent 名称（需与 AGENT_NAME 一致），选择“永久性代理”，点击“确定”。
   • 配置 Agent 参数：
     • 远程工作目录：与 AGENT_WORKDIR 一致（如 /home/jenkins/agent）。
     • 启动方式：选择 通过JNLP启动代理。
     • 记录页面中显示的 JNLP 连接命令 或 JNLP 密钥（用于 JNLP_SECRET）。

2. 获取 JNLP_SECRET：

   • 在 Agent 配置页面中，点击“显示JNLP连接指令”，复制“密钥”部分（格式为一串随机字符串），作为 JNLP_SECRET 环境变量值。

4.4 环境变量配置

4.5 卷挂载（可选）

• 工作目录持久化：通过 -v jenkins-agent-workdir:/home/jenkins/agent 挂载卷，避免任务数据丢失。
• Docker 集成：如需在 Agent 中执行 Docker 命令（如构建镜像），挂载 Docker 套接字：-v /var/run/docker.sock:/var/run/docker.sock。
• SSH 密钥/证书：挂载密钥文件到 /home/jenkins/.ssh，用于访问代码仓库（如 Git）。

5. Docker Compose 部署示例

创建 docker-compose.yml 文件，配置 Agent 服务：

version: '3.8'

services:
  jenkins-python-agent:
    image: jenkins/jnlp-agent-python:3.9
    container_name: jenkins-python-agent
    restart: always
    environment:
      - JENKINS_URL=[***]
      - JNLP_SECRET=your-jnlp-secret  # 替换为实际密钥
      - AGENT_NAME=python-agent-01
      - AGENT_WORKDIR=/home/jenkins/agent
      - JAVA_OPTS=-Xmx1g  # 分配 1GB 内存
    volumes:
      - jenkins-agent-workdir:/home/jenkins/agent
      - /var/run/docker.sock:/var/run/docker.sock  # 可选，用于 Docker 命令执行
    networks:
      - jenkins-network  # 确保与 Jenkins Master 在同一网络（如需）

volumes:
  jenkins-agent-workdir:  # 持久化工作目录

networks:
  jenkins-network:
    external: true  # 假设 Jenkins Master 已在该网络中

启动服务：

docker-compose up -d

6. 注意事项

• JNLP_SECRET 安全性：密钥仅用于 Agent 与 Master 认证，请勿暴露或硬编码在配置文件中，建议通过环境变量或密钥管理工具注入。
• Python 版本选择：通过镜像标签指定 Python 版本（如 3.8、3.11），避免使用 latest 标签导致版本变更。
• 资源限制：根据任务需求调整 JAVA_OPTS 和容器资源限制（如 --memory=2g），避免资源耗尽。
• 网络连通性：确保 Agent 容器能访问 Jenkins Master 的 JENKINS_URL（通常为 8080 端口或 HTTPS 443 端口）。