应用：实例分发型-边缘托管应用

1.整体流程

一个“实例分发的边缘托管应用”的上线整体流程，包括：应用对接开发、创建应用、应用配置、部署测试、集群管理。

2.对接介绍

1. 拆分应用节点

大部分应用是有不同独立可运行的组件或者模块构成的，这些独立可运行的组件或者模块，我们称为“节点”。比如一个“停车场管理系统”，典型包括：设备控制服务节点、业务管理节点、数据库节点。那么，其第一个是一个运行在jre的jar包、第二个是一个运行在tomcat上的war包、第三个是一个开源的MySQL数据库。此外，拆分节点时，需要注意以下两点：1. 功能相对独立；2. 存储尽量放在数据库节点上。

2. 对业务代码的改造

容器化部署对应用本身的业务逻辑有两个地方的影响，在应用打包成镜像之前（无论后续是否还有其他对接开发导致的调整），请先做好这两方面的改动：

1. 节点之间如何访问：在非容器化前，由于每个节点单独运行在主机上，因此一般情况下，节点之间的访问是通过IP地址来访问的。但是容器化改造之后，由于IP并不确定，因此请使用节点的“服务名称”（服务名称是在可视化编排页面设定的）。

2. 应用初始化信息的获取：应用初始化信息包含两种：应用自身在节点配置中所配置的自定义环境变量、系统分配的一些初始化信息（如AppKey）。这两类信息都位于环境变量中，应用涉及到这两类初始化信息，则需要作此改造。

3. 打包Docker镜像

目前仅支持Linux镜像，打包流程参考线上文档：https://help.aliyun.com/document_detail/114832.html。建议在Linux操作系统上执行打包操作。

4.OAuth对接示例

1.集群内部发起API请求，获取应用App的登录地址。代码示例：

    /**
     * 获取环境变量和回调的url
     * @return
     */
//iot.hosting.api.schema----是请求协议格式http
private static final String API_GATEWAY_SCHEMA = System.getenv("iot.hosting.api.schema");
//iot.hosting.api.domain--是跳转路径的回调ip地址
private static final String API_GATEWAY_DOMAIN = System.getenv("iot.hosting.api.domain");
//iot.hosting.api.port----是请求端口
private static final String API_GATEWAY_SCHEMA = System.getenv("iot.hosting.api.port");
// iot.hosting.appKey----是请求的appkey
private static final String API_GATEWAY_SCHEMA = System.getenv(" iot.hosting.appKey");
//PATH_APP_GET是请求应用app的响应路径
private static final String PATH_APP_GET = "/api/console/app/get";

@Override
    public String getAppIndex() {
        RequestBuilder builder = RequestBuilder.create(METHOD_GET);
        Map<String, String> queryParams = Maps.newHashMap();
        queryParams.put(PARAM_APP_KEY, appKey);

        builder.setUri(HttpUtils.buildUrl(schema, apiGatewayDomain, apiGatewayPort, PATH_APP_GET, queryParams));

        IoTxResult<AppDTO> result = httpProxy.invoke(
                (HttpRequestBase) builder.build(),
                new TypeReference<IoTxResult<AppDTO>>() {
                }
        );

        logger.info("path={}; params={}; result={}", PATH_APP_GET, JSON.toJSONString(queryParams), JSON.toJSONString(result));

        Assert.assertSuccess(result);
        AppDTO app = result.getData();
        return app.getLoginUrl();
    }

请求拼接示例：

http://30.42.XX.XX:32187/api/console/app/get?appKey=2813****

返回结果示例：

{
    {
        "code": 200,
        "data": {
            "aliyunPk": "101248722030****",
            "appKey": "2813****",
            "appMeta": {
                "logoUrl": "http://192.168.11.130:32628/index/28135***",
                "name": "oauth2边缘托管",
                "subVersionId": "1.0",
                "uuid": "937aaa0284864396b54ecadb0d16****",
                "versionUuid": "9ff097f16d8347e6abfcaec0cd14****"
            },
            "appSecret": "NGNiOWQyYzI4MGVhOWNlYmNhOTdmMDIyNTg2Mzlh****",
            "clusterId": "bbeba04d880d49dc80bf83632619****",
            "configName": "oauth2边缘托管",
            "configUuid": "a7b996cd6ab04b7fb3a54abbc81b****",
            "configVersionUuid": "8e43f4d96bef4a289ad9f9af079d****",
            "loginUrl": "http://192.168.XX.XX:30313/index",//应用登录url
            "name": "Oauth2演示",
            "oauth": {
                "path": "/index",
                "port": 8080,
                "protocol": "",
                "serviceName": "edge",
                "serviceUuid": ""
            },
            "type": "GENERAL_APP",
            "uuid": "731082ac0c444053bad624ec915b****"
        },
        "message": "success"
    }
}

