unicloud-private-env.md

# uniCloud 软件版

## 产品介绍

[uniCloud官网](https://doc.dcloud.net.cn/uniCloud/)介绍的uniCloud，默认都是`uniCloud serverless版`。

`uniCloud serverless版`基于云计算的`serverless`技术实现，后端逻辑代码运行在云厂商的公有云服务器（容器）中，服务器（容器）不跟具体开发者关联绑定，会随着终端用户量的变化自动弹性增减或收缩，开发者对服务器的具体型号、配置等无感。

现实中，部分开发者因合规要求（如数据必须在公司内网），或需要对后端服务器有更强的可控性，希望uniCloud能部署在自己机房内或自己的云厂商账号下，因此，`uniCloud软件版`应运而生。

### uniCloud软件版有哪些特点？

从开发工具、API、生态各维度，软件版和serverless版没有差别。开发者基于serverless版编写的uniCloud项目源码，可以平滑部署到软件版，前端uni-app代码、后端云函数、云对象等代码，均无需修改。

相比serverless版，`软件版`最主要的差别如下：
- 开发者需要单独购买服务器，自己安装操作系统（目前仅支持`linux`操作系统）；
- 开发者自己购买云存储、开通CDN加速产品；
- 开发者自己安装数据库，或者购买mongodb实例；
- 开发者自己处理负载均衡，自己负责日常运维。

而如上工作，`serverless版`均无需进行，serverless版通过`服务空间`的概念，将云函数、云存储、云数据库统一封装，开发者可一键开通所有业务，不需要额外去开通云存储及CDN，也无需去安装或购买云数据库实例。

进一步解释，uniCloud软件版实际上是一个`支持uniCloud语法的Node开发框架`。

你可以更具象化理解：uniCloud软件版就是`支持uniCloud语法的类Egg.js框架`。

> 和Egg.js框架差异：uniCloud软件版内置有定制版本的Node.js运行时，并且仅可在内置的定制Node.js上运行，不支持使用开发者安装的Node.js环境。

uniCloud软件版，作为一个开发框架，仅负责云函数、云对象的执行，支持在云函数中连接开发者自己的对象存储和数据库。而这些对象存储和数据库，需要开发者自己去购买开通，uniCloud软件版本身没有内置。

存储方面，uniCloud软件版目前支持如下3种存储方案：
- 本地存储：文件存储和uniCloud软件版在同一台服务器上；
- 阿里云OSS
- 腾讯云COS

数据库方面，uniCloud软件版仅支持`mongodb`，支持本地服务器上安装的mongodb，也支持在云厂商购买单独的mongodb实例。

## 安装指南

::: warning 注意
1. 为了与serverless版保持一致，软件版目前仅支持`mongo 4.0` 版本
2. uniCloud软件版内置的定制`node.js`版本为`16.20.2`
:::

### 获取安装软件

uniCloud软件版是付费软件，你需要先发邮件到`bd@dcloud.io`，通过商务采购后才能获得。

获得安装软件后，你需要将安装包上传到自己的服务器，然后登录服务器，进行文件解压；

```
# 创建uniCloud目录，需要root用户权限
mkdir /uniCloud
# 解压安装包
tar -zxvf [version].tar.gz -C /uniCloud
```


### 获取激活license

uniCloud软件版的license是和服务器硬件绑定的，激活软件之前需要先执行扫描操作：
- 下载[uniCloud-scan](https://web-ext-storage.dcloud.net.cn/unicloud/private/tools/get-hardware-id)
- 上传 uniCloud-scan到服务器
- 在服务器上执行`./uniCloud-scan`
- 将扫描结果发给DCoud商务经理，由DCloud侧生成`LICENSE`文件
- 将`LICENSE`文件上传至`/uniCloud/`目录下

### 启动/关闭软件

> 所有命令请在软件版环境根目录运行

启动

`./unicloud start -s [服务空间ID]`

停止

`./unicloud stop -s [服务空间ID]`


## 开发指南

### 创建服务空间

为了和serverless版保持一致的开发体验，你需要创建服务空间：
- 登录[uniCloud控制台](https://unicloud.dcloud.net.cn/) 创建DCloud服务空间，复制新建空间的SpaceId
- 登录部署uniCloud软件版的服务器，创建空间目录：
```
cd /uniCloud/spaces/
mkdir [SpaceId]
```

### 配置服务空间

在你的服务空间目录下创建`config.json`配置文件，文件内容如下：

```json
//下方为配置示例，如拷贝此内容切记去除注释
{
  "default": true, //是否为默认服务空间，一套uniCloud软件版环境下，只能有一个默认服务空间
  "spaceId": "pvt-xxx",//DCloud服务空间编号，可在uniCloud控制台查看
  "startAsDaemon": true, // 是否在后台运行; 默认 true
  "port": 7001, //端口号，可自定义，同一台服务器下，各服务空间的端口号不可重复
  "clientSecret": "xxx",//客户端通讯密钥
  "mongodb": { //mongo数据库连接配置
    "url": "mongodb://username:password@127.0.0.1:7001",//mongo数据库连接
    "database": "test", //数据库名称
    "maxPoolSize": 30, //最大连接数
    "minPoolSize": 10 //最小连接数
  },
  "storage": {//存储服务配置，如项目未使用存储服务可不配置此项
    "provider": "local",//服务商 支持local:本地存储 aliyun: 阿里云存储服务 tencent:腾讯云存储服务
    "dir": "file/upload", //文件上传目录
	"bucket": "",//存储桶名称，本地存储无需配置此项
    "cdnProtocol": "http://",//cdn协议 支持 http https
    "cdnDomain": "127.0.0.1:7001",//cdn域名
    "cdnRootPath": "/storage/file/",//cdn根目录
    "storageSecret": "xxxxxxxxxx",//本地存储服务访问密钥
  },
  "logger": { //日志服务配置
    "customLogDir": "/private-cloud-env/logs" //uniCloud软件版环境日志存储路径
  },
  "redis": {//redis库配置，如项目未使用redis服务可不配置此项
    "host": "127.0.0.1",//redis连接
    "port": 6379,//端口号
    "password": ""//密码
  },
  "spaceSecret": { //服务空间通讯配置
	"secretKeyId": "xxxx", //SpaceKeyID，可在uniCloud控制台查看
	"secretKey": "xxx" //SpaceSecret ，可在uniCloud控制台查看
  }
}
```

如项目中使用了存储服务，则还需额外增加存储服务的配置项。既在服务空间目录下创建`file`目录，并在`file`目录下增加`permission.json`配置文件。配置文件内容如下：

```json
//下方为配置示例，如拷贝此内容切记去除注释
{
  "*": {
    "read": true, //读权限
    "update": false,//修改权限
    "create": true,//创建权限
    "delete": "auth.uid == resource.uid"//删除权限
  }
}
```


### 使用HBuilerX开发调试

> 软件版暂不支持`oss`、`cos`等存储服务的本地调试。

#### 安装override插件包

软件版环境的`mongo`、`redis`等数据库是由开发者自行购买或安装的，因此要想在`HBuilderX`中连接这些服务，需安装相关的插件包和npm依赖，并为项目添加数据库等服务的配置文件。

1. 下载并解压`override插件包`，插件包可联系`DCloud`工作人员获取。

2. 将`override插件包`目录内的文件，移至`HBuilderX安装目录/plugins/unicloud/override`目录下。

3. 安装`mongo`、`redis`数据库依赖：在`HBuilderX安装目录/plugins/unicloud`目录下，分别执行 `npm install mongodb@3.6.3` 和 `npm install redis@3.1.2`。


#### 关联服务空间

`HBuilderX`中运行`uniCloud项目`，必须关联服务空间，但HBuilderX暂不支持关联DCloud服务空间，此时你需要按照如下操作进行：
- 创建一个免费的公有云服务空间，仅做为关联使用，无需担心费用；
- 修改配置文件：`vue2项目`的配置文件为：`vue.config.js`，`vue3项目`的配置文件为：`vite.config.js`，内容如下：

```js
//客户端DCloud服务空间连接配置示例
process.env.UNI_CLOUD_PROVIDER = JSON.stringify([{
	provider: 'dcloud',//声明为DCloud服务空间
	spaceName: 'private-space',//服务空间名称
	spaceId: 'pvt-xxx', //服务空间编号
	clientSecret: 'ba461799-fde8-429f-8cc4-4b6d306e2339',//客户端通讯密钥
	endpoint: 'http://127.0.0.1:7001'//DCloud服务空间的访问地址
}])
```

关于spaceId、clientSecret等DCloud服务空间相关信息，可在[uniCloud控制台](https://unicloud.dcloud.net.cn/)查看。

HBuilderX会尽快发版，支持关联DCloud服务空间。

#### 配置数据库链接

在项目中的`uniCloud目录`下新建`config.json`文件，并按需添加配置项。

```json
//下方为配置示例，如拷贝此内容切记去除注释
{
	"mongodb": { //mongo库连接配置
	  "url": "mongodb://username:password@127.0.0.1:7001",//mongo库连接地址
	  "database": "unicloud" //数据库名称
	},
	"redis": {//redis库连接配置，项目中不使用redis服务可不配置此项
	  "host": "127.0.0.1",//host
	  "port": 6379, //端口号
	  "password": "password"//密码
	}
}
```

#### 重启HBuilderX

以上步骤完成后，需重启`HBuilderX`后方可生效。

## 运维指南

### 域名解析及代理配置

项目测试期或上线后，通常需要以域名代替ip来访问服务空间中的云函数/云对象。下面我们提供了一个简单的域名解析和代理配置示例。配置生效后，可用`test.pvtcloud.com`代替原本的`127.0.0.1:7001`来访问服务空间中的云函数/云对象。

以`nginx`为例，配置如下：

```conf
server {
	listen        80;
	server_name  test.pvtcloud.com;
	root   D:/www/test.pvtcloud.com;
	location / {
		try_files $uri $uri/ /index.html;
	}
	location ~ (/client|/http/) {
		proxy_http_version 1.1;
		proxy_set_header Connection "keep-alive";
		proxy_set_header X-Real-IP $clientRealIp;
		proxy_set_header X-Real-PORT $remote_port;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header Host $http_host;
		proxy_set_header Scheme $scheme;
		proxy_set_header Server-Protocol $server_protocol;
		proxy_set_header Server-Name $server_name;
		proxy_set_header Server-Addr $server_addr;
		proxy_set_header Server-Port $server_port;
		proxy_pass http://127.0.0.1:7001;
	}
}

//注意，上述配置中用到的$clientRealIp变量并非是内置变量，需在nginx.conf文件的http模块定义后才可使用，以下为配置示例：
http {
	## Get Client Real IP
	map $http_x_forwarded_for  $clientRealIp {
		""   $remote_addr;
		~^(?P<firstAddr>[0-9\.]+),?.*$  $firstAddr;
	}
}

```


### 防火墙白名单配置

若你的服务器开启了防火墙功能，且需要访问如：`uniCloud软件版(联网版)`、`短信`、`一键登录`、`uni-ai`、`实人认证`、`uni-push`等在线业务，则需要将这些业务的API域名，添加到防火墙白名单中。

以`CentOS系统`为例，配置方式如下

```conf

# 添加域名白名单，实际配置时，请将 “DCloud API域名1/2” 替换为具体域名
sudo firewall-cmd --permanent --zone=public --add-rich-rules='rule family="ipv4" source address="DCloud API域名1" accept'
sudo firewall-cmd --permanent --zone=public --add-rich-rules='rule family="ipv4" source address="DCloud API域名2" accept'
# 添加更多域名...

# 重新加载firewalld配置：
sudo firewall-cmd --reload

```


#### 各业务API域名

- uniCloud软件版(联网版)及付费业务API域名
- - pucoa1.dcloud.net.cn
- - pucoa2.dcloud.net.cn
- - pucoabk.dcloud.net.cn

- uni-push业务API域名
- - restapi.getui.com