前端專案自動化部署——超詳細教程（Jenkins、Github Actions）

本教程主要講解了怎麼使用 Jenkins 和 Github Actions 部署前端專案。

1. 第一部分是使用 Gitea 配置區域網 git 伺服器，再使用 Jenkins 將 Gitea 下的專案部署到區域網伺服器。
2. 第二部分是使用 Github Actions 將 Github 專案部署到 Github Page 和阿里雲。

閱讀本教程並不需要你提前瞭解 Jenkins 和 Github Actions 的知識，只要按照本教程的指引，就能夠實現自動化部署專案。

PS：本人所用電腦作業系統為 windows，即以下所有的操作均在 windows 下執行。其他作業系統的配置大同小異，不會有太大差別。

Gitea + Jenkins 自動構建前端專案並部署到伺服器

Gitea 用於構建 Git 區域網伺服器，Jenkins 是 CI/CD 工具，用於部署前端專案。

配置 Gitea

1. 下載 Gitea，選擇一個喜歡的版本，例如 1.13，選擇 gitea-1.13-windows-4.0-amd64.exe 下載。
2. 下載完後，新建一個目錄（例如 gitea），將下載的 Gitea 軟體放到該目錄下，雙擊執行。
3. 開啟 localhost:3000 就能看到 Gitea 已經執行在你的電腦上了。
4. 點選註冊，第一次會彈出一個初始配置頁面，資料庫選擇 SQLite3。另外把 localhost 改成你電腦的區域網地址，例如我的電腦 IP 為 192.168.0.118。

1. 填完資訊後，點選立即安裝，等待一會，即可完成配置。
2. 繼續點選註冊使用者，第一個註冊的使用者將會成會管理員。
3. 開啟 Gitea 的安裝目錄，找到 custom\conf\app.ini，在裡面加上一行程式碼 START_SSH_SERVER = true。這時就可以使用 ssh 進行 push 操作了。

1. 如果使用 http 的方式無法克隆專案，請取消 git 代理。

git config --global --unset http.proxy
git config --global --unset https.proxy

配置 Jenkins

1. 需要提前安裝 JDK，JDK 安裝教程網上很多，請自行搜尋。
2. 開啟 Jenkins 下載頁面。

1. 安裝過程中遇到 Logon Type 時，選擇第一個。

1. 埠預設為 8080，這裡我填的是 8000。安裝完會自動開啟 http://localhost:8000 網站，這時需要等待一會，進行初始化。
2. 按照提示找到對應的檔案（直接複製路徑在我的電腦中開啟），其中有管理員密碼。

1. 安裝外掛，選擇第一個。

1. 建立管理員使用者，點選完成並儲存，然後一路下一步。

1. 配置完成後自動進入首頁，這時點選 Manage Jenkins -> Manage plugins 安裝外掛。

1. 點選 可選外掛，輸入 nodejs，搜尋外掛，然後安裝。
2. 安裝完成後回到首頁，點選 Manage Jenkins -> Global Tool Configuration 配置 nodejs。如果你的電腦是 win7 的話，nodejs 版本最好不要太高，選擇 v12 左右的就行。

建立靜態伺服器

1. 建立一個空目錄，在裡面執行 npm init -y，初始化專案。
2. 執行 npm i express 下載 express。
3. 然後建立一個 server.js 檔案，程式碼如下：

const express = require('express')
const app = express()
const port = 8080

app.use(express.static('dist'))

app.listen(port, () => {
    console.log(`Example app listening at http://localhost:${port}`)
})

它將當前目錄下的 dist 資料夾設為靜態伺服器資源目錄，然後執行 node server.js 啟動伺服器。

由於現在沒有 dist 資料夾，所以訪問網站是空頁面。

不過不要著急，一會就能看到內容了。

自動構建 + 部署到伺服器

1. 下載 Jenkins 提供的 demo 專案 building-a-multibranch-pipeline-project，然後在你的 Gitea 新建一個倉庫，把內容克隆進去，並提交到 Gitea 伺服器。

1. 開啟 Jenkins 首頁，點選 新建 Item 建立專案。

1. 選擇原始碼管理，輸入你的 Gitea 上的倉庫地址。

1. 你也可以嘗試一下定時構建，下面這個程式碼表示每 5 分鐘構建一次。

1. 選擇你的構建環境，這裡選擇剛才配置的 nodejs。

1. 點選增加構建步驟，windows 要選 execute windows batch command，linux 要選 execute shell。

1. 輸入 npm i && npm run build && xcopy .\build\* G:\node-server\dist\ /s/e/y，這行命令的作用是安裝依賴，構建專案，並將構建後的靜態資源複製到指定目錄 G:\node-server\dist\ 。這個目錄是靜態伺服器資源目錄。

