快速入门

CITA 是一个开源的区块链内核，任何人都可以基于 CITA 来搭建属于自己的一条区块链，在本文档中我们将带你搭建一条简单的链并运行其中的节点。

如果你想一键搭建属于你自己的链，你可以选择租用 CITA 的云服务。只需根据您的需求，在云服务平台选择适合自己的方案直接租用，帮你省去准备服务器以及部署 CITA 的一系列操作。具体请参考云服务支持。

如果你想在 CITA 上直接开发您的应用，我们建议你使用我们已经搭好的 CITA 测试链。测试链的水龙头的地址为：https://dapp.cryptape.com/faucet/, 可以在这里领取 Testnet 的代币。测试链的内核 CITA 的版本为 v0.22.0。该测试链由4个节点组成，各节点的 ip 地址和端口如下：

node 1: 121.196.200.225:1337 //或者通过域名访问： https://node.cryptape.com
node 2: 116.62.221.89:1338
node 3: 47.96.84.91:1339
node 4: 121.43.163.31:1340

依赖

系统平台要求

系统需支持 Docker 的安装。

CITA 的 Docker 镜像托管在 DockerHub 。因为 CITA 是基于 Ubuntu 18.04 稳定版开发的，因此该镜像中封装了 Ubuntu 18.04 还有其他一些 CITA 运行所需要的配置和文件。

如果你使用的是 macOS, 可以直接参考这里来安装试用 CITA.

安装 Docker

参见在线资料。

可使用下面的命令来检查 Docker 是否已经成功安装：

$ sudo docker run hello-world

获取 Docker 镜像

CITA 的 Docker 镜像托管在 DockerHub。

可以使用 docker pull 命令直接从 DockerHub 获取，参见在线资料。

对于内网环境，也可以通过 docker save 和 docker load 传递镜像，参见在线资料。

编译 CITA

下面的操作步骤是带你获取最新的源码进行编译，若你想直接下载编译好的发布包，可前往 Github 查看目前所有的 CITA 正式发布版本，直接下载你想要的版本发布包然后部署即可。

获取源码

从 Github 仓库下载 CITA 的源代码，然后切换到 CITA 的源代码目录

$ git clone https://github.com/cryptape/cita.git
$ cd cita
$ git submodule init
$ git submodule update

编译源代码

可以按照自己的需求自行选择相应的编译方式（Debug-调试模式或 Release-发行模式）

$ ./env.sh make debug

或者

$ ./env.sh make release

可选择替换 Rust Crates 的官方源，详细教程可以参考：

USTC Mirror Help for Rust Crates

Source Replacement for Rust Crates

How to map a configuration file into docker

编译生成的文件在发布件目录 target/install 下，生产环境下只需要这个目录即可。

Docker env 使用说明
在源码根目录下，我们提供了 env.sh 脚本，封装了 Docker 相关的操作。运行此脚本，以实际要运行的命令作为参数，即表示在 Docker 环境中运行相关命令。例如：
$ ./env.sh make debug
即表示在 Docker 环境中运行 make debug。
不带任何参数运行 ./env.sh，将直接获取一个 Docker 环境的 shell。
Notice
如果 Docker 容器是被 root 用户创建的，后续非 root 用户使用 ./env.sh 会出现如下错误：
$ ./env.sh
error: failed switching to "user": unable to find user user: no matching entries in passwd file
因此要保证操作使用的始终是同一个系统用户。
如果出现 Docker 相关的报错，可以执行如下命令并重试： shell docker kill $(docker ps -a -q)

部署CITA

配置节点

