企业官网建设流程全解析

1. 内网部署 Jenkins 的场景与前置思考

谈到 Jenkins，大多数教程会首先让你访问官方网站下载最新版本，然后在初始化向导里选择插件，全部默认就行——但这些都是建立在能够顺畅访问外网的前提下。我实际接触到的不少项目，尤其在企业信息部门、研发环境隔离的管理区域里，构建服务器往往部署在受控的内网网段。这类环境的一大特征就是网络出口受到严格管控，机器无法直接访问公网，要么就是能访问但延迟和限速都很难看，根本支撑不了持续从公网下载插件这种操作。于是“Jenkins 安装配置管理内网环境”就成了一个绕不开的话题。

这篇文章我会还原一套在完全内网环境下，从零把 Jenkins 装起来、配好插件、打通构建任务并持续维护的完整流程。它适合刚接触 Jenkins 的运维同学，也适合被“离线安装”折磨过的老手。内容里涉及的操作我都实际踩过坑，给出的方案也在不连接公网的机器上验证过，属于可以直接照着做的实战型总结。

1.1 什么样的环境需要走内网安装方案

先把手头的场景理清楚。“内网环境”这个词听起来明确，实际落到每个团队头上差别很大。根据我自己的经历，至少可以分成下面几类：

• 服务器只能访问企业内部局域网，局域网以外一律不通，属于物理隔离或策略隔离。
• 服务器可以访问公网，但需要经过统一的出口网关，网关对访问做限制，只开放特定端口、特定域名或者按时间段放行。
• 服务器部署在云上的私有网络中，本身没有公网映射，只能通过跳板机间接操作。

第一种最严格，所有软件包、插件、依赖都得提前在外网准备好，再以离线方式导入。第二种相对宽松，可以通过申请域名白名单的方式下载，但实际操作中白名单往往覆盖不全，总有插件依赖某个没在清单里的域名，导致下载中断。第三种介于两者之间，具体情况取决于跳板机允许哪种文件传输方式。

我实际遇到的一个典型场景是这样的：某团队要在办公网的核心网段搭一套持续集成环境，这个网段连 DNS 解析外网都被禁止。最开始同事按标准流程安装 Jenkins，卡在了初始化插件安装向导上，进度条一直转，最终超时失败。后来有人想到先在外网机器上下载好插件，再打包传到内网，这才把环境搭起来。整个过程看起来不难，但里面细节非常多：插件版本和 Jenkins 版本是否匹配、插件之间依赖怎么处理、导入之后要不要重启、构建时还需要哪些系统工具，这些都是坑。所以，部署之前先明确自己的网络属于哪一种约束等级，后面的方案设计才不会走偏。

1.2 安装前的资源盘点与版本选择

内网环境返工成本比外网高很多。每次需要外网资源都要走申请流程，多跑一趟就多拖一天，所以动手之前我建议先做一次资源盘点。需要考虑的主要有下面这些项：

• 构建服务器的操作系统和位数。是 CentOS 7、Ubuntu 20.04 还是 Windows Server，这直接决定了 JDK、Jenkins 安装包和插件文件的类型。
• 硬件配置，重点是内存和磁盘。一个任务较多的 Jenkins 实例，在构建高峰期内存占用会比较明显，建议至少 2GB，4GB 以上更从容。磁盘方面，Jenkins 的构建历史、工作空间、插件、日志都会持续占用空间，构建产物如果不做清理，几十 GB 很常见。
• JDK 版本。不同版本的 Jenkins 对 JDK 的要求不同，老版本用 JDK 8，较新的版本要求 JDK 11 或 17。这里有个很容易忽略的点：如果新装的 Jenkins 要求 JDK 11，而内网机器上只有 JDK 8，你得先把 JDK 升级的问题解决掉。
• Maven、Node、Python 等构建工具是否已经准备好。这些是构建任务真正会用到的，也是内网环境下需要提前下载并传输过去的东西。

版本选择要遵循“够用、稳定、可维护”的原则。有些人喜欢一上来就装最新版，外网环境随便折腾没关系，内网环境我强烈不建议这样。最新版 Jenkins 对插件的兼容性要求往往也是最新的，而你能拿到的插件包未必是同一代的版本，一旦不匹配，排查起来很费劲。反过来，选择上一个处于维护期的版本，把插件版本固定到与主版本兼容的组合，后续维护会轻松得多。