1. 儲存後，返回首頁。點選專案旁邊的小三角，選擇 build now。

1. 開始構建專案，我們可以點選專案檢視構建過程。

1. 構建成功，開啟 http://localhost:8080/ 看一下結果。

1. 由於剛才設定了每 5 分鐘構建一次，我們可以改變一下網站的內容，然後什麼都不做，等待一會再開啟網站看看。

1. 把修改的內容提交到 Gitea 伺服器，稍等一會。開啟網站，發現內容已經發生了變化。

使用 pipeline 構建專案

使用流水線構建專案可以結合 Gitea 的 webhook 鉤子，以便在執行 git push 的時候，自動構建專案。

1. 點選首頁右上角的使用者名稱，選擇設定。

1. 新增 token，記得將 token 儲存起來。

1. 開啟 Jenkins 首頁，點選 新建 Item 建立專案。

1. 點選構建觸發器，選擇觸發遠端構建，填入剛才建立的 token。

1. 選擇流水線，按照提示輸入內容，然後點選儲存。

1. 開啟 Jenkins 安裝目錄下的 jenkins.xml 檔案，找到 <arguments> 標籤，在裡面加上 -Dhudson.security.csrf.GlobalCrumbIssuerConfiguration.DISABLE_CSRF_PROTECTION=true。它的作用是關閉 CSRF 驗證，不關的話，Gitea 的 webhook 會一直報 403 錯誤，無法使用。加好引數後，在該目錄命令列下輸入 jenkins.exe restart 重啟 Jenkins。

1. 回到首頁，配置全域性安全選項。勾上匿名使用者具有可讀許可權，再儲存。

1. 開啟你的 Gitea 倉庫頁面，選擇倉庫設定。

1. 點選管理 web 鉤子，新增 web 鉤子，鉤子選項選擇 Gitea。
2. 目標 URL 按照 Jenkins 的提示輸入內容。然後點選新增 web 鉤子。

1. 點選建立好的 web 鉤子，拉到下方，點選測試推送。不出意外，應該能看到推送成功的訊息，此時回到 Jenkins 首頁，發現已經在構建專案了。

1. 由於沒有配置 Jenkinsfile 檔案，此時構建是不會成功的。所以接下來需要配置一下 Jenkinsfile 檔案。將以下程式碼複製到你 Gitea 專案下的 Jenkinsfile 檔案。jenkins 在構建時會自動讀取檔案的內容執行構建及部署操作。

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {  // window 使用 bat， linux 使用 sh
                bat 'npm i'
                bat 'npm run build'
            }
        }
        stage('Deploy') {
            steps {
                bat 'xcopy .\\build\\* D:\\node-server\\dist\\ /s/e/y' // 這裡需要改成你的靜態伺服器資源目錄
            }
        }
    }
}

1. 每當你的 Gitea 專案執行 push 操作時，Gitea 都會通過 webhook 傳送一個 post 請求給 Jenkins，讓它執行構建及部署操作。

小結

如果你的作業系統是 Linux，可以在 Jenkins 打包完成後，使用 ssh 遠端登入到阿里雲，將打包後的檔案複製到阿里雲上的靜態伺服器上，這樣就能實現阿里雲自動部署了。具體怎麼遠端登入到阿里雲，請看下文中的 《Github Actions 部署到阿里雲》 一節。

Github Actions 自動構建前端專案並部署到伺服器

如果你的專案是 Github 專案，那麼使用 Github Actions 也許是更好的選擇。

部署到 Github Page

接下來看一下如何使用 Github Actions 部署到 Github Page。

在你需要部署到 Github Page 的專案下，建立一個 yml 檔案，放在 .github/workflow 目錄下。你可以命名為 ci.yml，它類似於 Jenkins 的 Jenkinsfile 檔案，裡面包含的是要自動執行的指令碼程式碼。

這個 yml 檔案的內容如下：

name: Build and Deploy
on: # 監聽 master 分支上的 push 事件
  push:
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest # 構建環境使用 ubuntu
    steps:
      - name: Checkout
        uses: actions/checkout@v2.3.1  
        with:
          persist-credentials: false

      - name: Install and Build # 下載依賴 打包專案
        run: |
          npm install
          npm run build

      - name: Deploy # 將打包內容釋出到 github page
        uses: JamesIves/github-pages-deploy-action@3.5.9 # 使用別人寫好的 actions
        with:  # 自定義環境變數
          ACCESS_TOKEN: ${{ secrets.VUE_ADMIN_TEMPLATE }} # VUE_ADMIN_TEMPLATE 是我的 secret 名稱，需要替換成你的
          BRANCH: master
          FOLDER: dist
          REPOSITORY_NAME: woai3c/woai3c.github.io # 這是我的 github page 倉庫
          TARGET_FOLDER: github-actions-demo # 打包的檔案將放到靜態伺服器 github-actions-demo 目錄下

