Nginx Proxy Manager与Jenkins集成：自动化部署与反向代理配置-优快云博客

Nginx Proxy Manager与Jenkins集成：自动化部署与反向代理配置

【免费下载链接】nginx-proxy-manager 项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-proxy-manager

引言：为什么需要集成Nginx Proxy Manager与Jenkins？

在现代Web应用开发中，自动化部署和反向代理配置是两个关键环节。Nginx Proxy Manager（以下简称NPM）提供了直观的Web界面来管理Nginx反向代理和SSL证书，而Jenkins则是持续集成/持续部署（CI/CD）的行业标准工具。将这两者集成，可以实现应用部署与代理配置的无缝衔接，极大提升开发运维效率。

本文将详细介绍如何通过项目内置的Jenkinsfile实现NPM与Jenkins的集成，构建从代码提交到自动部署、反向代理配置更新的完整流水线。

Jenkinsfile解析：NPM的CI/CD流水线设计

项目根目录下的Jenkinsfile定义了完整的构建、测试和部署流程。该流水线主要包含以下关键阶段：

环境准备阶段

流水线首先设置了构建环境变量，包括镜像名称、版本号等关键信息。特别值得注意的是，对于不同分支（如master和其他开发分支），流水线会自动设置不同的镜像标签策略：

stage('Environment') {
  parallel {
    stage('Master') {
      when { branch 'master' }
      steps {
        script {
          buildxPushTags = "-t docker.io/jc21/${IMAGE}:${BUILD_VERSION} -t docker.io/jc21/${IMAGE}:${MAJOR_VERSION} -t docker.io/jc21/${IMAGE}:latest"
        }
      }
    }
    stage('Other') {
      when { not { branch 'master' } }
      steps {
        script {
          buildxPushTags = "-t docker.io/jc21/${IMAGE}:github-${BRANCH_LOWER}"
        }
      }
    }
    // 版本号同步步骤
  }
}

构建与测试阶段

流水线并行执行项目构建和文档生成，并对SQLite和MySQL两种数据库环境进行测试：

stage('Builds') {
  parallel {
    stage('Project') {
      steps {
        script {
          // 前端和后端构建
          def shStatusCode = sh(label: 'Checking and Building', returnStatus: true, script: '''
            set -e
            ./scripts/ci/frontend-build > ${WORKSPACE}/tmp-sh-build 2>&1
            ./scripts/ci/test-and-build > ${WORKSPACE}/tmp-sh-build 2>&1
          ''')
          // 错误处理逻辑
        }
      }
    }
    stage('Docs') {
      steps {
        dir(path: 'docs') {
          sh 'yarn install'
          sh 'yarn build'
        }
      }
    }
  }
}

// SQLite和MySQL测试阶段
stage('Test Sqlite') { ... }
stage('Test Mysql') { ... }

多架构构建与部署阶段

测试通过后，流水线使用buildx工具构建多架构容器镜像并推送到镜像仓库：

stage('MultiArch Build') {
  when { not { equals expected: 'UNSTABLE', actual: currentBuild.result } }
  steps {
    withCredentials([usernamePassword(credentialsId: 'jc21-docker-repo', passwordVariable: 'dpass', usernameVariable: 'duser')]) {
      sh 'docker login -u "${duser}" -p "${dpass}"'
      sh "./scripts/buildx --push ${buildxPushTags}"
    }
  }
}

Nginx Proxy Manager的基本部署与配置

在了解Jenkins集成之前，我们需要先熟悉NPM的基本部署方法。根据官方文档，NPM推荐使用Docker Compose进行部署：

version: '3.8'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

启动后，通过http://127.0.0.1:81访问管理界面，使用默认凭据（admin@example.com/changeme）登录并修改密码。

集成Jenkins与Nginx Proxy Manager的实现方案

方案一：通过Jenkins Pipeline自动更新NPM配置

利用NPM的API接口，我们可以在Jenkins流水线中添加步骤，在应用部署完成后自动更新反向代理配置。项目后端提供了完整的API支持，相关定义可在backend/lib/access/目录下的JSON文件中找到，例如proxy_hosts-create.json定义了创建代理主机的API规范。

以下是一个在Jenkins流水线中调用NPM API创建反向代理的示例脚本：

stage('Update Nginx Proxy') {
  steps {
    script {
      def npmApiUrl = "http://nginx-proxy-manager:81/api/nginx/proxy-hosts"
      def authToken = sh(script: "curl -s -X POST http://nginx-proxy-manager:81/api/tokens -H 'Content-Type: application/json' -d '{\"identity\":\"${NPM_USER}\",\"secret\":\"${NPM_PASSWORD}\"}' | jq -r .token", returnStdout: true).trim()
      
      sh """
        curl -X POST ${npmApiUrl} \
          -H 'Authorization: Bearer ${authToken}' \
          -H 'Content-Type: application/json' \
          -d '{
            "domain_names": ["app.example.com"],
            "forward_host": "newly-deployed-app",
            "forward_port": 80,
            "type": "proxy",
            "ssl_forced": true
          }'
      """
      
      // 通知NPM重新加载配置
      sh """
        curl -X POST http://nginx-proxy-manager:81/api/nginx/reload \
          -H 'Authorization: Bearer ${authToken}'
      """
    }
  }
}