2.应用请求控制台地址获取，用于免登跳转地址的获取。

 /**
     *
     * /api/console/host/account
     * @param path
     * @return
     */
    @Override
    public URI getURI(String path) {
        RequestBuilder builder = RequestBuilder.create(METHOD_GET);
        Map<String, String> queryParams = Maps.newHashMap();
        builder.setUri(HttpUtils.buildUrl(schema, apiGatewayDomain, apiGatewayPort, path, queryParams));
        logger.info("RequestBuilder请求url");
        IoTxResult<String> result = httpProxy.invoke(
                (HttpRequestBase) builder.build(),
                new TypeReference<IoTxResult<String>>() {

                }
        );
        logger.info("path={}; params={}; result={}", path, JSON.toJSONString(queryParams), JSON.toJSONString(result));
        Assert.assertSuccess(result);
        try {
            return new URI(result.getData());
        } catch (URISyntaxException e) {
            throw new RuntimeException(e);
        }
    }

请求拼接示例：

http://30.42.XX.XX:32187/api/console/host/account

3.应用请求发起。根据当前登录态，获取authcode,oauth授权的页面，可直接跳过授权页面，请求免登的地址：http://30.42.XX.XX:32187/oauth2/auth? 请求入参：

请求示例：

 http://30.42.XX.XX:32187/oauth2/auth? 
 redirect_uri=http://30.42.XX.XX:32187/index&
 client_id=28135051&state=28135051&
 response_type=code

代码示例：

 /**
     *获取免登url和code
     * @param appKey
     * @param redirectUri
     * @return
     */
    public String getLoginRedirectUrl(String appKey, String redirectUri) {
        Map<String, String> queryParams = Maps.newHashMap();
        queryParams.put(PARAM_CLIENT_ID, appKey);
        queryParams.put(PARAM_REDIRECT_URI, redirectUri);
        queryParams.put(PARAM_RESPONSE_TYPE, "code");

        URI accountUri = getAccountUri();

        return HttpUtils.buildUrl(
                schema,
                accountUri.getHost(),
                accountUri.getPort(),
                PATH_LOGIN,
                queryParams).toASCIIString();
    }

4.跳转redirect_uri获取oauthcode,IoT在验证当前用户合法后，将生成当前用户授权码oauthcode，在回跳redirect_uri地址时通过GET方式传递oauthcode，并同时返回state。返回示例：

http://30.42.XX.XX:32187/index?code=64a67ee15534defea7ad0d0535189b24&state=28135051

5.通过oauthcode换取accessToken,获取OAuth授权code后可通过该接口获取accessToken身份信息，详情请参见链接OAuth对接API。代码示例：

 /**
     * 根据code获取到token
     * @param appKey
     * @param oauthCode
     * @return
     */
    public String getAccessTokenByOauthCode(String appKey, String oauthCode) {
        RequestBuilder builder = RequestBuilder.create(METHOD_GET);

        Map<String, String> queryParams = Maps.newHashMap();
        queryParams.put(PARAM_CODE, oauthCode);
        queryParams.put(PARAM_GRANT_TYPE, "authorization_code");
        queryParams.put(PARAM_CLIENT_ID, appKey);

        URI accountUri = getAccountUri();
        builder.setUri(HttpUtils.buildUrl(accountUri.getScheme(), accountUri.getHost(), accountUri.getPort(), PATH_GET_ACCESS_TOKEN_BY_OAUTH_CODE, queryParams));

        IoTxResult<AccessTokenDTO> result = httpProxy.invoke(
                (HttpRequestBase) builder.build(),
                new TypeReference<IoTxResult<AccessTokenDTO>>() {
                }
        );

        PROXY_LOGGER.info("path={}; params={}; result={}", PATH_GET_ACCESS_TOKEN_BY_OAUTH_CODE, JSON.toJSONString(queryParams), JSON.toJSONString(result));

        Assert.assertSuccess(result);

        AccessTokenDTO accessTokenDTO = result.getData();
        Assert.assertNotNull(accessTokenDTO, "get accessToken failed");
        return accessTokenDTO.getAccessToken();
    }

6.通过accessToken换取用户信息,获取accessToken信息后，可通过accessToken来换取登录用户的用户信息，详情请参见OAuth对接API。代码示例：

