Skip to content

Commit 3bbddad

Browse files
laodouyalaodouya
laodouya
authored and
laodouya
committed
chore(publish): published 0.7.0 docs by [laodouya]
1 parent 91f1d47 commit 3bbddad

File tree

3 files changed

+380
-0
lines changed

3 files changed

+380
-0
lines changed

‎docs/deploy_miner.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
id: deploy_miner
3+
title: Deploy custom miner
4+
---
5+
16
## 部署 CovenantSQL Miner 节点
27

38
文档对应版本：

‎website/translated_docs/zh-CN/version-0.7.0/deploy_miner.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
id: deploy_miner
3+
title: 部署 CovenantSQL Miner 节点
4+
---
5+
16
## 部署 CovenantSQL Miner 节点
27

38
文档对应版本：

‎website/versioned_docs/version-0.7.0/deploy_miner.md

Lines changed: 370 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,370 @@
1+
---
2+
id: version-0.7.0-deploy_miner
3+
title: Deploy custom miner
4+
original_id: deploy_miner
5+
---
6+
7+
## 部署 CovenantSQL Miner 节点
8+
9+
文档对应版本：
10+
11+
cql HEAD-f0e4e13d-2019080103005
12+
covenantsql/covenantsql 1601418d1aef
13+
14+
### 环境依赖
15+
16+
#### 机器配置
17+
18+
推荐运行服务在 AWS 的 `c5.2xlarge` 型机器或其他同等配置的机器上 (8 核, 16 GB 内存)。
19+
20+
另外建议单独挂载数据盘用于 DB 存储。
21+
22+
#### Docker
23+
24+
CovenantSQL 使用 docker 来简化部署，可通过 Docker 的 [官方文档](https://docs.docker.com/install/) 来进行安装。
25+
26+
#### Docker 镜像
27+
28+
使用 docker 获取 CovenantSQL 的服务镜像以提供数据存储节点服务
29+
30+
```shell
31+
docker pull covenantsql/covenantsql:latest
32+
```
33+
34+
### 配置服务
35+
36+
#### 生成 Miner 配置文件
37+
38+
执行以下命令在当前目录中创建一个 config 目录，并生成 Miner 启动所需的配置文件 `config.yaml` 和 私钥 `private.key`
39+
40+
> 请将命令中的 `miner_external_ip` 和 `miner_listen_port` 替换成实际 miner 运行时对外提供服务的 ip 或域名以及端口号；需要注意的是，之后使用者的命令行客户端或 Adapter 都将使用这个地址连接 Miner，请确保这个地址在使用者的机器上可以访问（没有被云平台或其他防火墙限制访问）。可以使用 telnet 或者 nc 的形式在 Miner 启动后检查服务的可用性
41+
42+
```shell
43+
docker run -it --rm -v $(pwd)/config/:/app/config/ \
44+
--entrypoint /app/cql covenantsql/covenantsql:latest -- \
45+
generate -miner "<miner_external_ip>:<miner_listen_port>" /app/config/
46+
```
47+
48+
命令将会生成一个 miner 的配置文件和私钥，并在命令行中输出 Miner 的节点 id、公钥 hex 和 钱包地址，例如：
49+
50+
```shel
51+
Generated private key.
52+
Generating nonce...
53+
INFO cpu: 8
54+
INFO position: 3, shift: 0x20, i: 7
55+
INFO position: 1, shift: 0x20, i: 3
56+
INFO position: 3, shift: 0x0, i: 6
57+
INFO position: 2, shift: 0x0, i: 4
58+
INFO position: 2, shift: 0x20, i: 5
59+
INFO position: 0, shift: 0x0, i: 0
60+
INFO position: 1, shift: 0x0, i: 2
61+
INFO position: 0, shift: 0x20, i: 1
62+
nonce: {{2677734 0 6632872946 0} 26 0000003e2c8d0b39711edf19ef266a44996b93f7f830149f5d01491a6b7da99d}
63+
node id: 0000003e2c8d0b39711edf19ef266a44996b93f7f830149f5d01491a6b7da99d
64+
Generated nonce.
65+
Generating config file...
66+
Generated config.
67+
68+
Config file: /Users/xq262144/.cql/config.yaml
69+
Private key file: /Users/xq262144/.cql/private.key
70+
Public key's hex: 0338816967be3c24bd490f841de57f2c42daf024dd7f462305aab9a601c423ab8d
71+
Wallet address: eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451
72+
73+
Any further command could costs PTC.
74+
You can get some free PTC from:
75+
https://testnet.covenantsql.io/wallet/eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451
76+
```
77+
78+
可以得到 miner 的钱包地址：`eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451`
79+
80+
#### 给 Miner 帐户充值
81+
82+
执行以下命令将会给 miner 的钱包地址转入 `10000000000` 个 `Particle`
83+
84+
> 请将命令中的 `miner_wallet_address` 替换成上一步中生成的 miner 的钱包地址，例如上例中的 `eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451`
85+
86+
87+
```shell
88+
mkdir -v ./testnet/
89+
curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql:latest/develop/conf/testnet/config.yaml' -o ./testnet/config.yaml
90+
curl -kL -# 'https://raw.githubusercontent.com/covenantsql/covenantsql:latest/develop/conf/testnet/private.key' -o ./testnet/private.key
91+
92+
docker run -it --rm -v $(pwd)/testnet/:/app/config/ \
93+
--entrypoint /app/cql covenantsql/covenantsql:latest -- \
94+
transfer -config /app/config/config.yaml \
95+
-wait-tx-confirm -to-user "<miner_wallet_address>" \
96+
-amount 10000000000 \
97+
-token Particle
98+
```
99+
100+
命令将会从测试网帐户中划转金额给 miner 使用，miner 后续将会使用这笔费用作为押金来提供服务，将会得到类似以下的输出：
101+
102+
```shell
103+
INFO[0000] Geting bp address from dns: bp04.testnet.gridb.io
104+
INFO[0002] Register self to blockproducer: 00000000000589366268c274fdc11ec8bdb17e668d2f619555a2e9c1a29c91d8
105+
INFO init config success path=/app/config/config.yaml
106+
107+
108+
INFO wait transaction confirmation error="<nil>" tx_hash=09001b9904194400e85018984c5428616000669e5de0efac0dc65c72f11950a2 tx_state=Confirmed
109+
INFO succeed in sending transaction to CovenantSQL
110+
```
111+
112+
查询 miner 的账户余额以确定转账成功
113+
114+
```shell
115+
docker run -it --rm -v $(pwd)/config/:/app/config/ \
116+
--entrypoint /app/cql covenantsql/covenantsql:latest -- \
117+
wallet -config ./config/config.yaml
118+
```
119+
120+
将会得到类似以下的输出：
121+
122+
```shell
123+
INFO[0000] Geting bp address from dns: bp05.testnet.gridb.io
124+
INFO[0002] Register self to blockproducer: 0000000000293f7216362791b6b1c9772184d6976cb34310c42547735410186c
125+
INFO init config success path=/app/config/config.yaml
126+
127+
128+
wallet address: eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451
129+
Particle balance is: 100000000
130+
Wave balance is: 0
131+
```
132+
133+
Particle balance 这行输出中可以看到转账的金额，这样 miner 就可以提供服务了。
134+
135+
#### 添加 Miner 可服务的用户限制
136+
137+
在默认启动的情况下，Miner 是面向全网用户提供服务的。如果只希望给指定的 Miner 提供服务，需要在 Miner 上设置 TargetUsers 配置，并指定需要服务的用户的钱包地址。
138+
139+
修改 `miner` 的配置文件 `./config/config.yaml`，在 `Miner` 配置段下添加 `TargetUsers` 配置，指定一个需要服务的用户的 List，例如如下修改：
140+
141+
```diff
142+
--- old.yaml 2019-05-14 00:12:33.000000000 +0800
143+
+++ new.yaml 2019-05-14 00:12:19.000000000 +0800
144+
@@ -1,4 +1,5 @@
145+
Miner:
146+
RootDir: './data'
147+
MaxReqTimeGap: '5m'
148+
ProvideServiceInterval: '10s'
149+
+ TargetUsers: ['eb46e59dbc4eac17b51762f051937a0082ff7423742866e4baff6c6053719451']
150+
```
151+
152+
### 启动 Miner 服务
153+
154+
#### 创建 Container
155+
156+
执行以下命令以创建 miner 的
157+
158+
> 请将下述命令中的 `miner_name` 替换成所需的 miner docker container 名用于管理；`data_disk_dir` 替换成用于存放 miner 数据的目录的绝对地址(推荐挂载一个盘用于提供服务)；`miner_listen_port` 替换成miner 对外提供服务的端口号
159+
160+
```shell
161+
docker create --name "<miner_name>" \
162+
--restart always \
163+
-v $(pwd)/config/:/app/config/ \
164+
-v "<data_disk_dir>:/app/config/data/" \
165+
-e COVENANT_ROLE=miner \
166+
-e COVENANT_CONF=/app/config/config.yaml \
167+
-e METRIC_WEB_ADDR=0.0.0.0:4665 \
168+
--log-driver "json-file" \
169+
--log-opt "max-size=1g" \
170+
--log-opt "max-file=3" \
171+
-p "<miner_listen_port>:4661" \
172+
covenantsql/covenantsql:latest
173+
```
174+
175+
#### 启动 Miner
176+
177+
> 同样，请将 `miner_name` 替换为实际使用的 miner container 名
178+
179+
```shell
180+
docker start "<miner_name>"
181+
```
182+
183+
#### 检查 Miner 状态
184+
185+
> 同样，请将 `miner_name` 替换为实际使用的 miner container 名
186+
187+
```shell
188+
docker ps -a -f "name = <miner_name>"
189+
docker logs --tail=10 -f "<miner_name>"
190+
```
191+
192+
在单台或多台机器上重复上述步骤，启动多个实例，可以提供至多对应节点数量的 DB SideChain 服务。
193+
194+
#### 服务升级
195+
196+
执行以下命令更新镜像，然后重复 **创建 Container** 步骤 和 **启动 Miner** 步骤
197+
198+
```shell
199+
docker pull covenantsql/covenantsql:latest
200+
```
201+
202+
### 使用
203+
204+
#### 使用者账户和配置
205+
206+
使用 CovenantSQL 需要创建一个 DB 使用者的账户。这个账户必须与提供服务的 Miner 节点的账号不同，与此同时一个 Miner 账户也不能同时启动多个 Miner 服务，否则将会导致 Miner 或 DB 使用者的 Transaction 执行异常，用户不能正确创建 DB 或 Miner 不能正确上报使用者的费用信息等。
207+
208+
##### 生成使用者账户配置
209+
210+
执行如下命令将在 `./client_config` 目录下生成使用者账户的私钥和配置
211+
212+
```shell
213+
docker run -it --rm -v $(pwd)/client_config/:/app/config/ \
214+
--entrypoint /app/cql covenantsql/covenantsql:latest -- \
215+
generate /app/config/
216+
```
217+
218+
##### 向使用者账户中充值
219+
220+
类似向 Miner 账户充值，请执行如下命令：
221+
222+
> 请将 `client_wallet_address` 替换为创建的使用者账号的钱包地址
223+
224+
```shell
225+
docker run -it --rm -v $(pwd)/testnet/:/app/config/ \
226+
--entrypoint /app/cql covenantsql/covenantsql:latest -- \
227+
transfer -config /app/config/config.yaml \
228+
-wait-tx-confirm -to-user "<client_wallet_address>" \
229+
-amount 10000000000 \
230+
-token Particle
231+
```
232+
233+
#### 创建 DB 和使用
234+
235+
由于需要在指定的 Miner 上创建 DB，需要在创建 DB 时指定提供服务的 Miner 列表
236+
237+
> `create` 命令接受一个 DB 实例的 json 描述；将 `node_count` 替换为所需的节点数量，例如 1 代表创建一个节点的 DB SideChain；`targetminers` 提供指定 miner 的钱包地址列表；另外需要格外注意的时，所需创建的 DB SideChain 的节点数量需要小于或等于提供的指定 miner 数量，否则 CovenantSQL 会在指定 miner 之外的公用 miner 中随机分配节点以满足用户所需节点数量要求。
238+
239+
```shell
240+
docker run -it --rm -v $(pwd)/client_config/:/app/config/ \
241+
--entrypoint /app/cql covenantsql/covenantsql:latest -- \
242+
create -config /app/config/config.yaml -wait-tx-confirm \
243+
'{"node": <node_count>, "targetminers": ["<miner1_wallet_address>", "<miner2_wallet_address>" ...]}'
244+
```
245+
246+
命令执行完成后将会有类似如下的输出：
247+
248+
```shell
249+
time="2019-05-07T03:41:03Z" level=info msg="Geting bp address from dns: bp04.testnet.gridb.io"
250+
time="2019-05-07T03:41:05Z" level=info msg="Register self to blockproducer: 00000000003b2bd120a7d07f248b181fc794ba8b278f07f9a780e61eb77f6abb"
251+
level=info msg="init config success" path=/root/.cql/config.yaml
252+
level=info msg="create database requested"
253+
The newly created database is: "covenantsql://163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df"
254+
The connecting string beginning with 'covenantsql://' could be used as a dsn for `cql console`
255+
or any command, or be used in website like https://web.covenantsql.io
256+
```
257+
258+
其中 `covenantsql://163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df` 是数据库的连接串，可以在各类 SDK 或命令行工具中使用这个连接串访问数据库服务
259+
260+
#### 使用命令行工具连接数据库服务
261+
262+
可以是用 `cql` 工具提供的命令行功能访问数据库
263+
264+
> 将命令行中的 `dsn` 替换为上一步生成的数据库连接串
265+
266+
```shell
267+
docker run -it --rm -v $(pwd)/client_config/:/app/config/ \
268+
--entrypoint /app/cql covenantsql/covenantsql:latest -- \
269+
console -config /app/config/config.yaml "<dsn>"
270+
```
271+
272+
#### 启动 Adapter
273+
274+
Java SDK 因为CovenantSQL 的 RPC 和网络连接协议的限制，不能直接访问 Miner 或 BlockProducer 节点，需要通过 Adapter 进行协议转换来访问。实际运行时，Java SDK/Adapter/Miner 是以如下图所示的形式交互的：
275+
276+
```sequence
277+
Java SDK ->Adapter: HTTP(s) Request
278+
Adapter->Miner: ETLS RPC Request
279+
Miner->Adapter: ETLS RPC Response
280+
Adapter->Java SDK: HTTP(s) with JSON Response
281+
```
282+
283+
可以通过如下命令启动 Adapter：
284+
285+
> 请将命令中的 `adapter_name` 替换为所需的 adapter 的 docker container 名，将 `adapter_listen_port` 替换为所需暴露在物理机器上的端口号
286+
287+
```shell
288+
docker run -d -v $(pwd)/client_config/:/app/config/ \
289+
-e COVENANT_ROLE=adapter \
290+
-e COVENANT_CONF=/app/config/config.yaml \
291+
-e COVENANTSQL_ADAPTER_ADDR=0.0.0.0:4661 \
292+
--name "<adapter_name>" \
293+
--restart always \
294+
--log-driver "json-file" \
295+
--log-opt "max-size=1g" \
296+
--log-opt "max-file=3" \
297+
-p "<adapter_listen_port>:4661" \
298+
covenantsql/covenantsql:latest
299+
```
300+
301+
启动后如果 adapter 的 docker container 运行正常，将可以通过 `http://localhost:<adapter_listen_port>/` 访问 adapter 并获取到 adapter 的版本信息
302+
303+
#### 使用 Java SDK
304+
305+
参考 [CovenantSQL Java SDK Github](https://github.com/CovenantSQL/covenant-connector/tree/master/covenantsql-java-connector) 和 [CovenantSQL Java SDK 使用文档](https://developers.covenantsql.io/docs/en/driver_java) 通过 Adapter 访问
306+
307+
> 上一步启动的 Adapter 是运行在非 TLS 模式下的开发权限服务，任何访问 Adapter 的人都将以 Adapter 启动的账户（也就是 `./client_config` 中的私钥与配置）的权限访问数据库服务。
308+
>
309+
> 在 Java SDK 中设置配置 `ssl=false`（因为 Adapter 运行在了非 TLS 模式下提供的 http 服务），并以 `jdbc:covenantsql://<adapter_host>:<adapter_listen_port>/<database_id>` 即可访问（请将 `adapter_host` 替换为实际的运行机器的域名或 IP，将 `adapter_listen_port` 替换为上一步中的监听端口号，`database_id` 替换为创建 DB 后返回的 `dsn` 中去除 `covenantsql://` scheme 的 hex 串部分，例如：`jdbc:covenantsql://127.0.0.1:11151/163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df`）
310+
311+
#### 获取 Miner 节点的 metric 信息
312+
313+
Miner 提供了 metric 数据的导出接口，可以通过下述命令访问和导出：
314+
315+
> 讲命令中的 `miner_name` 替换为 启动 miner 的 container 名
316+
317+
```shell
318+
miner_internal_ip=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "<miner_name>" | head -1)
319+
curl -s "http://${miner_internal_ip}:4665/debug/vars"
320+
```
321+
322+
metric 信息对应表
323+
324+
| 字段名 | 含义 |
325+
| ------------------------ | ------------------------------------------------------------ |
326+
| service:miner:addr | 可访问的 Miner 的外部地址和端口（配置中的 ListenAddr） |
327+
| service:miner:node | Miner 的 DHT 网络节点 ID |
328+
| service:miner:wallet | Miner 的 钱包地址 |
329+
| service:miner:disk:root | Miner 的 数据目录地址 |
330+
| service:miner:disk:usage | Miner 使用的磁盘空间（KB） |
331+
| service:miner:db:count | Miner 上正在提供服务的 ShardChain 数量 |
332+
| service:miner:chain | Miner 上所有 ShardChain 统计信息，类型是一个 Map Map 的 key 是 ShardChain 的 DatabaseID |
333+
334+
针对每个 ShardChain 的统计信息，有如下字段
335+
336+
| 字段 | 含义 |
337+
| -------------- | ------------------------------------------- |
338+
| head:count | Chain 最新 Block 的编号（第几个块） |
339+
| head:height | Chain 最新 Block 的 Epoch（第几个出块周期） |
340+
| head:hash | Chain 最新 Block 的 Hash |
341+
| head:timestamp | Chain 最新 Block 的产生时间（UTC） |
342+
| requests:count | 最近 5 分钟统计范围内，1m 的请求数的平均值 |
343+
344+
#### 查看 Miner 节点上某个 DB Chain 的块信息
345+
346+
CovenantSQL 提供了一个方便的 Explorer 来展示数据库子链上的块信息，可以在通过如下命令启动 Explorer：
347+
348+
> 其中替换 `explorer_name` 为想要运行 explorer 的 docker container 名，`explorer_listen_port` 替换为所需暴露在物理机器上的端口号
349+
350+
```shell
351+
docker run -d -v $(pwd)/client_config/:/app/config/ \
352+
-e COVENANT_ROLE=observer \
353+
-e COVENANT_CONF=/app/config/config.yaml \
354+
-e COVENANTSQL_OBSERVER_ADDR=0.0.0.0:4661 \
355+
--name "<explorer_name>" \
356+
--restart always \
357+
--log-driver "json-file" \
358+
--log-opt "max-size=1g" \
359+
--log-opt "max-file=3" \
360+
-p "<explorer_listen_port>:4661" \
361+
covenantsql/covenantsql:latest
362+
```
363+
364+
启动在浏览器里访问 `http://<explorer_external_address>:<explorer_listen_port>/dbs/<database_id>`
365+
366+
> 其中 `explorer_external_address` 替换为物理机的外网 IP，`explorer_listen_port` 替换为上一步中指定的端口， `database_id` 替换为创建 DB 后返回的 `dsn` 中去除 `covenantsql://` scheme 的 hex 串部分，例如：`http://miner_machine:11106/dbs/163193957a22fccf165ad754ee514f13972c0eadee6455203b17b7bba76028df`
367+
368+
稍后等待块同步，即可在页面中看到历史产生的 Block，点击 Block 可以看到 Block 上承载的历史查询过的 Query 情况（如果没有自动出现块的信息，可以尝试手动刷新）
369+
370+
> CovenantSQL 有严格的权限控制，需要对数据库有读权限的人才能使用 Explorer 看到这些 Query 历史和 Block 信息

0 commit comments

Comments
 (0)