内网里能不能装起一套 DevOps 平台，和这套平台能不能真正跑起来，是两件事。多数项目卡住的位置不在安装步骤，而在依赖来源、环境边界和权限责任这三件事没有提前对齐：安装包顺利导入，第一次构建却因为拉不到依赖而失败；流水线显示了绿色，测试却不知道该验哪个制品；发布单上写的版本号和制品库里实际存在的包对不上号。

这篇指南面向需要在隔离内网或离线环境中交付代码托管、CI/CD 与制品管理的研发负责人、DevOps 工程师和运维交付人员。下面的顺序是：先定判断标准，再拆 8 个高频坑，然后是 6 个步骤，最后是验证清单与落地节奏。目标只有一个——让你在内网里跑通首条流水线，并且清楚每一步凭什么算成功。

判断标准：什么才算"部署完成"

内网私有化部署 DevOps 软件，和联网环境下的部署不是同一类任务。差异集中在三处，值得先分清。

依赖来源变了。联网环境下，基础镜像、语言依赖包、流水线插件、扫描规则库都来自公网仓库。内网里这些来源全部失效，必须提前准备离线介质并在内网建立可用的分发源。这一条决定了后面所有步骤的可行性。

环境边界变了。主机名解析、时间同步、证书信任链、网段可达关系，在公网环境下通常由云服务默认解决；在内网里，每一项都需要显式配置。流水线超时和拉取失败，多数时候是这四项中的某一项没配好，而不是工具本身有问题。

责任边界需要重新确认。开发关注分支与提交，测试关注构建产物与部署环境，运维关注发布与回滚，安全与审计关注权限记录与留存。内网部署把这几方的协作断点压缩进同一套系统里，边界不写清，后期就会反复返工。

由此可以给出一个可操作的判断标准：部署完成不等于控制台能登录，而是一次代码提交能在内网自动走完构建、扫描、制品入库、部署到测试环境，并且每一步都能追溯到具体的提交记录。

顺带说清工具边界，避免后面走弯路。Jenkins 主要承担构建调度与任务执行，代码托管、制品仓库、发布审批需要另外解决；GitLab 覆盖仓库与流水线，但需求与缺陷管理通常要再对接一套项目管理系统。相比之下，GitFox 的定位是代码—流水线—制品—发布—安全扫描的一体化底座，禅道负责需求—任务—缺陷—测试的协同，两者分工不同，写研发全流程时要分开看。选哪条路线取决于团队现状，这里不做结论，只提醒一点：先对齐链路断点，再比功能清单。

8 个高频坑：按落地时序排查失效点

下面 8 个坑按实际落地的时间顺序排列，越靠前的越容易在部署当天出现，越靠后的越容易在半年后才暴露。

坑 1｜把"能装上"当成"能跑起来"。症状是安装一路顺利，第一次构建就卡在拉取依赖。根因是按联网环境的经验准备环境，没有准备离线依赖与内网源。规避动作：部署前先列出全部外部依赖，包括基础镜像、语言包、流水线插件、扫描规则库、字体与根证书，逐项确认内网来源。

坑 2｜适配清单只看"支持"，不看组合粒度。症状是验收时被判定为"不在清单内"。CPU 架构、操作系统版本、数据库版本三者是组合关系，单独每一项都支持，不代表这个组合经过验证。规避动作：按"产品版本 + 操作系统版本 + CPU 架构 + 数据库版本"逐项核对，并保留核对记录。

坑 3｜把内网当成"只是没有外网"。症状是主机名解析失败、拉代码超时、证书校验不通过、日志时间错乱。根因是 DNS 与主机名、时间同步、证书的域名覆盖范围、内网仓库地址这四项没有规划。规避动作：把这四项写进部署前的环境自检清单，逐条验证后再开始安装。

坑 4｜构建节点的位置和标签没有规划。症状是流水线长时间排队，或者直接超时失败。根因通常是构建节点所在网段访问不到代码库或制品库，标签与任务类型不匹配，并发数也不够。规避动作：先画一遍网络可达关系，再确定节点数量、标签划分与并发上限。

坑 5｜先铺流水线，最后才理权限。症状是管理员账号一路跑通，上线前才发现无法交付给普通开发者使用。根因是身份来源、空间划分与审计要求被放到了最后。规避动作：在部署阶段就确定身份来源（统一认证或目录服务）、空间与组织映射、角色权限，并同步开启审计日志。

