摘要：內(nèi)容包括翻譯環(huán)境搭建項(xiàng)目管理與自動(dòng)化構(gòu)建三部分。博客首頁(yè)聲明官方文檔翻譯稿發(fā)布托管在七牛上的翻譯文檔倉(cāng)庫(kù)環(huán)境搭建翻譯與寫作一樣，首要之事均為專注于翻譯寫作本身，而不考慮樣式等方面。安裝完成后，運(yùn)行即可在啟動(dòng)一個(gè)本地的。

感興趣的同學(xué)可以關(guān)注這個(gè)翻譯項(xiàng)目 、 我的博客原文 和 我的Github

前段時(shí)間翻譯的Spring MVC官方文檔完成了第一稿，相關(guān)的文章和倉(cāng)庫(kù)可以點(diǎn)擊以下鏈接。這篇文章，主要是總結(jié)一下這個(gè)翻譯項(xiàng)目自開始到上線發(fā)布，完整的一個(gè)生命流程。內(nèi)容包括 翻譯環(huán)境搭建 、項(xiàng)目管理 與 自動(dòng)化構(gòu)建 三部分。

博客首頁(yè)聲明：Spring MVC官方文檔翻譯稿發(fā)布

托管在七牛上的翻譯文檔

Github倉(cāng)庫(kù)

翻譯與寫作一樣，首要之事均為專注于翻譯/寫作本身，而不考慮樣式等方面。而章節(jié)之間的聯(lián)系，自然也不想過多操心，這部分與樣式一起，都可交由工具去處理。然后版本管理，不用說一定要上，后面也會(huì)看到github的生態(tài)圈使得它與其他工具做到了無(wú)縫集成。那么總結(jié)起來(lái)，我們需要的工具大體是：

markdown

markdown編輯器 Atom

版本管理 Git

代碼托管平臺(tái) Github

寫書專用工具 Gitbook

HTML轉(zhuǎn)markdown工具

Markdown是一種近乎完美的寫作標(biāo)記語(yǔ)言，其最大的功勞便是將寫作從內(nèi)容中分離出來(lái)，這個(gè)分離使你只專注于寫作內(nèi)容本身，極大地提高了效率及工作愉悅度。沒有markdown的話，會(huì)是怎樣一種情況？想想HTML和寫論文經(jīng)常使用的word。你在HTML中為內(nèi)容混入各種各樣的樣式，寫論文時(shí)最痛苦的莫過于調(diào)樣式（不過筆者當(dāng)年寫論文時(shí)通過Office Word的樣式窗也是完美地解決了內(nèi)容和格式的問題）。

比如說，上面這段文字在markdown中寫出來(lái)是這樣的：

## 環(huán)境搭建

翻譯與寫作一樣，首要之事均為專注于翻譯/寫作本身，而不考慮樣式等方面。而章節(jié)之間的聯(lián)系，自然也不想過多操心，這部分與樣式一起，都可交由工具去處理。然后版本管理，不用說一定要上，后面也會(huì)看到github的生態(tài)圈使得它與其他工具做到了無(wú)縫集成。那么總結(jié)起來(lái)，我們需要的工具大體是：

* markdown
* markdown編輯器 Atom
* 版本管理 Git
* 代碼托管平臺(tái) Github
* 寫書專用工具 Gitbook
* HTML轉(zhuǎn)markdown工具

說起來(lái)markdown這個(gè)名字也有點(diǎn)意思，一般的標(biāo)記語(yǔ)言叫markup language。這里將up改成down，寓意著將標(biāo)記語(yǔ)言中與內(nèi)容本身無(wú)關(guān)的標(biāo)記全部剔除，形成一個(gè)精簡(jiǎn)子集。本篇不是markdown用法記，所以更多的語(yǔ)法請(qǐng)自行百度Google。我這里可以提供幾個(gè)鏈接：

Wikipedia: Markdown

Markdown overview

Github上最有名的Markdown Cheat Sheet倉(cāng)庫(kù)

