0.22.0

Translate

Getting Started

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 运行所需要的配置和文件。

安装 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

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

Docker env 和 daemon 使用说明

  • 在源码根目录下，我们提供了 env.sh 脚本，封装了 Docker 相关的操作。 运行此脚本，以实际要运行的命令作为参数，即表示在 Docker 环境中运行相关命令。 例如：

    $ ./env.sh make debug

    即表示在 Docker 环境中运行 make debug。

  • 不带任何参数运行 ./env.sh，将直接获取一个 Docker 环境的 shell。

  • 还提供了 daemon.sh，用法同 env.sh，效果是后台运行。

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 示例配置：

  ```shell
  $ ./env.sh ./scripts/create_cita_config.py 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

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

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

Note

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

    • 系统管理员账户
    • 出块时间间隔
    • 累积多少历史交易量后进行重复交易的检查
    • 系统合约详细参数
    • 共识节点地址

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

  • 对于多服务器部署一条链，选择一台服务器执行命令之后把相关节点目录进行拷贝。不可多服务器都执行配置脚本。

  • 在不同服务器部署多条链主要规划相关端口配置，参见 Config_Tool的功能和用法。在同一台服务器上部署多条链，除了规划端口配置外，由于 RabbitMQ 系统服务限制，多条链只能在一个Docker里运行。基于上面 test-chain 链所在的目录，生成一条新链：

    $ ./scripts/create_cita_config.py 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 | setup | start | stop | restart | ping
      top | backup | clean | logs | logrotate }
Run `cita help` for more detailed information.

启动节点

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

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

停止节点

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

$ ./env.sh ./bin/cita stop test-chain/0

其他操作

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

$ ./env.sh ./bin/cita help

Notice

  • 请不要先进到 bin 目录，再执行以上的部署操作，错误示范：

    $ cd bin
$ ./env.sh ./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/develop/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:

    ./env.sh 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:

    ./env.sh 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 调用。

← About CITANext →