Skip to content

Commit 67a494c

Browse files
laodouyalaodouya
laodouya
authored and
laodouya
committed
chore(publish): published 0.8.0 docs by [laodouya]
1 parent 3b9d7e0 commit 67a494c

27 files changed

+2964
-1
lines changed

‎docs/quickstart.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ If the problem persists please check out our GitHub page [submit issue](https://
6262
6363
### TestNet
6464
65-
At present, we have released the test network v0.7.0 for everyone to verify and experience the principle. You can choose to quickly perform access testing using the "public account".
65+
At present, we have released the test network v0.8.0 for everyone to verify and experience the principle. You can choose to quickly perform access testing using the "public account".
6666
6767
The configuration file and private key of the "public account":[config.yaml](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/config.yaml)、[private.key](https://raw.githubusercontent.com/CovenantSQL/CovenantSQL/develop/conf/testnet/private.key) (empty password)，or just run：
6868

‎website/translated_docs/zh-CN/version-0.8.0/adapter.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
id: adapter
3+
title: 📦 Adapter SDK
4+
---
5+
6+
# 通过 Adapter 使用 CovenantSQL
7+
8+
`CovenantSQL` 提供了 HTTP/HTTPS Adapter，类似于云数据库， 开发者可以直接用 HTTP 的形式使用 CovenantSQL。
9+
10+
## 安装和使用
11+
12+
首先，[安装 Docker](https://docs.docker.com/install/)。
13+
14+
然后，需要确认我们有一个可用的配置和公私钥对，通常我们默认的配置和公私钥对的存储位置为 `~/.cql/` 目录。生成或获取请参考 [QuickStart#创建账号](./quickstart#创建账号)
15+
16+
### Docker 运行 Adapter
17+
18+
下面的命令将使用`~/.cql/config.yaml` 和 `~/.cql/private.key` 启动 Adapter，并把端口映射在 `0.0.0.0:11105`
19+
20+
```bash
21+
export adapter_addr=0.0.0.0:11105
22+
docker rm -f cql-adapter
23+
docker run -itd \
24+
--env COVENANT_ROLE=adapter --env COVENANT_CONF=/app/config.yaml \
25+
--env COVENANTSQL_ADAPTER_ADDR=0.0.0.0:4661 \
26+
-v ~/.cql/config.yaml:/app/config.yaml \
27+
-v ~/.cql/private.key:/app/private.key \
28+
--name cql-adapter -p $adapter_addr:4661 \
29+
covenantsql/covenantsql:testnet
30+
```
31+
32+
### 创建数据库
33+
34+
使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例
35+
36+
```bash
37+
docker run -it --rm \
38+
-v ~/.cql/config.yaml:/app/config.yaml \
39+
-v ~/.cql/private.key:/app/private.key \
40+
--entrypoint /app/cql covenantsql/covenantsql:testnet \
41+
create -config /app/config.yaml -wait-tx-confirm -db-node 1
42+
```
43+
44+
命令会返回创建的数据库实例的连接串（DSN）
45+
46+
```bash
47+
covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4
48+
```
49+
50+
## 主流语言 Driver 的使用
51+
52+
1. [Golang](./driver_golang)
53+
2. [Java](./driver_java)
54+
3. [Python](./driver_python)
55+
4. [NodeJS](./driver_js)

‎website/translated_docs/zh-CN/version-0.8.0/advanced_deployment.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
id: advanced_deployment
3+
title: Private Deploy
4+
---
5+
6+
## 使用 CovenantSQL Docker 部署
7+
8+
### 安装 Docker
9+
10+
需要在机器上安装 docker 和 docker-compose 来一键部署 CovenantSQL
11+
12+
Docker：https://docs.docker.com/install/
13+
14+
Docker-Compose：https://docs.docker.com/compose/install/
15+
16+
### 下载项目
17+
18+
```bash
19+
git clone https://github.com/CovenantSQL/CovenantSQL
20+
cd CovenantSQL
21+
```
22+
23+
后续的所有命令，工作目录默认都是在 clone 的 CovenantSQL 源码目录中，可以执行
24+
25+
```bash
26+
export COVENANTSQL_ROOT=$PWD
27+
```
28+
29+
存为环境变量
30+
31+
### 启动 Docker 容器
32+
33+
现在有两种方式启动 CovenantSQL 容器：
34+
35+
1. 使用 Docker Hub 上的公共镜像
36+
2. 构建 CovenantSQL Docker 镜像
37+
38+
> 我们推荐普通用户使用第一种方式测试 CovenantSQL，第二种仅用于体验最新的开发中的特性。
39+
40+
#### 1. 使用 Docker Hub 上的公共镜像
41+
42+
然后直接启动：
43+
44+
```bash
45+
make start
46+
```
47+
48+
#### 2. 构建 CovenantSQL Docker 镜像
49+
50+
执行以下的命令在本地运行 CovenantSQL
51+
52+
```bash
53+
make docker # 从头编译新的镜像
54+
make start
55+
```
56+
57+
### 检查运行状态
58+
59+
检查容器状态：
60+
61+
```bash
62+
docker-compose ps
63+
```
64+
65+
确认所有组件都处于 `Up` 的状态
66+
67+
```
68+
Name Command State Ports
69+
---------------------------------------------------------------------------------------------------------------------
70+
covenantsql_adapter ./docker-entry.sh Up 0.0.0.0:11105->4661/tcp
71+
covenantsql_bp_0 ./docker-entry.sh Up 0.0.0.0:11099->4661/tcp, 0.0.0.0:12099->4665/tcp
72+
covenantsql_bp_1 ./docker-entry.sh Up 0.0.0.0:11100->4661/tcp, 0.0.0.0:12100->4665/tcp
73+
covenantsql_bp_2 ./docker-entry.sh Up 0.0.0.0:11101->4661/tcp, 0.0.0.0:12101->4665/tcp
74+
covenantsql_fn_0 ./docker-entry.sh -wsapi :8546 Up 4661/tcp, 0.0.0.0:11110->8546/tcp
75+
covenantsql_miner_0 ./docker-entry.sh Up 0.0.0.0:11102->4661/tcp, 0.0.0.0:12102->4665/tcp
76+
covenantsql_miner_1 ./docker-entry.sh Up 0.0.0.0:11103->4661/tcp, 0.0.0.0:12103->4665/tcp
77+
covenantsql_miner_2 ./docker-entry.sh Up 0.0.0.0:11104->4661/tcp, 0.0.0.0:12104->4665/tcp
78+
covenantsql_mysql_adapter ./docker-entry.sh -listen ... Up 4661/tcp, 0.0.0.0:11107->4664/tcp
79+
covenantsql_observer ./docker-entry.sh Up 4661/tcp, 0.0.0.0:11108->80/tcp
80+
```
81+
82+
## 操作 CovenantSQL
83+
84+
### 创建数据库
85+
86+
使用 `cql` 命令并使用 `create` 参数提供所需的数据库节点数量创建数据库实例，例如：创建一个单节点的数据库实例
87+
88+
```bash
89+
cql create -config ${COVENANTSQL_ROOT}/test/service/node_c/config.yaml -db-node 1
90+
```
91+
92+
> 修改 `create` 参数的值，可以创建运行在多节点上的实例，例如：创建两个节点的实例
93+
94+
```bash
95+
cql create -config ${COVENANTSQL_ROOT}/test/service/node_c/config.yaml -db-node 2
96+
```
97+
98+
命令会返回创建的数据库实例的连接串
99+
100+
```
101+
covenantsql://4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5
102+
```
103+
104+
### 访问数据库
105+
106+
使用 `cql` 命令并使用 `dsn` 参数提供数据库实例的连接串进行数据库访问
107+
108+
```bash
109+
cql console -config ${COVENANTSQL_ROOT}/test/service/node_c/config.yaml covenantsql://0a255f136520a2bc6a29055a619ec4f72c2c80fa600daf73b1caa375946ea0e4
110+
```
111+
112+
会得到如下输出，并进入 `cql` 交互命令行模式
113+
114+
```
115+
Connected with driver covenantsql (develop-34ae741a-20190415135520)
116+
Type "help" for help.
117+
118+
co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=>
119+
```
120+
121+
`cql` 交互命令行模式的使用方法类似 `mysql` 命令，例如：创建一个名为 `test` 的表，查看数据库中的表，插入记录，查询结果
122+
123+
```sql
124+
CREATE TABLE test (test TEXT);
125+
SHOW TABLES;
126+
INSERT INTO test VALUES("happy");
127+
SELECT * FROM test;
128+
```
129+
130+
会得到如下输出
131+
132+
```
133+
co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> CREATE TABLE test (test TEXT);
134+
CREATE TABLE
135+
co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> SHOW TABLES;
136+
name
137+
------
138+
test
139+
(1 row)
140+
141+
co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> INSERT INTO test VALUES("happy");
142+
INSERT
143+
co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=> SELECT * FROM test;
144+
test
145+
-------
146+
happy
147+
(1 row)
148+
149+
co:4bc27a06ae52a7b8b1747f3808dda786ddd188627bafe8e34a332626e7232ba5=>
150+
```
151+
152+
使用 `Ctrl + D` 快捷键或输入 `\q` 可以退出 `cql` 交互命令行
153+
154+
### SQLChain Observer
155+
156+
镜像中的 Observer 角色使用了和 mysql-adapter 镜像中相同的 private.key ，故可以免去新账户授权和转账的过程制。
157+
158+
（关于权限管理的详细说明请参考[数据库权限管理](cql_db_manage#数据库权限管理)）
159+
160+
#### 在浏览器使用 SQLChain Observer
161+
162+
我们在 `127.0.0.1:11108` 端口提供了一个 SQLChain 的 Observer 可以看到 SQL 语句在链上的情况。

‎website/translated_docs/zh-CN/version-0.8.0/advanced_secure_gateway.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
id: advanced_secure_gateway
3+
title: 数据库安全网关
4+
---
5+
6+
### CQL SecureGateway 字段级加密/权限管理
7+
8+
CQL SecureGateway (CGS) 目前仅开放给部分企业用户使用，如有深入了解或者试用需求请[联系我们](mailto:info@covenantsql.io)。
9+
10+
#### 模块结构
11+
12+
![CovenantSQL.字段级加密.安全网关](https://github.com/CovenantSQL/docs/raw/master/website/static/img/CovenantSQL.SecureGateway.png)
13+
14+
#### 访问接口
15+
16+
CGS 使用的是 MySQL 5.x 的二进制协议，所有兼容 MySQL 5.x 的语言驱动都可以直接使用。
17+
18+
#### 权限设置
19+
20+
支持对 **用户/用户组** 和 **字段/字段组** 组合形式授权（字段表示为 **库.表.字段** 的三元组）
21+
22+
#### 示例配置
23+
24+
##### 权限
25+
26+
设置分为两个部分，分组 和 策略
27+
分组如下
28+
29+
用户组
30+
31+
| 用户 | 用户组 |
32+
| ----- | --------------- |
33+
| user1 | admin,userGroup |
34+
| user2 | admin,userGroup |
35+
| user3 | userGroup |
36+
37+
字段组
38+
39+
| 字段 | 字段组 |
40+
| ------------- | -------- |
41+
| db1.tbl1.col2 | someCols |
42+
| db1.tbl1.col3 | someCols |
43+
| db1.tbl1.col4 | someCols |
44+
45+
策略如下
46+
47+
| 用户/用户组 | 字段/字段组 | 权限点（写入/读取） |
48+
| ----------- | ------------- | ------------------- |
49+
| user1 | db1.tbl1.col1 | write |
50+
| user2 | db1.tbl1.col1 | read |
51+
| admin | someCols | read |
52+
| userGroup | db1.tbl2.col1 | read |
53+
| userGroup | db2.tbl1.* | read |
54+
55+
#### 加密设置
56+
57+
支持以 字段 & 加密密钥 的形式配置加密设置（字段表示为 **库.表.字段** 的三元组）
58+
在用户对字段有权限的前提下，加密/解密才能继续进行。
59+
60+
#### 示例配置
61+
62+
##### 密钥
63+
64+
| 字段 | 密钥 |
65+
| ------------- | ---- |
66+
| db1.tbl1.col1 | key1 |
67+
| db1.tbl1.col2 | key2 |
68+
| db1.tbl1.col3 | key3 |
69+
| db1.tbl2.col1 | key1 |
70+
| db2.tbl1.col1 | key1 |
71+
72+
##### 效果
73+
74+
结合上面`权限` & `密钥`的配置，生效的访问限制如下：
75+
76+
| 数据库 | 表 | 字段 | 需要的密钥 | 可访问用户+权限 |
77+
| ------ | ---- | ---- | ---------- | ----------------------- |
78+
| db1 | tbl1 | col1 | key1 | user1 write; user2 read |
79+
| db1 | tbl1 | col2 | key2 | user1 read; user2 read |
80+
| db1 | tbl1 | col3 | key3 | user1 read; user2 read |
81+
| db1 | tbl1 | col4 | 无 | user1 read; user2 read |
82+
| db1 | tbl2 | col1 | key1 | userGroup read |
83+
| db2 | tbl1 | * | key1 | userGroup read |
84+

‎website/translated_docs/zh-CN/version-0.8.0/arch.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
id: arch
3+
title: Architecture
4+
---
5+
6+
7+
## 3 层架构
8+
9+
10+
![CovenantSQL 3 Layer design](https://github.com/CovenantSQL/CovenantSQL/raw/ed2878359345cd86e4221f14cd59e4654361b64e/logo/arch.png)
11+
12+
- 第一层: **全局共识层**(主链，架构图中的中间环):
13+
- 整个网络中只有一个主链。
14+
- 主要负责数据库矿工与用户的合同匹配，交易结算，反作弊，子链哈希锁定等全局共识事宜。
15+
- 第二层: **SQL 共识层**(子链，架构图中的两边环):
16+
- 每个数据库都有自己独立的子链。
17+
- 主要负责数据库各种事务的签名，交付和一致性。这里主要实现永久可追溯性的数据历史，并且在主链中执行哈希锁定。
18+
- 第三层: **数据储存层**(支持 SQL-92 的数据库引擎):
19+
- 每个数据库都有自己独立的分布式引擎。
20+
- 主要负责：数据库存储和加密；查询处理和签名；高效索引。
21+
22+
23+
## 共识算法
24+
25+
CQL 支持两种共识算法：
26+
27+
1. DPoS (委任权益证明) 应用在数据库的 `最终一致性` 和 Block Producer 所在的 `第一层 (全局共识层)` ，CQL 的矿工在客户端将所有SQL查询及其签名打包成块，从而形成整个区块链，我们把这个算法命名为 [`Xenomint`](https://github.com/CovenantSQL/CovenantSQL/tree/develop/xenomint)
28+
2. BFT-Raft (拜占庭容错算法)<sup>[bft-raft](#bft-raft)</sup> 应用于数据库的 `强一致性`。我们把这个实现命名为 [`Kayak`](https://github.com/CovenantSQL/CovenantSQL/tree/develop/kayak). 矿工 leader 会基于 `Kayak` 做 `两阶段提交` 来支持 `Transaction`.<sup>[transaction](#transaction)</sup>
29+
30+
可以用命令行 `cql create -db-eventual-consistency -db-node 3` 来创建 `最终一致性` CQL 数据库
31+
32+
33+
## 项目对比
34+
35+
| | 以太坊 | Hyperledger Fabric | AWS QLDB | CovenantSQL |
36+
| ---------------------------- | ----------------- | ---------------------- | ----------- | ------------------------------------------------------------ |
37+
| **开发语言** | Solidity, ewasm | Chaincode (Go, NodeJS) | ? | Python, Golang, Java, PHP, NodeJS, MatLab |
38+
| **开发模式** | Smart Contract | Chaincode | SQL | SQL |
39+
| **是否开源** | Y | Y | N | Y |
40+
| **高可用节点** | 3 | 15 | ? | 3 |
41+
| **列级别 ACL** | N | Y | ? | Y |
42+
| **数据格式** | File | Key-value | Document | File<sup>[fuse](#fuse)</sup>, Key-value, Structured |
43+
| **存储加密** | N | API | Y | Y |
44+
| **数据脱敏** | N | N | N | Y |
45+
| **多租户** | DIY | DIY | N | Y |
46+
| **吞吐量（1秒延迟）** | 15~10 tx/s | 3500 tx/s | ? | 11065 tx/s (Eventually Consistency)<br/>1866 tx/s (Strong Consistency) |
47+
| **一致性延迟** | 2~6 min | < 1 s | ? | < 10 ms |
48+
| **开放网络上的安全性** | Y | N | Only in AWS | Y |
49+
| **共识机制** | PoW + PoS(Casper) | CFT | ? | DPoS (Eventually Consistency)<br/>BFT-Raft (Strong Consistency) |
50+
51+
### 注释：
52+
- <a name="bft-raft">BFT-Raft</a>: 在一个 CQL leader 离线的情况下，有两种可能的选择：等待 leader 上线，以保证数据的完整性，或者提拔 follwers 以保证服务可用性；目前是需要一定的人工介入来进行策略选择，这部分仍在迭代中，欢迎任何建议。
53+
54+
- <a name="transaction">事务 (Transaction)</a>: 说到 `ACID`，CQL 具有完整的 "一致性，隔离性，持久化" 和特定的 `Atomicity` 支持。即使在强一致性的模式下，CQL 事务只支持在 leader 节点上执行。如果你想要并发执行事务："读取 `v`, `v++`, 写回 `v` ", 仅有的办法是："从 leader 读取 `v` , `v++`, 从 leader 写回 `v`"
55+
56+
- <a name="fuse">FUSE</a>: CQL 有一个从 CockroachDB 移植过来的 [FUSE 客户端](https://github.com/CovenantSQL/CovenantSQL/tree/develop/cmd/cql-fuse)，目前性能不是很理想，仍然存在一些小问题。但它可以通过如下的 fio 测试：
57+
58+
```bash
59+
fio --debug=io --loops=1 --size=8m --filename=../mnt/fiotest.tmp --stonewall --direct=1 --name=Seqread --bs=128k --rw=read --name=Seqwrite --bs=128k --rw=write --name=4krandread --bs=4k --rw=randread --name=4krandwrite --bs=4k --rw=randwrite
60+
```

0 commit comments

Comments
 (0)