RIAK1.4.2 ReadMe文档翻译

#+SETUPFILE: "doc/basho-doc-style.iorg"

Welcome to Riak.

* Overview
综述
  Riak is a distributed, decentralized data storage system.
  Riak 是一个分布式的 分散数据的存储系统。
  Below, you will find the "quick start" directions for setting up and
  接下来，你将发现设置和使用Riak“快速开始”的说明
  using Riak.  For more information, browse the following files:
        对于更多的信息，浏览下面的文件：
 
    - README:  this file
    README：本文件
    - LICENSE: the license under which Riak is released
    许可：Riak遵循这个协议
    - doc/
        - admin.org: Riak Administration Guide
    - admin.org:Riak 管理指南
        - architecture.txt: details about the underlying design of Riak
    - architecture.txt: 详细的介绍了Riak底层设计
        - basic-client.txt: slightly more detail on using Riak
    - basic-client.txt：客户简单使用Riak的介绍
        - basic-setup.txt:  slightly more detail on setting up Riak
    - basic-setup.txt:  配置Riak的简单介绍
        - man/riak.1.gz: manual page for the riak(1) command
    - man/riak.1.gz:riak(1)命令的使用手册页面
        - man/riak-admin.1.gz manual page for the riak-admin(1) command
    - man/riak-admin.1.gz  riak-admin(1) 命令使用手册
        - raw-http-howto.txt: using the Riak HTTP interface
    - raw-http-howto.txt: 使用Riak的http接口

* Where to find more
  去哪发现更多
Below, you'll find a basic introduction to starting and using Riak as
接下来，你将发现开始和何用Riak作为键/值存储的入门介绍
a key/value store.  For more information about Riak's extended feature
想要获取关于Riak的拓展特性包括 MapReduce，查找，次要索引，多样存储策略，等等
set, including MapReduce, Search, Secondary Indexes, various storage
strategies, and more, please visit our docs at http://docs.basho.com/.
请浏览我们在http://docs.basho.com/ 上的文档

* Quick Start

  This section assumes that you have copy of the Riak source tree. To get
  这部分假设你已经有了Riak原树的备份。想要开始，你需要
  started, you need to:
  1. Build Riak
     建设 Riak
  2. Start the Riak server
     启动Riak服务
  3. Connect a client and store/fetch data
     连接一个客户端 和存储和取数据

** Building Riak
    建设Riak

   Assuming you have a working Erlang (R14B02 or later) installation,
   假设你有一个Erlang(R14B02或更高版本)的安装工作,
   building Riak should be as simple as:

#+BEGIN_EXAMPLE
   $ cd $RIAK
   $ make rel
#+END_EXAMPLE

** Starting Riak

   Once you have successfully built Riak, you can start the server with the
   following commands:

#+BEGIN_EXAMPLE
   $ cd $RIAK/rel/riak
   $ bin/riak start
#+END_EXAMPLE

   Now, verify that the server started up cleanly and is working:
   现在，验证服务已经成功启动并正在运行

   : $ bin/riak-admin test

   Note that the $RIAK/rel/riak directory is a complete, self-contained instance
   注意：$RIAK/rel/riak目录 是一个 完成的自主独立的Riak and Erlang实例
   of Riak and Erlang. It is strongly suggested that you move this directory
   如果你计划运行一个生产实例,强烈建议将这个目录移动到源代码目录之外.
   outside the source tree if you plan to run a production instance.

** Connecting a client to Riak
    为Riak连接一个客户端
   Now that you have a functional server, let's try storing some data in
   现在你已经有了一个可以提供功能的服务，让我们试着在它里面存储一些数据。
   it. First, start up a erlang node using our embedded version of erlang:
   首先，用我们嵌入式版本erlang启动一个erlang节点
#+BEGIN_EXAMPLE
   $ erts-<vsn>/bin/erl -name riaktest@127.0.0.1 -setcookie riak
  
   Eshell V5.7.4  (abort with ^G)
   (riaktest@127.0.0.1)1>
#+END_EXAMPLE

   Now construct the node name of Riak server and make sure we can talk to it:
   现在构造一个Riak server节点 并确保我们能够跟它进行会话。

#+BEGIN_EXAMPLE
   (riaktest@127.0.0.1)4> RiakNode = 'riak@127.0.0.1'.

   (riaktest@127.0.0.1)2> net_adm:ping(RiakNode).
   pong
   (riaktest@127.0.0.1)2>
#+END_EXAMPLE
  
   We are now ready to start the Riak client:
   现在我们已经启动了一个Riak客户端

#+BEGIN_EXAMPLE
   (riaktest@127.0.0.1)2> {ok, C} = riak:client_connect(RiakNode).
   {ok,{riak_client,'riak@127.0.0.1',<<4,136,81,151>>}}
