全栈应用指南 | Jenkins+Gitlab+Cnpm 私有库发包流程核心原理解析

hauk0101
1,445 阅读8分钟

一起养成写作习惯！这是我参与「掘金日新计划 · 4 月更文挑战」的第1天，点击查看活动详情。

背景

最近在修改团队私有仓库中的私有工具包代码时，发现发包流程有些不合理的地方，比如有些包还需要手动发包，有些包居然是以个人名义发的，这样就导致当这个人不在团队时，就无法正常更新包。在跟运维同学一起排查问题的过程中，记下了遇到的问题点，为了方便后续其他同学维护私有包，所以在团队内部补充了私有仓库发包的流程，以及一些常见问题的技术文档。

在这里将一些脱敏后的核心流程整理了一份，如果能方便在做这块的其他同学，便是达到了目的。

目录

  • 私有包发包流程图
  • 核心步骤说明
    • Gitlab 相关步骤
    • Jenkins 相关步骤
    • 业务方使用相关步骤
  • Jenkins 构建逻辑说明
    • Shell 命令示例
    • 核心命令说明
  • Cnpm Server 服务说明
  • 发包相关的客户端配置
  • 注意事项
  • 常见问题说明

私有包发包流程图

本文档所介绍的方案是基于 Jenkins + Gitlab + Cnpm 搭建。如果你的团队没有使用这些，其实可以对照的相关的方案进行改造，只要了解其中的核心逻辑，一些步骤组合均可适用。

概念说明
  • Jenkins 是一个开源软件项目，是基于Java开发的一种持续集成工具，用于监控持续重复的工作，旨在提供一个开放易用的软件平台，使软件项目可以进行持续集成。
  • GitLab 是一个用于仓库管理系统的开源项目，使用 Git 作为代码管理工具，并在此基础上搭建起来的Web服务。安装方法是参考 GitLab 在 GitHub 上的 Wiki 页面。
  • Cnpm：Private npm registry and web for Enterprise, base on koa, MySQL and Simple Store Service.
私有包发包流程图

Jenkins+Gitlab+CNPM 发包流程图.png

核心步骤说明

本步骤主要为了根据上述流程图，说明不同用户角色，在不同方向上需要做的事情。

Gitlab 相关步骤
  • 私包维护人员，在本地开发私有包相关的代码
  • 开发完成后，提交合并至项目分支，为了便于统一管理，建议可以将打包分支命名为 cnpm-publish
Jenkins 构建私有包
  • 拥有发包权限的私包管理者（可以和私包维护人员同角色，具体根据团队实际情况而定），进入对应的构建任务
  • 选择 cnpm-publish 分支，也可以默认在 Jenkins 任务中固定为此分支
  • 选择 version 发包版本，也可以固定小版本发包（根据实际情况而定），默认使用 patch 版本，更多版本号说明，参考官方文档：www.npmjs.cn/cli/version…
  • 开始构建，观察是否成功，成功后可以在业务中安装使用，如果不成功，请参考下方的常见问题。
业务方使用相关步骤
  • 使用私有包的业务方，在使用时需要操作的步骤，npm install @私有包前缀/私有包名称@latest --save --registry http://内网私有库地址:7001 --scope=@私有包前缀
  • 不同私包建议在开发阶段，完善对应的开发文档

Jenkins 构建逻辑说明

此模块主要是为了讲解在 Jenkins 中涉及的一些核心内容

Shell 命令示例
cd /data/jenkins_home/workspace/对应的私包项目名
echo "$version"
echo "$branch"
vars=`echo $branch|awk -F/ '{print $2}'`
git checkout $vars
git pull
git branch
npm i
npm run build
npm version $version
cat package.json
npm config set registry http://内网私有库地址:7001/
npm publish
grepfile=`grep 'version' //data/jenkins_home/workspace/对应的私包项目名/package.json | awk -F":" '{print $2}' | sed 's/\"//g' | sed 's/ //g' | sed 's/,//g'`
git add .
git commit -m "Update ${grepfile}"
git push
核心命令说明
  • git branch ：表示在 jenkins 工作空间中切换到对应的分支，即 cnpm-publish 分支，用于在 jenkins 工作空间中变更代码，并最终提交至 gitlab ，目的是为了保证代码中的 package.json 与实际私有包的版本号保持一致
  • npm i ：表示安装私有包开发及打包时需要的依赖
  • npm run build：压缩、编译私有包，因为开发的私有包有可能是 typescript ，也可能是通过 es2015+ 等
  • npm version $version : 利用 npm 的命令进行自动升级 package.json 的版本号，jenkins 中的 $version 为 patch、minor、major
  • npm config set registry : 设置当前 npm 的源，为下一步的发布做准备
  • npm publish：发布
  • grepfile=grep version：利用 shell 命令，获取发包后的版本号，用于提交代码时，git commit 中的说明，此处可以根据实际情况进行优化，仅供参考
  • git add. / git commit / git push：发布成功之后，将更新之后的 package.json 同步到 gitlab