上面有一個 ACCESS_TOKEN 變數需要自己配置。

1. 開啟 Github 網站，點選你右上角的頭像，選擇 settings。

1. 點選左下角的 developer settings。

1. 在左側邊欄中，單擊 Personal access tokens（個人訪問令牌）。

1. 單擊 Generate new token（生成新令牌）。

1. 輸入名稱並勾選 repo。

1. 拉到最下面，點選 Generate token，並將生成的 token 儲存起來。

1. 開啟你的 Github 專案，點選 settings。

點選 secrets->new secret。

建立一個金鑰，名稱隨便填（中間用下劃線隔開），內容填入剛才建立的 token。

將上文程式碼中的 ACCESS_TOKEN: ${{ secrets.VUE_ADMIN_TEMPLATE }} 替換成剛才建立的 secret 名字，替換後程式碼如下 ACCESS_TOKEN: ${{ secrets.TEST_A_B }}。儲存後，提交到 Github。

以後你的專案只要執行 git push，Github Actions 就會自動構建專案併發布到你的 Github Page 上。

Github Actions 的執行詳情點選倉庫中的 Actions 選項檢視。

具體詳情可以參考一下我的 demo 專案 github-actions-demo。

構建成功後，開啟 Github Page 網站，可以發現內容已經發布成功。

Github Actions 部署到阿里雲

初始化阿里雲伺服器

1. 購買阿里雲伺服器，選擇作業系統，我選的 ubuntu
2. 在雲伺服器管理控制檯選擇例項->更多->金鑰->重置例項密碼（一會登陸用）
3. 選擇遠端連線->VNC，會彈出一個密碼，記住它，以後遠端連線要用（ctrl + alt + f1~f6 切換終端，例如 ctrl + alt + f1 是第一個終端）
4. 進入後是一個命令列 輸入 root（預設使用者名稱），密碼為你剛才重置的例項密碼
5. 登陸成功， 更新安裝源 sudo apt-get update && sudo apt-get upgrade -y
6. 安裝 npm sudo apt-get install npm
7. 安裝 npm 管理包 sudo npm install -g n
8. 安裝 node 最新穩定版 sudo n stable

建立一個靜態伺服器

mkdir node-server // 建立 node-server 資料夾
cd node-server // 進入 node-server 資料夾
npm init -y // 初始化專案
npm i express
touch server.js // 建立 server.js 檔案
vim server.js // 編輯 server.js 檔案

將以下程式碼輸入進去（用 vim 進入檔案後按 i 進行編輯，儲存時按 esc 然後輸入 :wq，再按 enter），更多使用方法請自行搜尋。

const express = require('express')
const app = express()
const port = 3388 // 填入自己的阿里雲對映埠，在網路安全組配置。

app.use(express.static('dist'))

app.listen(port, '0.0.0.0', () => {
    console.log(`listening`)
})

執行 node server.js 開始監聽，由於暫時沒有 dist 目錄，先不要著急。

注意，監聽 IP 必須為 0.0.0.0 ，詳情請看部署Node.js專案注意事項。

阿里雲入埠要在網路安全組中檢視與配置。

建立阿里雲金鑰對

請參考建立SSH金鑰對和繫結SSH金鑰對 ，將你的 ECS 伺服器例項和金鑰繫結，然後將私鑰儲存到你的電腦（例如儲存在 ecs.pem 檔案）。

開啟你要部署到阿里雲的 Github 專案，點選 setting->secrets。

點選 new secret

secret 名稱為 SERVER_SSH_KEY，並將剛才的阿里雲金鑰填入內容。

點選 add secret 完成。

在你專案下建立 .github\workflows\ci.yml 檔案，填入以下內容：

name: Build app and deploy to aliyun
on:
  #監聽push操作
  push:
    branches:
      # master分支，你也可以改成其他分支
      - master
jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: Install Node.js
      uses: actions/setup-node@v1
      with:
        node-version: '12.16.2'
    - name: Install npm dependencies
      run: npm install
    - name: Run build task
      run: npm run build
    - name: Deploy to Server
      uses: easingthemes/ssh-deploy@v2.1.5
      env:
          SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }}
          ARGS: '-rltgoDzvO --delete'
          SOURCE: dist # 這是要複製到阿里雲靜態伺服器的資料夾名稱
          REMOTE_HOST: '118.190.217.8' # 你的阿里雲公網地址
          REMOTE_USER: root # 阿里雲登入後預設為 root 使用者，並且所在資料夾為 root
          TARGET: /root/node-server # 打包後的 dist 資料夾將放在 /root/node-server

儲存，推送到 Github 上。

以後只要你的專案執行 git push 操作，就會自動執行 ci.yml 定義的指令碼，將打包檔案放到你的阿里雲靜態伺服器上。