坑 6｜制品存了，但找不到。症状是存储空间持续增长，回滚时却找不到对应版本。根因是制品没有与提交记录绑定，命名和版本策略缺失，也没有清理策略。规避动作：约定制品命名与版本规则，确保制品与提交记录一一对应，并配置保留与清理策略。

坑 7｜制品与发布之间没有门禁。症状是未经测试验证的构建产物可以直接进入生产环境。根因是缺少测试通过的前置条件、审批流程和回滚路径。规避动作：把测试结果与扫描结果设为发布前置条件，生产发布增加审批环节，并提前确认可回滚的历史版本。

坑 8｜把离线部署当成一次性工程。症状是半年后需要升级或扩容时，没人说得清当初是怎么装的。根因是没有离线升级包导入流程、没有备份与恢复演练、也没有监控告警。规避动作：从第一天起就把离线升级流程、备份恢复步骤和告警规则整理成可重复执行的文档。

6 个步骤：从环境准备到首条流水线跑通

这 6 步按真实依赖排序，前一步没有可观察的成功信号，不建议进入下一步。每一步末尾标注了需要同时留意的坑位。

步骤 1：定边界，先出两份清单

先确认三件事：部署形态是单机、主备还是多节点；使用者规模与项目数量大致多少；需要启用哪些模块（代码托管、流水线、制品库、代码扫描、发布与审批）。

然后产出两份清单。一份是适配清单，按"产品版本 + 操作系统版本 + CPU 架构 + 数据库版本"的组合逐项确认；另一份是资源清单，明确每类节点的 CPU、内存、磁盘与存储规划，尤其是制品库的容量增长预期。

成功信号：两份清单都能逐项对应到具体版本号，而不是"支持国产化"这类笼统表述。对应坑 1、坑 2。

步骤 2：把内网基础环境准备好

这是最容易被压缩、也最容易在后面反复补课的一步。动作包括：服务器与操作系统就位，磁盘按要求挂载；配置主机名解析与 DNS；配置时间同步并确认各节点时间一致；准备 TLS 证书，确认证书覆盖实际访问的域名；开放所需端口并确认网段可达；搭建内网软件源与私有镜像仓库，并把基础镜像提前同步进去。

成功信号：节点之间可以按主机名互相访问，证书校验不报错，各节点时间一致，内网源可以正常拉取基础镜像。对应坑 3。

步骤 3：部署平台本体与依赖组件

按安装包说明依次部署数据库、缓存、代码托管与流水线引擎、制品库等组件。完全离线环境下，安装介质与依赖包需要提前导入，容器化部署还要处理镜像的导入与标签管理。

部署完成后不要只看到进程启动就收工，要逐项确认各组件健康检查通过，并验证关键路径：能否登录控制台、能否创建仓库、能否访问制品库。成功信号：控制台可正常登录，各组件健康状态正常，能创建一个空仓库并成功推送一次代码。对应坑 3。

步骤 4：先把身份与权限接好

在铺流水线之前完成权限设计，比事后补要省力得多。动作是：接入企业统一认证或目录服务，保证账号来源唯一；按部门、产品线或项目组划分空间，让不同团队的仓库、流水线、制品彼此隔离；为角色分配仓库、分支、流水线、制品库的权限；开启审计日志，确认关键操作有记录。

成功信号：用一个新建的普通账号登录，只能看到被授权的空间与仓库，越权访问会被拒绝。对应坑 5。

步骤 5：打通构建节点、制品库与内网源

这一步把"能登录"变成"能构建"。动作包括：部署构建节点并联通代码库与制品库所在网段；为节点设置标签，区分构建类型与资源规格；配置内网镜像仓库地址与依赖源，让构建过程不依赖公网；按制品类型（容器镜像、通用文件、包管理格式）建立对应的制品库，并约定命名与版本规则。

成功信号：构建节点能在内网成功拉取代码，完成一次构建并把产物推送到内网制品库。对应坑 4、坑 6。

步骤 6：用一个低风险仓库跑通首条流水线

不要拿核心系统做第一次尝试。选一个依赖少、影响面小的仓库，配置触发方式（代码提交、合并完成后触发或手动触发均可，先选最可控的一种），然后按阶段编排任务：拉取代码 → 安装依赖 → 执行单元测试 → 代码扫描 → 构建制品 → 推送制品库 → 部署到测试环境。

