如何将Knowage cockpit嵌入HTML 解决嵌入后登录报错问题

直接复制驾驶舱URL通过iframe嵌入会触发Knowage默认的CSRF校验和同源会话限制，会出现重复登录、登录后报错的问题，必须通过官方SDK走授权流程实现嵌入。

1. 前置配置 #

• 登录Knowage管理员后台，进入管理员设置 > 配置 > 安全，找到CORS allowed origins配置项，填入你嵌入页面的域名（本地测试可填http://localhost:对应端口），保存后重启Knowage服务生效
• 确认要嵌入的驾驶舱已给demo_admin账号开放访问权限，或者设置为公开可访问
• 确认你部署的Knowage服务下/knowage/js/sdk/knowage-sdk.js路径可正常访问，后续需要在嵌入页面引入该SDK文件

2. 嵌入代码示例 #

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>Knowage驾驶舱嵌入演示</title>
    <!-- 替换下方地址为你自己的Knowage服务地址 -->
    <script src="http://你的Knowage服务域名/knowage/js/sdk/knowage-sdk.js"></script>
</head>
<body>
    <!-- 驾驶舱渲染容器，可自定义宽高 -->
    <div id="cockpit-box" style="width: 100%; height: 850px;"></div>

    <script>
        // 初始化SDK实例
        const sdkInstance = new KnowageSDK({
            address: "http://你的Knowage服务域名/knowage",
            // 测试阶段可直接填账号密码，生产环境建议替换为JWT token
            user: "demo_admin",
            password: "你的demo_admin账号密码"
        });

        // 加载指定驾驶舱
        sdkInstance.loadCockpit({
            // 驾驶舱ID可从驾驶舱访问页的地址栏参数中获取，对应documentId或cockpitId的数值
            id: 目标驾驶舱的数字ID,
            container: "cockpit-box",
            // 可选配置，隐藏不需要的UI元素
            parameters: {
                hideToolbar: true,
                hideBreadcrumb: true
            }
        });
    </script>
</body>
</html>

3. 常见问题排查 #

• 仍提示需要登录：先检查CORS配置是否正确添加了嵌入页域名，再确认SDK初始化的账号密码/令牌有效，对应账号有驾驶舱访问权限
• 驾驶舱加载报错：打开浏览器控制台查看错误码，403为权限或CORS配置错误，404为SDK路径或驾驶舱ID填写错误
• 生产环境不要在前端硬编码账号密码，可先在服务端调用Knowage的/restful-services/2.0/authenticate接口获取授权令牌，再将令牌传给前端SDK做初始化，避免账密泄露。

内容的提问来源于stack exchange，提问作者merry