印記中文推出文檔CDN + COS部署方案

原文連接

簡介

印記中文的成立主要是爲了協助社區更好地翻譯與部署文檔。最近聯合騰訊雲一塊兒設計了一套有效提高訪問速度及下降流量消耗成本的方案，即 COS 對象存儲服務 及 CDN 加速方案。本文主要描述方案大致的實現過程，若是你是技術文檔的管理者，苦於沒有優秀的文檔部署方案，能夠聯繫印記中文(docschina)，咱們會提供接入服務。若是你遇到性能問題，咱們也能夠提供免費的技術諮詢服務

QQ羣：492361223

也能夠關注咱們的公衆號：

官網：docschina.org

代碼存放及CI構建

通常而言，對公有代碼，通常採用 Github + Travis-CI 存放及構建方式。而對於私有代碼來講，則會直接使用 Bitbucket + Pipeline (Bitbucket自有的構建服務)。（點擊如下標題展開詳細內容）

Github + Travis-CI

自動構建與部署服務的架構以下圖：

Sample process

在代碼倉庫方面，咱們須要兩個分支，一個是 master 分支，用於存放文檔源碼，另外一個是 gh-pages 分支，用於存放生成的文檔文件。

而後，咱們須要配置 .travis.yml 文件，用於 Travis-CI 構建和部署咱們的項目，下面是求全配置，表示僅在在 master 分支有 push 或者 pull request 事件的時候，纔會觸發構建，使用語言是 node.js，版本是 6.x，首先運行完安裝依賴的 npm install 以後，再運行 bash ./scripts/deploy.sh。

javascript branches: only: - master language: node_js node_js: - "6" script: - bash ./scripts/deploy.sh sudo: required install: - npm install

那麼 ./scripts/deploy.sh 腳本中，主要就是承擔構建、鑑權，以及代碼推送的功能。

javascript // deploy.sh 第一部份，用於構建代碼 npm run dist

javascript // deploy.sh 第二部份，用於與github鑑權 REPO=`git config remote.origin.url` SSH_REPO=${REPO} git config --global user.name "Travis CI" git config --global user.email "ci@travis-ci.org" git remote set-url origin "${SSH_REPO}" openssl aes-256-cbc -K $encrypted_7562052d3e34_key -iv $encrypted_7562052d3e34_iv -in scripts/deploy_key.enc -out scripts/deploy_key -d chmod 600 scripts/deploy_key eval `ssh-agent -s` ssh-add scripts/deploy_key

javascript // deploy.sh 第三部份，用於向github推送代碼 chmod -R 777 node_modules/gh-pages/ npm run deploy // dist是生產代碼目錄，deploy 所跑腳本是 gh-pages -d dist，最終將代碼推送到gh-pages 分支

那第二部份的 ssh key 怎麼生成呢？其實整個 github 的鑑權原理不難，用工具成生 ssh key 公鑰與私鑰，而後將公鑰存放到 github 的 repository 中，將私鑰存放到代碼庫中，在Travis-CI 推送代碼以前添加私鑰，那麼推送的時候就能夠順利鑑權成功。

那具體怎麼生成 ssh key呢，具體能夠參考這個文檔 Generating a new SSH key to generate SSH Key。

而後，到你的文檔本地代碼倉庫鍵入如下示例命令：

javascript ssh-keygen -t rsa -b 4096 -C ci@travis-ci.org Enter file in which to save the key (/var/root/.ssh/id_rsa): deploy_key

當有如下問題的時候，可 enter 跳過。

Enter passphrase (empty for no passphrase):

打開 deploy_key.pub 文件，將內容複製，而後到線上代碼倉庫 https://github.com/<your name>/<your repo>/settings/keys中，添加 ssh public key。

deploy keys in github

而後安裝 travis client tool，用於上傳 SSH Key 信息到 Travis-CI 服務器。上傳完後，運行如下命令：

javascript travis encrypt-file deploy_key

travis encrypt-file result

使用，將如下代碼複製到 deploy.sh 中，而且將 deploy_key.enc 文件複製到 scripts 目錄下。記得千萬不要上傳 deploy_key.pub 文件。

javascript openssl aes-256-cbc -K $encrypted_7562052d3e34_key -iv $encrypted_7562052d3e34_iv -in scripts/deploy_key.enc -out scripts/deploy_key -d

而後使用如下命令進行登錄:

javascript travis login

Bitbucket + Pipeline

Bitbucket + Pipeline 與 Github + Travis-CI 的流程是大致類似的，你能夠稍微參考一下上一節的架構圖。只是個別流程有細微出入。

生成 SSH Key 與 Github 的辦法同樣，可參考 Generating a new SSH key。

而後前往 https://bitbucket.org/account/user/username/ssh-keys/，或者點擊網站左下角頭像，進入 Bitbucket Setting， Security， SSH keys，進行公鑰添加。




至於 deploy.sh 腳本，也略有一些出入。

javascript // deploy.sh 第一部份，用於構建代碼 npm run dist

javascript // deploy.sh 第二部份，用於與github鑑權 REPO=`git config remote.origin.url` SSH_REPO=${REPO} git config --global --replace-all user.name "xxxxxx" git config --global --replace-all user.email "xxxxxx@gmail.com" git remote set-url origin "${SSH_REPO}" chmod 600 scripts/id_rsa eval `ssh-agent -s` ssh-add scripts/id_rsa ssh -T git@bitbucket.org