具体确定版本的办法很简单：在外网机器上打开 Jenkins 官方下载页，查看现有的长期支持版本列表，根据已有 JDK 版本挑一个合适的 LTS。官方说明里明确标出了每个版本对应的最低 Java 要求，对照着选基本不会错。同时把版本号记下来，后面下载插件时也要认准同一个版本，避免混用。

2. 环境准备与安装方式的取舍

2.1 JDK 环境的离线准备

如果说 Jenkins 是车，JDK 就是发动机，发动机型号得跟车型匹配。内网环境准备 JDK，不只要把压缩包解压出来，环境变量、路径指向、版本唯一性都得处理好。

外网机器下载 JDK 时要选与目标系统匹配的包。Linux x86_64 就下载 tar.gz 格式，Windows Server 就下载 exe 安装版或者 zip 解压版。这里我推荐优先使用 tar.gz 或 zip 这种解压即用的格式。原因是内网批量部署时，对每台机器的安装位置和目录结构能做到高度一致，也不会被安装向导里的额外选项干扰。传到内网后放到固定的安装目录，Linux 下我习惯放在 /opt/jdk 或者 /usr/local/java，Windows 下放在 D:\tools\java，然后在系统环境变量里设置 JAVA_HOME 和 PATH。设置完顺手执行 java -version，确认能正常输出版本信息，再往后走。

还有一个平时不太留意的小问题：同一台机器上可能有其他软件自带了 JDK，或者安装过多个 JDK 版本。系统 PATH 里靠前的如果是旧版本，Jenkins 启动时可能因为找不到合适 Java 报错，或者界面起来了但某些功能异常。遇到这类问题，最直接的排查手段是开一个干净的终端，临时清掉多余的环境变量，只保留 JAVA_HOME 和 PATH，再跑一次 java -version，很快就能定位。

2.2 安装包获取与选择

Jenkins 安装包的类型有好几种，外网环境随便选，内网环境就需要综合考虑传输便捷性和部署灵活性。常见的选择是这些：

我个人的建议是内网环境优先用 war 包。war 包不依赖特定的目录结构，想放哪里放哪里，启动方式简单，前端调试和看日志都非常直观。后续想把它注册成系统服务也很容易，Linux 用 systemd，Windows 用第三方工具包装一下，都能实现开机自启。如果你对服务管理要求很高，也可以先用 war 包把环境跑通，再考虑迁移到原生服务方式，这样切换的代价最小。

2.3 Windows 与 Linux 两种安装路径

Linux 下的部署，我比较推荐把 jenkins.war 放到 /opt/jenkins 目录下，然后用 systemd 做服务管理。创建一个服务文件，指定运行用户、JAVA_HOME、JENKINS_HOME 和启动命令，结构大致像这样：

[Unit] Description=Jenkins Service After=network.target [Service] User=jenkins Environment="JAVA_HOME=/opt/jdk8" Environment="JENKINS_HOME=/var/lib/jenkins" ExecStart=/opt/jdk8/bin/java -jar /opt/jenkins/jenkins.war Restart=always [Install] WantedBy=multi-user.target

这里必须特别注意 JENKINS_HOME。这个环境变量决定了 Jenkins 的所有配置、插件和构建记录放在哪。默认情况下，Jenkins 会把数据放在当前用户目录下的 .jenkins 文件夹里，但生产环境建议把它指向一个独立、空间充足、方便备份的目录，比如 /var/lib/jenkins。数据目录与程序目录分开，后续升级、备份、迁移都方便得多。

Windows 下则是另一种玩法。可以用命令行直接启动 war 包做验证，但长期运行最好注册成 Windows 服务。常用做法是配合 winsw 这类小工具，写好 XML 配置文件，指定可执行文件路径、参数、日志输出位置，然后用命令完成服务注册。注册过程有两个容易踩坑的地方：一是路径里含空格时，XML 配置中的转义和引号经常出问题；二是服务运行账号如果是普通用户，需要给它赋予数据目录和日志目录的读写权限，否则 Jenkins 连自己的数据目录都访问不了。