#+END_EXAMPLE

   Let's create a shopping list for bread at /groceries/mine:
   让我们创建一个面包的购物列表在/groceries/mine:
#+BEGIN_EXAMPLE
   (riaktest@127.0.0.1)6> O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
   O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
   {r_object,<<"groceries">>,<<"mine">>,
          [{r_content,{dict,0,16,16,8,80,48,
                            {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                            {{[],[],[],[],[],[],[],[],[],[],[],[],...}}},
                      ["bread"]}],
          [],
          {dict,1,16,16,8,80,48,
                {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
          undefined}

    (riaktest@127.0.0.1)3> C:put(O0, 1).
#+END_EXAMPLE
   
    Now, read the list back from the Riak server and extract the value
    现在，从Riak服务上这个列表，并提取这些值

#+BEGIN_EXAMPLE
    (riaktest@127.0.0.1)4> {ok, O1} = C:get(<<"groceries">>, <<"mine">>, 1).
    {ok,{r_object,<<"groceries">>,<<"mine">>,
              [{r_content,{dict,2,16,16,8,80,48,
                                {[],[],[],[],[],[],[],[],[],[],[],[],...},
                                {{[],[],[],[],[],[],
                                  [["X-Riak-Last-Modified",87|...]],
                                  [],[],[],...}}},
                          ["bread"]}],
              [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
                {1,63415509105}}],
              {dict,0,16,16,8,80,48,
                    {[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                    {{[],[],[],[],[],[],[],[],[],[],[],...}}},
              undefined}}

     (riaktest@127.0.0.1)5> %% extract the value
     (riaktest@127.0.0.1)5> V = riak_object:get_value(O1).
     ["bread"]
#+END_EXAMPLE

     Add milk to our list of groceries and write the new value to Riak:
     添加牛奶到我们的食品列表并向Riak写入新值：


#+BEGIN_EXAMPLE
     (riaktest@127.0.0.1)6> %% add milk to the list
     (riaktest@127.0.0.1)6> O2 = riak_object:update_value(O1, ["milk" | V]).
     {r_object,<<"groceries">>,<<"mine">>,
          [{r_content,{dict,2,16,16,8,80,48,
                            {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                            {{[],[],[],[],[],[],
                              [["X-Riak-Last-Modified",87,101,100|...]],
                              [],[],[],[],[],...}}},
                      ["bread"]}],
          [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
            {1,63415509105}}],
          {dict,0,16,16,8,80,48,
                {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
          ["milk","bread"]}

     (riaktest@127.0.0.1)7> %% store the new list
     (riaktest@127.0.0.1)7> C:put(O2, 1).
     ok
#+END_EXAMPLE

     Finally, see what other keys are available in groceries bucket:
    最后，看在食品桶中什么键值是可用的
#+BEGIN_EXAMPLE
     (riaktest@127.0.0.1)8> C:list_keys(<<"groceries">>).
     {ok,[<<"mine">>]}
#+END_EXAMPLE

** Clients for Other Languages
    其他语言的客户端
   Client libraries are available for many languages.  Rather than
   客户端库对于很多语言都是可用的。
   bundle them with the Riak server source code, we have given them
   而不是受它服务端的源代码所限制，我们给了他们自己的源库。
   each their own source repository.  Currently, official Riak
   目前官方的Riak客户端语言库包含
   client language libraries include:

   + Javascript
     https://github.com/basho/riak-javascript-client

   + Python
     https://github.com/basho/riak-python-client

   + Ruby
     https://github.com/basho/riak-ruby-client

   + Java
     https://github.com/basho/riak-java-client

   + PHP
     https://github.com/basho/riak-php-client

   + Erlang
     https://github.com/basho/riak-erlang-client
     (using protocol buffers instead of distributed Erlang)

* Server Management
    服务管理

** Configuration
    配置
   Configuration for the Riak server is stored in $RIAK/rel/riak/etc
   Riak服务的配置存放在$RIAK/rel/riak/etc目录
   directory. There are two files:
    是两个文件
   - vm.args
     This file contains the arguments that are passed to the Erlang VM
    这个文件包含参数被传到运行Riak服务的Erlang虚拟机
     in which Riak runs. The default settings in this file shouldn't need to be
     在大多数环境中这个文件配置的默认参数不应该被修改
     changed for most environments.

   - app.config
     This file contains the configuration for the Erlang applications
     that run on the Riak server.
    这个文件包含的配置是为了运行Riak服务上的Erlang应用
   More information about this files is available in doc/basic-setup.txt.
    关于这些配置文件的更多信息在doc/basic-setup.txt中
** Server Control
    服务控制
*** bin/riak
    This script is the primary interface for starting and stopping the Riak
    这些脚本是启动和停止Riak服务的初级接口
    server.

    To start a daemonized (background) instance of Riak:
    想要后台启动Riak实例

    : $ bin/riak start

    Once a server is running in the background you can attach to the Erlang
  
    console via:
 Riak服务一旦后台运行后，你可以通过
    : $ bin/riak attach

    Alternatively, if you want to run a foreground instance of Riak, start it
    或者，如果你想前台运行Riak实例，这样启动：
    with:

    : $ bin/riak console

    Stopping a foreground or background instance of Riak can be done from a
    停止一个前台或者后台的Riak实例，可以通过一个这个shell命令
    shell prompt via:

    : $ bin/riak stop

    Or if you are attached/on the Erlang console:
    或者，你是通过attached执行
    : (riak@127.0.0.1)1> q().

    You can determine if the server is running by:
    你可以通过这样判断服务是否启动
    : $ bin/riak ping

*** bin/riak-admin
    This script provides access to general administration of the Riak server.
    提供访问Riak服务的管理总处的脚本
    The below commands assume you are running a default configuration for
    下面的命令假定你运行了一个默认配置的（Riak服务）
    parameters such as cookie.

    To join a new Riak node to an existing cluster:
    想向一个已经存在簇中添加一个新的Riak节点
#+BEGIN_EXAMPLE
    $ bin/riak start # If a local server is not already running
    $ bin/riak-admin join <node in cluster>
#+END_EXAMPLE

    (Note that you must have a local node already running for this to work)
    （注意:确保本地节点已经已经运行）
    To verify that the local Riak node is able to read/write data:
    想要确保你本地的Riak节点可以被读/写
    : $ bin/riak-admin test

    To backup a node or cluster run the following:
    想备份一个节点或者一个簇
    : $ bin/riak-admin backup riak@X.X.X.X riak <directory/backup_file> node
    : $ bin/riak-admin backup riak@X.X.X.X riak <directory/backup_file> all
   
    Restores can function in two ways, if the backup file was of a node the
    可以通过两种方法恢复数据，如果备份文件是一个节点，这个节点想要恢复。
    node will be restored and if the backup file contains the data for a
    和如果这个备份文件包含整个簇的数据，并且想要恢复整个簇的数据
    cluster all nodes in the cluster will be restored.
   
    To restore from a backup file:
    通过备份文件恢复数据
    : $ riak-admin restore riak@X.X.X.X riak <directory/backup_file>
   
    To view the status of a node:
    浏览节点状态
    : $ bin/riak-admin status
   
    If you change the IP or node name you will need to use the reip command:
    如果你向改变IP或者是节点名称，你需要用reip命令
    : $ bin/riak-admin reip <old_nodename> <new_nodename>
   
   
    
* Contributing to Riak and Reporting Bugs
    向Riak做贡献，这个提交一个bug（这部分就翻译了）

  Basho encourages contributions to Riak from the community. Here's how to get started.

  - Fork the appropriate sub-projects that are affected by your
    change. Fork this repository if your changes are for release
    generation or packaging.
  - Make your changes and run the test suite. (see below)
  - Commit your changes and push them to your fork.
  - Open pull-requests for the appropriate projects.
  - Basho engineers will review your pull-request, suggest changes,
    and merge it when it's ready and/or offer feedback.

To report a bug or issue, please open a [[https://github.com/basho/riak/issues][new issue]] against this repository.

You can read the [[http://docs.basho.com/riak/latest/references/appendices/community/How-to-Report-a-Bug/][full guidelines for bug reporting and code contributions]] on the Riak Docs.

** Testing
  To make sure your patch works, be sure to run the test suite in each
  modified sub-project, and dialyzer from the top-level project to
  detect static code errors.

  To run the QuickCheck properties included in Riak sub-projects,
  download QuickCheck Mini: http://quviq.com/downloads.htm NOTE: Some
  properties that require features in the Full version will fail.

*** Running unit tests
   The unit tests for each subproject can be run with =make= or
   =rebar= like so:

#+BEGIN_SRC shell
make eunit
#+END_SRC

#+BEGIN_SRC shell
./rebar skip_deps=true eunit
#+END_SRC

*** Running dialyzer
    Dialyzer performs static analysis of the code to discover defects,
    edge-cases and discrepancies between type specifications and the
    actual implementation.

    Dialyzer requires a pre-built code analysis table called a PLT.
    Building a PLT is expensive and can take up to 30 minutes on some
    machines.  Once built, you generally want to avoid clearing or
    rebuilding the PLT unless you have had significant changes in your
    build (a new version of Erlang, for example).

**** Build the PLT
     Run the command below to build the PLT.
   
#+BEGIN_SRC shell
make build_plt
#+END_SRC

**** Check the PLT
     If you have built the PLT before, check it before you run
     Dialyzer again. This will take much less time than building the
     PLT from scratch.

#+BEGIN_SRC shell
make check_plt
#+END_SRC

**** Run Dialyzer
   
#+BEGIN_SRC shell
make dialyzer
#+END_SRC