链级配置 · CITAHub Docs

当拿到发布件解压后，或从源码编译后，不要着急启动节点，在这之前，很重要的一步就是我们需要对链进行初始化配置。这些配置信息将被写入链的创世块，创世块一旦生成，SysConfig 中只有 chainName，operator，website 这三项可以在链运行之后再进行修改，其他项均不可再修改, 因此请大家慎重设定各配置项。在 CITA 里面，我们提供了工具 config tool 来帮助你在起链前对链进行初始化配置, 提供了命令行工具 CITA-CLI 来帮助你在起链后修改个别配置。

本文档将为你详细介绍链的各个可配置项，包括链自身的一些属性、系统合约、RPC接口、节点间网络连接等；然后通过具体的操作示例，演示如何起链前对链进行初始化配置；并带你详细了解初始化配置后文件的目录结构；最后，将通过具体示例，演示起链后如何修改个别配置。相信阅读完此文档后，你将可以自己定制一条满足你需求的链。

可配置项

执行以下命令查看各个配置项：

$ bin/cita create --help
usage: create_cita_config.py create [-h]
                                    [--authorities AUTHORITY[,AUTHORITY[,AUTHORITY[,AUTHORITY[, ...]]]]]
                                    [--chain_name CHAIN_NAME]
                                    [--nodes IP:PORT[,IP:PORT[,IP:PORT[,IP:PORT[, ...]]]]]
                                    [--super_admin SUPER_ADMIN]
                                    [--contract_arguments Contract.Argument=Value [Contract.Argument=Value ...]]
                                    [--timestamp TIMESTAMP]
                                    [--resource_dir RESOURCE_DIR]
                                    [--grpc_port GRPC_PORT]
                                    [--jsonrpc_port JSONRPC_PORT]
                                    [--ws_port WS_PORT] [--enable_tls]
                                    [--enable_version] [--stdout]

我们一一解释：

Notice 起链时，强制要求的配置项为 super_admin 和 nodes，系统不提供默认配置。

`--authorities` 将共识节点的地址写到链上

安全起见，我们建议的流程是：先由每个共识节点单独生成各自的私钥和地址，私钥请务必由自己妥善保管；地址交由负责起链的管理员，通过该命令写到链上。起链后，生成的 test-chain/*/privkey 文件为空，由各节点独自将自己的私钥填写进来。
没有传递参数的话，默认会自动生成对应节点数量的私钥/地址对：地址写到链上；私钥存放在各个节点的 test-chain/*/privkey 文件里。

`--chain_name` 指定链的名字

执行该命令后会生成以链的名字为名称的文件夹，该文件夹里面再按节点序号创建 0，1，2 等节点文件夹，分别存放每个节点的配置文件。
如果没有传递 chain_name 参数，则默认链的名字为 test-chain。

`--nodes` 指定节点的 ip 地址和端口

每个节点都需要提供 ip 和 port，ip 与 port 用冒号隔开，节点间用逗号隔开。这个参数有多少个网络地址，最终将会生成对应数量的节点(上限256)，并且相对应的节点序号就按照参数中网络地址的顺序，从 0 开始，往后递增。

`--super_admin` 指定超级管理员地址

该账户拥有最高权限，用来管理整条链的运行状态。用户必须自己设置超级管理员。

`--contract_arguments` 指定链自身的一些系统配置和系统合约的配置

test-chain/template 目录下的 init_data.yml 中记录了一种示例配置，我们可以看到各配置项如下：

-Contracts:
 -SysConfig:
   delayBlockNumber: 1
   checkCallPermission: false
   checkSendTxPermission: false
   checkCreateContractPermission: false
   checkQuota: false
   checkFeeBackPlatform:false
   chainOwner: '0x0000000000000000000000000000000000000000'
   chainName: test-chain
   chainId: 1
   operator: test-operator
   website: https://www.example.com (https://www.example.com/)
   blockInterval: 3000
   economicalModel: 0
   name: CITA Test Token
   symbol: CTT
   avatar: https://cdn.cryptape.com/icon_cita.png
   autoExec: false
 -QuotaManager:
   admin: '0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523'
 -NodeManager:
   nodes:
   '0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523'
   stakes:
   0
 -ChainManager:
   parentChainId: 0
   parentChainAuthorities: []
 -Authorization:
   superAdmin: '0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523'
 -Group:
   parent: '0x0000000000000000000000000000000000000000'
   name: rootGroup
   accounts:
   '0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523'
 -Admin:
   admin: '0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523'
 -VersionManager:
   version: 1