Cnpm Server 服务说明

  • 私有库使用的是技术方案是淘宝开源的 cnpm 项目
  • 私有库项目地址：需要拉取到本地，根据情况进行私有化配置，比如数据库、启动的服务端口等等
  • 私有库项目部署好之后，会产生两个地址：
    • 一个是私有库地址，用于 npm publish 和 npm install，默认会是 7001 端口，示例（根据实际情况而定：192.168.1.149:7001)
    • 另一个是查看私有库中已发布的包地址，默认会是 7002 端口，示例（根据实际情况而定：192.168.1.149:7002)

发包相关的客户端配置

本模块只是列举一些常见的 npm publish 相关的命令说明，并不建议在团队中本地使用，建议在对应的 jenkins 打包环境中使用

发布私有包

  • 添加用户(第一次发布包,添加一次即可,已添加过用户名的,非第一次直接登录即可)

    $ npm config set registry http://192.168.1.149:7001

    $ npm adduser

    输入姓名:***

    密码:***

    邮箱:*****

  • 登陆

    npm login --registry http://192.168.1.149:7001 --scope=@私有包前缀

    输入姓名:***

    密码:***

    邮箱:*****

  • 发布私有包

    npm publish

下载私有包
npm install @私有包前缀/私有包名@latest  --save --registry http://192.168.1.149:7001 --scope=@私有包前缀
版本号控制
1.1.0: 指定版本
~1.1.0: 1.1.0 <= 版本 < 1.2.0
^1.1.0: 1.1.0 <= 版本 < 2.0.0
latest/*：安装最新版本。
包结构规范

必须包含的文件：package.json，README.md

注意事项

此处的注意事项，更多是根据我们团队内部而定，仅供大家参考

  • 新项目禁止本地发包，务必用 Jenkins 部署构建任务，使用 jenkins_cnpm （如没有，建议创建或参考团队实际情况进行命名） 账户进行发布，可以与运维同学沟通参考已有项目进行配置，因为会导致其他非包拥有者无法正常发布
  • 禁止本地修改 package.json，因为会导致发布时版本冲突，发布失败
  • 禁止本地打包之后提交代码至 gitlab ，如果涉及到打包编译操作，需要将命令放到对应的私有包的 package.json 中，并在 jenkins 任务中进行编译
  • 如果不熟悉如何发包，建议仔细阅读“发包相关的客户端配置”模块的相关说明
  • 发包分支务必统一使用 cnpm-publish
  • 新项目务必完善对应的文档（至少包括私有包开发的 README.md 文档，业务方使用的说明文档），方便其他同学安装、维护，好的文档能体现一个开发者的基本素养。

常见问题说明

发布失败，显示 403 Forbidden
  • 进入 http://192.168.1.149:7002/ 包管理地址，查到目标私有包，查看其 Maintainers 中是否包含用户 jenkins_cnpm ，如果没有则需要加入
  • 确保 jenkins_cnpm 用户已经登录私有仓库地址，登录方式
npm login --registry http://192.168.1.149:7001 --scope=@私有包前缀

输入姓名:jenkins_cnpm

密码:***

邮箱:*****
  • 检查当前版本私有包版本和发布的版本是否冲突，如果要发布的版本号小于当前版本号，则也会发布失败
如果私有包已经按个人名义发包，如何添加 jenkins_cnpm 账号
  • 登录个人账户进入私有仓库，参考问题1的登录方式，然后按如下步骤进行添加用户即可
npm owner add 个人账户 @私有包前缀/私有包
  • 如果没有权限添加用户，可以使用管理员登录（系统默认账号密码：admin/admin），进行权限添加
在发包过程中，发包成功，但同步代码至 gitlab 失败
  • 确保私包项目的 gitlab 中，已添加 jenkins_cnpm 用户
  • 确保 jenkins 对应的打包目录中已登录 jenkins_cnpm 用户
  • 确保已执行 git add / git commit 操作，才可以进行 git push 命令

杂谈

  • 要区分 Cnpm 客户端命令工具和私有库项目的区别，cnpm 客户端命令工具与 npm 命令工具作用相似，但 cnpm 私有库项目则作用不同
  • 本文不对 jenkins、gitlab、cnpm 的使用细节做过多阐述，重心放在这三者的关联逻辑。
  • 为了减少每次 npm install 的时候都设置一遍 npm set --registry ，可以在业务项目中添加 .npmrc 文件，设置 registry 源地址
  • 为了保证一些非私有库的包正常安装，可以在 cnpm 项目中设置转发源，在 cnpm 项目的 config/config.js 文件中修改如下配置：
// if install return 404, try to sync from source registry
  syncByInstall: true,

参考资料

浏览知识共享许可协议

知识共享许可协议
本作品采用知识共享署名-相同方式共享 4.0 国际许可协议进行许可。

avatar
文章
阅读
粉丝