javascript // deploy.sh 第三部份，用於向github推送代碼 chmod -R 777 node_modules/gh-pages/ npm run deploy // dist是生產代碼目錄，deploy 所跑腳本是 gh-pages -d dist，最終將代碼推送到gh-pages 分支

Webhook

設置 Webhook，是用於在構建完畢後，向部署服務器發起請求，觸發自動部署的腳本。只要跟部署服務器約定好 url 路徑，而後根據須要配置好 webhook 便可。

Github Webhook

如下是 Github Webhook 設置的截圖。

1st part Github Webhook

2nd part of Github Webhook

Bitbucket Webhook

如下是 Bitbucket 的 Webhook 設置截圖。

部署服務

騰訊雲 COS

COS，即對象存儲（Cloud Object Storage，是面向企業和我的開發者提供的高可用，高穩定，強安全的雲端存儲服務。您能夠將任意數量和形式的非結構化數據放入COS，並在其中實現數據的管理和處理。COS支持標準的Restful API接口，是很是適合做爲靜態文件部署存儲服務。

首先，建立一個 Bucket，沒有備案的域名請選擇海外的節點，同時選擇 CDN 加速（後面須要用）：



建立後，會進入 Vue Bucket 的文件列表頁面，目前是空的。到 基礎配置，中開啓 靜態網站配置。



而後進入域名管理**，添加域名。




而後到你的域名管理提供商，配置一下 CNAME 解析。直接用上圖的域名和 CNAME 值。




若是須要開啓 HTTP2，還能夠去申請 HTTPS 證書，騰訊雲能夠申請免費的 HTTPS 證書。

騰訊雲 CDN

等域名CDN加速部署好後，能夠點擊 COS 域名配置 中，具體域名的 高級配置，進入 CDN 管理界面。

進入 緩存配置，添加一些緩存規則，如 js, css, png, jpg 等帶有 md5 的資源能夠長久緩存，而 html 等資源則不宜緩存。



而後進入 高級配置，在當中配置 HTTPS 證書 和 開啓 HTTP2。

部署服務器

在部署服務器中，須要部署一個服務，用於監聽 Github 或者 Bitbucket 發出來 Webhook 請求，而後根據請求參數，去運行腳本自動將文件部署到騰訊雲 COS 存儲服務當中。

技術方案可大致以下實行。

監聽請求方面， koa + pm2 部署一個小型服務，根據參考運行騰訊雲 COS 文件上傳腳本，而後用 nginx 反向代理技術將請求代理到此小型服務中。

至於 騰訊雲 COS 文件上傳腳本，本人推薦 Java 與 Python 版本的，尤爲是 Python 版本的比較容易安裝部署。
1. COSCMD 工具
2. 本地同步工具

小型服務根據請求參考，先到本地部署好的文檔 gh-pages 分支代碼處，先行更新代碼，而後再運行文件上傳工具，將文件依次上傳到 COS 服務中。

如下是使用 COSCMD 工具的一個簡單示例：

javascript const execSync = require("child_process").execSync, moment = require("moment"), fs = require("fs-extra"), path = require("path"); // COSCMD 基本配置 const config = { "appid": "xxx", "secret_id": "xxx", "secret_key": "xxx", "timeout": 60, "max_thread": 20, }; // 執行命令方法 function exeCmd(cmd) { var result = execSync(cmd); console.log(`[${moment().format('YYYY-MM-DD HH:mm:ss')}]${result}`); } exports.index = function* () { // 從請求 url 參數中得到 project 和 cos 部署節點區域的值 const project = this.params.project || '', region = this.params.region || 'cn-east'; console.log(`[${moment().format('YYYY-MM-DD HH:mm:ss')}]，${project} is starting to update. The region is ${region}！`); // gh-pages 分支代碼存放位置 const codePath = path.join(`/docs/files/${project}`); if (!fs.existsSync(codePath)) { this.response.status = 400; console.log(`${codePath} does not exist`); return; } // 更新 gh-pages 文件 const updateCommand = `cd ${codePath};sudo git pull origin gh-pages;sudo git reset --hard gh-pages;`; exeCmd(updateCommand); // 更新 COSCMD 配置 const configCommand = `coscmd config -a ${config.secret_id} -s ${config.secret_key} -u ${config.appid} -b ${project} -r ${region} -m ${config.max_thread}`; exeCmd(configCommand); // 篩選要上傳的文件或文件夾 let info = fs.readdirSync(`/docs/files/${project}`, 'utf-8'); info = info.filter((item) => { if (item.indexOf('.') === 0) { return false; } return true; }); // COSCMD 上傳文件 info.forEach((item) => { let syncCommand = ''; let stat = fs.statSync(path.join(`/docs/files/${project}/${item}`)); if (stat.isDirectory()) { syncCommand = `sudo coscmd upload -r /docs/files/${project}/${item} ${item}/`; } else { syncCommand = `sudo coscmd upload /docs/files/${project}/${item} ${item}`; } exeCmd(syncCommand); }); this.body = "success";