方案二：通过容器标签实现动态路由

另一种集成方式是利用Jenkins构建的特定标签容器镜像，结合NPM的容器DNS解析能力实现动态路由。在NPM中配置代理主机时，将"Forward Hostname/IP"设置为容器服务名称，NPM会自动通过容器DNS解析到最新版本的容器。

这种方式的优势在于不需要修改NPM配置，只需确保Jenkins部署的新容器使用固定的服务名称。项目的Docker Compose配置示例可参考docker/docker-compose.dev.yml。

完整集成方案：从代码提交到自动代理配置

结合Jenkinsfile的现有逻辑，我们可以设计一个完整的集成方案：

开发者提交代码到GitHub
Jenkins检测到代码变更，触发流水线
流水线执行构建、测试，并构建新版本容器镜像
推送新镜像到镜像仓库
部署新镜像到生产环境（可通过Jenkins的Deploy插件或SSH步骤实现）
调用NPM API更新反向代理配置，指向新部署的服务
通知相关人员部署结果

以下是实现这一流程所需的Jenkinsfile扩展：

// 在现有MultiArch Build阶段之后添加
stage('Deploy to Production') {
  when { branch 'master' }
  steps {
    script {
      // 部署到生产环境的步骤，例如使用SSH远程执行docker-compose命令
      sshPublisher(publishers: [sshPublisherDesc(
        configName: 'production-server',
        transfers: [sshTransfer(
          sourceFiles: 'docker-compose.prod.yml',
          remoteDirectory: '/opt/npm-deploy'
        )],
        execCommand: 'cd /opt/npm-deploy && docker-compose pull && docker-compose up -d'
      )])
      
      // 更新NPM配置
      updateNpmProxyConfig()
      
      // 发送部署通知
      slackSend channel: '#deployments', message: "Nginx Proxy Manager ${BUILD_VERSION} deployed successfully"
    }
  }
}

def updateNpmProxyConfig() {
  // 实现方案一中的API调用逻辑
  // ...
}

NPM管理界面导览

NPM提供了直观的Web界面来管理各种代理和SSL设置，主要功能区域包括：

仪表盘：概览系统状态和关键指标
代理主机：管理HTTP/HTTPS反向代理
重定向主机：配置URL重定向规则
流：管理TCP流代理
SSL证书：申请和管理SSL证书
访问列表：配置IP白名单/黑名单

详细的NPM使用指南可参考官方文档docs/src/guide/index.md。

常见问题与解决方案

问题1：Jenkins无法推送容器镜像到仓库

解决方案：确保Jenkins服务器已正确配置镜像仓库凭据，并且拥有推送权限。项目中使用了withCredentials步骤安全管理凭据：

withCredentials([usernamePassword(credentialsId: 'jc21-docker-repo', passwordVariable: 'dpass', usernameVariable: 'duser')]) {
  sh 'docker login -u "${duser}" -p "${dpass}"'
  sh "./scripts/buildx --push ${buildxPushTags}"
}

问题2：NPM配置更新后不生效

解决方案：通过NPM API或管理界面手动触发Nginx配置重载。API调用示例：

curl -X POST http://nginx-proxy-manager:81/api/nginx/reload \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

问题3：SSL证书自动续期失败

解决方案：检查NPM容器是否有权限访问Let's Encrypt服务器，以及端口80是否正确映射。相关配置可在NPM设置中调整。

总结与最佳实践

将Nginx Proxy Manager与Jenkins集成，可以显著提升Web应用的部署和管理效率。基于项目现有的Jenkinsfile，我们推荐以下最佳实践：

分支策略：使用master分支构建生产版本，开发分支使用独特标签，避免版本冲突
安全管理：通过Jenkins凭据系统管理所有敏感信息，如镜像仓库密码、NPM API令牌
测试覆盖：确保在CI流程中包含对不同数据库环境的测试，如项目中已实现的SQLite和MySQL测试
渐进式部署：对于关键系统，可在更新NPM配置前先部署到测试环境验证
监控告警：集成监控工具，监控Nginx和后端服务健康状态，及时发现部署问题

通过本文介绍的方法，您可以充分利用项目内置的CI/CD能力，构建一个自动化、可靠的Web服务部署和代理管理系统。如需进一步定制流水线，可参考Jenkins官方文档和NPM的API规范backend/doc/api.swagger.json。

如果您在实施过程中遇到问题，可参考项目的FAQ文档或参与社区讨论获取支持。

【免费下载链接】nginx-proxy-manager 项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-proxy-manager

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考