无论哪种系统，安装完成后第一步都是访问 http://服务器IP:8080/。页面会提示输入初始密码，Linux 默认路径是 /var/lib/jenkins/secrets/initialAdminPassword，Windows 默认路径是 C:\Users\当前用户.jenkins\secrets\initialAdminPassword。拿到密码解锁之后，就进入管理员账号创建环节。这个初始密码只在首次启动时有效，创建好了管理员账号，建议立刻把这个密码文件处理掉，避免敏感信息长期留在磁盘上。

3. 内网条件下的插件离线安装

3.1 为什么插件是内网部署最大的坑

把 Jenkins 装起来其实只需要几分钟，真正让内网部署变得痛苦的是插件。Jenkins 核心本身是一个框架，大量功能依赖插件实现，比如 Git 拉取代码、Maven 构建、邮件通知、权限管理、流水线语法，全对应不同的插件。默认情况下，Jenkins 首次启动时会通过插件站点加载大量插件元数据，然后根据选择自动下载安装。在外网环境里这个过程需要一点时间但整体顺畅，内网环境里这一步基本必挂，机器访问不了插件下载服务器，页面一直转圈，最后直接超时。

更麻烦的是，即使你绕过了初始化向导，先进系统创建管理员账号，后续手动安装指定插件时还是会有问题。插件之间存在依赖关系，你装 A 插件，它可能要求你先装 B 和 C，而且 B、C 还有各自的版本范围。外网下 Jenkins 会自动解析依赖并下载所有必要插件，内网下手动上传单个插件时，Jenkins 不会自动去外网拉依赖，于是就会看到插件上传成功但没激活、功能入口缺失、流水线语法报错等一系列连锁反应。

3.2 插件管理的两种离线方案

插件离线安装主要有两种思路，都值得掌握。

第一种是手动下载单个插件并上传。操作路径是：进入系统管理，找到插件管理页面，在高级选项卡里有一个“上传插件”的功能，选择本地文件后上传。这种方式适合插件数量少、依赖关系简单的情况。如果只需要一个独立的工具型插件，上传一个文件就完事。但如果要装 Git 插件、Pipeline 插件、Credentials 插件、SSH 插件这一整套，手动一个个传就很痛苦，依赖顺序还得自己理清，维护成本偏高。

第二种是整体导入外网环境准备好的插件包。具体做法是：在外网机器上安装同版本 Jenkins，把需要的插件全部装好，然后进入数据目录下的 plugins 目录，把里面所有 .jpi 或 .hpi 文件打包，传进内网后解压到内网 Jenkins 的 plugins 目录，最后重启。这个方法的好处是绕开了依赖解析问题，因为外网 Jenkins 在安装时已经把依赖全部下载并配置好了。我实测下来这是最省心的方式，也是我现在做内网部署时优先用的方案。

使用整体导入时有两点要注意。一是外网机器和内网机器的 Jenkins 版本最好一致，否则插件目录里可能混入与核心版本不兼容的文件，重启后出现插件加载失败。二是如果你希望连插件的预配置状态一起迁移，可以更进一步，把整个 JENKINS_HOME 目录打包迁移，不只是 plugins 目录。这样连全局配置、视图、凭据等都能带过来，适合需要在多套环境里复刻相同配置的场景。

3.3 插件依赖问题的处理思路

即使整体导入，偶尔也会遇到漏网之鱼。比如某个插件加载失败，首要任务就是看系统管理页面有没有相关提示，把插件名记下来。然后登录服务器，到 JENKINS_HOME/plugins 目录下看对应文件是否存在。文件存在但依赖缺失，就找依赖插件补充；文件直接不存在，那就补齐文件本身。还有一种情况是插件版本冲突，两个插件引用了同一个公共库的不同版本，Jenkins 日志会给出相对明确的错误，解决办法一般是升、降其中一个插件，把版本对齐到两者都能接受的区间。

内网环境下有一个做法很值得推荐：你在外网把插件环境准备好之后，给整套插件文件做一个备份包，命名可以是“插件集合-版本号-日期”。以后需要内部环境扩展新功能时，只需要在备份包基础上差量补充新增插件和依赖，不需要重新走一遍完整导入流程。这套管理习惯一旦养成，后期加插件、升级插件都会省很多事。

4. 配置管理：从初始设置到任务落地

4.1 初始配置与管理员账号