編輯器的選擇并無(wú)定式，打造一個(gè)完全符合自己操作習(xí)慣的編輯器也是每個(gè)程序員應(yīng)做的一個(gè)工作，這里我不贅述。在Mac上，不錯(cuò)的markdown編輯器有Sublime 3、Atom、MacDown、Mark Editor、Gitbook Editor、Mou等，可挑選適合自己的，我選擇的是Atom，是因?yàn)橛幸粋€(gè)剛性的需求它能夠滿足：

與終端（terminal）的集成。由于使用了版本管理，同時(shí)有時(shí)有拷貝文件、查看目錄等需求，命令行肯定是必須隨時(shí)在手的。終端方面我的選擇是iTerm2+zsh，關(guān)于它們的配置和特性，可以查看博客的這兩篇文章 Mac優(yōu)雅的工具集——iTerm2篇 和 Mac優(yōu)雅的工具集——oh-my-zsh篇。對(duì)如何在Mac上構(gòu)建一個(gè)優(yōu)雅的工具集有興趣的同學(xué)，也可以前往Gitbook看看我正在寫的這個(gè)系列：關(guān)于優(yōu)雅地使用Mac OS的理念、想法、工具與實(shí)踐集，不過還沒寫完就是了。

Git作為版本管理的意義也不贅言。你肯定不想自己的工作區(qū)最后變成這樣：

同樣本小節(jié)也不是Git入門的命令集，這部分請(qǐng)自行查閱學(xué)習(xí)。當(dāng)然我還是可以給出一些鏈接，雖然沒有太多的意義我真的不知道為什么我還要給?；镜膸讉€(gè)命令能熟悉就可以滿足日常的需要了。另外，zsh下的Git可以配一下 快捷鍵(alias) 和 自動(dòng)補(bǔ)全，具體配置非常簡(jiǎn)單，可以來(lái)這篇文章Mac優(yōu)雅的工具集——oh-my-zsh篇看一下最終的效果。

Git - 簡(jiǎn)易指南

A Visual Git Reference

廖雪峰的官方網(wǎng)站：史上最淺顯易懂的Git教程這浮夸的標(biāo)題收視率果然好

Github是世界上最大的同性交友平臺(tái)目前最大我并無(wú)依據(jù)的代碼托管平臺(tái)，其生態(tài)圈之繁榮與力量令人震驚，幾乎你需要的所有工具和資源都可以在上面找到。它與Git不是一個(gè)層級(jí)的概念git=github.substring(0, 3)，這部分請(qǐng)自行搜索。在這個(gè)平臺(tái)上，我可以給翻譯項(xiàng)目一個(gè)README.md文件，為閱讀的人做簡(jiǎn)單的介紹以及引流，同時(shí)它可與CI（持續(xù)集成）、Gitbook等工具完美集成，其內(nèi)置的issue、pull-request功能還能與Zenhub結(jié)合，直接當(dāng)成trello來(lái)進(jìn)行項(xiàng)目管理之用。相關(guān)的工具下一節(jié)會(huì)介紹。

上文提到了翻譯內(nèi)容與樣式的分離。實(shí)際上在這里樣式這部分就是由Gitbook自帶的渲染引擎來(lái)負(fù)責(zé)的。此外，Gitbook還能幫助你管理整個(gè)書的目錄結(jié)構(gòu)、章節(jié)生成、搜索、詞匯表、站點(diǎn)構(gòu)建與生成等，同時(shí)它也有豐富的插件生態(tài)。這一切只需要你進(jìn)行少量的配置（其實(shí)，就只是在書的根目錄下運(yùn)行gitbook init命令，它會(huì)生成下圖所示的一個(gè)目錄結(jié)構(gòu)），其低學(xué)習(xí)成本與高效益，使它成為了寫書最易入門的趁手工具。

.
├── README.md
└── SUMMARY.md

項(xiàng)目管理方面的需求，主要是有時(shí)會(huì)有想法出現(xiàn)，希望增加什么特性，或者想到什么問題不想馬上修，那么最好是有一個(gè)TODOLIST可以隨時(shí)記錄下來(lái)，并且能被方便地檢索到。這方面的需求，怎么解決呢？