* `SysConfig` : 初始化一些系统信息
  - `delayBlockNumber` : 表示系统合约在几个块之后生效，默认为 1 个块。当前此功能已废弃。
  - `checkCallPermission` : 合约调用权限检查开关
  - `checkSendTxPermission` : 发送交易权限检查开关
  - `checkCreateContractPermission` : 创建合约权限检查开关
  - `checkQuota` : 配额检查开关
  - `checkFeeBackPlatform` : 出块激励选择开关，默认为 false，表示返回给共识节点，为 true 时返回给运营方地址( chainOwner )
  - `chainOwner` : 运营方地址，结合 checkFeeBackPlatform 一块使用
  - `chainName` : 链的名字
  - `chainId` : 链 Id
  - `operator` : 运营方名称
  - `website` : 运营方网站
  - `blockInterval` ： 出块间隔，默认 3 秒
  - `economicalModel`： 经济模型。CITA 中存在两种经济模型，Quota(默认) 和 Charge。`economicalModel = 0` 表示 Quota 模型，交易只需不超过限额即可，限额由管理员设置，详细机制可查看[配额管理](../system/quota)；`economicalModel = 1` 表示 Charge 模型， 交易需要手续费，针对交易的每一步执行进行单步扣费模式，扣除余额，详细机制可查看[配额价格管理](../system/price)。
  - `name` : Token 名称
  - `symbol` : Token 符号
  - `avatar` : Token 图标链接
  - `autoExec` : 自动执行开关（默认：false）
* `QuotaManager` : 初始化配额管理合约的管理员地址
  - `admin` : 默认管理员地址
* `NodeManager` : 初始化共识节点管理合约
  - `nodes` : 共识节点地址
  - `stakes` : 共识节点对应的出块权重
* `ChainManager` : 初始化链的一些信息，用于跨链。
  - `parentChainId` : 父链 ID
  - `parentChainAuthorities` : 父链的共识节点列表
* `Authorization` : 初始化权限管理合约
  - `superAdmin` : 管理员地址
* `Group` : 初始化用户组管理合约
  - `parent` : 父组的地址
  - `name` : 组的名称
  - `accounts` : 组内用户列表
* `Admin` : 管理员
  - `admin` : 管理员地址
* `VersionManager` : 协议版本管理合约
  - `version` : 协议版本号

`--time_stamp` 指定起链的时间戳

具体数值是指自 1970-1-1 以来的毫秒数，默认是取当前的时间，如果时间取在未来，则链起来之后不会出块。
这个值在生成的genesis.son文件中可以查看到。

`--resource_dir` 指定资源目录

除了创世块中的数组，链有时候还需要额外自带一些数据（比如说零知识证明），但是因为数据比较大，无法放入创世块，因此在这里可以通过传递参数指定一个单独的资源目录。
指定该参数后，生成的配置会多一个 resource 目录，用户指定目录下的文件将会被拷贝进来，然后，配置工具会计算该目录下所有文件的 hash 值，作为 genesis.json 中 prevhash 字段中的值。prevhash 默认全部是 0，通过传入此参数，prevhash 的值将发生改变。

`--grpc_port`、`jsonrpc_port`、`ws_port` 指定起始端口号

grpc，jsonrpc，ws_port 等参数指定的端口号是一个起始端口号。节点实际使用的端口号，按照节点排列顺序顺延，即 port+n（ n 为节点序号）。比如总共 4 个节点，传递 grpc_port 参数为 7000 ，则 test-chain/0 的 grpc 端口号为 7000，test-chain/1 的 grpc 端口号为 7001，以此类推。
grpc_port 存在 test-chain/*/executor.toml 中，jsonrpc port 和 ws port 都存在 test-chain/*/jsonrpc.toml 中。
CITA有一些保留端口，设置节点网络端口，或者自定义端口的时候要避免产生端口冲突。保留端口有：
- 默认的 grpc 端口：5000 到 5000 + N（N 为节点总数,以下相同）
- 默认的 jsonrpc 端口：1337 到 1337 + N
- 默认的 websocket 端口：4337 到 4337+N
- 默认的 rabbitmq 端口：4369(epmd)/25672(Erlang distribution)/5671，5672(AMQP)/15672(management plugin)

`--enable_tls` 是否开通节点间通讯加密