初始化完成后，Jenkins 一般会要求创建一个管理员账号。很多人觉得内网环境没什么风险，账号密码随便填就行，但构建服务器一旦进入团队日常流程，安全问题就会浮现出来。密码强度、权限范围、是否使用独立账号，都应提前考虑。我的建议是创建一个专用管理员账号，密码复杂度按企业标准执行，账号信息放到内部密码管理工具里，不要明文写在共享文档中。

除了账号，系统配置页面里还有几项要在搭建初期就处理好。系统管理里的“系统配置”是最重要的一张页面，其中 Jenkins URL、系统管理员邮箱、全局属性这三项尤其值得关注。Jenkins URL 如果填错，后续很多功能都会受影响，特别是邮件通知里生成的链接、插件回调地址、仓库 Webhook 回调等。所以必须填内网其他机器都能访问到的地址，不要填 localhost。系统管理员邮箱是构建通知的默认发件人，配置不正确，邮件插件会报认证错误。全局属性里的环境变量可以定义一些团队通用的常量，比如版本号、部署路径、仓库地址，所有构建任务都能引用，后续调整只需要改一处。

4.2 全局工具配置

命令行工具链的正常工作，本质上是靠 PATH 环境变量把可执行文件找出来。Jenkins 里的“全局工具配置”就是做类似的事，为 JDK、Git、Maven 等工具配置路径。Jenkins 提供了自动安装能力，可以让它从网上下载指定版本的工具，但这要求 Jenkins 所在机器能访问公网。内网环境下必须关掉自动安装，改用手动指定路径。

在全局工具配置页面里，可以新增 JDK 安装项，输入名称，比如 jdk8，再填 JAVA_HOME 路径。Jenkins 不会主动校验路径有效性，只有构建任务实际用到时才会去读。所以填之前最好在服务器上确认一下路径真实存在。很多人在这里把路径填错，构建任务直接报 “Unable to locate executable” 的错误，日志里看半天才发现是路径问题。Git 的配置类似，可以新增安装项后指定 git 可执行文件路径，也可以直接保留默认，让 Jenkins 去 PATH 里找 git。如果服务器上装了多个 Git，还是建议显式指定，避免构建时用到预期外的版本。

Maven 的配置也是一样的逻辑，在工具配置里指定 Maven 安装路径，同时确认 Maven 的 settings.xml 中本地仓库和镜像源已经配置好。这里多说一句，内网环境下 Maven 构建非常依赖私有仓库，如果团队还没有本地制品库服务，我强烈建议先搭一个，否则每次构建都会卡在依赖下载阶段，Jenkins 再稳定也没用。

4.3 系统配置中的关键项

系统配置页面里除了工具配置，还有不少值得逐项过一遍的内容。一个是 Jenkins URL，前面提过，这里补充一个细节：如果后续在 Jenkins 前面加了 Nginx 做反向代理，那么 Jenkins URL 一定要填外部访问的域名或 IP 加端口，而不是本机内网地址。否则你用正确的域名打开页面，页面内部生成的资源链接却指向无法访问的内网地址，样式全是乱的，构建日志里部分链接也点不开。

邮件通知是另一个内网环境容易出问题的点。内网邮件服务器往往是企业内部系统，需要确认 SMTP 认证方式、端口、是否启用 TLS。配置完一定要点击“发送测试邮件”按钮验证，不要等到构建失败才发现邮件一直没送达。我遇到过好几次：构建界面显示成功，邮件却没发出去，原因只是 SMTP 端口写错或者账号过期。这种问题埋得深，等发现的时候可能已经过去很多天。

全局属性里的环境变量也建议尽早规划。有些构建脚本在系统层依赖环境变量，比如版本号、部署路径、仓库地址。把这些信息放到系统全局属性里，多个任务共享同一个值，后续调整路径只需要改一处系统配置，不用逐个改任务，能避免不少重复劳动。

4.4 凭据管理与权限控制

凭据管理是内网环境中容易忽视但非常重要的部分。Jenkins 的凭据存储在系统管理里的凭据页面，可以添加用户名密码、SSH 密钥、Token 等类型。Git 仓库拉取、制品库上传、远程服务器部署，基本都离不开凭据。内网环境建议使用专门的部署账号来创建凭据，并按简历规范的命名方式管理，比如 git-dep-account 或 registry-upload-token，同时在描述中写明用途和创建时间。