Github內(nèi)置的issue功能已經(jīng)好用到爆，再加上專為Github issue功能定制的Zenhub簡(jiǎn)直就是活生生把issue當(dāng)成trello來(lái)用。一些內(nèi)置特性如下，稍加體驗(yàn)即可滿足所有小型項(xiàng)目管理上的需求：

issue可以通過commit sha直接與相關(guān)的單次提交關(guān)聯(lián)，還可以 通過提交信息來(lái)引用、關(guān)閉issue

issue中支持GFM(Github Flavored Markdown)，可以直接使用todolist的語(yǔ)法

通過Command/Ctrl+V可以直接在留言中上傳截圖

可以為issue添加標(biāo)簽（tag）、類別（pipeline, 如正在做、還沒做、已完成等）

可以為issue估點(diǎn)、指定負(fù)責(zé)人、燃盡圖，簡(jiǎn)直就是為敏捷實(shí)踐而生，不過在這個(gè)翻譯項(xiàng)目中用不到這些，畢竟自己給自己估點(diǎn)沒什么意思

自動(dòng)化什么的構(gòu)建？這還要從本翻譯稿的托管平臺(tái)——Gitbook——說起。gitbook是一個(gè)絕好的寫作平臺(tái)，官方也通過Webhooks提供了與Github的集成，只要你把代碼git push到遠(yuǎn)端倉(cāng)庫(kù)，Gitbook就會(huì)自動(dòng)拉取倉(cāng)庫(kù)中的內(nèi)容，依照特定的格式為書本構(gòu)建站點(diǎn)。過大概2到3分鐘，你就可以在Gitbook上看到自己最新的更新已經(jīng)到書上了。一切看起來(lái)都十分美好，一鍵提交與部署。但是有一個(gè)最大的問題：Gitbook在國(guó)內(nèi)的速度不行，輕則卡頓，重則整站被墻刷不出頁(yè)面。

這種情況下，我決定將整個(gè)翻譯同時(shí)遷移到七牛上。七牛的CDN在國(guó)內(nèi)速度名聲在外，用來(lái)托管靜態(tài)站點(diǎn)再好不過只需要拍兩張身份證正反雙面的照片上傳等待審核即可。遷移也很簡(jiǎn)單，因?yàn)間itbook生成的靜態(tài)站點(diǎn)其實(shí)就是_book文件夾，只需要把這個(gè)文件夾下的全部東西放到七?？臻g上去，在使用index.html作為入口就可以了。但是，問題又來(lái)了：

七牛網(wǎng)站上無(wú)法上傳文件夾。就算可以，我也無(wú)法忍受每次都要手動(dòng)將文件夾拖上去

每次倉(cāng)庫(kù)有更新，都需要將最新的內(nèi)容同步到七?？臻g上，并覆蓋舊版本的同名文件

第二步的操作還不能通過githook+shell的方式來(lái)做，因?yàn)檎麄€(gè)過程的耗時(shí)會(huì)使git push的反饋周期變長(zhǎng)，從而使得我更不傾向于頻繁提交，影響翻譯體驗(yàn)

解決方案也很簡(jiǎn)單：

第一條，尋找七牛的SDK，通過命令行進(jìn)行上傳

第二條，既然不能，[細(xì)想]也沒必要在本地做，那么就在遠(yuǎn)端做好了。遠(yuǎn)端在哪里呢？CI/Pipeline啊，這樣構(gòu)建站點(diǎn)、同步文件等工作都可以并行進(jìn)行了，既不會(huì)阻礙本地開發(fā)速度，也不是翻譯時(shí)需要考慮的問題，我還是只需要像以前一樣git push提交代碼即可，站點(diǎn)從構(gòu)建到最終上線，都有CI在負(fù)責(zé)