先切换到发布件目录
- 如果之前选择从源码开始编译：

    $ cd target/install
    ```

  * 如果之前选择下载编译好的发布包：

    ```shell
    $ cd cita_secp256k1_sha3/
    ```

* 使用发布件目录中的 `create_cita_config.py` 工具用来生成节点配置文件，包括创世块配置、节点相关配置、网络连接配置、私钥配置等。执行以下命令行可使用该工具生成默认的本地 4 个节点的 Demo 示例配置：

> **Notice**
> `bin/cita` 脚本默认是通过启动容器执行命令，若是本地配置了相关的环境直接使用，请 加上 `bebop` 关键词
>
>   ```shell
>   $ bin/cita bebop create --super_admin "0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523" --nodes "127.0.0.1:4000,127.0.0.1:4001,127.0.0.1:4002,127.0.0.1:4003"
>   ```
> 下同


```shell
$ bin/cita create --super_admin "0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523" --nodes "127.0.0.1:4000,127.0.0.1:4001,127.0.0.1:4002,127.0.0.1:4003"

节点初始化操作成功后，将在发布件目录下生成节点的配置文件，其生成的节点目录为：

test-chain/0
test-chain/1
test-chain/2
test-chain/3

执行以下命令依次配置四个节点

  $ bin/cita setup test-chain/0
  $ bin/cita setup test-chain/1
  $ bin/cita setup test-chain/2
  $ bin/cita setup test-chain/3

Note
生产环境中，用户需要根据实际情况更改默认配置。使用命令 bin/cita create -h 来获得详细帮助信息，允许自定义的配置包括：

系统管理员账户

出块时间间隔

累积多少历史交易量后进行重复交易的检查

系统合约详细参数

共识节点地址

该工具更详细的使用说明请参考 Config Tool。

对于多服务器部署一条链，选择一台服务器执行命令之后把相关节点目录进行拷贝。不可多服务器都执行配置脚本。
在不同服务器部署多条链主要规划相关端口配置，参见 Config_Tool的功能和用法。在同一台服务器上部署多条链，除了规划端口配置外，由于 RabbitMQ 系统服务限制，多条链只能在一个Docker里运行。基于上面 test-chain 链所在的目录，生成一条新链：
$ bin/cita create --super_admin "0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523"  --chain_name test2-chain --jsonrpc_port 2337 --ws_port 5337 --grpc_port 6000 --nodes "127.0.0.1:8000,127.0.0.1:8001,127.0.0.1:8002,127.0.0.1:8003"
运行 test2-chain 方式与上面 test-chain 一致，并且只能在同一个Docker 里运行。

节点命令

通过 bin/cita 查看节点命令。

Usage: cita <command> <node> [options]
where <command> is one of the following:
    { help | create | port | setup | start | stop | restart
      ping | top | backup | clean | logs | logrotate }
Run `cita help` for more detailed information.

启动节点

执行以下命令依次启动四个节点，该命令正常情况下不会返回，节点后台运行。

$ bin/cita start test-chain/0
$ bin/cita start test-chain/1
$ bin/cita start test-chain/2
$ bin/cita start test-chain/3

停止节点

以“0”节点为例，执行以下命令即可停止“0”节点：

$ bin/cita stop test-chain/0

其他操作

更多其他操作使用以下命令查看帮助信息：

$ bin/cita help

输出如下：

Usage: cita <command> <node> [options]
This is the primary script for controlling the cita node.
 INFORMATIONAL COMMANDS
    help
        You are here.
 BUILDING COMMANDS
    create <config>
        Creates blockchains according to the following config,
        use "cita create -h" to get more information.
        "cita-config" has the same function.
    port <ports>
        Sets docker port, for example: "cita port 1337:1337"
 SERVICE CONTROL COMMANDS
    setup <node>
        Ensuring the required runtime environment for cita node, like
        RabbitMQ service. You should run this command at the first time
        of running cita node.
    start <node>
        Starts the cita node in the background. If the node is already
        started, you will get the message "Node is already running!" If the
        node is not already running, no output will be given.
    stop <node> [debug] [mock]
        Stops the running cita node. Prints "ok" when successful.  When
        the node is already stopped or not responding, prints:
        "Node 'NODE_NAME' not responding to pings."
    restart <node>
        Stops and then starts the running cita node. Prints "ok"
        when successful.  When the node is already stopped or not
        responding, prints: "Node 'NODE_NAME' not responding to
        pings."
 DIAGNOSTIC COMMANDS
    ping <node>
        Checks that the cita node is running. Prints "pong" when
        successful.  When the node is stopped or not responding, prints:
        "Node 'NODE_NAME' not responding to pings."
    top <node>
        Prints services processes information similar
        to the information provided by the `top` command.
    stat <node> (deprecated, use 'top' instead)
    logs <node> <service>
        Fetch the logs of the specified service.
 SCRIPTING COMMANDS
    backup <node>
        Backup the node's data and logs into backup directory, which actually
        copy that data and logs into backup directory. Prints the specified
        backup commands. When the node is running, prints:
        "Node is already running!"
    clean <node>
        Clean the node's data and logs, which actually move that data and logs
        into backup directory. Prints the specified backup commands. When the
        node is running, prints: "Node is already running!"
    logrotate <node>
        Archives the current node logs, starts fresh logs. Prints the archived
        logs path.