/**
     * 根据token获取用户信息
     * @param accessToken
     * @return
     */
    public UserInfoDTO getUserInfoByAccessToken(String accessToken) {
        RequestBuilder builder = RequestBuilder.create(METHOD_GET);

        Map<String, String> queryParams = Maps.newHashMap();
        queryParams.put(PARAM_ACCESS_TOKEN, accessToken);

        URI accountUri = getAccountUri();
        builder.setUri(HttpUtils.buildUrl(accountUri.getScheme(), accountUri.getHost(), accountUri.getPort(), PATH_GET_USER_INFO_BY_ACCESS_TOKEN, queryParams));

        IoTxResult<UserInfoDTO> result = httpProxy.invoke(
                (HttpRequestBase) builder.build(),
                new TypeReference<IoTxResult<UserInfoDTO>>() {
                }
        );

        PROXY_LOGGER.info("path={}; params={}; result={}", PATH_GET_USER_INFO_BY_ACCESS_TOKEN, JSON.toJSONString(queryParams), JSON.toJSONString(result));

        Assert.assertSuccess(result);

        UserInfoDTO userInfoDTO = result.getData();
        Assert.assertNotNull(userInfoDTO, "get userInfo failed");

        return userInfoDTO;
    }

7.accessToken有效性判断,检查当前URL登录的token是否有效， /user/oauth2/accesstoken/check?access_token=xxx。代码示例：

 /**
     * token登录有效期检查
     * @param token
     * @return
     */
    public boolean checkLogin(String token) {
        RequestBuilder builder = RequestBuilder.create(METHOD_GET);

        Map<String, String> queryParams = Maps.newHashMap();
        queryParams.put(PARAM_ACCESS_TOKEN, token);

        URI accountUri = getAccountUri();
        builder.setUri(HttpUtils.buildUrl(accountUri.getScheme(), accountUri.getHost(), accountUri.getPort(), PATH_LOGINCHECK, queryParams));

        IoTxResult<Boolean> result = httpProxy.invoke(
                (HttpRequestBase) builder.build(),
                new TypeReference<IoTxResult<Boolean>>() {
                }
        );

        PROXY_LOGGER.info("path={}; params={}; result={}", PATH_LOGINCHECK, JSON.toJSONString(queryParams), JSON.toJSONString(result));

        Assert.assertSuccess(result);
        return result.getData();
    }

具体oauth-demo参考附件：

5.多副本应用部署

5.1注意事件

1.多副本部署目前仅支持RedisHA和MysqlHA的三方节点进行数据存储，在应用配置可选择副本数。如图所示：2.系统应用如果接入了应用设备，每个应用实例需要有一个独立的设备证书（ProductKey、DeviceName、DeviceSecret）身份，那可能就不能同时运行2个副本的应用。此时cmp的连接会有互踢机制，导致部署失败。3.应用自身存在逻辑问题，举例说明，如下图所示：

3.应用管理

3.1 创建应用

在应用接入 > 创建应用 页面填写应用基本信息，如图所示：

选择应用类型为实例分发，如图所示：

根据应用实际情况选择部署方式与系统类型，如图所示：

• 应用类型：

• 账号分发：用户付款后，只需要交付账号给其使用。

• 实例分发：用户付款后，单独为客户部署一套应用。

• 一次性交付：定制项目或交付型应用。

• 部署方式：

• 云端托管部署：平台根据应用提供者的配置，自动分配资源，并部署应用。

• 边缘托管部署：平台根据应用提供者的配置，自动分配资源，并部署应用到边缘。

3.2 应用配置

创建应用完成后点击初始化应用，填写版本说明，创建应用完成后可以看到版本管理、实例管理、授权实例功能，如图所示：

3.2.1 可视化编排

点击版本管理 > 可视化编排 ，可视化编排是对一个应用的定义。包括一份应用中的节点构成、节点的配置、启动顺序等，如图所示：

注意⚠️，如果需要对接硬件设备，自研节点的主机网络请选择true，表示部署的服务Pod将使用宿主机网段而不是分配给该主机的Overlay网络。

服务类型

ClusterIP：表示节点提供的服务主要对该配置其他节点提供服务，系统会分配一个ClusterIP与节点Service绑定，在overlay网络外不能访问。

LoadBalancer：会从创建集群时提供的服务地址段中分配一个IP绑定到该服务，可以在集群外可通局域网络里访问。

应用配置可视化编辑页面分为三部分内容：

• 左侧部分为节点：显示已支持的各类节点，所有节点配置请查看节点说明。

• 中间部分为画布：显示应用需要的节点及部署顺序关系。注意⚠️，节点间的部署顺序关系，是通过连线来表示的，连线箭头所指节点先部署，连线起点后部署。

• 右侧部分为节点属性：显示某个节点可以配置的参数。

左侧的节点列表，分成了四类：

• 自研节点：用户自己上传的镜像的载体。一份配置，可以又多个自研节点。