想法出來(lái)了，在實(shí)施的時(shí)候還是走了一些彎路的。這些折騰過程在此無(wú)法深表，只有可能帶過程序員們都懂的。在CI的選擇上，我選擇了Jenkins 2.0，原因比較純粹，最近項(xiàng)目上在使用Jenkins 2.0，我剛好當(dāng)是練手。至此文章成筆之時(shí)，我仍在考察其他選擇，比如travis-ci，看起來(lái)UI和配置都簡(jiǎn)單許多，這部分可能是后文了。下面會(huì)簡(jiǎn)單介紹折騰搭建Jenkins 2.0作為本翻譯項(xiàng)目CI的步驟和關(guān)鍵節(jié)點(diǎn)。

話說Jenkins不愧為CI/CD領(lǐng)域的先鋒，這個(gè)產(chǎn)品每周都會(huì)發(fā)一個(gè)小版本（目前最新是2.11）。Jenkins 2.0的安裝，可以通過直接下載安裝包的方式下載，在Mac上也可以通過brew install jenkins來(lái)下載安裝。安裝完成后，運(yùn)行jenkins即可在localhost:8080啟動(dòng)一個(gè)本地的jenkins。

流程十分簡(jiǎn)單，免費(fèi)用戶可以有一個(gè)空間，有一定的流量限制，不過通常來(lái)說對(duì)于只有一個(gè)空間需求的用戶來(lái)說，這樣的流量應(yīng)該不會(huì)超吧。由于我已經(jīng)超過了一個(gè)空間的需求，同時(shí)我又有配置獨(dú)立域名的需求，所以需要更多的權(quán)限。流程也很簡(jiǎn)單，進(jìn)行實(shí)名認(rèn)證、填寫身份證、上傳本人及身份證正反面照片各一張本人不需拍反面，最后保證賬戶里有最少10元即可。

pipeline搭建起來(lái)了，接下來(lái)我們需要捋一捋前面說到的兩個(gè)步驟：構(gòu)建站點(diǎn)、上傳站點(diǎn)文件到七?？臻g。細(xì)分下來(lái)，主要是有以下的task要做：

引入必要的依賴

構(gòu)建站點(diǎn)

同步到七牛

我們想要構(gòu)建站點(diǎn)，必然使用gitbook的命令行工具；要使用七牛的命令行，也必然引入相應(yīng)的工具。這里我走過一些彎路，比如嘗試將七牛工具以插件形式引入到Jenkins job中來(lái)，但是2.0以后，我們更傾向于使用腳本來(lái)描述構(gòu)建工作，而非將Jenkins單純當(dāng)作一個(gè)轉(zhuǎn)存/轉(zhuǎn)儲(chǔ)的工作區(qū)間并為該workspace零散地寫一些適配腳本。因此，在pipeline類型的項(xiàng)目就不存在每個(gè)job特定的配置空間，若想使用插件，配置起來(lái)有些麻煩。于是，最后我決定使用七牛的npm包（肯定是有的），并通過NPM來(lái)管理所有依賴。以下是一個(gè)package.json文件需引入的依賴：

{
   ...
   "devDependencies": {
        "gitbook": "^3.1.1",
        "gitbook-cli": "^2.3.0",
        "qiniu": "^6.1.11"
    },
    ...
}

另外，需要注意的是，Gitbook的渲染引擎已經(jīng)升級(jí)到v3.1.1版本，與Legacy v2.6.7版引擎相比，主要的區(qū)別是v3支持多個(gè)部分(part)的文章、默認(rèn)關(guān)閉了目錄中章節(jié)前的數(shù)字等。其中multipart的部分有些小bug但還可以忍受，但是默認(rèn)關(guān)閉的目錄數(shù)字則需要通過以下的配置給設(shè)置回來(lái)。在book.json文件中：

{
   "gitbook": ">=3.1.0",
   "pluginsConfig": {
      "theme-default": {
         "showLevel": true
      }
   }
}

簡(jiǎn)單地運(yùn)行命令gitbook build即可生成站點(diǎn)目錄。最后的構(gòu)建腳本Jenkinsfile.groovy如下所示：