指定节点间数据是否使用 TLS (Transport Layer Security) 加密传输，不加此选项默认为不加密传输。
创建链时加上此选项，会在 test-chain/*/network.toml 配置文件中增加 enable_tls = true 的配置项。

`--enable_version` 是否使能 JSON-RPC 接口 `getVersion`

配置当前链是否能够通过 JSON-RPC 的 getVersion 接口来获得当前链的 CITA 软件版本号。不加此选项默认为不开启这个接口。
创建链时加上此选项，会在 test-chain/*/jsonrpc.toml 配置文件中增加 enable_version = true 的配置项。

`--stdout` 是否将 CITA 日志输出到标准输出

配置当前链的日志信息输出到标准输出，CITA 的日志默认以文件形式输出到 test-chain/*/logs 下。
创建链时加上此选项，会在 test-chain/*/forever.toml 配置文件中增加为每个微服务的启动参数添加 -s 选项。

初始化配置操作示例

以下是最基础起链命令，该命令生成一条包含四个节点的新链，端口默认 4000 , 4001 , 4002 , 4003，默认超级管理员，经济模型为 Quota, 所有权限控制关闭。

$ 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"

接下来演示来生成一条高级配置的链, 命令如下：

$ 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" --contract_arguments SysConfig.checkSendTxPermission=true SysConfig.checkCallPermission=true SysConfig.economicalModel=1 SysConfig.checkFeeBackPlatform=true SysConfig.chainOwner=0x9a6bd7272edb238f13002911d8c93dd6bb646d15

上述命令，生成一条包含四个节点，端口默认 4000 , 4001 , 4002 , 4003，超级管理员地址 0x4b5ae4567ad5d9fb92bc9afd6a657e6fa13a2523，运营方地址 0x9a6bd7272edb238f13002911d8c93dd6bb646d15，经济模型 Charge，出块激励返回运营方，权限全开的链。

初始化配置后生成的目录结构

采用 create 默认创建 4 个共识节点的目录结构如下:

$ ls test-chain/
0 1 2 3 template
$ ls 0
address     consensus.toml  forever.toml       logs
auth.toml   data            genesis.json       network.toml
chain.toml  executor.toml   jsonrpc.toml       privkey

相对应给出的参数，生成 4 个节点，test-chain/* 里面包含节点的配置文件，具体如下：

privkey : 存放私钥
address : 存放地址
*.toml : 各个微服务配置文件，详细说明见微服务说明
genesis.json ：生成 genesis 块文件，其中 timestamp 为时间戳，秒为单位；prevhash 指前一个块哈希，这里是默认值；而 alloc 指部署到创世块的合约内容；
test-chain/template 目录下是模板文件，包括这个链的共识节点地址 test-chain/template/authorities.list，系统参数 test-chain/template/init_data.yml, 节点端口地址 test-chain/template/nodes.list 等信息
logs : 记录链运行的日志信息
data : 数据存储

修改个别配置操作示例

起链后，也就是说创世块一旦生成，除 chainName, operator, website 三项可以在运行时更改，其他配置均无法修改。接下来我们用 cita-cli 来进行演示，以管理员修改 chainName 作为示例：

确保你的链正常运行，进入 cita-cli 交互式模式，输入命令：

$ scm SysConfig setChainName --chain-name "AAA" --admin-private \ 0x5f0258a4778057a8a7d97809bd209055b2fbafa654ce7d31ec7191066b9225e6

查询交易回执无误后，我们成功的把链名称从默认的 test-chain 更改为 AAA。

我们可以通过 getMeta 查询更改后的结果，示例如下：

$ rpc getMetaData

输出：

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "blockInterval": 3000,
    "chainId": 1,
    "chainName": "AAA",
    "economicalModel": 1,
    "genesisTimestamp": 1538101178583,
    "operator": "test-operator",
    "tokenAvatar": "https://cdn.cryptape.com/icon_cita.png",
    "tokenName": "CITA Test Token",
    "tokenSymbol": "CTT",
    "validators": [
      "0x185e7072f53574666cf8ed8ec080e09b7e39c98f"
    ],
    "version": 1,
    "website": "https://www.example.com"
  }
}

chainName 已更新。

可配置项

--authorities 将共识节点的地址写到链上

--chain_name 指定链的名字

--nodes 指定节点的 ip 地址和端口

--super_admin 指定超级管理员地址

--contract_arguments 指定链自身的一些系统配置和系统合约的配置

--time_stamp 指定起链的时间戳

--resource_dir 指定资源目录

--grpc_port、jsonrpc_port、ws_port 指定起始端口号

--enable_tls 是否开通节点间通讯加密

--enable_version 是否使能 JSON-RPC 接口 getVersion

--stdout 是否将 CITA 日志输出到标准输出