权限控制方面，Jenkins 默认对匿名用户开放读权限。如果你的内网环境里随便一台机器都能访问这台服务器，那么匿名用户就能看到任务列表和构建日志。对于敏感项目来说，这显然不够稳妥。你可以在全局安全配置里启用基于矩阵的授权策略，给不同用户组分配不同的权限。常见划分方式是：团队成员拥有读取和构建权限，管理员拥有系统配置和任务管理权限，只读人员只能看不能操作。配置完成后，建议开一个无痕浏览器窗口验证一下匿名用户实际可见范围，比管理员嘴上说“权限没问题”要靠谱得多。

5. 内网环境下的任务构建与分发

5.1 创建一轮基础的构建任务

当 Jenkins 环境跑通、插件装齐，接下来最关心的就是怎么创建构建任务。这里以最常见的“自由风格项目”为例，走一遍完整配置流程。

进入新建任务页面，输入任务名称，选择“构建一个自由风格的软件项目”。在源码管理一栏选择 Git，填写内网 Git 仓库地址，比如 http://git.internal.example.com/group/repo.git。凭据选择之前创建的部署账号。分支构建器填写需要构建的分支，比如 main 或 develop。构建触发器一栏，可以选择轮询 SCM，也可以使用 Webhook，但内网环境下有些 Webhook 因为网络策略无法从代码托管平台主动回调，反而定时轮询更可靠。

构建环境一栏，我建议勾选“构建前删除工作空间”，避免旧产物和新代码混合干扰构建。构建步骤一栏，可以添加“调用顶层 Maven 目标”，填写 clean package；也可以添加“执行 shell”步骤，跑自定义脚本，比如复制产物到指定目录、执行测试脚本等。配置完成点击“立即构建”，观察控制台输出日志。日志是内网环境下排查问题的主要入口，构建失败的绝大多数原因都能在里面找到线索。

5.2 与内网代码仓库的对接

内网环境对接代码仓库，我见过最多的问题出在凭据类型上。Git 仓库用 SSH 协议，但你在凭据里添加的是用户名密码，Jenkins 就会报 “Could not read from remote repository”。解决方法是改用 SSH 密钥凭据，并确保公钥已经添加到代码仓库对应的账户配置里。

另一种常见情况是代码仓库使用自签名的 HTTPS 证书。构建机器如果没有把证书导入到系统信任库，Jenkins 拉取代码时也会因为证书校验失败而中断。处理办法有两个：要么把自签名证书导入到 Jenkins 运行账号对应的 Java 证书库，要么在系统配置中关闭 Git 客户端的 SSL 校验。这里要劝一句，如果团队安全规范允许，还是优先使用正规证书，不要为了图省事关闭校验。如果非要关闭，也要评估仓库的访问范围和风险等级再做决定。

还有一个小细节是端口。内网 Git 服务如果使用自定义 SSH 端口，地址里必须写明端口，比如 ssh://git@git.internal.example.com:2222/group/repo.git。我见过服务器配置完全正确，但 Jenkins 一直拉取失败的情况，后来排查发现就是地址里没有写端口，Git 默认走了 22，直接被网络策略拦掉。日志里多看看连接信息，这类问题其实不难发现。

5.3 构建产物管理与定时触发

构建任务的最后一步是保存产物并考虑如何触发下一次构建。内网环境里，自动触发有两种常见模式：一种是代码托管平台支持持续集成钩子，提交代码后主动调用 Jenkins 的构建接口；另一种是网络条件受限时只能选定时轮询，Jenkins 定期检查代码仓库是否有变化，有变化才触发构建。

定时轮询的配置在构建触发器里，语法类似 crontab。比如 H/5 * * * * 表示每 5 分钟检查一次。使用 H 参数可以让 Jenkins 在指定时间段内随机化执行时刻，避免多个任务同一时间争抢资源。这个细节在任务数量多的时候特别有用，可以把 H 理解为一种错峰机制，让每个任务在各自的随机时刻分散触发。

构建产物管理方面，简单做法是在构建步骤的 shell 里把产物复制到指定目录，比如 /data/artifacts/项目名/构建号/，再用一个固定符号链接指向最新版本。更规范的做法是配置归档制品插件，把构建得到的 jar、war 包归档到 Jenkins 的构建记录里，用户可以在任务页面的构建历史中直接下载。任务多的时候，磁盘消耗会涨得很快，所以还要设置构建保留策略，比如只保留最近 10 次构建记录，超过自动清理工作空间和归档文件，避免磁盘被历史数据堆满。

