web産品維護說明書編寫

最近一直在做web産品的運維,其中重要的一步就是項目或功能的上線釋出,這個過程需要研發,測試和運維的通力合作。産品編碼完成并經測試通過以後,研發提供項目的維護說明書,運維人員根據維護說明書在生産環境中完成産品或功能的上線釋出。維護說明書的好壞直接關系到上線過程是否能夠順利完成，經曆了幾個産品的上線過程,和研發測試人員的不斷溝通,對維護說明書的書寫有了一些思路, 一份比較好的維護說明書大緻需要包括以下幾個部分:

一.軟體包和第三方軟體

軟體包指研發coding的成果,這個當然是必須的。第三方軟體指産品中使用到的開源或其他現成的軟體,如MySQL, Apache etc。

a) 産品中用到的第三方軟體一定要說明版本号，需要使用到高版本軟體的特性，需要在維護說明書中指出，并給出軟體版本及具體的編譯參數。

b) 為了後續性能調優的友善，生産環境中不會使用LAMP的內建環境，是以維護說明書中也不要使用這種內建環境。

c) 同一産品中不同的子項目可能由不同的項目組并行開發,為保證産品內建友善,上線後不出或少出問題, 不同的子項目應使用相同版本的第三方軟體，如有子項目需要使用高版本的特性則這些子項目統一使用高版本的軟體。研發負責人應該在詳細設計評審時明确各軟體使用的版本，以友善測試和生産環境準備。

d) 對于第三方軟體的安裝，如果有比較特殊的設定，需要在維護說明書中寫明。

e) 産品中需要的各個子項目軟體包須在維護說明書中寫明具體的版本号,以友善進行版本控制。

f) 産品上線以後，運維組需要将維護說明書中軟硬體依賴關系表補充完整，将所有用到的軟硬體版本記錄在維護說明書中。以友善後續查詢。

二．産品部署及相關配置

1. 資料庫資訊

1) 對于上線的新産品，研發統一給出sql格式的檔案，并以”版本号+資料庫名.sql”的形式命名。為部署友善，盡量不要在維護說明書中出現建庫建表的sql語句。

2) 對于線上産品的更新帶來的資料庫變動，運維組支援2種更新方式：

a) 研發提供新資料庫結構，給出sql格式的檔案，并以”版本号+資料庫名.sql”的形式命名。運維組協助研發制定資料遷移方案，并負責實施，資料遷移完成後，由測試組測試資料遷移後資料的完整性和可用性（當資料量達到一定規模後，将強制采用這種方案）。

b) 在産品使用者不是特别多的情況下，研發提供資料庫變更腳本（sql檔案），以“老版本号+新版本号+資料庫名+update.sql”命名，直接在生産系統中修改資料庫。維護說明書中不要再出現alter等修改資料庫的語句，不要隻在維護說明書中寫哪個表增加哪個字段等說明。

2. 配置檔案修改

1) 維護說明說中須指明所有必要的配置項及修改方法，如資料庫連接配接、資料目錄指定等。

2) 相關的配置參數要有解釋說明，例如：

./conf/ftp.conf裡的配置項：

server_home: 伺服器環境變量路徑 示例： server_home=/opt/htdocs/home

server_port: 伺服器端口号 示例：server_port=80

對于不能修改的配置參數（雖然寫在配置檔案中，但在程式中依然用到了絕對路徑的某些配置項），需要在維護說明書中明确指出。涉及到通路控制的參數，如資料庫密碼，伺服器密碼，網站管理者密碼等，運維組在上線完成後将全部修改，以保證所有對系統的通路都經過授權。

3) 關于異地部署，運維組應當盡可能保證不同地點生産環境的一緻性，以利于産品部署及自動化流程的開發，對于部署環境中的不同之處，運維組需要在上線報告中明确指出，并在部署過程中盡快統一不一緻的地方。

3.系統安全性

1) 運維組須保證所有新上線的産品均不用root帳号運作，如有特殊需求，研發需要在維護說明書中指出。産品上線完成以後，運維負責人須修改生産系統中伺服器，資料庫的帳号密碼，避免非授權的通路。

2) 生産系統開啟防火牆規則，預設禁止所有端口通路，維護說明書中需要明确開放哪些端口，原則上采用最少端口原則，不會開放全部端口。

三. 備份

1) 新系統上線前，産品經理和研發需要在維護說明書中明确産品中哪些需要備份，包括項目，資料庫，重要的使用者資料等，同時需要明确備份周期（即一旦發生資料丢失可以接受的最大值）。運維組根據産品經理的要求制定相應的備份政策和恢複方案，必要時請測試組進行資料恢複測試。

2) 原有系統更新時，産品經理和研發需要在維護說明書中明确現有版本中哪些資料需要保留，運維組會在系統更新完成後，checklist前恢複需要保留的資料。

四．系統復原方案

系統更新前，研發需要在維護說明書中提供必要的系統復原方案，以便于在系統更新失敗後能夠很快復原到上一個可用版本。

運維組需要協助研發制定和完善系統復原方案，并保證該方案能夠成功執行，必要時請測試組進行復原方案的測試。

五．監控點說明

對于系統中重要的監控點，研發應該在維護說明書中指出；對于系統内部流程的監控，研發需要給出監控方案；運維組需要協助研發完善監控方案，并負責實施産品監控。

六．CheckList

研發和測試需要提供系統上線後的checklist，以保證系統上線完成以後運維組能夠對系統進行自檢，保證系統正常運作。Checklist應該能夠覆寫産品中所有的關鍵點，必要時在checklist結束以後請測試組對生産系統進行回歸測試。

對系統中出現的所有需要身份認證的角色，産品經理和研發需要在維護說明書中提供建立測試帳号的方法（也可以同時提供測試帳号）；所有checklist執行完畢，測試組回歸測試結束後，運維組須清理所有測試帳号，以保證上線後的系統不被非法通路。

運維組在執行完checklist後需要将checklist表補充完整，填寫各項的檢查人和時間。

下表是checklist的示例：

檢查項

正确結果

備注

檢查人

時間

使用者登入

正常登入系統

使用普通使用者帳号

xxx

x年x月x日

七．上線報告

運維組在産品上線或更新的過程中，可以根據實際操作修改維護說明書，添加必要的注釋等，并在上線或更新完成後做為上線報告送出。因為上線報告中包括了資料庫密碼等生産系統的通路控制資訊，是以上線報告由運維負責人存檔，隻有運維負責人和負責該項目的運維人員可以查閱。

以上是在前面一些項目過程中的總結，還需要在後面的項目中和研發測試人員不斷溝通，不斷完善。項目上線過程及營運初期，運維離不開研發人員的協助，因為隻有研發才最了解自己的産品，運維需要在這段時間裡向研發人員學習，盡快熟悉自己正在運維的産品。