# 部署文档
## 核心服务部署文档
DID核心服务主要包含以下三个服务：
- DID（did）服务主要实现DID核心逻辑提供gRPC接口；
- DID-ADMIN（did-admin）服务主要实现管理员DID相关业务逻辑包含DID核心逻辑；
- 网关服务（did-gateway）主要实现转发、代理相关请求和权限管理。
### DID服务（did）
#### 硬件配置
| 配置 | 最低配置 | 推荐 |
|-----|-------|-------|
| CPU | 1.5Hz | 2.4Hz |
| 内存 | 8G | 16G |
| 核心 | 4核 | 8核 |
| 带宽 | 2Mb | 10Mb |
#### 软件环境准备
| 软件 | 版本 | 描述 |
|-----------|----------|-----|
| k8s | v1.18+ | |
| kubectl工具 | 与k8s集群匹配 | |
| redis | v7.2+ | 缓存 |
| mysql | v8+ | 数据库 |
数据库可选：人大金仓，postgresql等数据库
#### 安装物料
| 软件 | 描述 |
|---------------------|---------|
| did/etc | did配置文件 |
| did/did.7z | 合约文件 |
| did/deployment.yaml | k8s配置文件 |
下载[DID物料包](https://git.chainweaver.org.cn/chainweaver/did/did/-/releases/v1.1.0)
https://git.chainweaver.org.cn/chainweaver/did/did/-/releases/v1.1.0
物料包内容如下：
```shell
.
├── did # did服务安装物料
│ ├── deployment.yaml
│ ├── did-v1.1.0.7z
│ └── etc
│ ├── crypto-config
│ │ ├── ca
│ │ │ └── ca.crt
│ │ ├── client1.key
│ │ ├── client1.pem
│ │ ├── client1.tls.crt
│ │ └── client1.tls.key
│ ├── did.yaml
│ ├── sdk_config_pk.yml
│ └── templates
│ ├── 100000.json
│ ├── 100001.json
│ ├── 100002.json
│ └── 100003.json
├── did-admin # did-admin 服务安装物料
│ ├── deployment.yaml
│ └── etc
│ └── did-admin.yaml
└── did-gateway # did-admin 服务安装物料
├── deployment.yaml
└── etc
├── did-gateway.yaml
└── tls
├── server.crt
├── server.csr
└── server.key
```
DID服务配置文件列表
```shell
did
├── deployment.yaml # k8s配置文件
├── did-v1.1.0.7z # did合约
└── etc # 启动时初始化依赖
├── crypto-config # 连接链节点依赖
│ ├── ca
│ │ └── ca.crt
│ ├── client1.key
│ ├── client1.pem
│ ├── client1.tls.crt
│ └── client1.tls.key
├── did.yaml # 服务配置
├── sdk_config_pk.yml # 连接链节点配置
└── templates # 初始化VC模板内容
├── 100000.json
├── 100001.json
├── 100002.json
└── 100003.json
```
#### 配置did.yaml
需根据自身需要修改did/etc/did.yaml，如下所示：
> 隐私数据加密相关操作步骤参考：[附录：配置加密](../tech/00_配置加密.md) 数据库配置、密码等可加密
配置签发机构的信息：
```yaml
...
# 配置签发机构的信息
CNBN:
# 签发机构DID
DID: did:cndid:cndid
# 密钥对，必须是国密
Crypto:
PublicKey: "etc/crypto-config/client1.pem"
PrivateKey: "etc/crypto-config/client1.key"
# 对外暴露的地址
Service:
- "http://192.168.1.181:30002/api/v1"
...
```
数据库配置：
> 在启动前需要提前创建对应数据库
> `CREATE DATABASE did;`
```yaml
...
#DataSource: host=127.0.0。1 port=54321 user=system password=123456 dbname=did sslmode=disable client_encoding=UTF8
#Type: kingbase
DataSource: root:passw0rd@tcp(127.0.0.1:6379)/did?parseTime=true&loc=Asia%2fShanghai
Type: mysql # kingbase，mysql
...
```
Redis缓存配置：
```yaml
...
# 缓存配置
RedisConf:
Host: 127.0.0.1:6379
Pass: password
...
```
#### 部署步骤
##### 整体流程
- 修改配置文件
- 启动did服务（若未部署合约则报错）
- 查询did服务对应数据库的管理台did document
- 部署did合约
- 重启did服务
##### 部署到Kubernetes集群
使用\`kubectl create\` 命令创建挂载的map文件：
```shell
# 创建配置文件
kubectl create cm did-configmap-yml --from-file=./etc/did.yaml --from-file=./etc/sdk_config_pk.yml --dry-run=client -o yaml > did-configmap-yml.yaml --insecure-skip-tls-verify
kubectl create cm did-configmap-cnbn-key --from-file=./etc/crypto-config/client1.key --from-file=./etc/crypto-config/client1.pem --dry-run=client -o yaml > did-configmap-cnbn-key.yaml --insecure-skip-tls-verify
kubectl create cm did-configmap-cnbn-key-ca --from-file=./etc/crypto-config/ca/ca.crt --dry-run=client -o yaml > did-configmap-cnbn-key-ca.yaml --insecure-skip-tls-verify
kubectl create cm did-configmap-templates --from-file=./etc/templates --dry-run=client -o yaml > did-configmap-templates.yaml --insecure-skip-tls-verify
```
使用\`kubectl apply\` 命令应用map文件：
```shell
# 部署
kubectl apply -f did-configmap-yml.yaml -n=did --insecure-skip-tls-verify
kubectl apply -f did-configmap-cnbn-key.yaml -n=did --insecure-skip-tls-verify
kubectl apply -f did-configmap-cnbn-key-ca.yaml -n=did --insecure-skip-tls-verify
kubectl apply -f did-configmap-templates.yaml -n=did --insecure-skip-tls-verify
```
使用\`kubectl apply\` 命令部署资源定义文件到Kubernetes集群：
> 如果该步骤拉不到镜像请参考附录[kubectl操作指南](../tech/01_kubectl%E6%93%8D%E4%BD%9C%E6%8C%87%E5%8D%97.md)
```shell
kubectl apply --force --record -n=did -f deployment.yaml --insecure-skip-tls-verify
```
##### 验证部署检查Pod状态，确保DID服务已成功启动并运行
> 初次部署需要启动后获取DID document信息，安装did合约成功后重启。
利用\`kubectl get\` 命令查看服务是否启动
```shell
kubectl get pod -n did | grep did
```
返回结果如下，1/1则表示微服务有一个实例，启动成功1个pod实例，如果是2/2则表示有两个实例，启动成功了2个pod实例。
```shell
didXXXXX-XXX 1/1 Running 0 1d
```
检查Service和Ingress资源配置，保外部访问路径和端口正确：
```shell
kubectl get svc,ing -n did | grep did
```
利用日志验证是否部署成功，日志会有如下输出：
```
did rpc server version: v1.0.0, name: did, git commit: 49416ff,git Branch: develop,build time: 2024-04-11T07:35:09Z
```
##### 拷贝document（链上已有合约忽略此步骤）
执行SQL语句，查询\`id = 'did:cndid:cndid'\` 的document内容：
```sql
SELECT document
FROM did
WHERE id = 'did:cndid:cndid';
```
##### 部署合约 did.7z（链上已有合约忽略此步骤）
> 下载CMC命令：[v2.3.3版本发布页面](https://git.chainmaker.org.cn/chainmaker/chainmaker-go/-/releases/v2.3.3)
>
>
使用CMC命令：[长安链CMC工具（pk）](https://docs.chainmaker.org.cn/dev/%E5%91%BD%E4%BB%A4%E8%A1%8C%E5%B7%A5%E5%85%B7pk.html)
注意：`--contract-name`字段值需要和`did.yaml`中的`ChainMaker.ContractName`字段值一致，参数中的didDocument的值为上一步查询的json内容，需转义。
```
./cmc client contract user create --contract-name=did --runtime-type=DOCKER_GO \
--byte-code-path=./did.7z --version=1.0 --sdk-conf-path=./etc/sdk_config_pk.yml \
--gas-limit=999999999 --sync-result=true \
--params='{"didDocument":"{\"@context\":\"https://www.w3.org/ns/did/v1\",\"id\":\"did:cnbn:7d5e485e5fb34bc1846848c50c9eeb38e8ba62fe\",......}"}'
```
##### 重启did服务
```shell
kubectl rollout restart deployment -n did did
```
### DID-ADMIN服务（did-admin）
#### 硬件配置
| 配置 | 最低配置 | 推荐 |
|-----|-------|-------|
| CPU | 1.5Hz | 2.4Hz |
| 内存 | 8G | 16G |
| 核心 | 4核 | 8核 |
| 带宽 | 2Mb | 10Mb |
#### 软件环境准备
| 软件 | 版本 | 描述 |
|-----------|----------|----|
| k8s | v1.18+ | |
| kubectl工具 | 与k8s集群匹配 | |
#### 安装物料
| 软件 | 描述 |
|---------------------------|---------------|
| did-admin/etc | did-admin配置文件 |
| did-admin/deployment.yaml | k8s配置文件 |
配置文件列表
```
did-admin
├── deployment.yaml
└── etc
└── did-admin.yaml
```
#### 配置
##### 配置did-admin.yaml
需根据自身需要修改did-admin/etc/did-admin.yaml，如下所示：
DID服务地址
```
...
# did服务地址
GrpcTarget: did-service:17787
...
```
#### 部署步骤
##### 进入到目录
```
cd did-admin
```
##### 部署到Kubernetes集群
使用\`kubectl create\` 命令创建挂载的map文件：
```
kubectl create cm did-admin-configmap-yml --from-file=./etc/did-admin.yaml --dry-run=client -o yaml > did-admin-configmap-yml.yaml --insecure-skip-tls-verify
```
使用\`kubectl apply\` 命令应用map文件：
```
kubectl apply -n=did -f did-admin-configmap-yml.yaml --insecure-skip-tls-verify
```
使用\`kubectl apply\` 命令部署资源定义文件到Kubernetes集群：
> 如果该步骤拉不到镜像请参考附录[kubectl操作指南](../tech/01_kubectl%E6%93%8D%E4%BD%9C%E6%8C%87%E5%8D%97.md)
```
kubectl apply -n=did --force -f deployment.yaml --insecure-skip-tls-verify
```
##### 验证部署检查Pod状态，确保DID服务已成功启动并运行
利用\`kubectl get\` 命令查看服务是否启动
```
kubectl get pod -n did | grep did-admin
```
返回结果如下，1/1则表示微服务有一个实例，启动成功1个pod实例，如果是2/2则表示有两个实例，启动成功了2个pod实例。
```
did-admin-XXXXX-XXX 1/1 Running 0 1d
```
检查Service和Ingress资源配置，保外部访问路径和端口正确：
```
kubectl get svc,ing -n did | grep did-admin
```
利用health接口验证是否部署成功（ip为k8s work的地址, host为端口号）
```
http://ip:host/api/v1/did/health
```
结果如下：
```
{"code":200000,"msg":"操作成功","data":{"version":"v1.0.0","name":"did-admin","buildTime":"2024-04-11T08:13:36Z","gitCommit":"ec0cc7a","gitBranch":"develop","startTime":"2024-04-11T16:14:20+08:00","now":"2024-04-11T16:16:55+08:00"}
```
#### 签发VC
以上步骤全部完成，需要对`did:cndid:cndid`签发VC
请参考[签发VC](../tech/02_%E7%AD%BE%E5%8F%91VC.md)文档
## 网关服务（did-gateway）
### 硬件配置
| 配置 | 最低配置 | 推荐 |
|-----|-------|-------|
| CPU | 1.5Hz | 2.4Hz |
| 内存 | 8G | 16G |
| 核心 | 4核 | 8核 |
| 带宽 | 2Mb | 10Mb |
### 软件环境准备
| 软件 | 版本 | 描述 |
|-----------|----------|----|
| k8s | v1.18+ | |
| kubectl工具 | 与k8s集群匹配 | |
### 安装物料
| 软件 | 描述 |
|-----------------------------|-----------------|
| did-gateway/etc | did-gateway配置文件 |
| did-gateway/deployment.yaml | k8s配置文件 |
配置文件列表
```
did-gateway
├── deployment.yaml
└── etc
├── did-gateway.yaml
└── tls
├── server.crt
├── server.csr
└── server.key
```
### 配置
#### 配置did-gateway.yaml
需根据自身需要修改did-gateway/etc/did-gateway.yaml，如下所示：
CA证书和密钥地址
```
...
# Https CA证书
CertFile: ./etc/tls/server.crt
# Https CA密钥
KeyFile: ./etc/tls/server.key
...
```
did-admin服务地址
```
...
# cnbn服务地址
DIDAdmin: did-admin-service:17786
...
```
### 部署步骤
#### 进入到目录
```
cd did-gateway
```
#### 部署到Kubernetes集群
使用\`kubectl create\` 命令创建挂载的map文件：
```
kubectl create cm did-gateway-configmap-yml --from-file=./etc/did-gateway.yaml --dry-run=client -o yaml > did-gateway-configmap-yml.yaml --insecure-skip-tls-verify
kubectl create cm did-gateway-configmap-tls-key --from-file=./etc/tls/server.key --from-file=./etc/tls/server.crt --dry-run=client -o yaml > did-gateway-configmap-tls-key.yaml
```
使用\`kubectl apply\` 命令应用map文件：
```
kubectl apply -n=did -f did-gateway-configmap-yml.yaml --insecure-skip-tls-verify
kubectl apply -n=did -f did-gateway-configmap-tls-key.yaml --insecure-skip-tls-verify
```
使用\`kubectl apply\` 命令部署资源定义文件到Kubernetes集群：
> 如果该步骤拉不到镜像请参考附录[kubectl操作指南](../tech/01_kubectl%E6%93%8D%E4%BD%9C%E6%8C%87%E5%8D%97.md)
```
kubectl apply -n=did --force --record -f deployment.yaml --insecure-skip-tls-verify
```
##### 验证部署检查Pod状态，确保DID服务已成功启动并运行
利用\`kubectl get\` 命令查看服务是否启动
```
kubectl get pod -n did | grep did-gateway
```
返回结果如下，1/1则表示微服务有一个实例，启动成功1个pod实例，如果是2/2则表示有两个实例，启动成功了2个pod实例。
```
did-gateway-XXXXX-XXX 1/1 Running 0 1d
```
检查Service和Ingress资源配置，保外部访问路径和端口正确：
```
kubectl get svc,ing -n did | grep did-gateway
```
利用health接口验证是否部署成功（ip为k8s work的地址，host为端口号）
```
https://ip:host/api/v1/did/health
```
结果如下：
```
{"code":200000,"msg":"操作成功","data":{"version":"v1.0.0","name":"did-gateway","buildTime":"2024-04-11T07:09:18Z","gitCommit":"8263170","gitBranch":"develop","startTime":"2024-04-11T15:13:50+08:00","now":"2024-04-11T15:13:55+08:00"}
```
## 管理台部署文档
### 高可用方案
二进制部署高可用方案，可用虚拟IP加2个负载完成。
- VIP转发到2个nginx
- nginx负载到各个服务
- SDK与DID管理台通过VIP访问
- 各个微服务之间也使用VIP进行访问
#### 硬件配置
| 配置 | 最低配置 | 推荐 |
|-----|-------|-------|
| CPU | 1.5Hz | 2.4Hz |
| 内存 | 8G | 16G |
| 核心 | 4核 | 8核 |
| 带宽 | 2Mb | 10Mb |
#### 软件环境准备
| 软件 | 版本 | 描述 |
|:---------------|:------:|:---------|
| docker | 18+ | 可选 |
| k8s | v1.18+ | 可选 |
| docker-compose | v2.26+ | 可选 |
| redis集群 | 7.2+ | 单机/集群 |
| mysql | v8+ | mysql数据库 |
| 可访问的Docker镜像服务 | - | 存储镜像 |
数据库可选：人大金仓，postgresql等数据库
### docker-compose单机版部署
数据库可选：人大金仓，postgresql等数据库
***安装物料包：***
[物料包](https://chainmaker-1256298121.cos.ap-beijing.myqcloud.com/did-mgr-docker-compose-v1.1.0.tar.gz )
***解压物料包：***
```shell
tar xvf ./did-mgr-docker-compose-v1.1.0.tar.gz
```
##### docker与docker-compose
- 确保已有一个运行中的Docker，版本建议为18或更高。
- 已安装docker-compose命令行工具，用于docker-compose.yml的部署。
##### Docker镜像仓库
-
项目方准备一个公网可访问的Docker镜像仓库，用于存储“DID管理台”微服务的镜像。在后续运行部署流程时会自动拉取，如果Docker所在环境无法访问互联网，需要手动先在可联网的机上从Docker-compose镜像仓库下载并保存镜像文件：
- did-kms.tar
- did-mgr-holder-service.tar
- did-mgr-issuer-service.tar
- did-mgr-common-service.tar
- did-mgr-front.tar
- 将下载的文件转移到Docker所在服务器磁盘，然后载入Docker镜像到服务器。载入命令在物料包中，执行：
```shell
./load_docker_image.sh
```
即可。
#### 部署流程
##### 根据实际需要修改 config 文件
在实际项目使用中可能会存在测试环境、预生产环境、生产环境等多套环境，请根据实际环境的需求调整etc文件夹中yaml配置文件中的参数。
```shell
did-kms-etc
└── kms.yaml
did-mgr-common-service-etc
└── did-mgr-common-service-api.yaml
did-mgr-holder-service-etc
└── holder.yaml
did-mgr-issuer-service-etc
└── vc-issuer-api.yaml
```
**【注意：DID管理台服务在启动时会自动连接数据库并创建对应的表，在配置数据库连接字符串时，请确保数据库已经创建，而且账号具有在该数据库中创建表的DDL权限。】
**
###### 修改kms.yaml
```shell
Name: kms.rpc
ListenOn: 0.0.0.0:17781
Timeout: 30000
DidService: https://192.168.1.181:30032 #修改为真实的DID服务地址
Database:
DbType: "mysql"
DSN: "root:passw0rd@tcp(ip:13306)/kms_database?parseTime=true"
# DbType: "kingbase"
# DSN: "host=192.168.1.181 port=54321 user=SYSTEM password=passw0rd dbname=test sslmode=disable"
```
> 注：DidService表示DID服务，请将该字段修改为真实的DID服务地址。
###### 修改did-mgr-common-service-api.yaml
```shell
Name: did-mgr-common-service-api
Host: 0.0.0.0
Port: 17782
MaxBytes: 5368709120
Timeout: 10000
service:
issuer: did-mgr-issuer-service:17784
holder: did-mgr-holder-service:17783
did: http://192.168.1.181:30002 #修改连接到的DID服务地址
adminUser:
user: admin #修改默认用户名
password: password #修改默认密码
jwt:
expires_time: 7200
issuer: did-mgr-issuer-service:17884
key: "!@#$abcd%^&*++``123" #修改jwt的key
```
> 注：did字段表示DID服务，请将该字段修改为真实的DID服务地址。
###### 修改holder.yaml
```shell
Name: holder
Host: 0.0.0.0
Port: 17783
GrpcTarget: did-kms:17781
DidService: https://192.168.1.181:30003
# mysql链接地址，满足 $user:$password@tcp($ip:$port)/$db?$queries 格式即可
#DataSource: root:passw0rd@tcp(192.168.1.181:13306)/holder_database?parseTime=true
Database:
DbType: "kingbase" #修改为mysql或者kingbase（人大金仓）
DSN: "root:passw0rd@tcp(mysql:3306)/holder_database?parseTime=true"
#连接mysql或者人大金仓的数据库连接字符串
```
> 注：DidService表示DID服务，请将该字段修改为真实的DID服务地址。
###### 修改 vc-issuer-api.yaml
```shell
Name: vc-issuer-api
Host: 0.0.0.0
Port: 17784
Database:
DbType: "mysql" #修改为mysql或者kingbase（人大金仓）
DSN: "root:passw0rd@tcp(mysql-mgr-service:3306)/mgr_issuer?charset=utf8mb4&parseTime=true&loc=Local" #连接mysql或者人大金仓的数据库连接字符串
Issuer:
DID: "" #修改颁发者的DID
IdPrefixUrl: "http://192.168.1.181:30003/api/v1/did/vc/" #修改服务的URL前缀
DID:
Endpoint: "192.168.1.181:30003" #DID服务的IP和端口
KMS:
Endpoints:
- "did-kms:17781" #DID-KMS服务的server和端口
```
> 注：
> - Endpoint字段表示DID服务，请修改为真实的DID服务地址。
> - IdPrefixUrl字段的URL前缀修改为真实的DID服务地址。
> - Endpoints字段表示DID -KMS服务，检查其格式是否如上述所示。
##### 创建Docker容器，部署DID管理台服务
使用`docker-compose`命令部署资源定义文件到docker，以`startAll.sh`启动所有DID管理台微服务为例（包括数据库）：
```shell
docker-compose -f ./db-docker-compose.yml \
-f ./did-kms-docker-compose.yml \
-f ./did-mgr-common-service-docker-compose.yml \
-f ./did-mgr-holder-service-docker-compose.yml \
-f ./did-mgr-issuer-service-docker-compose.yml \
-f ./did-mgr-front.yml \
up -d
```
如果已经提前准备了数据库，无需通过脚本启动数据库那么可以将启动命令改为：
```shell
docker-compose -f ./did-kms-docker-compose.yml \
-f ./did-mgr-common-service-docker-compose.yml \
-f ./did-mgr-holder-service-docker-compose.yml \
-f ./did-mgr-issuer-service-docker-compose.yml \
-f ./did-mgr-front.yml \
up -d
```
##### 检查容器部署状态
执行以下命令，确保“DID管理台”微服务已成功启动并运行：
```shell
docker ps | grep did-kms
```
返回结果如下，则表示启动成功。
```shell
25473b8ce360 hub-dev.cnbn.org.cn:17754/opennet/did-kms:v1.1.0 "./kms" 1 hours ago Up 1 hours 0.0.0.0:17781->17781/tcp, :::17781->17781/tcp
```
##### 访问“DID管理台”
在物料包中提供了checkHealth.sh，运行后可以检查每个服务是否正常运行。其中did-mgr-common-service是对SDK提供服务的网关。
```shell
./checkHealth.sh
```
##### 初始化“DID管理台"数据
打开管理台网站:
http://{NodeIP}:8888
然后注册用户，导入私钥或者企业实名认证生成新私钥，第一个注册的用户将是did管理台的管理员。
> 注：NodeIP默认为localhost
#### 修改配置管理
在DID管理台中，所有配置通过yaml文件进管理，避免在镜像中硬编码配置。当前配置不满足预期，需要进行调整时可根据需要更新*
.yaml中的部分的内容，并使用停止容器然后启动容器以应用新的配置。
```shell
#关闭现有容器
./stopAll.sh
#重新启动容器，将会重新加载配置文件
./startAll.sh
```
#### 服务的升级
当DID管理台微服务有新版本发布时，需要更新对应的镜像和容器。可以执行：
```bash
./upgradeAll.sh
```
更新镜像，重启服务，并检查服务状态。
### k8s集群版部署
#### 软件环境准备
| 软件 | 版本 | 描述 |
|:---------------|:--------:|:---------|
| k8s集群 | v1.18+ | |
| kubectl工具 | 与k8s集群匹配 | |
| redis集群 | 7.2+ | |
| mysql | v8+ | mysql数据库 |
| 可访问的Docker镜像服务 | - | 存储镜像 |
***物料包下载：***
[物料包](https://chainmaker-1256298121.cos.ap-beijing.myqcloud.com/did-mgr-k8s-v1.1.0.tar.gz )
***解压物料包：***
```shell
tar xvf did-mgr-k8s-v1.1.0.tar.gz
```
##### k8s集群
- 确保已有一个运行中的Kubernetes集群，版本建议为v1.18或更高。
- 已安装并配置`kubectl`命令行工具，用于与Kubernetes集群交互。
##### docker 镜像仓库
-
项目方准备一个公网可访问的Docker镜像仓库，用于存储“DID管理台”微服务的镜像。在后续运行部署流程时会自动拉取，如果Kubernetes所在环境无法访问互联网，需要自建Docker镜像仓库服务，并将先在可联网的机上从Docker镜像仓库下载并保存镜像文件：
- did-kms.tar
- did-mgr-holder-service.tar
- did-mgr-issuer-service.tar
- did-mgr-common-service.tar
- did-mgr-front.tar
再载入这些镜像到Kubernetes能访问的自建Docker镜像仓库服务中。
#### 部署流程
##### 配置 namespace.yaml
检查是否存在did namespace，若无记录则创建Namespace
```shell
kubectl get ns|grep did
```
创建 did namespace
```shell
# 创建namespace
kubectl create namespace did
```
##### 根据实际需要修改 ConfigMap
**【注意：DID管理台服务在启动时会自动连接数据库并创建对应的表，在配置数据库连接字符串时，请确保数据库已经创建，而且账号具有在该数据库中创建表的DDL权限。】
**
###### 修改 did-kms-configmap
```shell
apiVersion: v1
data:
kms.yaml: |-
Name: kms.rpc
ListenOn: 0.0.0.0:17781
Timeout: 30000
DidService: https://192.168.1.181:30032
Database:
DbType: "mysql"
DSN: "root:passw0rd@tcp(ip:13306)/kms_database?parseTime=true"
# DbType: "kingbase"
# DSN: "host=192.168.1.181 port=54321 user=SYSTEM password=passw0rd dbname=test sslmode=disable"
kind: ConfigMap
metadata:
name: did-kms-configmap
```
> 注：
> - DidService表示DID服务，请将该字段修改为真实的DID服务地址。
> - DSN字段定义了数据库连接，请修改为真实的数据库连接信息。
###### 修改did-mgr-common-service-configmap
```shell
apiVersion: v1
data:
did-mgr-common-service-api.yaml: |-
Name: did-mgr-common-service-api
Host: 0.0.0.0
Port: 17782
MaxBytes: 5368709120
Timeout: 10000
service:
issuer: http://did-mgr-issuer-service:17884
holder: http://did-mgr-holder-service:17883
did: http://192.168.1.181:30002
adminUser:
user: admin
password: password
jwt:
expires_time: 7200
issuer: did-mgr-issuer-service:17884
key: "!@#$abcd%^&*++``123"
kind: ConfigMap
metadata:
creationTimestamp: null
name: did-mgr-common-service-configmap
```
> 注：
> - did字段定义了DID服务，请将其改为真实的DID服务地址。
> - issuer与holder字段的端口号请依据实际修改。
> - 请修改jwt的key值。
###### 修改did-mgr-holder-service-configmap
```shell
apiVersion: v1
data:
holder.yaml: |-
Name: holder
Host: 0.0.0.0
Port: 27781
GrpcTarget: did-kms-service:17781
Database:
DbType: "mysql"
DSN: "root:passw0rd@tcp(9.135.0.21:3306)/holder_database?parseTime=true"
kind: ConfigMap
metadata:
creationTimestamp: null
name: did-mgr-holder-service-configmap
```
> 注：
> - DSN字段定义了数据库连接，请修改为真实的数据库连接信息。
> - Port定义了holder服务的端口号，其他服务中有关holder信息的配置按照此处填写。
###### 修改did-mgr-issuer-service-configmap
```shell
apiVersion: v1
kind: ConfigMap
metadata:
name: did-mgr-issuer-service-configmap
data:
vc-issuer-api.yaml: |-
Name: vc-issuer-api
Host: 0.0.0.0
Port: 17784
Database:
DbType: "mysql"
DSN: "root:passw0rd@tcp(9.135.0.21:3306)/mgr_issuer?charset=utf8mb4&parseTime=true&loc=Local"
Issuer:
DID: "did:cnbn:b27356b68f224d6394dabb69144bdf7e"
IdPrefixUrl: "http://192.168.1.181:30002/api/v1/did/vc/"
DID:
Endpoint: "192.168.1.181:30032"
KMS:
Endpoints:
- "did-kms-service:17781"
```
> 注：
> - DSN字段定义了数据库连接，请修改为真实的数据库连接信息。
> - DID字段修改为颁发者的DID。
> - IdPrefixUrl字段前缀修改为真实的DID服务地址。
> - Endpoint字段定义了DID服务，请修改为真实的DID服务地址。
###### 修改did-mgr-front-configmap
这里主要是前端网页的Nginx配置，具体如下：
```shell
gzip_types
application/atom+xml
application/javascript
application/json
application/rss+xml
application/vnd.ms-fontobject
application/x-font-ttf
application/x-web-app-manifest+json
application/xhtml+xml
application/xml
application/octet-stream
font/opentype
image/svg+xml
image/x-icon
text/css
text/plain
text/x-component;
server {
listen 8888;
root /usr/share/nginx/html;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_read_timeout 300;
proxy_pass http://192.168.3.170:18782/;
}
}
```
> 注：proxy_pass字段修改为真实的did-mgr-common-service-api服务地址。
##### 部署到k8s集群
使用`kubectl apply`命令部署资源定义文件到k8s集群，以did-kms微服务为例：
```shell
kubectl apply -f did-kms-deployment.yaml
```
##### 检查pod状态
执行下列命令，确保"DID管理台”微服务已成功启动并运行：
```shell
kubectl get pod -n did
```
返回结果如下，1/1则表示微服务有一个实例，启动成功1个pod实例，如果是2/2则表示有两个实例，启动成功了2个pod实例。
```shell
did-kms-XXXXX-XXX 1/1 Running 0 1d
```
检查Service资源配置，保外部访问路径和端口正确：
```shell
kubectl get svc -n did | grep did-kms
```
##### 部署其他微服务
使用相同的方法，运行kubectl apply可以部署剩余的管理台微服务:
```shell
kubectl apply -f did-mgr-common-service-deployment.yaml
kubectl apply -f did-mgr-issuer-service-deployment.yaml
kubectl apply -f did-mgr-holder-service-deployment.yaml
kubectl apply -f did-mgr-front.yaml
```
也可以直接使用`./deployAll.sh`来部署所有的DID管理台微服务。
##### 检查各“DID管理台”微服务
根据各个Service的配置，通过curl或其他HTTP客户端访问“DID理台”的URL:
```shell
curl -s http://{NodeIP}:30782/api/v1/did/health
curl -s http://{NodeIP}:30783/api/v1/did/health
curl -s http://{NodeIP}:30784/api/v1/did/health
```
> 注：NodeIP默认为localhost，端口号请填写真实的服务端口。
>
如果服务正常，那么将返回成功的消息。
##### 初始化did管理台数据
打开管理台网站:
http://{NodeIP}:8888
然后注册用户，导入私钥或者企业实名认证生成新私钥，第一个注册的用户将是did管理台的管理员。
> 注：NodeIP默认为localhost。
#### 配置管理
在DID管理台中，所有配置应通过k8s的ConfigMap进管理，避免在镜像中硬编码配置。当前配置不满足预期，需要进行调整时可执行以下命令进行配置的更新。
- 根据需要更新deployment.yaml中的ConfigMap部分的内容，并使用`kubectl rollout restart`重启Pod以应用新的配置。
```shell
# 载入修改后的配置到k8s
kubectl apply -f deployment.yaml
# 重启对应的微服务，以应用修改后的配置
kubectl rollout restart deployment/did-kms
```
#### 服务升级
当DID管理台微服务有新版本发布时，需要更新对应的镜像和容器。
##### 更新“DID管理台”服务的镜像
更新镜像可以进行如下操作, 以did-kms服务升级为v1.1.1为例:
- 打开did-kms-deployment.yaml，找到其中的
```shell
image: hub-dev.cnbn.org.cn/opennet/did-kms:v1.1.0
```
将其改为：
```bash
image: hub-dev.cnbn.org.cn/opennet/did-kms:v1.1.1
```
##### 更新DID管理台服务的容器
接下来使用以下命令将变更应用到k8s中：
```shell
kubectl apply -f did-kms-deployment.yaml
kubectl rollout restart did-kms
```
即可通知k8s更新pod容器为最新的镜像的实例。
### 二进制单机版部署
本章节适用于企业环境无K8s集群，无Docker,采用单机二进制部署的场景。
#### 软件环境准备
| 软件 | 版本 | 描述 |
|:-----------|:-----:|:-------------------|
| redis集群 | 7.2+ | |
| mysql | v8+ | mysql数据库 |
| Nginx | 1.24+ | |
| Linux部署物料包 | - | did-mgr-bin.tar.gz |
#### 部署流程
##### 解压物料包
[物料包](https://chainmaker-1256298121.cos.ap-beijing.myqcloud.com/did-mgr-bin-v1.1.0.tar.gz )
```shell
tar xvf ./did-mgr-bin-v1.1.0.tar.gz
```
##### 根据实际需要修改config文件
在实际项目使用中可能会存在测试环境、预生产环境、生产环境等多套环境，请根据实际环境的需求调整.yaml配置文件中的参数:
```shell
did-kms-etc
└── kms.yaml
did-mgr-common-service-etc
└── did-mgr-common-service-api.yaml
did-mgr-holder-service-etc
└── holder.yaml
did-mgr-issuer-service-etc
└── vc-issuer-api.yaml
```
**【注意：DID管理台服务在启动时会自动连接数据库并创建对应的表，在配置数据库连接字符串时，请确保数据库已经创建，而且账号具有在该数据库中创建表的DDL权限。】
**
###### 修改kms.yaml
```shell
Name: kms.rpc
ListenOn: 0.0.0.0:17781
Timeout: 30000
DidService: https://192.168.1.181:30032 #修改为真实的DID服务地址
Database:
DbType: "mysql"
DSN: "root:passw0rd@tcp(192.168.1.182:13306)/kms_database?parseTime=true"
# DbType: "kingbase"
# DSN: "host=192.168.1.181 port=54321 user=SYSTEM password=passw0rd dbname=test sslmode=disable"
```
> 注：
> - DidService表示DID服务，请将该字段修改为真实的DID服务地址。
> - DSN字段请修改为真实的数据库连接信息。
###### 修改did-mgr-common-service-api.yaml
```shell
Name: did-mgr-common-service-api
Host: 0.0.0.0
Port: 17782
MaxBytes: 5368709120
Timeout: 10000
service:
issuer: did-mgr-issuer-service:17784
holder: did-mgr-holder-service:17783
did: http://192.168.1.181:30002 #修改连接到的DID服务地址
adminUser:
user: admin #修改默认用户名
password: password #修改默认密码
Database:
DbType: "mysql"
DSN: "root:passw0rd@tcp(192.168.1.182:13306)/en1common_database?parseTime=true"#修改为真实的数据库连接信息
jwt:
expires_time: 7200
issuer: did-mgr-issuer-service:17884
key: "!@#$abcd%^&*++``123" #修改jwt的key
```
> 注：
> - did表示DID服务，请修改为真实的DID服务地址。
> - DSN字段请修改为真实的数据库连接信息。
> - 请修改jwt的key值。
###### 修改holder.yaml
```shell
Name: holder
Host: 0.0.0.0
Port: 17783
GrpcTarget: did-kms:17781
DidService: http://192.168.1.181:30003 #修改连接到的DID服务地址
# mysql链接地址，满足 $user:$password@tcp($ip:$port)/$db?$queries 格式即可
#DataSource: root:passw0rd@tcp(192.168.1.181:13306)/holder_database?parseTime=true
Database:
DbType: "kingbase" #修改为mysql或者kingbase（人大金仓）
DSN: "root:passw0rd@tcp(mysql:3306)/holder_database?parseTime=true" #连接mysql或者人大金仓的数据库连接字符串
```
> 注：
> - DidService表示DID服务，请将该字段修改为真实的DID服务地址。
> - DSN字段请修改为真实的数据库连接信息。
###### 修改vc-issuer-api.yaml
```shell
Name: vc-issuer-api
Host: 0.0.0.0
Port: 17784
Database:
DbType: "mysql" #修改为mysql或者kingbase（人大金仓）
DSN: "root:passw0rd@tcp(mysql:3306)/mgr_issuer?charset=utf8mb4&parseTime=true&loc=Local" #连接mysql或者人大金仓的数据库连接字符串
Issuer:
DID: "" #修改颁发者的DID
IdPrefixUrl: "" #修改服务的URL前缀
DID:
Endpoint: "192.168.1.181:30003" #DID服务的IP和端口
KMS:
Endpoints:
- "did-kms:17781" #DID-KMS服务的server和端口
```
> 注：
> - DidService表示DID服务，请将该字段修改为真实的DID服务地址。
> - DSN字段请修改为真实的数据库连接信息。
> - 修改颁发者的DID。
> - 修改IdPrefixUrl前缀为真实的DID服务地址。
##### 运行二进制，部署DID管理台后台服务
使用`./startAll.sh`命令部署DID管理台服务，以启动所有DID管理台微服务为例（数据库请提前启动好）：
```shell
#!/bin/bash
# Start did-kms and output logs to did-kms.log
nohup ./did-kms -f ./did-kms-etc/kms.yaml > did-kms.log 2>&1 &
# Start did-mgr-holder-service and output logs to did-mgr-holder-service.log
nohup ./did-mgr-holder-service -f ./did-mgr-holder-service-etc/holder.yaml > did-mgr-holder-service.log 2>&1 &
# Start did-mgr-issuer-service and output logs to did-mgr-issuer-service.log
nohup ./did-mgr-issuer-service -f ./did-mgr-issuer-service-etc/vc-issuer-api.yaml > did-mgr-issuer-service.log 2>&1 &
# Start did-mgr-common-service and output logs to did-mgr-common-service.log
nohup ./did-mgr-common-service -f ./did-mgr-common-service-etc/did-mgr-common-service-api.yaml > did-mgr-common-service.log 2>&1 &
echo "All services have been started."
```
##### 检查进程状态
执行完上面的 startAll.sh后，需要执行下面的命令，确认“DID管理台”微服务已成功启动并运行：
```shell
ps aux | grep did
```
返回结果如下，则表示启动成功：
```shell
devinyz+ 3255760 1.6 0.2 2125964 47460 pts/0 Sl 11:31 0:00 ./did-kms -f ./did-kms-etc/kms.yaml
devinyz+ 3255761 1.6 0.3 2171468 57412 pts/0 Sl 11:31 0:00 ./did-mgr-holder-service -f ./did-mgr-holder-service-etc/holder.yaml
devinyz+ 3255762 1.6 0.3 2238116 54528 pts/0 Sl 11:31 0:00 ./did-mgr-issuer-service -f ./did-mgr-issuer-service-etc/vc-issuer-api.yaml
devinyz+ 3255763 0.6 0.1 1863036 29528 pts/0 Sl 11:31 0:00 ./did-mgr-common-service -f ./did-mgr-common-service-etc/did-mgr-common-service-api.yaml
```
##### 在Nginx中部署“DID管理台”前端
在物料包中提供了did-mgr-front.tar.gz，解压该物料包：
```shell
tar xvf did-mgr-front.tar.gz
```
将获得dist文件夹和deploy文件夹。
在deploy文件夹中包含Nginx配置文件，复制其到Nginx配置文件夹：
```shell
sudo cp deploy/nginx/conf.d/default.conf /etc/nginx/conf.d
```
dist文件夹为前端相关html、js等文件，修改/etc/nginx/conf.d/default.conf文件，将默认的/usr/share/nginx/html替换为之前解压出来的dist文件夹路径：
```shell
root/data/did-mgr-front/dist;
```
proxy_pass的值为前面部署的did-mgr-common-service的URL，如：
```shell
proxy_pass http://localhost:17782/;
```
判断Nginx服务是否正常启动：
```shell
sudo systemctl status nginx
```
> 注：如果启动失败，请检查Nginx服务日志，排除错误之后重启Nginx服务。
重启Nginx服务，浏览器访问： http://{服务器IP}:8888
即可！
##### 初始化did管理台数据
打开管理台网站:
http://{NodeIP}:8888
然后注册用户，导入私钥或者企业实名认证生成新私钥，第一个注册的用户将是did管理台的管理员。
#### 修改配置管理
在DID管理台中，所有配置yaml文件进管理，避免在镜像中硬编码配置。当前配置不满足预期，需要进行调整时可执行以下命令进行配置的更新。
- 对于后端服务: 根据需要更新*.yaml中的部分的内容，并使用stopAll.sh停止进程,然后启动服务以应用新的配置。
```shell
#关闭现有DID服务
./stopAll.sh
#重新启动DID服务，将会重新加载配置文件
./startAll.sh
```
- 对于前端服务，因为是基于Nginx，请使用Nginx服务的命令进行服务的关闭和重启。
```shell
#关闭Nginx服务
sudo systemctl stop nginx
#重启Nginx服务
sudo systemctl restart nginx
```
#### 服务的升级
当DID管理台微服务有新版本发布时，需要更新对应的二进制。
在服务器上载入最新的物料包，并执行以下命令：
```shell
./upgradeAll.sh
```
系统会自动完成物料包的解压、服务的停止、二进制文件的替换、服务的启动等动作。
## 同步服务部署文档
### 设计方案
子链合约部分我们介绍为了保证子链与主链did 状态数据库一致，我们需要以块为最小单位进行同步迁移。所以我们得到以下同步服务流程：
1) 同步服务监听主链区块
2) 同步服务解析主链区块，并检查是否存在在关注列表的 did topic，存在进入第三步，否则丢弃并回到第一步
3) 同步服务按照主链区块中交易顺序构建 did event 数据 list
4) 同步服务将整理的主链中某个块的 event 数据打包，调用同步合约进行上链操作
5) 子链 did 同步合约将同步服务的 event 数据解包并写入链上
### 部署流程
#### 硬件配置
| 配置 | 最低配置 | 推荐 |
|-----|-------|-------|
| CPU | 1.5Hz | 2.4Hz |
| 内存 | 8G | 16G |
| 核心 | 4核 | 8核 |
| 带宽 | 2Mb | 10Mb |
#### 合约部署
本服务应用前提需要两条 ChainMaker 链，请自行部署搭建，主链安装DID合约，子链安装DID同步合约。
主链DID合约在：[DID合约](https://git.chainweaver.org.cn/chainweaver/did/did-contract/-/tree/master/standard-did)
DID同步合约在：[DID同步合约](https://git.chainweaver.org.cn/chainweaver/did/did-contract/-/tree/v1.2.0_subchain/standard-did)
> 可下载已编译好的文件[同步合约](https://git.chainweaver.org.cn/chainweaver/did/did-contract/-/releases/v1.2.0_sc)
> 进行部署，或根据服务器配置自行编译后部署
请将以上两个合约安装到对应的ChainMaker链上。
#### docker 方式部署
##### 软件依赖
| 名称 | 版本 | 描述 |
|----------------|--------|------------|
| docker | 18+ | 运行服务 |
| docker-compose | v1.26+ | docker部署工具 |
> 注：
>
> - 确保已有一个运行中的Docker，版本建议为18或更高。
> - 已安装docker-compose命令行工具，用于docker- compose.yml的部署。
> - 确保可以从长安链镜像仓库hub-dev.cnbn.org.cn拉取镜像。
##### 创建etc目录，准备配置文件：
配置文件目录结构如下：
```shell
did-sync
├── docker-compose.yml
└── etc
├── config.yaml # 服务配置文件
├── mainchain_user.key # 主链 SDK 客户端用户交易签名私钥
├── sdk_config_mainchain.yml # 主链 SDK 配置文件
├── sdk_config_subchain.yml # 子链 SDK 配置文件
└── subchain_user.key # 子链 SDK 客户端用户交易签名私钥
```
1. 主链 sdk 配置文件：sdk_config_mainchain.yml
2. 子链 sdk 配置文件：sdk_config_subchain.yml
3. 服务配置文件：config.yaml 配置项如下，请根据注释自行调整
> 需确认以下部分：
> 1、syncContract部分：主链did合约名称，若有特殊要求（明确知道需同步数据起止区块高度）可自行配置，默认将同步所有；
> 2、主子链配置文件路径，子链同步合约名称是否正确。
```yaml
system:
env: test
db-type: sqlite
# 日志配置
zap:
# 日志输出级别
level: debug
# 日志格式, json 格式 或者 console
format: console
# 日志输出前缀
prefix: "[did-sync]"
# 日志输出路径
path: ./logs/service.log
# 是否显示代码行号
show-line: true
# 是否打印到控制台
log-in-console: false
# 监听主链did合约信息
syncContract:
# 主链DID合约名称
name: "DID"
topic: #设置为空表示监听当前合约下的所有event
# - "SetDidDocument"
# - "SetTrustRootList"
# - "RevokeVc"
# - "AddBlackList"
# - "DeleteBlackList"
# - "AddTrustIssuer"
# - "DeleteTrustIssuer"
# - "Delegate"
# - "RevokeDelegate"
# - "SetVcTemplate"
# - "VcIssueLog"
# - "DisableVcTemplate"
# - "EnableVcTemplate"
# 如果结束高度设置为-1,则一直同步
endHeight: -1
# 开始同步 主链区块高度
startHeight: 0
# 子链配置信息
subCmSdk:
# DID 同步合约名称
contractName: "DIDSub"
chainConfig:
sdkPath: "./etc/sdk_config_subchain.yml"
chainId: "chain_sub_test"
# 主链配置信息
mainCmSdk:
chainConfig:
sdkPath: "./etc/sdk_config_mainchain.yml"
chainId: "chain_main_test"
```
##### 准备 docker-compose.yml 文件
可自行拉取服务镜像：
```shell
docker pull hub-dev.cnbn.org.cn/opennet/did-sync:v1.2.0_qc
```
docker-compose.yml 文件内容如下：
```yaml
services:
did-sync:
image: hub-dev.cnbn.org.cn/opennet/did-sync:v1.2.0_qc
container_name: did-sync
volumes:
- ./etc:/did-sync/etc
- ./logs:/did-sync/logs
- ./data:/did-sync/data
restart: always
```
##### 使用 `docker-compose` 命令部署资源定义文件到 docker:
```shell
docker-compose -f ./docker-compose.yml up -d
```
##### 验证部署检查容器状态:
```shell
docker ps | grep did-sync
```
返回结果如下，则表示启动成功。
```shell
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
cedf2c8beaf3 hub-dev.cnbn.org.cn/opennet/did-sync:v1.2.0_qc "./did-sync" 4 seconds ago Up 3 seconds did-sync
```
若未成功启动可查看docker容器日志检查原因：
```shell
docker logs did-sync
```
##### 查看服务日志：
```shell
cat ./logs/service.log
```
返回结果如下，则表示启动成功。
```shell
========
_____ _____ _____ _____
| __ \_ _| __ \ / ____|
| | | || | | | | |_____| (___ _ _ _ __ ___
| | | || | | | | |______\___ \| | | | '_ \ / __|
| |__| || |_| |__| | ____) | |_| | | | | (__
|_____/_____|_____/ |_____/ \__, |_| |_|\___|
__/ |
|___/
========
Service Name: DID Sync Service
Version: v1.2.0_qc
Build Time: 2024-08-15 08:07:41
Git Commit: v1.2.0_qc(a8d35d9d)
Start Time: 2024-08-15T16:44:30+08:00
Now Time: 2024-08-15T16:44:30+08:00
2024-08-15 16:44:30.878 [INFO] [did-sync] did-sync/main.go:64 Starting did sync service
```
##### 停止服务：
```shell
docker-compose -f ./docker-compose.yml down
```
若要清空数据请删除 logs目录及 etc 目录下的 sqlite.db 本地数据库文件
#### k8s 部署方式
##### 软件依赖
| 名称 | 版本 | 描述 |
|-----------|----------|------------------|
| docker | 18+ | 拉取镜像使用 |
| k8s | v1.18+ | 服务 Kubernetes 集群 |
| kubectl工具 | 与k8s集群匹配 | |
> 注：
>
> - 确保已有一个运行中的 Kubernetes 集群，版本建议为v1.18或更高
> - 已安装并配置`kubectl`命令行工具，用于与 Kubernetes 集群交互
> - 确保可以从长安链镜像仓库 hub-dev.cnbn.org.cn 拉取镜像
##### 将镜像载入k8s的work节点
项目方准备一个公网可访问的Docker镜像仓库，用于存储DID微服务的镜像。在后续运行部署流程时会自动拉取，如果Kubernetes所在环境无法访问互联网，需要手动载入Docker镜像到Kubernetes的Worker节点，执行如下命令：
```shell
# 手动载入Docker镜像，找个能连hub-dev.cnbn.org.cn的服务器
docker pull hub-dev.cnbn.org.cn/opennet/did-sync:v1.2.0_qc
# 保存文件到本地
docker save -o did-sync-v1.2.0.tar hub-dev.cnbn.org.cn/opennet/did-sync:v1.2.0_qc
# 自行上传文件 did-sync-v1.2.0.tar 到Kubernetes的Worker节点服务器
# Kubernetes的Worker节点服务器载入镜像
docker load -i did-sync-v1.2.0.tar
#查看是否载入成功
docker images | grep hub-dev.cnbn.org.cn/opennet/did-sync
# 若显示如下说明成功
hub-dev.cnbn.org.cn/opennet/did-sync v1.2.0_qc cdf19ec76c3a 2 hours ago 190MB
```
##### 准备 deployment.yaml 配置文件
配置文件目录结构如下：
```shell
did-sync
└── deployment.yaml
```
deployment.yaml 文件内容如下，请自行修改 ConfigMap 配置相关内容：
> 注：
>
> - config.yaml 为服务配置文件，请确认简单主链did合约信息、同步合约名称和主子链配置（sdk_config文件路径）是否正确
> - *.key 文件为用户私钥，sdk_config.yml 文件为链 SDK 配置文件 请确保内容正确
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
creationTimestamp: null
name: did-sync-configmap
data:
# 服务配置
config.yaml: |+
system:
env: test
db-type: sqlite
# 日志配置
zap:
# 日志输出级别
level: debug
# 日志格式, json 格式 或者 console
format: console
# 日志输出前缀
prefix: "[did-sync]"
# 日志输出路径
path: ./logs/service.log
# 是否显示代码行号
show-line: true
# 是否打印到控制台
log-in-console: false
# 监听主链did合约信息
syncContract:
# 主链DID合约名称
name: "DID"
topic: #设置为空表示监听当前合约下的所有event
# - "SetDidDocument"
# - "SetTrustRootList"
# - "RevokeVc"
# - "AddBlackList"
# - "DeleteBlackList"
# - "AddTrustIssuer"
# - "DeleteTrustIssuer"
# - "Delegate"
# - "RevokeDelegate"
# - "SetVcTemplate"
# - "VcIssueLog"
# - "DisableVcTemplate"
# - "EnableVcTemplate"
# 如果结束高度设置为-1,则一直同步
endHeight: -1
# 开始同步 主链区块高度
startHeight: 0
# 子链配置信息
subCmSdk:
# DID 同步合约名称
contractName: "DIDSub"
chainConfig:
sdkPath: "./etc/sdk_config_subchain.yml"
chainId: "chain_sub_test"
# 主链配置信息
mainCmSdk:
chainConfig:
sdkPath: "./etc/sdk_config_mainchain.yml"
chainId: "chain_main_test"
mainchain_user.key: |
-----BEGIN PRIVATE KEY-----
MIGTAgEAMBMGByqGSM49AgEGCCqBHM9VAYItBHkwdwIBAQQgelqvKuVT3RMtKqC3
ZCJI4Tac8tYkS50erVjLPe+rhBegCgYIKoEcz1UBgi2hRANCAARe9ivpYoa0yirj
VPmCAm8XYbqhuj2RWdPhTr81/B15t/0Zp/oL0g48l4vWp/89X3n9S94g2VIYECbN
VpYRWCRs
-----END PRIVATE KEY-----
sdk_config_mainchain.yml: |
chain_client:
# 链ID
chain_id: "chain_main_test"
# 客户端用户交易签名私钥路径
user_sign_key_file_path: "./etc/mainchain_user.key"
# 客户端用户交易签名私钥密码(无密码则不需要设置)
# user_sign_key_pwd: "123"
# 签名使用的哈希算法，和节点保持一直
crypto:
hash: SM3
auth_type: public
# 同步交易结果模式下，轮询获取交易结果时的最大轮询次数，删除此项或设为<=0则使用默认值 10
retry_limit: 20
# 同步交易结果模式下，每次轮询交易结果时的等待时间，单位：ms 删除此项或设为<=0则使用默认值 500
retry_interval: 500
# txid配置项：默认支持TimestampKey，如果开启enableNormalKey则使用NormalKey
enable_normal_key: false
nodes:
- # 节点地址，格式为：IP:端口:连接数
node_addr: "127.0.0.1:12391"
# 节点连接数
conn_cnt: 10
rpc_client:
max_receive_message_size: 100 # grpc客户端接收消息时，允许单条message大小的最大值(MB)
max_send_message_size: 100 # grpc客户端发送消息时，允许单条message大小的最大值(MB)
send_tx_timeout: 60 # grpc 客户端发送交易超时时间
get_tx_timeout: 60 # rpc 客户端查询交易超时时间
sdk_config_subchain.yml: |
chain_client:
# 链ID
chain_id: "chain_sub_test"
# 客户端用户交易签名私钥路径
user_sign_key_file_path: "./etc/subchain_user.key"
# 客户端用户交易签名私钥密码(无密码则不需要设置)
# user_sign_key_pwd: "123"
# 签名使用的哈希算法，和节点保持一直
crypto:
hash: SM3
auth_type: public
# 同步交易结果模式下，轮询获取交易结果时的最大轮询次数，删除此项或设为<=0则使用默认值 10
retry_limit: 20
# 同步交易结果模式下，每次轮询交易结果时的等待时间，单位：ms 删除此项或设为<=0则使用默认值 500
retry_interval: 500
# txid配置项：默认支持TimestampKey，如果开启enableNormalKey则使用NormalKey
enable_normal_key: false
nodes:
- # 节点地址，格式为：IP:端口:连接数
node_addr: "127.0.0.1:12395"
# 节点连接数
conn_cnt: 10
rpc_client:
max_receive_message_size: 100 # grpc客户端接收消息时，允许单条message大小的最大值(MB)
max_send_message_size: 100 # grpc客户端发送消息时，允许单条message大小的最大值(MB)
send_tx_timeout: 60 # grpc 客户端发送交易超时时间
get_tx_timeout: 60 # rpc 客户端查询交易超时时间
subchain_user.key: |
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIMiaCfztbtenIgNHKjqFHtgJy9B3cyWVLIfM0bFn86pUoAoGCCqGSM49
AwEHoUQDQgAEjXCPDCb9TjjPCKDSo85EDRr7El79ZpWR9xeu9zMidwDcF3U4Zt1u
AudJ3nLiANAxRsKqPmXIiAu5kOF9Svrd8Q==
-----END EC PRIVATE KEY-----
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: did-sync
spec:
replicas: 1
selector:
matchLabels:
app: did-sync
template:
metadata:
labels:
app: did-sync
spec:
containers:
- name: did-sync
image: hub-dev.cnbn.org.cn/opennet/did-sync:v1.2.0_qc
volumeMounts:
- name: config-volume
mountPath: /did-sync/etc
volumes:
- name: config-volume
configMap:
name: did-sync-configmap
```
##### 部署到 Kubernetes 集群
使用`kubectl apply`命令部署资源定义文件到 Kubernetes 集群：
```shell
kubectl apply -f ./deployment.yaml
```
验证部署检查Pod状态，确保 DID 同步服务已成功启动并运行：
```shell
kubectl get pods | grep did-sync
```
返回结果如下，1/1则表示微服务有一个实例，启动成功1个pod实例。
```shell
NAME READY STATUS RESTARTS AGE
did-sync-xxxxx-xxx 1/1 Running 0 2s
```
若未成功启动可查看 k8s pod检查原因：
```shell
# 查看pod详情
kubectl describe pod did-sync-xxxxx-xxx
# 查看pod日志
kubectl logs did-sync-xxxxx-xxx
```
服务启动后进入服务查看运行日志：
```shell
# 进入服务pod
kubectl exec -it did-sync-xxxxx-xxx -- /bin/sh
# 查看日志
tail -f ./logs/service.log
```
##### 停止服务：
```shell
kubectl delete -f ./deployment.yaml
```
## APP后端服务部署
### 后端 k8s部署方式
#### 硬件配置
| 配置 | 最低配置 | 推荐 |
|-----|-------|-------|
| CPU | 1.5Hz | 2.4Hz |
| 内存 | 8G | 16G |
| 核心 | 4核 | 8核 |
| 带宽 | 2Mb | 10Mb |
#### 软件环境准备
| 软件 | 版本 | 描述 |
|:---------------|:------:|:-----------|
| docker | 18+ | docker容器服务 |
| docker-compose | v1.26+ | |
| redis集群 | 7.2+ | |
| mysql | V8+ | mysql数据库 |
| 可访问的Docker镜像服务 | - | 存储镜像 |
数据库可选：人大金仓，postgresql等数据库
##### Kubernetes集群
- 确保已有一个运行中的Kubernetes集群，版本建议为v1.18或更高。
- 已安装并配置`kubectl`命令行工具，用于与Kubernetes集群交互
##### Docker镜像仓库
- 项目方准备一个公网可访问的Docker镜像仓库，用于存储“DID APP后台”微服务的镜像。在后续运行部署流程时会自动拉取。
- 如果Kubernetes所在环境无法访问互联网，需要手动载入Docker镜像到Kubernetes的Worker节点。载入命令在物料包中，执行以下流程:
```shell
docker pull hub-dev.cnbn.org.cn/opennet/did-app-backend:v1.1.0
docker save did-app-backend-v1.1.0.tar hub-dev.cnbn.org.cn/opennet/did-app-backend:v1.1.0
# 上传文件 did-app-backend-v1.1.0.tar 到服务器
docker load -i did-app-backend-v1.1.0.tar
```
#### 部署流程
- 下载部署仓库： https://git.chainweaver.org.cn/chainweaver/did/did-app-backend
- 在下载的仓库的k8s目录下，即是k8s的部署did-app-backend-deployment.yaml，该文件是服务的部署文件，也是did-app-backend-configmap配置文件
【注意:DID APP后台服务在启动时会自动连接数据库并创建对应的表，在配置数据库连接字符串时，请确保数据库已经创建，而且账号具有在该数据库中创建表的DDL权限】
##### 根据实际需要修改ConfigMap
在实际项目使用中可能会存在测试环境、预生产环境、生产环境等多套环境，请根据实际环境的需求调整ConfigMap中的参数，如复制份数、日志输出等。
##### 修改did-app-backend-configmap
修改did-app-backend-deployment.yaml中的ConfigMap配置(以下是一些关键的配置描述):
- mysql：改为实际的数据库的服务配置
```shell
mysql:
#数据库类型 mysql、kingbase
db_type: "mysql"
#数据库服务登录信息
dsn: root:passw0rd@tcp(192.168.1.35:3311)/did_app?charset=utf8&parseTime=True&loc=Local
max_idle_conns: 10
max_open_conns: 100
time_out: 20
```
- email_auth_code：改为实际发邮件的服务配置
```shell
email_auth_code:
#邮箱服务配置
host: "xxx"
#邮箱服务端口
port: 11465
#邮箱服务账号
username: "xxx"
#邮箱服务密码
passwd: "xxx"
#邮箱服务发件人
from: "xxx"
#邮箱验证码有效期
expiration_time: 300
#邮箱验证码发送间隔
send_time: 60
#邮箱验证码长度
size: 6
```
- auth_code：改为实际下发短信的服务配置
```shell
# 腾讯云下发短信信息
auth_code:
# 腾讯云短信服务配置,一般是sms.tencentcloudapi.com
domain: xxx
# 腾讯云短信服务代理地址,如果是内网无法连接互联网，可以设置代理地址
proxy: ""
# 腾讯云短信服务密钥id
secret_id: xxx
# 腾讯云短信服务密钥
secret_key: xxx
# 短信验证码有效期
expiration_time: 300
# 短信验证码发送间隔
send_time: 60
# 短信验证码长度
size: 6
# 短信模板(腾讯云短信服务申请的模版)
template:
# 通用模板您正在操作xxx，验证码为： {1}，请于5分钟内填写，如非本人操作，请忽略本短信。
default: xxx
# 邀请码短信：
#您的同事（手机号：{1}）已在「xxx平台」创建了企业账号，并将您设置为{2}，请登录账号，选择「认领新的管理员身份」。 登录手机号：{3} 登录密码 ：{4}
invitation: xxx
# 腾讯云短信服务appid
app_id: xxx
# 短信发送者(可配置成如xxx平台)
sign_name: xxx
```
- RedisConf：改为实际缓存数据库的服务配置
```shell
RedisConf:
# redis模式,如node、cluster
Type: node
# redis地址
Host: 192.168.3.170:16379
# redis密码
Pass: passw0rd
```
- did：改为实际did-admin服务地址
```shell
# did-admin服务配置
did:
# did-admin核心服务地址
urlAddr: http://did-admin-service:17781
```
- auth_service：电子营业执照调用参数配置
```shell
auth_service:
# 是否开启mock.
# false: 真实调用
# true: mock调用，使用模拟数据进行实名认证
mock: true
# 电子营业执照服务地址
url: xxx
# 如果是内网无法连接互联网，可以设置代理地址
proxy: ""
# 电子营业执照服务sys code
sys_code: xxx
# 电子营业执照服务auth code
auth_code: xxx
# 暂时不需要，任意配置即可
sign: xxx
# 版本，目前配置为1
version: 1
```
##### 部署到Kubernetes集群
- 使用`kubectl apply`命令部署资源定义文件到Kubernetes集群:
```shell
kubectl apply -f did-app-backend-deployment.yaml
```
##### 验证部署检查Pod状态，确保DID APP后台微服务已成功启动并运行
- 利用`kubectl get` 命令查看服务是否启动
```shell
kubectl get pod -n did| grep did-app
```
返回结果如下，1/1则表示微服务有一个实例，启动成功1个pod实例，如果是2/2则表示有两个实例，启动成功了2个pod实例:
```shell
did-app-XXXXX-XXX 1/1 Running 0 1d
```
检查Service和Ingress资源配置，保外部访问路径和端口正确:
```shell
kubectl get svc,ing -n did| grep did-app
```
- 利用health接口验证是否部署成功(ip为k8s work的地址，host为端口号)
```shell
curl -X GET https://ip:host/api/v1/did-app/health
```
返回结果如下，表示部署成功:
```shell
{"code":200000,"msg":"操作成功","data":{"version":"v1.0.0","app_chinese_name":"航运贸易app","didIssuer":"did:cndid:cndid","personAuthEnable":false,"downloadLink":"https://zxchain-wallet-1258344699.cos.ap11.apk"}}
```
## APP应用编译
### 简介
航运贸易APP是一款使用flutter构建的移动端APP，在运行源码前需要安装并下载flutter相关SDK。
> flutter 开发文档：https://docs.flutter.dev/
### 准备工作
- 按照官方文档提示安装flutter并完成相关设置。
- 由于本app目前仅支持Android，所以可以忽略IOS相关配置。
- 推荐使用VSCode编辑器，需安装flutter和dart相关插件。
### SDK版本要求
| SDK | 版本号 |
|--------------|---------------|
| Flutter SDK | >= 3.22.2+ |
| Dart SDK | 3.3.0+ 4.0.0- |
| Android SDK | 34.0.0+ |
以上版本供参考，可根据官方文档提示适当升级。
### 源码下载和运行
- 源码地址：https://git.chainweaver.org.cn/chainweaver/did/did-app-front 。
- 源码下载完成后可用VSCode打开。
- 运行以下命令安装依赖：
```shell
flutter pub get
```
- 点击VSCode左侧【运行和调试】按钮启动项目。
### 修改配置文件
- 配置文件地址：`lib/utils/const/const.dart`;
- 配置解释：
```shell
static String env = 'dev'; //修改此处env变量，改变app运行环境
static dynamic byEnv({dynamic dev, dynamic preview, dynamic production}) {
return env == 'dev' ? dev : (env == 'preview' ? preview : production);
}
//设置服务地址
//app的后端服务
static String didAppBaseUrl = byEnv(
dev: "http://dev.com", //开发环境
preview: 'https://preview.cn', //预览环境
production:
'https://production.cn' //生产环境
);
//存证后端服务
static String didAuthAppBaseUrl = byEnv(
//存证2的公共存证的测试环境的访问方式
dev: "http://192.168.1.135:8280",
preview: 'https://tdh-api-pre.cnbn.org.cn',
production: 'https://tdh-api.cnbn.org.cn:19981');
```
### 准备证书
- 准备有效的Android证书
- 使用debug启动模式（即直接使用VSCode进行编译）可以不用证书，注释下方代码中debug配置即可，配置文件地址：
`android/app/build.gradle`：
```gradle
signingConfigs{
release { //配置证书
storeFile file("cdid.android.keystore")
storePassword "chainmaker"
keyPassword "chainmaker"
keyAlias "cdid"
}
buildTypes {
release {
signingConfig signingConfigs.release
minifyEnabled true
proguardFiles '../proguard-rules.pro'
shrinkResources true
}
//没有证书，运行debug模式删除此配置即可
debug {
signingConfig signingConfigs.release
}
}
```
### 编译和安装
- 编译：在根目录下执行以下命令：
```shell
flutter build apk --obfuscate --split-debug-info=./split_debug_info.
```
- 编译完成后，在`/build/app/outputs/flutter-apk`目录下会生成名为`app-release.apk`的文件。
- 安装：安装此apk。
### 调试模式
- 启动调试模式：app安装完成后打开，在开屏页多次点击【欢迎使用】文字，进入项目后，浮动展示`bug`图标，表示进入了调试模式。
- 点击`bug`图标可以查看当前的请求及错误日志等信息。