elasticsearch文檔-modules

modules == 模塊 cluster == [原文](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-cluster.html) 基本概念 === cluster: 集群，一個集群通常由很多節點(node)組成 node: 節點，比如集群中的每台機器可以看做一個node shard: 分片，ES是分布式搜索引擎，會把數據拆分成很多個shard，一個索引默認有5個shard replica: 副本，ES是high availability的， 為了數據安全會把同一份數據存放在多個節點，默認情況下一個索引的數據會存兩份副本。一份是primary，一份是replica。 primary: 主節點 rebalancing: 指數據在集群的節點中重新分配，比如當集群中增加或者移除節點時就會發生rebalancing Shards allocation === Shards allocation是指在各個節點分配shard的過程。 在初始化恢復, 分配replica, rebalancing, 新增或移除節點時會發生。 一些基本配置如下 `cluster.routing.allocation.allow_rebalance` 根據集群中節點的狀態來控制什么時候可以rebalancing， 可以設置三種方式。 * `indices_primaries_active`: 僅當所有的primary shards是active的時候才允許rebalancing。 * `indices_all_active`: 僅當所有的shards是active的時候才允許rebalancing。 * `always`: 一組shard、replication是active時就可以rebalancing。 默認值為`indices_all_active`，可以減少cluster初始化恢復時各節點之間的交互。 `cluster.routing.allocation.cluster_concurrent_rebalance` 設置在cluster中最多可以允許幾個rebalancing同時進行，默認為2, 如果設置為-1則意味着不做限制。 `cluster.routing.allocation.node_initial_primaries_recoveries` 限制每個節點可以同時初始化恢復primary shard數量。 這個設置是為了防止同時進行的recovery進程太多影響節點負載，因為大多數情況下用的是local gateway，速度相當快，所以可以同時執行多個recovery進程而不會造成太多的負荷，默認是4。 `cluster.routing.allocation.node_concurrent_recoveries` 限制每個節點並行recovery的數量， 默認是2。 `cluster.routing.allocation.disable_new_allocation` 設置是否禁止分配新的新的primary shard，注意, 設置為true會阻止新建的索引的shard分配。 因為如果primary不存在，replica會自動提升為primary， 所以這個配置通過更新cluster配置的API動態更新才有意義。 `cluster.routing.allocation.disable_allocation` 是否禁止分配primary和replica，這個配置通過更新cluster配置的API動態更新才有意義。 `cluster.routing.allocation.disable_replica_allocation` 是否禁止分配replica，和上面的設置類似， 這個配置通過更新cluster配置的API動態更新才有意義。 `indices.recovery.concurrent_streams` 設置在從對應的shard恢復一個shard時，可以同時打開的數據流的數量(節點級別)，默認是3。 Cluster allocation awareness === 分片規則 集群分片規則(Cluster allocation awareness)允許我們用一些參數來配置整個集群中shard和replica的分片規則。 下面通過一個例子來解釋一下。 假設我們有幾個機架，我們給一節點配置一個名為rack_id的屬性(其他名字也可以)， 配置例子如下: node.rack_id: rack_one 上面例子為這個節點配置了一個名為rack_id的屬性， 值為rack_one。 接下來將rack_id配置為分片規則所用的屬性（在所有節點都要設置）。 cluster.routing.allocation.awareness.attributes: rack_id 上面的配置意味着分片規則會基於屬性rack_id來做shard和replica分配。 例如，我們有兩個node.rack_id屬性設置為rack_one的節點, 部署了一個有5個shards和1個replica的索引， 索引數據會分布到這兩個節點上(每個節點有5個shard， 1個replica, 總共10個shards)。 如果我們再加入兩個節點，這兩個節點的node.rack_id屬性設置為rack_two, shard會在這些節點上重新分配， 但是一個shard和他的replica不會分配到有相同rack_id屬性的節點上。 可以為分片規則設置多個屬性， 比如: cluster.routing.allocation.awareness.attributes: rack_id,zone 注意：啟用了分片規則屬性后，如果一個節點沒有配置這些屬性， shard就不會分配到這個節點上。 forced awareness === 強制行分片規則 有時候我們提前知道用來做分片規則的屬性會有更多的值， 我們不希望一些replica被分配到一組特定節點上， 對於這種情況， 我們可以針對這些屬性值用強制分片規則。 例如，我們用屬性zone來做分片規則屬性，並且我們知道會有兩個zone：zone1和zone2。 下面是強制分片規則設置的例子： ``` cluster.routing.allocation.awareness.force.zone.values: zone1,zone2 cluster.routing.allocation.awareness.attributes: zone ``` 現在我們先啟用兩個node.zone屬性設置成zone1的節點，然后創建一個有5個shard和1個replica的索引。 索引建完后只有5個shard（沒有replica），要等到我們再啟用更多屬性node.zone為zone2的節點時，replica才會被分配。 automatic preference when searching / geting === 在執行search或者執行get指令時， 接受請求的節點會優先選擇與其有相同屬性值的節點分片上執行請求。 realtime settings update === 這些設置可以通過更新cluster配置的api在一個運行着的cluster上實時更新。 shard allocation filtering === 可以用include/exclude過濾器控制索引部署到哪些節點上，過濾器可以設置在索引級別，也可以設置在集群級別， 我們先看一下設置在索引級別的例子。 假設我們有四個節點， 每個節點配置了一個名為tag的分片規則屬性(可以是任何名字)，節點1的tag屬性置為value1, 節點2的tag屬性設置為value2，以此類推。 我們可以把配置項`index.routing.allocation.include.tag`設置為value1,value2來使創建的索引只部署到哪些tag屬性為value1和value2的節點上，例如 ``` curl -XPUT localhost:9200/test/_settings -d '{ "index.routing.allocation.include.tag" : "value1,value2" }' ``` 另一方面， 我們將配置項`index.routing.allocation.exclude.tag`設置為value3， 這樣創建的索引會被部署到tag屬性為value3之外的那些節點上，例如 ``` curl -XPUT localhost:9200/test/_settings -d '{ "index.routing.allocation.exclude.tag" : "value3" }' ``` 從0.90版開始， 可以用`index.routing.allocation.require.*`來設置一系列規則， 只有符合全部規則的節點才會分配shard， 相對而言`include`則是只要符合任意一條就可以。 `include`, `exclude`和`require`的值都支持通配符, 例如`value1*`。 一個特殊的節點名是`_ip`，可以用來匹配節點的ip地址. 另外一個特殊屬性`_host`可以用來匹配節點的主機名和ip地址。 上面說過，一個節點可以配置幾個屬性， 例如 ``` node.group1: group1_value1 node.group2: group2_value4 ``` 對應的， `include`, `exclude` 和 `require` 也可以用幾個屬性, 例如 ``` curl -XPUT localhost:9200/test/_settings -d '{ "index.routing.allocation.include.group1" : "xxx" "index.routing.allocation.include.group2" : "yyy", "index.routing.allocation.exclude.group3" : "zzz", "index.routing.allocation.require.group4" : "aaa" }' ``` 這些設置可以用更新配置的api實時更新, 實時移動索引(索引的分片)。 Cluster級別的過濾器可以用更新cluster設置的api來實時定義和更新，這些設置在解除一個節點時很有用(即使replica數量設置為0)。 下面是根據ip地址解除一個節點的例子: ``` curl -XPUT localhost:9200/_cluster/settings -d '{ "transient" : { "cluster.routing.allocation.exclude._ip" : "10.0.0.1" } }' ``` discovery == [原文](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-discovery.html) discovery模塊負責發現集群(cluster)中的節點，以及選舉出主節點。 注意，ES是一個基於端到端(p2p)的系統，節點之間直接通信，所有主要的API(index, search, delete)不需要和主節點(master node)通信。 主節點的職責是維護整個集群的狀態，並且在節點加入或者離開集群時重新分片。 每次集群的狀體改變會通知到集群中的其他節點(方式取決於discovery模塊的具體實現)。 settings === 配置項`cluster.name`用來給集群設置一個名字，以此把一個集群和其他的集群區分開。 默認的集群名是elasticsearch， 不過推薦改為能反映集群用途的有實際意義的名字。 ec2 discovery === EC2 discovery機制使用EC2的API來執行自動發現，用不到，不看了。 zen discovery === Zen發現機制 zen發現機制是ES默認的內置發現模塊。 它提供了多播和單播兩種發現方式，並且能夠很容易的擴展以支持雲環境。 zen發現機制是和其他模塊集成在一起的，比如所有節點之間通訊是用trasport模塊來完成。 Zen發現機制分為幾個子模塊，接下來分別做詳細解釋。 ping === ping是指一個節點用發現機制發現其他節點的過程， 支持多播(multicast)和單播(unicast)兩種方式，也可以組合使用。 multicast === multicast是指發送一個或多個多播請求，存在的節點會接受並且相應請求。 它提供了一組以`discovery.zen.ping.multicast`為前綴的配置項。 | Setting | Description | | --------------|:----------------------------------------------| | group | group地址，默認值為224.2.2.4 | | port | 端口，默認為54328 | | ttl | 多播消息的ttl，默認是3 | | address | 綁定地址，默認為null，即綁定所有可用的network接口。 | unicast === 在多播禁用的情況下可以使用unicast發現方式。 它需要一個主機列表， 它提供了下面以`discovery.zen.ping.unicast`為前綴的配置項。 | Setting | Description | | --------------|:----------------------------------------------------------------------| | hosts | 一個數組或者以逗號分隔的字符串， 每個值的格式為host:port或者host[port1-port2] | unicast發現方式需要借助transport模塊來實現。 master election === 主節點選舉 作為ping初始化過程的一部分， 需要選舉出一個集群的master節點或者加入到一個已經選出的master節點， 這個過程是自動完成。 可以通過配置項`discovery.zen.ping_timeout`來設置ping的超時時間(默認是3s)以應對網絡速度慢或者網絡擁堵的情況。 設置一個比較大的值可以減少失敗的幾率。 節點可以設置屬性`node.master`為false來避免被選舉為master節點。 注意， 如果一個節點被設置為客戶端節點(`node.client`屬性設置為true)， 這個節點不會被選舉為master節點(`node.master`自動設置為false)。 屬性`discovery.zen.minimum_master_nodes`設置一個集群中最少的合格master節點數量， 對於2個節點以上的集群，建議設置為大於1的值。 舉個例子， 假設集群有5個節點， `minimum_master_nodes`設置為3, 如果2個節點掉線了，這兩個節點不會自己組建一個集群， 而是嘗試加入另一個集群。 這個設置可以避免網絡故障時有些節點試圖自行組織集群，從而導致整個集群不穩定。 fault detection === 錯誤檢測 有兩種錯誤檢測方式，一種是master節點ping集群中所有其他的節點來驗證他們是否存活，另一種是每個節點ping master節點來驗證它是否存活，或者是否需要初始化一個選舉。 下面的配置項用於設置錯誤檢測，前綴是`discovery.zen.fd`: | Setting | Description | | ------------------|:----------------------------------| | ping_interval | ping的頻率， 默認1s | | ping_timeout | ping的超時時間， 默認30s | | ping_retries | 如果ping失敗或者超時，重試的次數 | external multicast === 外部多播 multicast 發現機制還支持外部多播請求，外部客戶端可以發送多播請求， 格式為： ``` { "request" : { "cluster_name": "test_cluster" } } ``` 響應格式類似節點信息的響應(只有節點信息，包括transport/http地址以及節點的屬性): ``` { "response" : { "cluster_name" : "test_cluster", "transport_address" : "...", "http_address" : "...", "attributes" : { "..." } } } ``` 注意，可以禁用內部multicast發現機制，只啟用外部多播發現機制。 方式為將`discovery.zen.ping.multicast.enabled`設為true（默認），但是將`discovery.zen.ping.multicast.ping.enabled`設為false。 gateway == [原文](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-gateway.html) gateway模塊存儲集群元數據(meta data)的狀態，集群元數據主要包括索引的配置和聲明的mapping定義。 每次集群元數據發生變化時（比如添加或刪除索引），會通過gateway來持久化這些變化。 集群啟動時會從gateway讀取並且應用這些數據。 設置在節點級別的gateway自動控制索引所用的gateway。 比如節點用`fs` gateway，該節點創建的索引也自動用`fs` gateway。 在這種情況下， 如節點不應該持久化狀態數據， 應該明確設置為`none`(唯一可以設置的值)。 ES默認使用的gateway是local gateway。 recovery after nodes / time === 大多數場景下，集群的元數據只能在特定的節點已經啟動后才能被恢復， 或者等待到超時。 這在集群重啟時非常有用，此時每個節點的本地索引存儲仍然可用，不需要從gateway恢復（能夠減少從gateway恢復的時間）。 `gateway.recover_after_nodes`(數字類型)設置多少個合格的data節點以及master節點啟動后觸發recovery。 `gateway.recover_after_data_nodes` 和`gateway.recover_after_master_nodes`含義類似，只不過分別設置data節點和master節點的數值。 `gateway.recover_after_time`(事件類型)設置在所有的`gateway.recover_after...nodes`條件滿足后，等待多長時間再開始recovery。 `gateway.expected_nodes`設置預期多少個合格的data和master節點啟動后就開始recovery，一旦滿足條件馬上啟動recovery，`recover_after_time`設置會被忽略，對應的也支持`gateway.expected_data_nodes`和`gateway.expected_master_nodes`這兩個配置項。 一個配置的例子如下: ``` gateway: recover_after_nodes: 1 recover_after_time: 5m expected_nodes: 2、 ``` 這個例子配置了在一個預期兩個節點的集群中，在一個節點啟動后的5分鍾后執行recovery，一旦集群中有已經有兩個節點啟動了，立即開始recovery（不等待，忽略recover_after_time）。 注意，一旦元數據從gateway恢復了，那么這個配置就不再有效，直到下次集群完整重啟。 在集群元數據沒有恢復時，為了避免和真實的集群元數據沖突，所有操作都會被阻止。 local gateway === 本地網關 local gateway從每個節點的本地存儲中恢復整個集群狀態和索引數據， 並且不需要節點級別的共享存儲。 注意，和共享類的gateway不同， local gateway的持久化不是異步的，一單一個操作被執行， 數據就會被存儲以備集群恢復時使用。 非常重要的一點是在配置`gateway.recover_after_nodes`時要包括大多數在整個集群重啟后期望啟動的節點， 這可以確保集群恢復到最新的狀態。 例如: ``` gateway: recover_after_nodes: 1 recover_after_time: 5m expected_nodes: 2 ``` 注意，為了能夠備份/快照完整地集群狀態， 建議禁用flush的情況下所有節點的本地存儲都要有副本(理論上不需要所有的，只需要確保每個shard的副本被備份，這依賴replication的設置)。 共享存儲比如S3可以在一個地方保存不同節點的拷貝，盡管代價是帶來了更多的IO。 shared fs gateway === shared FS gateway已經廢棄，以后會被移除， 不看了。 hadoop gateway === hadoop gateway以后會被移除， 不看了。 s3 gateway === s3 gateway以后會被移除， 不看了。 http == [原文](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-http.html) http模塊允許通過http訪問ES的接口。 http是完全異步的，意味着等待響應時不會阻塞線程。 如果有可能， 考慮使用HTTP keep alive來獲得更好的性能，並且http客戶端不要啟用HTTP chunking。 settings === 下面是http模塊的一些設置。 | Setting | Description | | -------------------------- |:--------------------------------------| | http.port | 綁定的端口范圍， 默認9200-9300 | | http.max_content_length | http請求大小的上限， 默認100mb | | http.max_initial_line_length | http url的最大長度， 默認4kb | | http.compression | 是否支持http壓縮， 默認是false | | http.compression_level | http壓縮的級別， 默認是6 | http模塊共享通用的network設置。 disable http === 設置`http.enabled`為false可以禁用http模塊，比如創建非數據節點來接收http請求，這些節點利用內部的transport來和數據節點通信。 indices == [原文](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-indices.html) indices模塊可以對所有索引進行全局管理。 indexing buffer === 索引緩沖的設置可以控制多少內存分配給索引進程。 這是一個全局配置，會應用於一個節點上所有不同的分片上。 `indices.memory.index_buffer_size`接受一個百分比或者一個表示字節大小的值。 默認是10%，意味着分配給節點的總內存的10%用來做索引緩沖的大小。 這個數值被分到不同的分片(shards)上。 如果設置的是百分比，還可以設置`min_index_buffer_size` (默認48mb)和`max_index_buffer_size`（默認沒有上限）。 `indices.memory.min_shard_index_buffer_size`設置分配給每個分片的索引緩沖內存的下限，默認4mb。 ttl interval === 你可以動態設置`indices.ttl.interval`來控制自動刪除過期documents的檢查間隔，默認是60s。 刪除是批量進行的，你可以設置`indices.ttl.bulk_size`來適應你的需要，默認值是10000。 其余的參考_ttl的文檔。 recovery === 以下設置用來管理recovery的策略: | Setting | Description | | ----------------------------------|:----------------------------------| | indices.recovery.concurrent_streams| 默認是3 | | indices.recovery.file_chunk_size | 默認512kb | | indices.recovery.translog_ops | 默認1000 | | indices.recovery.translog_size | 默認512kb | | indices.recovery.compress | 默認true | | indices.recovery.max_bytes_per_sec| 默認20mb | | indices.recovery.max_size_per_sec | 0.90.1去掉，用`indices.recovery.max_bytes_per_sec`代替| 下面的設置對存儲進行限流: | Setting | Description | | ------------------------------------------|:--------------------------------------| | indices.store.throttle.type | 可以是`merge` (默認), `not`或者`all` | | indices.store.throttle.max_bytes_per_sec | 默認20mb | jmx == removed as of v0.90. memcached == [原文](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-memcached.html) memcached模塊可以通過memecached協議來訪問ES的接口。 memcached模塊通過一個名為transport-memcached插件提供，插件的安裝說明見[transport-memcached](https://github.com/elasticsearch/elasticsearch-transport-memcached)，也可以下載memcached插件並放在plugins目錄下。 memcached協議支持二進制和文本兩種協議, 會自動檢測應該用哪一種協議。 mapping rest to memcached protocol Memcached命令會被映射到REST接口，並且會被同樣的REST層處理，下面是支持的memcached命令列表: get memcached的GET命令映射到REST的GET方法。 用URI (帶參數)來做key。 memcached的GET命令不允許在請求中帶body(SET不允許返回結果)， 為此大多數REST接口(比如search)允許接受一個"source"作為URI的參數。 set memcached的SET命令映射為REST的POST。 用URI (帶參數)來做key, body映射為REST的body。 delete memcached的DELETE命令映射為REST的DELETE。 用URI (帶參數)來做key。 quit memcached的QUIT命令用來斷開客戶端鏈接。 settings === 以下設置可以用來配置memcached: | Setting | Description | | --------------------------|:--------------------------------------| | memcached.port | 綁定端口范圍， 默認11211-11311 | 同樣共享通用的network設置。 disable memcached === 設置`memcached.enabled`為false可以禁用memcached模塊， 默認檢測到該插件即啟用memcached模塊。 network settings == [原文](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-network.html) 一個節點的多個模塊都用到了網絡基本配置，例如transport模塊和HTTP模塊。 節點級別的網絡配置可以用來設置所有基於網絡的模塊的通用配置（除了被每個模塊明確覆蓋的那些配置項）。 `network.bind_host`用來設置綁定的ip地址， 默認綁定`anyLocalAddress` (0.0.0.0或者::0)。 `network.publish_host`配置其他節點和本節點通信的地址。 這個當然不能是`anyLocalAddress`, 默認是第一個非回環地址或者本機地址。 `network.host`設置是一個簡化設置， 它自動設置`network.bind_host`和`network.publish_host`為同一個值。 兩個設置都可以配置為主機ip地址或者主機名， 還可以設置為下表中列出來的值。 | Logical Host Setting Value| Description 　　 | | --------------------------|:------------------------------------------| | _local_ | 本機ip地址 | | _non_loopback_ | 第一個非loopback地址 | | _non_loopback:ipv4_ | 第一個非loopback的ipv4地址 | | _non_loopback:ipv6_ | 第一個非loopback的ipv6地址 | | _[networkInterface]_ | 指定網卡的IP地址. 例如 _en0_ | | _[networkInterface]:ipv4_ | 指定網卡的IPv4地址. 例如 _en0:ipv4_ | | _[networkInterface]:ipv6_ | 指定網卡的IPv6地址. 例如 _en0:ipv6_ | | _non_loopback:ipv6_ | 第一個非loopback的ipv6地址 | cloud-aws === 如果安裝了`cloud-aws`插件， 下表列出來值也是有效的設置: | EC2 Host Value | Description | | --------------------------|:----------------------------------------------------------| | _ec2:privateIpv4_ | The private IP address (ipv4) of the machine | | _ec2:privateDns_ | The private host of the machines | | _ec2:publicIpv4_ | The public IP address (ipv4) of the machine | | _ec2:publicDns_ | The public host of the machines | | _ec2_ | Less verbose option for the private ip address | | _ec2:privateIp_ | Less verbose option for the private ip address | | _ec2:publicIp_ | Less verbose option for the public ip address | tcp settings === 任何使用TCP的組件 (比如HTTP, Transport和Memcached)共享下面的設置: | Setting | Description | | --------------------------|:----------------------------------------------| | network.tcp.no_delay | 啟用或禁用tcp no delay。 默認是true. | | network.tcp.keep_alive | 啟用或禁用tcp keep alive。 默認不設置 | | network.tcp.reuse_address| 地址是否應該被重用，在非windows的機器上默認是true | | network.tcp.send_buffer_size| tcp發送緩沖區的大小。 默認不設置 | | network.tcp.receive_buffer_size| tcp接收緩沖區的大小。 默認不設置 | node == [原文](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-node.html) ES可以設置一個節點是否在本地存儲數據，存儲數據意味着不同索引的分片可以分配到這個節點上。 默認每個節點都可以作為數據節點(data node)，可以設置`node.data`為false來關閉。 這是一個很強大的配置， 可以很簡單的來創建一個智能負載均衡。 我們可以啟動一個數據節點的集群而不啟用http模塊， 這可以通過設置`http.enabled`為true做到， 這些節點通過transport模塊相互通信， 在集群的前端可以啟動一個和或者多個啟用了http模塊的非數據節點， 所有的http通訊由這些非數據節點來執行。 這樣做的好處是首先能夠創建一個智能負載均衡器。 這些非數據節點仍然是集群的一部分， 他們將請求重定向到那些有相關數據的節點上。 另一個好處是對於那些scatter/gather操作(比如search), 這些節點可以執行一部分處理， 因為它們啟動scatter處理並且執行實際的gather過程。 這樣數據節點可以專注於索引和查詢這類大負載的工作，而不需要處理http請求， 占用網絡負載，或者執行gather過程。 plugins == [原文](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-plugins.html) Plugins提供了以自定義的方式增強ES基本功能的途徑， 范圍包括添加自定義mapping類型, 自定義分詞, 原生腳本， 自定義discovery等等。 installing plugins === 安裝插件可以手工將插件安裝包放到`plugins`目錄， 也可以用`plugin`腳本來安裝。 在github的[elasticsearch](https://github.com/elasticsearch)能找到好幾個插件， 名字以"elasticsearch-"開頭。 從0.90.2開始， 插件可以通過執行 `plugin --install /<user/component>/`的形式來安裝。 插件會從`download.elasticsearch.org`自動下載, 如果插件不存在的話, 就從maven(central and sonatype)下載。 注意， 如果插件放在maven central或者sonatype的話, ``是`groupId`，`<user/component>`是`artifactId`。 對於以前的版本， 老的安裝方式是 `plugin -install /<user/component>/` 一個插件也可以直接通過指定它的URL來安裝， 例如 `bin/plugin --url file://path/to/plugin --install plugin-name ` 或者對於老版本來說是 `bin/plugin -url file://path/to/plugin -install plugin-name` 從0.90.2開始, 插件的更新信息可以通過運行 `bin/plugin -h`來獲得。 site plugins === 插件可以包含一個站點， 任何位於`plugins`目錄下的插件如果包含一個`_site`目錄， 目錄里的內容就可以當做靜態內容通過`/_plugin/[plugin_name]/url`來訪問，在進程已經開始的情況下也可以向其添加內容。 安裝的插件如果不包含任何java相關的內容， 會被自動檢測為site插件， 內容會被移動到`_site`目錄下。 安裝github托管的插件非常簡單， 比如運行 ``` # From 0.90.2 bin/plugin --install mobz/elasticsearch-head bin/plugin --install lukas-vlcek/bigdesk # From a prior version bin/plugin -install mobz/elasticsearch-head bin/plugin -install lukas-vlcek/bigdesk ``` 會自動安裝這兩個site插件，elasticsearch-head插件可以通過 `http://localhost:9200/_plugin/head/`訪問， bigdesk插件可以通過`http://localhost:9200/_plugin/bigdesk/`訪問。 mandatory plugins === 如果你依賴一些插件， 你可以通過屬性`plugin.mandatory`來定義這些強制性(mandatory)插件， 下面是一個配置的例子: ``` plugin.mandatory: mapper-attachments,lang-groovy ``` 出於安全考慮， 如果mandatory插件沒有安裝， 節點不會啟動。 installed plugins === 當前已加載的插件列表可通過Node Info API獲得。 removing plugins === 要刪除一個插件，可以手工將它從`plugins`目錄移除，也可以用`plugin`腳本。 刪除一個插件通常可以用下面的形式: ``` plugin --remove ``` silent/verbose mode === 運行`plugin`腳本時, 可以加`--verbose`參數獲得更多的信息(調試模式)。 相反的， 如果希望`plugin`腳本靜默與運行可以用`--silent`選項。 注意， 退出碼可能是: ``` 0: everything was OK 64: unknown command or incorrect option parameter 74: IO error 70: other errors bin/plugin --install mobz/elasticsearch-head --verbose plugin --remove head --silent ``` scripting == scripting模塊可以用腳本來執行自定義表達式， 比如可以用腳本將"script fields"作為查詢的一部分返回， 或者用來計算某個查詢的自定義評分等。 腳本模塊默認用擴展過的[mvel](http://mvel.codehaus.org/)作為腳本語言， 之所以用是因為它非常快而且用起來很簡單， 大多數情況下需要的是簡單的表達式(比如數學方程式)。 其他`lang`插件可以提供執行不同語言腳本的能力， 目前支持的腳本插件有javascript的`lang-javascript`，Groovy的`lang-groovy`， Python的`lang-python`。 所有可以用`script`參數的地方可以設置`lang`參數來定義腳本所用的語言。 `lang`的選項可以是`mvel`, `js`, `groovy`, `python`, 和`native`。 default scripting language === 默認的腳本語言是(如果沒有指定`lang`參數)`mvel`。 如果要修改默認語言的話可以將設置`script.default_lang`為合適的語言。 preloaded scripts === 腳本可以作為相關api的一部分， 也可以將腳本放到`config/scripts`來預加載這些腳本， 這樣用到這些腳本的地方可以直接引用腳本的名字而不用提供整個腳本， 這有助於減少客戶端和節點間的傳輸的數據量。 腳本的名字從其所在的目錄結構繼承，不需要帶文件名的后綴， 例如被放在`config/scripts/group1/group2/test.py`的腳本會被命名為group1_group2_test。 disabling dynamic scripts === 建議ES運行在某個應用或者代理的后端，這樣可以將ES和外部隔離， 如果用戶被授權運行動態腳本(即使在search請求)，那么他們就可以訪問ES所在的機器。 首先， 你不應該用`root`用戶來運行ES, 因為這樣會允許腳本在你的服務器上沒有限制的做任何事， 其次你不應該直接將ES暴露給用戶訪問， 如果你打算直接將ES暴露給用戶， 你必須決定是否足夠信任他們在你的服務器上運行腳本。 如果答案是不的話, 即使你有個代理僅允許GET請求， 你也應該在每個節點的`config/elasticsearch.yml`加入如下設置來禁用動態腳本: ``` script.disable_dynamic: true ``` 這樣可以僅允許配置過的命名腳本或者通過插件注冊的原生Java腳本運行， 防止用戶通過接口來運行任意腳本。 native (java) scripts === 即使`mvel`已經相當快了，注冊的原生java腳本還能執行的更快。 實現`NativeScriptFactory`接口的腳本才會被執行。 主要有兩種形式，一種是擴展`AbstractExecutableScript`，一種是擴展`AbstractSearchScript`(可能大多數用戶會選擇這種方式, 可以借助`AbstractLongSearchScript`, `AbstractDoubleSearchScript`, `AbstractFloatSearchScript`這幾個輔助類來實現擴展)。 可以通過配置來注冊腳本， 例如：`script.native.my.type`設為`sample.MyNativeScriptFactory`將注冊一個名為my的腳本。 另一個途徑是插件中訪問`ScriptModule`的`registerScript`方法注冊腳本。 設置`lang`為`native`並且提供腳本的名字就可以執行注冊的腳本。 注意， 腳本需要位於ES的classpath下， 一個簡單方法是在plugins目錄下創建一個目錄(選擇一個描述性的名字)，將jar/classes文件放在這個目錄，他們就會被自動加載。 score === 所有的腳本都可以在facets中使用, 可以通過`doc.score`訪問當前文檔的評分。 document fields === 大多數腳本都會用到document的字段， `doc['field_name']`可以用來訪問document中的某個字段(document通常通過腳本的上下文傳給腳本)。 訪問document的字段非常快， 因為他們會被加載到內存中(所有相關的字段值/token會被加載到內存中)。 下表是能夠從字段上拿到的數據： | Expression | Description | | ------------------------------|:----------------------------------------------------------| | doc['field_name'].value | 字段的原生值， 比如，如果是字段short類型，就返回short類型的值 | | doc['field_name'].values | 字段的原生值的數組， 比如，如果字段是short類型，就返回short[]類型的數組。 記住，單個文檔中的一個字段可以有好幾個值，如果字段沒有值就返回空數組 | | doc['field_name'].empty | boolean值， 表明文檔的字段是否有值 | | doc['field_name'].multiValued | boolean值， 表明文檔的字段是否有多個值 | | doc['field_name'].lat | geo point類型的維度值 | | doc['field_name'].lon | geo point類型的經度值 | | doc['field_name'].lats | geo point類型的維度數組 | | doc['field_name'].lons | geo point類型的經度數組 | | doc['field_name'].distance(lat, lon) | geo point類型的字段到給定坐標的plane距離(單位是miles)　　　| | doc['field_name'].arcDistance(lat, lon) | geo point類型的字段到給定坐標的arc距離(單位是miles) | | doc['field_name'].distanceInKm(lat, lon) | geo point類型的字段到給定坐標的plane距離(單位是km) 　　　　 | | doc['field_name'].arcDistanceInKm(lat, lon) | geo point類型的字段到給定坐標的arc距離(單位是km) | | doc['field_name'].geohashDistance(geohash) | geo point類型的字段到給定geohash的距離(單位是miles) | | doc['field_name'].geohashDistanceInKm(geohash)| geo point類型的字段到給定geohash的距離(單位是km) | stored fields === 執行腳本時也可以訪問存儲的字段(Stored)， 注意，因為他們不會被記載到內存，所以訪問速度與訪問document字段相比慢很多。 可以用`_fields['my_fields_name'].value`或`_fields['my_fields_name'].values`的形式來訪問。 source field === 執行腳本時也可以獲取源字段(source)。 每個文檔的源字段會被加載，解析，然后提供給腳本計算。 可以通過上下文的`_source`來訪問源字段，例如`_source.obj2.obj1.fields3`。 mvel built in functions === 以下是腳本中可以使用的內置函數: | Function | Description 　　　　　　 | | ----------------------|:---------------------------------------------------------------------| | time() | The current time in milliseconds. 　　　　　　　　　| | sin(a) | Returns the trigonometric sine of an angle. | | cos(a) | Returns the trigonometric cosine of an angle. | | tan(a) | Returns the trigonometric tangent of an angle. | | asin(a) | Returns the arc sine of a value. | | acos(a) | Returns the arc cosine of a value. | | atan(a) | Returns the arc tangent of a value. | | toRadians(angdeg) | Converts an angle measured in degrees to an approximately equivalent angle measured in radians. | | toDegrees(angrad) | Converts an angle measured in radians to an approximately equivalent angle measured in degrees. | | exp(a) | Returns Euler’s number e raised to the power of value. 　　　　| | log(a) | Returns the natural logarithm (base e) of a value. 　　　　| | log10(a) | Returns the base 10 logarithm of a value. | | sqrt(a) | Returns the correctly rounded positive square root of a value. | | cbrt(a) | Returns the cube root of a double value. | | IEEEremainder(f1, f2) | Computes the remainder operation on two arguments as prescribed by the IEEE 754 standard. 　　　　| | ceil(a) | Returns the smallest (closest to negative infinity) value that is greater than or equal to the argument and is equal to a mathematical integer. | | floor(a) | Returns the largest (closest to positive infinity) value that is less than or equal to the argument and is equal to a mathematical integer. | | rint(a) | Returns the value that is closest in value to the argument and is equal to a mathematical integer. | | atan2(y, x) | Returns the angle theta from the conversion of rectangular coordinates (x, y) to polar coordinates (r,theta). | | pow(a, b) | Returns the value of the first argument raised to the power of the second argument. 　| | round(a) | Returns the closest int to the argument. | | random() | Returns a random double value. | | abs(a) | Returns the absolute value of a value. | | max(a, b) | Returns the greater of two values. | | min(a, b) | Returns the smaller of two values. | | ulp(d) | Returns the size of an ulp of the argument. 　　　　 | | signum(d) | Returns the signum function of the argument. 　　　 　| | sinh(x) | Returns the hyperbolic sine of a value. | | cosh(x) | Returns the hyperbolic cosine of a value. | | tanh(x) | Returns the hyperbolic tangent of a value. 　　　　 | | hypot(x, y) | Returns sqrt(x2 + y2) without intermediate overflow or underflow. 　　　　　　　　 | arithmetic precision in mvel === 用基於MVEL的腳本做兩個數的除法時， 引擎遵循java的默認規則， 這意味着如果你把兩個整數相除(你可以在mapping里配置字段為integer類型)， 結果仍然是整數。 也就是說如果你在腳本中計算`1/num`這樣的表達式， 如果num是整數8的話，結果是0而不是你可能期望的0.125，你需要明確用doubel來指定精度以獲得期望的結果，用比如`1.0/num`。 thread pool == 為了提高線程管理和內存使用的效率， 一個節點會用到好幾個線程池， 比較重要的是以下幾個。 | Function | Description | | --------------|:----------------------------------------------------------------------------------------------| | index | 用於index/delete, 默認是`fixed`, 大小為`# of available processors`, queue_size是`200` | | search | 用於count/search, 默認是`fixed`, 大小為`3x # of available processors`, queue_size是`1000` | | suggest | 用於suggest, 默認是`fixed`, 大小為`# of available processors`, queue_size是`1000` | | geting | 用於get, 默認是`fixed`, 大小為`# of available processors`, queue_size是`1000` | | bulk | 用於bulk, 默認是`fixed`, 大小為`# of available processors`, queue_size是`50` | | percolate | 用於percolate, 默認是`fixed`, 大小為`# of available processors`, queue_size是`1000` | | warmer | 用於warm-up, 默認是`scaling`, keep-alive是`5m ` | | refresh | 用於refresh, 默認是`fixed`, keep-alive是`5m ` | | percolate | 用於percolate, 默認是`fixed`, 大小為`# of available processors`, queue_size是`1000` | 可以通過設置線程池的類型以及參數來修改指定的線程池，下面的例子配置index線程池可以用更多的線程： ``` threadpool: index: type: fixed size: 30 ``` 注意， 可以通過Cluster Update Settings接口在運行期間修改線程池的設置。 thread pool types === 以下是線程池的類型以及對應的參數。 cache cache線程池是沒有大小限制的， 只要有請求就會啟動一個線程， 下面是設置的例子: ``` threadpool: index: type: cached ``` fixed fixed線程池有固定的大小， 如果當前沒有可用的線程時，就把請求放到一個隊列里， 隊列可以設置大小。 `size`參數設置線程的數量， 默認是cpu內核數乘以5。 `queue_size`設置存放掛起請求的隊列的大小， 默認是-1， 即沒有大小限制。 如果一個請求進來而隊列已經滿了的情況下， 這個請求會被舍棄。 配置例子如下: ``` threadpool: index: type: fixed size: 30 queue_size: 1000 ``` processors setting === ES會自動檢測處理器的數量， 並且會自動根據處理器的數量來設置線程池。 有時候可能檢測出來的處理器數量是錯的， 這種情況下可以設置`processors` 來聲明處理器的數量。 可以用帶`os`參數的nodes info接口來檢查自動檢測出來的處理器數量。 thrift == thrift傳輸模塊允許通過thrift協議對外暴露REST接口， Thrift協議可以提供比http協議更好的性能。 因為thrift既提供了協議，也提供了傳輸的實現方式， 用起來應該很簡單(盡管缺乏相關文檔)。 使用thrift需要安裝[transport-thrift插件](https://github.com/elasticsearch/elasticsearch-transport-thrift) 。 [thrift schema](https://github.com/elasticsearch/elasticsearch-transport-thrift/blob/master/elasticsearch.thrift)可以用來生成thrift的客戶端代碼。 thrift的相關配置如下: | Setting | Description | | --------------|:--------------------------------------------------------------| | thrift.port | 綁定的端口， 默認9500-9600 | | thrift.frame | 默認-1, 即不分frame, 可以設置比較大的值來指定frame的大小(比如15mb)。| transport == 傳輸模塊用於集群內節點間的內部通訊。 每次跨節點的調用都會用到transport模塊(比如某個節點接受http GET請求，實際執行處理的是另一個持有數據的節點)。 transport機制是完全異步的， 即等待響應時不會阻塞線程， 異步通信的好處首先是解決了C10k問題， 另外也是scatter(broadcast)/gather操作(比如搜索)的方案。 tcp transport === TCP transport是用TCP實現傳輸模塊， 允許如下設置: | Setting | Description | | ------------------------------|:----------------------------------------------------------| | transport.tcp.port | 綁定的端口范圍， 默認9300-9400 | | transport.tcp.connect_timeout | socket鏈接的超時時間， 默認2s | | transport.tcp.compress | 設置為true可以啟用壓縮(LZF)， 默認是false。 | tcp transport共享通用網絡設置。 local transport === 這在JVM內做集成測試時非常有用。 當使用`NodeBuilder#local(true)`時會自動啟用。