• 阿里云节点：一个节点，在应用被部署之后，对应阿里云RDS产品的一个实例（如一个RDS for MySQL数据库实例）。

• 三方节点：各类主流开源中间件Docker镜像。这一类镜像完全来自于第三方，功能、性能、质量、安全等，均保持不变。

• 初始化节点：这类节点属于辅助节点，在整个部署的生命周期，只会执行一次（其他节点通常不止一次，比如节点健康检查失败就会重启）。

3.2.2模型与权限

权限声明

点击版本管理 > 模型与权限 > 权限声明，在应用的分发模式，每一次分发，都有可能归属到不同的买家。因此，每一个应用实例，都需要一个唯一的值来代表应用实例的身份。这里，我们采用了AppKey + AppSecret的模式。随之而来的是，我们如何给AppKey授权。应用在调用IoT的各种API的时候，拿的这个AppKey需要被事先授权。因此，应用上架时，有必要清晰的指出该应用会调用哪些API，这样才能在AppKey产生的那一刻，给他授相应的权限，在此页面可对实例进行授权等操作，如图所示：注意⚠️ 若需要对接数据模型服务需要添加数据模型权限，对接单租户免登，需要开通oauth协议服务权限。

数据模型

点击数据模型 > 添加数据模型，在列表中，除了选择要声明的模型之外，还要选择版本、数据权限、订阅。其中，数据权限有三种：查、增 | 查、增 | 删 | 改 | 查，分别对应不同的操作类型。如图所示：

服务依赖

点击服务依赖 > 添加服务模型（应用为服务依赖方添加，服务提供方无需添加），选择对应的服务模型，并配置服务模型的API，如图所示：

服务提供

点击服务提供 > 添加服务模型（应用为服务提供方添加，服务依赖方无需添加），选择对应的服务模型，并选择相应的端口，如图所示：

3.2.3免登路径

如果需要在边缘控制台中查看已部署的应用信息，则需要配置免登路径，否则边缘控制台的免登跳转会无法识别跳转路径，如图所示：

3.3 实例管理

点击实例管理 > 部署实例，按照界面提示填写参数，如图所示：参数设置如下：

• 单击部署，执行部署任务。

• 部署应用时，需要根据应用配置占用相应的云资源。

• 部署过程可能会花费较长时间，请耐心等待。

• 应用部署成功后，您可以在部署记录页进行查看、运维和删除等操作，详情请参考运维工具文档。

3.4 发布版本

应用部署成功后，可点击发布版本，版本发布后将不能在进行调试、修改、删除等操作，如图所示：

4.云端集群管理

4.1 创建集群

在应用接入 > 集群管理页面填写集群基本信息，如图所示：

• 边缘集群：支持脱离公网，实现集群与应用边对边通讯。

• 智能边缘一体机集群：支持脱离公网，实现集群与应用边对边通讯，同时提供智能边缘一体机集群的集群组件。

• 存储地址：NFS服务器地址。

• 存储路径：NFS Mount路径。

• 服务地址段：边缘可用来分配的边缘服务网段。

建议使用与当前边缘局域网段不同的子网，否则有发生IP冲突的可能性导致服务异常。例如当前主机所在网络为192.168.1.0/24；可在路由器中再添加另一个子网192.168.2.0/24专门用来分配服务VIP。

4.2 创建节点

在管理 > 添加通用节点页面填写节点基本信息，如图所示：

节点名称：与集群名称不同，节点名称会被使用在K8s中，所以对命名有一定要求：只支持数字、小写英文、短划线，不能以短划线开头和结尾，长度限制4-30。节点IP段：节点IP段为当前主机所在网段，需要用户提供以分配对应的Flannel Overlay服务网段。

4.3 加入节点

节点创建完成后点击启动脚本 > 复制脚本到主机命令行执行，若完成，控制台状态将变成运行中，如图所示：

4.4 组件管理（智能边缘一体机集群）

在组件管理 > 初始化集群底座按钮对智能边缘一体机集群提供的集群组件进行初始化，如图所示：

5.边缘集群管理

点击集群管理 > 应用管理 可查看部署在此集群的所有部署的应用列表与提供的集群组件信息，同时可以对已部署的应用进行测试，如图所示：

点击边缘控制台 > 管理复制IP+端口号，打开新的浏览器页面进行访问，使用“超级账户iotedgeadmin”登录“集群控制台”，用户名与密码一致，首次登录强制修改密码。

登录成功后，可点击部署应用的应用卡片，进入应用详情，如图所示：点击账号管理 > 新建账号，添加“集群用户”（用户名、密码、手机号），其中，手机号必填且唯一，并提示用户，手机号是系统之间免登的凭据，如图所示：