這個 Actions 主要做了兩件事：

1. 克隆你的專案，下載依賴，打包。
2. 用你的阿里雲私鑰以 SSH 的方式登入到阿里雲，把打包的檔案上傳（使用 rsync）到阿里雲指定的資料夾中。

如果還是不懂，建議看一下我的 demo。

ci.yml 配置檔案講解

1. name，表示這個工作流程（workflow）的名稱。
2. on，表示監聽的意思，後面可以加上各種事件，例如 push 事件。

下面這段程式碼表示要監聽 master 分支的 push 事件。當 Github Actions 監聽到 push 事件發生時，它就會執行下面 jobs 定義的一系列操作。

name: Build app and deploy to aliyun
on:
  #監聽push操作
  push:
    branches:
      # master分支，你也可以改成其他分支
      - master
jobs:
...

1. jobs，看字面意思就是一系列的作業，你可以在 jobs 欄位下面定義很多作業，例如 job1、job2 等等，並且它們是並行執行的。

jobs:
  job1:
      ...
  job2:
      ...
  job3:
    ...

回頭看一下 ci.yml 檔案，它只有一個作業，即 build，作業的名稱是自己定義的，你叫 good 也可以。

1. runs-on，表示你這個工作流程要執行在什麼作業系統上，ci.yml 檔案定義的是最新穩定版的 ubuntu。除了 ubuntu，它還可以選擇 Mac 或 Windows。

1. steps，看字面意思就是一系列的步驟，也就是說這個作業由一系列的步驟完成。例如先執行 step1，再執行 step2...

setps 步驟講解

setps 其實是一個陣列，在 YAML 語法中，以 - 開始就是一個陣列項。例如 ['a', 'b', 'c'] 用 YAML 語法表示為：

- a
- b
- c

所以 setps 就是一個步驟陣列，從上到下開始執行。從 ci.yml 檔案來看，每一個小步驟都有幾個相關選項：

1. name，小步驟的名稱。
2. uses，小步驟使用的 actions 庫名稱或路徑，Github Actions 允許你使用別人寫好的 Actions 庫。
3. run，小步驟要執行的 shell 命令。
4. env，設定與小步驟相關的環境變數。
5. with，提供引數。

綜上所述，ci.yml 檔案中的 setps 就很好理解了，下面從頭到尾解釋一邊：

    steps:
    - uses: actions/checkout@v1
    - name: Install Node.js
      uses: actions/setup-node@v1
      with:
        node-version: '12.16.2'
    - name: Install npm dependencies
      run: npm install
    - name: Run build task
      run: npm run build
    - name: Deploy to Server
      uses: easingthemes/ssh-deploy@v2.1.5
      env:
          SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }}
          ARGS: '-rltgoDzvO --delete'
          SOURCE: dist # 這是要複製到阿里雲靜態伺服器的資料夾名稱
          REMOTE_HOST: '118.190.217.8' # 你的阿里雲公網地址
          REMOTE_USER: root # 阿里雲登入後預設為 root 使用者，並且所在資料夾為 root
          TARGET: /root/node-server # 打包後的 dist 資料夾將放在 /root/node-server

1. 使用 actions/checkout@v1 庫克隆程式碼到 ubuntu 上。
2. 使用 actions/setup-node@v1 庫安裝 nodejs，with 提供了一個引數 node-version 表示要安裝的 nodejs 版本。
3. 在 ubuntu 的 shell 上執行 npm install 下載依賴。
4. 執行 npm run build 打包專案。
5. 使用 easingthemes/ssh-deploy@v2.1.5 庫，這個庫的作用就是用 SSH 的方式遠端登入到阿里雲伺服器，將打包好的資料夾複製到阿里雲指定的目錄上。

從 env 上可以看到，這個 actions 庫要求我們提供幾個環境變數：

1. SSH_PRIVATE_KEY: 阿里雲金鑰對中的私鑰（需要你提前寫在 github secrets 上），
2. ARGS: '-rltgoDzvO --delete'，沒仔細研究，我猜是複製完檔案就刪除掉。
3. SOURCE：打包後的資料夾名稱
4. REMOTE_HOST: 阿里雲公網 IP 地址
5. REMOTE_USER: 阿里雲伺服器的使用者名稱
6. TARGET: 你要拷貝到阿里雲伺服器指定目錄的名稱

如果你想了解一下其他 actions 庫的實現，可以直接複製 actions 庫的名稱去搜尋引擎搜尋一下，例如搜尋 actions/checkout 的結果為：

都看到這了，給個贊再走吧。

參考資料

• Jenkins 使用者手冊
• GitHub Actions 文件
• GitHub Pages 文件
• Gitea 文件
• GitHub 操作的工作流程語法

更多文章，敬請關注