node ("main") {
    stage "Pull latest changes from SCM"
    git([
        url: "[email protected]:linesh-simplicity/translation-spring-mvc-4-documentation.git",
        branch: "master"
    ])

    stage "Download dependencies: Gitbook/Gitbook-cli/Qiniu"
    sh "npm install"

    stage "Build book serving directory through Gitbook"
    sh "gitbook build --gitbook=3.1.1"

    stage "Upload production _book to Qiniu through their API"
    sh "./jenkins/sync-book-to-qiniu.sh"
}

使用七牛的命令行工具進(jìn)行文件上傳，需要配置一些東西，主要是要同步的本地目錄、七牛的Access key和Secret Key等，示例代碼則可以從七牛SDK的官網(wǎng)上參考。我最后完成的這份同步腳本sync-book-to-qiniu.js如下所示，其中完成了 準(zhǔn)備本地同步目錄 、 排除不同步文件 、 指定覆蓋上傳策略等工作：

const qiniu  = require("qiniu");
const glob   = require("glob");
const crypto = require("crypto-js")

const ignoredFiles = [
    "Jenkinsfile.groovy",
    "sync-book-to-qiniu.js",
    "sync-book-to-qiniu.sh",
    "mvc-origin.md",
    "package.json"
];

// node ./jenkins/sync-book-to-qiniu.js $ACCESS_KEY $SECRET_KEY
let qiniuAccessKey = process.argv.slice(2, 3);
let qiniuSecretKey = process.argv.slice(3);

// Prepare Qiniu configuration options
qiniu.conf.ACCESS_KEY = qiniuAccessKey.toString(crypto.enc.Utf8);
qiniu.conf.SECRET_KEY = qiniuSecretKey.toString(crypto.enc.Utf8);
bucket = "mvc-linesh-tw";

glob.sync("_book/**/*.*", {}).filter(filename => {
    for (let ignored of ignoredFiles) {
        if (filename.endsWith(ignored)) return false;
    }
    return true;
}).forEach(filepath => {
    const resource_key_in_qiniu_api = filepath.substring("_book/".length, filepath.length);
    // ":" means allow override upload. For further details refer to offical API docs
    const policyToken = new qiniu.rs.PutPolicy(bucket + ":" + resource_key_in_qiniu_api).token();
    uploadFile(policyToken, resource_key_in_qiniu_api, filepath)
})

function uploadFile(uptoken, key, localFile) {
    let extra = new qiniu.io.PutExtra();
    qiniu.io.putFile(uptoken, key, localFile, extra, function(error, response) {
        if(!error) {
            console.log("[Success] File uploaded: " + response.key);
        } else {
            console.log(error);
        }
    });
}

同行們求review代碼啊～

AK(Access Key)和SK(Secret Key)是七牛分配給注冊(cè)開發(fā)者的一對(duì)密鑰，不能泄露，否則其他人得到了就可以對(duì)你的七牛空間進(jìn)行任意操作。但是，你要把構(gòu)建工作自動(dòng)化，就必須這段腳本提交到github上，同時(shí)CI還要能從你的代碼中讀出正確的AK和SK，這要如何做到呢？回答是，通過CI提供的接口，由pipeline將參數(shù)注入到你的代碼中。這樣，AK和SK就被保存在了pipeline上，別人無(wú)權(quán)對(duì)其進(jìn)行訪問。在Jenkins CI上，這是通過一個(gè)EnvInject插件來(lái)做到的，在travis-ci中則更加簡(jiǎn)單，直接設(shè)置。

呼呼，最后看到這個(gè)圖的時(shí)候還是很激動(dòng)的，所有的部署工作都成功了。那么也是時(shí)候結(jié)束了，本篇文章總結(jié)起來(lái)，先是提到如何準(zhǔn)備和搭建讓翻譯工作更加專注和高效的環(huán)境和工具，如markdown/atom/gitbook/git/github等，然后講到如何使用github的issue和zenhub來(lái)輔助管理翻譯項(xiàng)目中的待辦事項(xiàng)和協(xié)作，最后一節(jié)講述了如何使用CI工具將整個(gè)站點(diǎn)的構(gòu)建和發(fā)布自動(dòng)化，提高翻譯和部署效率。任何有疑問或說錯(cuò)的地方，也請(qǐng)各位給我指出。

—— 2016-07-01