编排完成后先保存为草稿，确认阶段顺序与参数无误再发布，然后提交一次真实代码验证。成功信号：一次提交能自动触发完整流程，任一阶段失败时日志能定位到具体原因。对应坑 7。

首条流水线跑通后的验证清单

绿色流水线只说明这一次成功了，下面的清单用来确认这套内网环境可以被长期依赖。建议逐项走一遍，并保留记录。

• 触发链路：提交代码后自动触发，全程无需人工介入；手动触发和定时触发也能正常执行。
• 制品可追溯：构建产物进入内网制品库，并能关联到具体的提交记录或需求单号。
• 制品可用：能下载历史版本，能回滚到上一个稳定版本。
• 部署可验证：制品能部署到测试环境并正常访问，失败时有明确日志。
• 权限有效：新账号只能看到被授权的空间与仓库，越权操作被拒绝。
• 审计完整：登录、权限变更、评审、发布等关键操作均有日志可查。
• 度量可读：构建成功率、构建时长、失败原因可以查看，而不是只能靠人工统计。
• 离线可重复：断开外部网络后再跑一次完整流程，确认没有任何环节依赖公网。

其中任何一项不通过，都说明部署还没有结束，只是安装结束了。

落地节奏与责任分工

跑通首条流水线只是起点。接下来的推进节奏，建议按"低风险仓库 → 单条产品线 → 全量项目"三段走：先用试点验证权限模型和流水线模板是否够用，再把经过验证的流水线沉淀为公共模板，新项目直接引用，最后才做全量迁移。每段的交付物不同，验收标准也应该不同。

责任分工同样要提前写清，避免落到"谁都在管、谁都不负责"。开发关注分支规范与提交质量，测试关注构建产物与部署环境的对应关系，运维关注发布执行与回滚操作，安全与审计关注权限分配与日志留存，管理角色关注交付节奏与卡点分布。内网环境里没有外部服务兜底，分工不清的代价会比联网环境更高。

关于度量口径，可以参考 DORA 提出的四项指标——部署频率、变更前置时间、服务恢复时间和变更失败率。它们衡量的是交付速度与稳定性的平衡，适合用来定位瓶颈，而不适合直接当作考核数字。

常见问题

完全不能联网的内网，安装包和依赖怎么准备？

在同构环境或允许联网的中转环境中，提前把安装介质、依赖包、基础镜像和插件下载完整，再通过受控介质导入内网，并在内网建立软件源与私有镜像仓库。关键是把"外部依赖"列成清单并逐项确认来源，而不是等到构建失败再逐个补。

私有化部署一定要用国产 CPU 和操作系统吗？

不一定，取决于项目是否有信创或等保方面的验收要求。如果有，适配清单必须按"产品版本 + 操作系统版本 + CPU 架构 + 数据库版本"的组合逐项核对，因为验收看的是组合，而不是单项。如果没有硬性要求，也应优先选择与现有服务器环境一致、运维团队熟悉的组合，降低长期维护成本。

构建节点需要几台，什么配置？

取决于并发构建数量和构建类型。可以先按团队规模估算日常并发，留出一定余量，再根据实际排队情况扩容。需要注意的是，构建节点和制品库通常会占用较多磁盘，规划时要把构建缓存和制品增长一并考虑，而不是只算操作系统占用。

为什么建议从低风险仓库开始跑首条流水线？

因为首次编排一定会遇到参数、权限、路径或缓存方面的问题。用低风险仓库试错，代价只是重跑一次；用核心系统试错，代价可能是影响正常交付。等流程稳定、模板沉淀之后再逐步替换成关键项目。

需不需要和项目管理系统打通？

如果研发流程中需求、缺陷与代码、发布需要互相追溯，打通会明显减少人工核对的工作量。GitFox 与禅道之间可以做到代码关联需求、任务与缺陷，让需求到发布形成可追溯的链路。是否打通取决于团队的追溯要求，功能与集成范围以官方文档和实际部署验证为准。

内网私有化部署 DevOps 软件真正的交付物，不是一套装好的系统，而是一条能在隔离环境里稳定跑通、并且可追溯、可验证、可升级的交付链路。8 个坑和 6 个步骤的作用，是让这条链路的每一段都有人确认过边界。