https://gitee.com/sleepywang1024/easyconfig/blob/master/user-guide.md?
easyconfig用戶操作指南
面向研發(fā)團(tuán)隊(包括產(chǎn)品)配參日常維護(hù)及管理工作，介紹easyconfig管理控制臺的操作指導(dǎo)。如果你還在做系統(tǒng)的開發(fā)建設(shè)，請移駕quickstart、開發(fā)指南，如果你在早期設(shè)計階段，請移駕設(shè)計指南。
easyconfig的管理控制臺的默認(rèn)地址為**/easyconfig-admin/home.html** ，如果重新配置了這個地址，請通過修改后的地址訪問。
easyconfig開啟內(nèi)置安全控制機制，需要登陸才能訪問。首次訪問**/easyconfig-admin/home.html** 時看到不是首頁，而是登陸頁面，如下所示：
easyconfig內(nèi)置的默認(rèn)賬號是easy，密碼為config。安全考慮，easyconfig用戶需要及時修改此賬號密碼，或者刪除此賬號。詳細(xì)操作請參考用戶及安全管理。
錄入用戶名、密碼，點擊【登錄】，easyconfig驗證成功后，就可以進(jìn)入easyconfig首頁了，如下示意：
【首頁】是easyconfig的門戶，通常情況所有用戶操作都在這里進(jìn)行，或者由這里導(dǎo)航到相應(yīng)功能頁面。
easyconfig是系統(tǒng)參數(shù)的倉庫和庫管員。要讓它行使管理職責(zé)，并不需要你把貨物拉過來，easyconfig會自己去拉。
對于系統(tǒng)代碼中已經(jīng)定義的配參，easyconfig能自動檢測并展示給出來，供用戶選擇及導(dǎo)入。而不需要通過線下手段復(fù)制粘貼——繁瑣且容易出錯。
【首頁】-> 【配參工具】 -> 【查看并裝載】
操作界面如下圖所示。展示所有通過@Value、@EasyValue、@ValueEx標(biāo)注，但并沒有納入到easyconfig管理和更新的配參，都會展示出來。
選中并執(zhí)行導(dǎo)入，立即生效。
如果不想導(dǎo)入所有，過濾框輔助定位你要導(dǎo)入的內(nèi)容。
表格列說明
操作選中為待導(dǎo)入項
配參代碼屬性代碼，程序引用配參項使用
推導(dǎo)名稱來自@EasyValue 和 @ValueEx的name屬性，沒有name屬性，則為配參代碼
當(dāng)前數(shù)值Bean對象中相應(yīng)屬性的當(dāng)前數(shù)值
推導(dǎo)格式基于Bean對象中相應(yīng)屬性，推導(dǎo)的配參數(shù)據(jù)類型、對象屬性等
被適用于當(dāng)前配參在什么地方被使用了
easyconfig會嘗試推導(dǎo)出配參的數(shù)據(jù)類型和格式，如果是Bean對象，會推導(dǎo)其屬性以及各個屬性的類型等。這些都會與代碼、名稱、數(shù)值一起導(dǎo)入進(jìn)來，給配參的管理帶來很多便利。
推導(dǎo)的類型和格式還不盡完善，對配參的管理已經(jīng)有很大幫助，歡迎研發(fā)同學(xué)在推導(dǎo)的基礎(chǔ)上進(jìn)一步完善，詳情參見配參設(shè)置與校驗。
配參維護(hù)和實時更新都是配參管理的核心功能，其它功能圍繞這個核心的展開的。
【首頁】-> 【編輯】（【操作列】的編輯按鈕）
【首頁】-> 鼠標(biāo)雙擊【配參數(shù)值】 單元格
【首頁】 -> 【設(shè)置】 （【操作列】的設(shè)置按鈕）
表格列說明
配參代碼配參屬性的代碼，供程序使用、不能修改、自動增序排列
配參名稱配參屬性的名稱，供人閱讀、使用，可修改
配參數(shù)值配參對應(yīng)的內(nèi)容，雙擊可就地編輯。內(nèi)容過多時截斷展示，懸浮框展示全部。
最后修改配參最后的修改人和 修改時間
操作針對當(dāng)前配參行的操作：修改、設(shè)置、歷史、探查及刪除。歷史?提供恢復(fù)功能。
通過鼠標(biāo)雙擊配參項的配參數(shù)值單元格，可以直接對配參進(jìn)行修改。
點擊【操作列】的編輯按鈕具有與雙擊配參數(shù)值同樣效果。
通過配參設(shè)置功能可以設(shè)計配參數(shù)值、加解密、以及配參名稱、類型、結(jié)構(gòu)、各類約束，管理屬性如必需、只讀等。特別適合于對復(fù)雜數(shù)據(jù)類型配參的維護(hù)，以及用于特殊管理要求的配參維護(hù)。
無論是快捷編輯，還是通過設(shè)置編輯，都是在客戶端進(jìn)行，不會立即生效。生效需要點擊執(zhí)行**【保存配參】**操作。
【首頁】提供配參項過濾查找功能（左側(cè)上部）。輸入查找內(nèi)容時，配參列表實時基于輸入進(jìn)行過濾。
過濾內(nèi)容包括：代碼、名稱、數(shù)值。
變更歷史及恢復(fù)功能通過記錄修改歷史、以及基于修改記錄恢復(fù)配參，承擔(dān)了以下管理職責(zé)：
問題盤查
合規(guī)審計
錯誤快速恢復(fù)
版本快速切換
【主頁】 -> 【配參管理】 -> 【管理變更】 -> 【整體回滾】 、 【批次回滾】 、 【批次修復(fù)】
【主頁]】-> 【歷史】(操作列)
單一配參記錄的恢復(fù)操作在主界面的**【歷史】對話框中，恢復(fù)操作后，需要保存配參**方能生效。
主要的變更歷史記錄管理和恢復(fù)操作存在于**【管理變更】**頁面。如下圖所示：
表格列說明
#變更ID，遞增，倒序（降序）排列
變更匯總此次變更修改的配參數(shù)量、以及變更的說明信息等
變更內(nèi)容此次變更的詳細(xì)記錄。包括代碼、變更動作、修改前后的數(shù)值、明文/密文、以及修改前的名稱、約束等內(nèi)容。
變更觸發(fā)變更由誰在什么時間發(fā)起
操作【整體回滾】 、 【批次回滾】 、 【批次恢復(fù)】
變更詳情的執(zhí)行次序是由上至下。當(dāng)執(zhí)行變更恢復(fù)操縱時，系統(tǒng)執(zhí)行依次執(zhí)行逆向的反操作：改回原來的狀態(tài)。當(dāng)一個變更發(fā)生后又連續(xù)發(fā)生多次變更的情況下，恢復(fù)到當(dāng)前變更時就會出現(xiàn)針對一個配參多次改回的情況，詳細(xì)記錄依次的修改。這種設(shè)計會適度增大日志數(shù)據(jù)，但不影響最終結(jié)果。
動作標(biāo)識動作說明
createdeasyconfig中新建配參項，由沒有納入管理到納入管理
updated配參項的數(shù)值被修改
setup配參項被修改，包括數(shù)值、名稱、密文/明文、約束等等
deleted配參項被從easyconfig中移除，不再接受其管理
針對一次配參變更的恢復(fù)支持兩種情況：
【批次回滾】 ：把此次變更所涉及的配參，恢復(fù)到此次變更之前的內(nèi)容(此次結(jié)果錯誤，需修復(fù))。
【批次恢復(fù)】：把此次變更所涉及的配參，恢復(fù)到此次變更之后的內(nèi)容(此次結(jié)果正確，需保留)
把所有配參作為一個整體進(jìn)行管理維護(hù)。
【整體回滾】：從最新(最后)一次變更開始，所有內(nèi)容逆向依次恢復(fù)到當(dāng)前變更之前(此次修改被恢復(fù))。
配參、屬性、變量這些都是技術(shù)術(shù)語，可用于任意系統(tǒng)和模塊。研發(fā)的實際情況也是如此，只要是一個系統(tǒng)的，無論屬于那個模塊，混雜在一起管理。如果配參很多，就變得混亂和不便。
配參分組管理是針對上述問題的解決方案，歸屬于統(tǒng)一模塊的配參放到一起單獨管理，與其它配參分開。
分組管理?的基本方式是把相同配參代碼前綴的配參歸屬到一起管理，【管理分組】就是維護(hù)分組代碼前綴與分組名稱的對照表，對于沒有定義分組的配參，統(tǒng)一歸屬到【主頁】的默認(rèn)分組中。
【首頁】->【配參管理】 -> 【管理分組】
分組維護(hù)界面如下圖所示，包括分組的創(chuàng)建、修改、刪除。
配參可以在多種環(huán)境下配置，除了常見的配置properties、yml文件外，還有命令行參數(shù)、操作系統(tǒng)環(huán)境變量、配置中心等等。另外，一個配參可以在多處、以多種方式被使用。
配參詳情探查?告訴用戶配參都在什么地方被配置、配置的數(shù)值是什么、以及當(dāng)前的生效數(shù)值是什么。還有配參都在什么地方被使用，使用此配參的對象的相應(yīng)屬性值是什么。通常都會與配參相同，但由于組合表達(dá)式的存在、默認(rèn)值的存在、以及可能的處理異常，也會存在不一致的情況。
總之，配參詳情探查幫助用戶洞悉配參定義?和?使用，發(fā)現(xiàn)問題及不一致，以及評估配參變更對系統(tǒng)的影響。例如easyconfig刪除動態(tài)配參，系統(tǒng)并不會保持當(dāng)前數(shù)值不變、也不是設(shè)置為null或0，而是會導(dǎo)致前一個低優(yōu)先級配置生效。
【首頁】 -> 【探查及刪除】 （【操作列】的探查及刪除按鈕）
【首頁】->【配參工具】 -> 【探查工具】
針對已經(jīng)納入管理的配參，通過【主頁】面【操作列】的探查及刪除按鈕就可以進(jìn)行，如下圖示意：
針對還沒有納入管理的配參，例如其它模塊引用、未使用@Value等標(biāo)注引用等，可以手工輸入配參代碼進(jìn)行探查。如下圖示意：
數(shù)據(jù)項說明
數(shù)值配參在數(shù)據(jù)源中的數(shù)值。
來源配參來源的數(shù)據(jù)源的名稱，通常是一些屬性文件，?easyconfig_dynamic_property_source就是easyconfig自己。
實現(xiàn)配參裝載到系統(tǒng)中的實現(xiàn)類。
數(shù)據(jù)項說明
beanName配參所在對象在Spring中的Bean Name
toString()配參所在對象toString()訪問返回值
class配參所在對象的定義類
lib配參所在對象定義類所存放的目錄或jar包
數(shù)值配參被引用的屬性的當(dāng)前數(shù)值
標(biāo)注配參被引用的屬性的標(biāo)注聲明
聲明配參被引用的屬性的定義聲明
已經(jīng)納入easyconfig管理的配參，可以通過執(zhí)行**【刪除此配參項】**刪除。刪除后次一優(yōu)先級的定義生效。
應(yīng)用系統(tǒng)的行為除了受研發(fā)人員定義的配參，還有受到操作系統(tǒng)環(huán)境變量，JAVA運行時變量，以及指定的profiles文件等影響。環(huán)境變量查看為用戶提供這些信息的查看。
通過動態(tài)配參設(shè)置，也能對這類變量的數(shù)值進(jìn)行覆蓋，但要慎之又慎，動態(tài)配參的設(shè)置目的是研發(fā)人員創(chuàng)建的配參。
【首頁】->【輔助功能】 -> 【環(huán)境變量】
Profiles。應(yīng)用系統(tǒng)的active和default的profiles信息。
System Environment。操作系統(tǒng)的環(huán)境變量信息。
System Properties。Java相關(guān)的環(huán)境信息。
把一個系統(tǒng)環(huán)境下的全部和部分配參，遷移到另一個環(huán)境中，easyconfig為此提供了導(dǎo)出和導(dǎo)入工具。
【首頁】->【配參工具】 -> 【導(dǎo)出】
【首頁】->【配參工具】 -> 【導(dǎo)入】
【導(dǎo)出】當(dāng)前頁面的所有配參定義，包括代碼、名稱、數(shù)值、約束等。
注：【主頁】面上的配參項過濾查找功能，會作用于【導(dǎo)出】功能。也就是只導(dǎo)出當(dāng)前頁面展示的配參。
導(dǎo)入的操作界面如下圖所示，導(dǎo)入操作過程如下：
選取配參文件，配參文件必須是easyconfig導(dǎo)出的json格式。
指定更新范圍（可選）。導(dǎo)入只更新部分內(nèi)容，名稱、數(shù)值、約束復(fù)選，默認(rèn)為選中為數(shù)值。
過濾待導(dǎo)記錄（可選）。只導(dǎo)入部分配參項，可以通過界面環(huán)境下拉框、過濾框進(jìn)行過濾定位。
選中導(dǎo)入記錄（可選）。只導(dǎo)入部分配參項，通過選中/取消精確指定要導(dǎo)入的配參項。
指定導(dǎo)入的環(huán)境。
執(zhí)行**【導(dǎo)入配參(保存后生效)】**。用導(dǎo)入數(shù)據(jù)更新【主頁】相應(yīng)配參的相應(yīng)內(nèi)容。
保存配參（【主頁】）到配參數(shù)據(jù)源。導(dǎo)入操作不是立即生效，行為類似于編輯，需要保存配參方能生效。
針對敏感信息，easyconfig支持已加密的形式保存在數(shù)據(jù)源，無論研發(fā)人員還是運維人員看到的都是密文。 盡管數(shù)據(jù)源存儲的是密文，但應(yīng)用系統(tǒng)接收到的仍然是明文，否則就無法基于這些配參做事情了。
【首頁】 -> 【設(shè)置】 （【操作列】的設(shè)置按鈕） -> 【配參數(shù)值】
【首頁】 -> 【配參工具】 -> 【加解密工具】
在**【設(shè)置】功能的【配參數(shù)值】頁簽，可以對配參進(jìn)行加解密，只需要選中或取消選中【密文形式保存】** 復(fù)選框，然后【確認(rèn)】及【保存配參】即可。如下圖示意所示：
對于一些關(guān)鍵如基礎(chǔ)的數(shù)據(jù)庫連接、用戶密碼之類，且需要第一時間加載的配參，需要easyconfig工作之前生效，前述方法就不可以了。例如easyconfig動態(tài)配參數(shù)據(jù)源的連接用戶密碼，可以使用脫機方式設(shè)置密文。
使用獨立的**【加解密工具】**獲得密文，然后配置到屬性文件中。具體方式是屬性文件中放置密文，同時把加密屬性的代碼登記到easyconfig.cipher-keys屬性下(不同加密項的代碼逗號分割)。
加解密工具的界面如下圖所示：
加解密工具?需要在easyconfig服務(wù)已經(jīng)工作的情況下才能使用，有時候未必方便。還有另外一個更簡單的方式，使用java命令行操作，只需要具有easyconfig的jar包即可。如下加解密示意：
java-jar.\easyconfig-core-0.7.0.jar-encrypthelloworld-saltmyappOX6wN3jBTdn+a2VNEuYbiQ==java-jar.\easyconfig-core-0.7.0.jar-decryptOX6wN3jBTdn+a2VNEuYbiQ==-saltmyapphelloworld
注意：
后面這兩種加解密方式，是供開發(fā)人員研發(fā)階段使用，并且需要配合easyconfig.cipher-keys屬性一起使用，用于哪些需要在easyconfig完成啟動之前就需要加解密的參數(shù)。
普通的配參加解密使用第一種方式即可，方便簡單。
配參聯(lián)機修改、實時生效，會帶來更多修改需求，以及更多人的參與，這會導(dǎo)致更多出錯機會。詳盡的約束定義和修改校驗?zāi)艽蠓容^少出錯概率。
通過管理控制臺編輯配參數(shù)值，就會得到相應(yīng)的校驗檢查，通不過校驗則無法保存。
正常情況下，校驗規(guī)則設(shè)置和配參數(shù)值編輯歸屬于不同階段的不同工作，校驗規(guī)則設(shè)置屬于研發(fā)階段的一次性工作，而配參數(shù)值的修改屬于測試、運維階段的日常工作。
約束設(shè)置：【首頁】 -> 【設(shè)置】 （【操作列】的設(shè)置按鈕）
支持六種數(shù)據(jù)類型，如下圖所示：
類型說明：
類型說明
string文本類型，可進(jìn)一步約束模式、長度、枚舉
boolean布爾類型，true、false取其一
integer整數(shù)，可進(jìn)一步約束范圍
number數(shù)字，可進(jìn)一步約束范圍
array數(shù)組，可約束元素數(shù)量、元素類型以及針對元素的約束
object對象，可約束屬性清單、屬性是否必需，以及針對屬性的進(jìn)一步約束
最大做小長度
文本模式，內(nèi)置常用模式以及正則表達(dá)式
合法候選枚舉值，以[,]號分割的文本選項。
### 配參默認(rèn)值
表示此配參通常情況下的傾向數(shù)值，輔助配參數(shù)值的設(shè)置和恢復(fù)。默認(rèn)值并不能強制約束配參沒有被easyconfig設(shè)置時，系統(tǒng)采用的默認(rèn)值，依賴于＠Value等標(biāo)注的默認(rèn)值、屬性文件定義、命令行參數(shù)等一系列內(nèi)容。
表示此配參不能為空，必須設(shè)置。
表示此配參不能修改，只能查看。實際中可能是無法動態(tài)修改，修改也無效；也可能只是比較關(guān)鍵，防止誤操作。
提供描述說明信息以便指導(dǎo)用戶，并不作為校驗檢查內(nèi)容。
easyconfig提供或編輯完善的JSON Schema規(guī)則的能力（如下圖示意），系統(tǒng)會根據(jù)JSON Schema規(guī)則做校驗檢查。有關(guān)JSON Schema的能力和規(guī)范，請參考JSON Schema官方文檔?。
注：
通過easyconfig已有配參裝載加載進(jìn)來的配參，數(shù)據(jù)類型已經(jīng)基于程序中的屬性類型進(jìn)行了推導(dǎo)，滿足許多用戶的基本需要，簡化設(shè)置工作。
配參可以先進(jìn)行修改但不生效，經(jīng)過確認(rèn)、審批、或者特定情景滿足后(例如1月1日0點)再生效。
easyconfig提供修改保存、修改發(fā)布獨立操作的能力，并配合權(quán)限控制，很好地滿足以上需求。
【首頁】 -> 【保存-等待發(fā)布】
【首頁】 -> 【配參管理】->【管理變更】 ->【變更發(fā)布】、【灰度發(fā)布】、【變更撤銷】
配參修改完成后，可以逐步逐節(jié)點進(jìn)行生效，以便能
配參修改在生產(chǎn)環(huán)境中測試；
逐步、平穩(wěn)地配參切換；
發(fā)現(xiàn)發(fā)布問題及時終止發(fā)布；
【首頁】 -> 【保存-灰度發(fā)布】
或者
【首頁】 -> 【保存-等待發(fā)布】，然后在【首頁】 -> 【配參管理】->【管理變更】 ->【灰度發(fā)布】
選擇灰度發(fā)布后，需要指定要發(fā)布的應(yīng)用節(jié)點，確認(rèn)進(jìn)行發(fā)布后，相關(guān)節(jié)點配參生效。
在全部節(jié)點發(fā)布生效完成之前，可以分多次進(jìn)行，也可以提前終止。
注：終止通常意味著回滾，否則終止也并不意味著相關(guān)節(jié)點永遠(yuǎn)不別更新，當(dāng)節(jié)點重啟時，沒有回滾的內(nèi)容仍然會被更新。
與springboot類似，easyconfig對多profiles提供支持，且更簡便和強大。通過管理控制臺，可以動態(tài)地維護(hù)各個profile的配參信息。
【首頁】 -> 【環(huán)境:${profile}】
【首頁】 -> 【環(huán)境:管理環(huán)境...】
在管理控制臺，可以切換當(dāng)前管理的環(huán)境，以及對當(dāng)前換環(huán)境配參的管理，如下所示。
在管理控制臺，可以對應(yīng)用系統(tǒng)使用的環(huán)境進(jìn)行配置，如下所示。
環(huán)境配置可以對環(huán)境增刪改，但只是方便管理，應(yīng)用系統(tǒng)節(jié)點啟用哪些環(huán)境，并不由此決定。應(yīng)用系統(tǒng)啟動時，通過配參easyconfig.profiles.active指定所啟動實例生效哪些環(huán)境。
easyconfig提供了靈活的機制，獨立或與宿主應(yīng)用系統(tǒng)一起管理用戶和控制安全。
easyconfig提供四種安全控制方式：none、self、host、mixture，詳細(xì)信息在developer-guide中介紹，此處主要介紹內(nèi)置安全模式的操作，即：
easyconfig.security.mode=self
【首頁】 -> 【輔助功能】 -> 【管理用戶】
用戶管理提供對用戶的創(chuàng)建(授權(quán))和刪除。對于不再允許使用系統(tǒng)的用戶，需要進(jìn)行刪除。管理用戶如下圖所示：
新建用戶需要提供用戶名(登錄名稱)、用戶密碼等， 如下圖示意：
針對每一位用戶，easyconfig提供功能和數(shù)據(jù)權(quán)限控制，以滿足不同的需要。
功能支持四種權(quán)限：查看、變更、發(fā)布、管理，數(shù)據(jù)權(quán)限針對每一條每一組配參進(jìn)行，支持三種權(quán)限：查看、變更、發(fā)布。各種權(quán)限語義如下：
查看：查看配參；
變更：對配參進(jìn)行修改（不包括發(fā)布生效）；
發(fā)布：對修改的配參進(jìn)行發(fā)布（修改相關(guān)節(jié)點中Spring中的Bean的屬性）；
管理：管理用戶、權(quán)限；
訪問地址在【首頁】 -> {用戶菜單}(首頁右上角用戶名稱下拉菜單 -> 【退出登錄】。
點擊則立即退出，返回到登陸頁面。
開啟安全控制但沒有登陸會自動展示登陸頁面。輸入用戶名、密碼正確后可進(jìn)行登陸。記住我功能默認(rèn)有效期為30天。
訪問地址在【首頁】 -> {用戶菜單}(首頁右上角用戶名稱下拉菜單 -> 【修改密碼】
訪問地址在【首頁】 -> {用戶菜單}(首頁右上角用戶名稱下拉菜單 -> 【切換用戶】
點擊則轉(zhuǎn)到登陸頁面，此時還沒有退出，還可以重新返回主頁面。