6. 常见问题排查与避坑实录

6.1 插件安装失败的几种典型表现

插件这块的问题，我遇到过很多种形态，挑几个最常见的复盘。

第一种是上传插件后显示“插件未安装”或“插件加载失败”。多半是插件文件没问题，但依赖短缺。解决办法是把内网 Jenkins 数据目录下的 plugins 目录打包，放到外网同版本 Jenkins 上对比差异，看缺了哪些文件补进去。我管这个方法叫“差量补齐法”，依赖关系复杂时非常有效。

第二种是上传时提示文件格式不对或扩展名不被支持。通常是下载插件时选错了文件类型。插件平台一般提供 .hpi 和 .jpi 两种格式，Jenkins 都能识别。如果你拿到的文件其实是源码包或者普通压缩包，自然过不了格式校验。下载时认准 .hpi 或 .jpi 结尾的文件就行。

第三种是流水线里的步骤提示方法不存在，比如 writeFile 或者 sh 无效。这通常是某个流水线相关插件没有装全或者版本太旧。内网流水线任务特别容易遇到这种情况，因为流水线里用到的步骤很多，依赖链也长。排查思路还是沿用差量补齐法，在外网环境把用到的相关步骤插件装齐，再整体导入内网。

6.2 构建任务执行中的常见障碍

构建任务执行本身的问题，大多出在网络和工具链上。挑几个实际遇到的场景。

先把最容易出问题的几个场景整理成一张速查表：

Maven 构建时依赖下载失败是内网环境里最常见的问题。没有配置私服的情况下，Maven 默认去中央仓库下载，公网不通就整个构建卡死。解决方法是修改 Maven 的 settings.xml，把中央仓库镜像改成内网私有仓库地址。如果团队还没有制品库，强烈建议先搭一个，构建效率和依赖管理都能明显改善。

shell 脚本执行权限问题也很典型。Jenkins 执行 shell 命令时，默认用基础用户运行，如果你的脚本需要写某些系统目录，比如 /opt 或 /var/run，就要确保该用户对这些目录有足够权限。我经常看到构建前半段正常，后半段因为复制产物到目标目录时权限不足而失败，日志里显示 Permission denied，这类问题往往只在特定任务上出现，排查成本反而更高。

6.3 其他容易被忽略的小坑

除了插件和构建问题，内网 Jenkins 环境里还有一些细节值得留意。

第一，时区问题。某些操作系统默认时区不是本地标准时间，构建日志里的时间戳会和实际时间差几个小时。排查问题时如果发现构建记录时间和自己操作时间对不上，先检查系统时区，不用怀疑 Jenkins 本身。通过 date 命令看系统时间，不对就修正时区并同步时间。

第二，磁盘空间问题。Jenkins 的构建记录、插件、工作空间在持续使用后体积会迅速膨胀。我自己就遇到过日志文件占满磁盘，Jenkins 连数据目录都访问不了，页面直接报严重错误的情况。预防方法是定期清理旧构建，并在数据目录所在文件系统上做空间监控。就算内网没有统一监控平台，也可以写个脚本定时检查磁盘使用率，到阈值发邮件通知。

第三，端口冲突。Jenkins 默认监听 8080 端口，如果内网其他服务已经占了这个端口，启动时就会提示端口占用。解决方法是在启动参数里加 --httpPort=8090 或者通过配置指定其他端口。但要注意端口变了之后，所有访问链接、邮件通知里的地址、Webhook 回调都要同步，不然团队其他人还停留在旧端口上，以为 Jenkins 挂了。

最后再分享一个小技巧。内网环境的 Jenkins 一旦稳定运行，最重要的就是记录“当前环境标识”：Jenkins 版本、JDK 版本、插件清单、关键配置项的路径和值。把这套信息记录成一份简单的环境档案，放在团队内部文档里。以后无论是升级、迁移，还是新开一套环境，只要有这份档案，整个流程会顺畅非常多。我后来做所有内网部署都会先建这份档案，它帮我省下的时间远超前期记录花掉的时间。