Notice
请不要先进到 bin 目录，再执行以上的部署操作，错误示范：
$ cd bin
$ cita setup test-chain/0
请勿在一台服务器上运行多个容器。因为虽然 CITA 在 Docker 中运行，但是容器并没有做网络隔离。

请不要同时在 host 系统里面运行 CITA 以及相关的 RabbitMQ 等软件，以免造成端口冲突

使用docker-compose

前面运行节点的方法，是将所有节点放在同一个容器中，并且容器没有做网络隔离。

对于复杂的测试场景，会造成一些不便。

使用docker-compose可以让每个节点单独一个容器，网络也是隔离的。

安装docker-compose

sudo curl -L "https://github.com/docker/compose/releases/download/1.23.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

准备发布件

latest_release_tag=$(curl --silent "https://api.github.com/repos/cryptape/cita/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
echo "latest release tag: $latest_release_tag"
wget https://github.com/cryptape/cita/releases/download/$latest_release_tag/cita_secp256k1_sha3.tar.gz
tar zxvf cita_secp256k1_sha3.tar.gz
cp -r cita_secp256k1_sha3 cita_secp256k1_sha3_node0
cp -r cita_secp256k1_sha3 cita_secp256k1_sha3_node1
cp -r cita_secp256k1_sha3 cita_secp256k1_sha3_node2
cp -r cita_secp256k1_sha3 cita_secp256k1_sha3_node3

wget https://raw.githubusercontent.com/cryptape/cita/$latest_release_tag/tests/integrate_test/docker-compose.yaml

启动

USER_ID=`id -u $USER` docker-compose up

后台启动

USER_ID=`id -u $USER` docker-compose up -d

停止

docker-compose down

进入容器内执行命令

docker-compose exec node0 /usr/bin/gosu user /bin/bash

日志

容器默认输出的是chain微服务的日志

docker-compose logs -f

也可以直接到挂载目录下查看所有微服务的日志

tail -100f cita_secp256k1_sha3_node0/test-chain/0/logs/cita-jsonrpc.log

验证

查询节点个数

Request:

curl -X POST --data '{"jsonrpc":"2.0","method":"peerCount","params":[],"id":74}' 127.0.0.1:1337

Result:

{
"jsonrpc": "2.0",
"id": 74,
"result": "0x3"
}

查询当前块高度。

Request:

curl -X POST --data '{"jsonrpc":"2.0","method":"blockNumber","params":[],"id":83}' 127.0.0.1:1337

Result:

{
"jsonrpc": "2.0",
"id": 83,
"result": "0x8"
}

返回块高度，表示节点已经开始正常出块。

更多 API（如合约调用、交易查询）请参见RPC 调用。

CITAHub Docs

0.23.0

配置

系统管理

JSON RPC

系统合约接口

架构设计

协议升级

参考

CITA-Toolchain-intro

CITA-CLI

SDK

ReBirth

Cyton

Microscope

CITA-IDE

CITA Truffle Box

CITA Web Debugger

依赖