Article body
正文
SaaS产品增加BI能力时，团队常在两个极端之间摇摆：自己重建分析平台，周期长；直接跳转到外部BI，用户体验割裂。嵌入式BI PaaS提供中间路径，ISV保留产品入口与行业逻辑，平台提供数据建模、指标、可视化和AI能力。
路径一：嵌入分析成果
团队把已经发布的看板或报表嵌入业务页面，通常通过安全链接、Token和容器完成。这个模式上线快，适合客户门户、经营驾驶舱和固定报表。工程重点包括单点登录、租户上下文、行级权限、自适应尺寸和主题一致性。
成果嵌入适合需求稳定的页面。用户可以筛选、联动和导出，但产品团队对单个组件的控制较少。ISV需要提前规划页面布局与移动端适配，避免把桌面看板缩小后直接塞进窄容器。
路径二：嵌入分析能力
产品通过SDK嵌入图表、筛选器、设计器或ChatBI等模块。业务页面可以控制布局和导航，用户仍使用平台提供的分析能力。这条路径适合需要自助分析、报告创作或对话问数的行业软件。
模块化嵌入增加了前后端集成工作。团队要统一用户身份、菜单权限、事件通信和主题变量，还要处理宿主应用与BI组件的版本兼容。良好的SDK应暴露清晰的初始化、事件和销毁接口。
路径三：Headless深度集成
Headless模式通过API调用数据集、指标、查询、图表和权限服务，ISV自己构建全部界面。它适合产品体验要求高、已有设计系统、需要在业务流程中调用分析能力的团队。Data Agent也可以通过这些API创建资源或返回结构化结果。
深度集成带来最高自由度，也要求ISV承担更多产品与工程责任。接口版本、幂等、错误码、审计和限流都要纳入设计。团队还要区分同步查询与异步任务，为耗时操作提供进度和取消能力。
用交付边界选择模式
固定报表优先成果嵌入，自助分析优先能力嵌入，产品级重构选择Headless。很多项目会组合三种路径：经营首页嵌入看板，分析中心嵌入设计器，核心业务流程调用指标API。选型时应先画出用户旅程和权限边界，再决定技术形态。
工程细节与实施补充
一、嵌入式BI PaaS概述
1.1 什么是嵌入式BI PaaS
嵌入式BI PaaS（Platform as a Service）是一种专门用于帮助企业将BI能力嵌入到现有应用中的技术平台。与传统的BI工具不同，嵌入式BI PaaS平台将复杂的报表制作、数据连接、权限管理等功能封装为可调用的服务/API，开发者只需通过简单的集成操作，即可在自己的应用中实现数据可视化功能。
一个成熟的嵌入式BI PaaS平台通常具备以下核心特征：
1.2 嵌入式BI的价值
对于企业而言，嵌入式BI带来了显著的商业价值：
- 用户体验提升：用户无需离开当前工作上下文即可完成数据分析，降低了使用门槛
- 开发成本降低：无需从零构建BI能力，复用成熟平台的功能
- 数据一致性：统一的数据底座确保各业务系统使用同一套数据口径
- 快速迭代：借助平台能力快速响应业务变化，缩短需求交付周期
1.3 衡石科技BI PaaS平台简介
衡石科技是国内领先的嵌入式BI PaaS平台提供商，其平台具备以下技术优势：
- 集成友好的开放架构：支持零代码整合嵌入
- 精细化权限控制：与主流身份认证系统无缝对接
- 丰富的生态集成：已服务WPP、宝马、广汽本田、阳狮集团、国药集团、亚马逊云科技等200+家SaaS生态伙伴
- 持续迭代的能力：最新6.2版本增强了门户链接和仪表盘容器控件功能
二、嵌入式BI PaaS的三种集成模式
衡石科技BI PaaS平台提供了三种层次的集成模式，从浅到深分别是：分析成果嵌入、分析能力嵌入和深度集成定制。这三种模式对应着不同的业务场景和技术复杂度，企业可以根据自身需求选择合适的集成深度。
2.1 三种集成模式概览
┌─────────────────────────────────────────────────────────────────────┐
│ 嵌入式BI PaaS集成层次 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 层次三：深度集成定制（Headless API） │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ▸ 自定义前端交互 │ │
│ │ ▸ 完全控制分析流程 │ │
│ │ ▸ 定制化数据处理管道 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ▲ │
│ 层次二：分析能力嵌入（模块化嵌入） │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ▸ 数据集开发模块嵌入 │ │
│ │ ▸ 仪表盘创作模块嵌入 │ │
│ │ ▸ 多租户隔离创作空间 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ▲ │
│ 层次一：分析成果嵌入（组件化嵌入） │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ▸ 完整仪表盘嵌入 │ │
│ │ ▸ 单图表/单控件嵌入 │ │
│ │ ▸ 灵活参数传递 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘2.2 模式一：分析成果嵌入
2.2.1 适用场景
分析成果嵌入模式非常适合以下业务场景：
2.3 模式二：分析能力嵌入
2.3.1 适用场景
分析能力嵌入模式适合以下业务场景：
2.4 模式三：深度集成定制
2.4.1 模式概述
当企业需要完全掌控分析前端的交互体验和业务流程时，前两种模式就无法满足需求了。此时，深度集成定制模式通过提供完整的API接口，让开发者能够以衡石BI PaaS为分析底座，从零构建完全定制化的前端应用。
核心能力：
- Headless API：无头API，支持任意前端框架
- 完整的数据管道控制：自定义数据处理流程
- 灵活的交互定制：打造独特的用户体验
- 流程编排：根据业务需求调整分析流程
三、集成开放层技术要点
无论选择哪种集成模式，衡石BI PaaS平台都提供了完善的技术支持，确保集成的稳定性和安全性。
3.1 认证与权限体系
3.1.1 SSO登录支持
衡石BI PaaS支持多种SSO登录方式，确保与宿主系统的身份体系无缝对接：
// SSO配置示例
const ssoConfig = {
// Microsoft Teams集成
teams: {
enabled: true,
tenantId: 'your-teams-tenant-id',
clientId: 'your-app-client-id'
},
// Authing SAML2集成
authing: {
enabled: true,
domain: 'your-company.authing.cn',
appId: 'your-app-id'
},
// JWT令牌验证
jwt: {
enabled: true,
issuer: 'your-auth-service',
secretKey: 'your-secret-key',
algorithms: ['RS256']
}
};3.1.2 精细化权限控制
┌─────────────────────────────────────────────────────────────────────┐
│ 权限控制层次 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 组织层 (Organization) │
│ ├── 组织管理员 │
│ └── 组织成员 │
│ │ │
│ ▼ │
│ 工作空间层 (Workspace) │
│ ├── 工作空间管理员 │
│ ├── 分析师 │
│ └── 查看者 │
│ │ │
│ ▼ │
│ 资源层 (Resource) │
│ ├── 仪表盘: 创建/编辑/查看/删除/导出 │
│ ├── 数据集: 创建/编辑/查看/删除 │
│ └── 数据源: 创建/编辑/查看/删除 │
│ │
└─────────────────────────────────────────────────────────────────────┘3.2 CORS配置
跨域资源共享（CORS）是前端集成中的常见问题。衡石BI PaaS支持动态配置CORS：
// CORS配置
const corsConfig = {
allowedOrigins: [
'https://app.example.com',
'https://portal.example.com',
'http://localhost:3000' // 开发环境
],
allowedMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
allowedHeaders: [
'Content-Type',
'Authorization',
'X-Requested-With'
],
credentials: true,
maxAge: 86400 // 预检请求缓存时间
};3.3 AI助手SDK
衡石6.x版本提供了AI助手SDK，支持在React应用中快速集成智能分析能力：
// AI助手集成示例
import { AIAssistant } from '@hengshi/ai-sdk-react';
const App = () => {
return (
<BIProvider
baseUrl="https://bi-platform.example.com"
token={userToken}
>
<AIAssistant
// AI助手配置
theme="dark"
position="bottom-right"
placeholder="输入问题，我来帮你分析..."
// 功能配置
capabilities={[
'natural_language_query', // 自然语言查询
'chart_recommendation', // 图表推荐
'insight_generation', // 洞察生成
'sql_assistant' // SQL助手
]}
// 数据范围限制
dataScope={{
datasets: ['sales_data', 'customer_data'],
restrictions: ['region:华东'] // 数据权限
}}
// 回调函数
onQuery={handleQuery}
onError={handleError}
/>
</BIProvider>
);
};四、版本更新：6.2版本集成增强
衡石BI PaaS平台的6.2版本带来了重要的集成增强功能：
4.1 门户链接增强
// 6.2版本门户链接支持
const portalUrl = `${biBaseUrl}/portal/${orgId}/${folderId}`;
const dashboardUrl = `${portalUrl}/dashboard/${dashboardId}`;
// 直接定位到特定目录
const folderUrl = `${portalUrl}/folder/${folderId}?view=list`;4.2 仪表盘容器导入导出
// 导出仪表盘包（含容器）
const exportPackage = await dashboardClient.exportDashboard('dashboard-123', {
includeContainer: true, // 包含容器样式
includeData: false, // 不包含数据
format: 'json'
});
// 导入仪表盘包
await dashboardClient.importDashboard({
package: exportPackage,
targetFolder: 'new-folder-id',
overwrite: false
});五、总结与最佳实践
5.1 三种集成模式对比
5.2 集成最佳实践
- 从简单开始：优先考虑分析成果嵌入，根据业务需求逐步深入
- 注重安全性：始终通过后端获取访问令牌，避免前端暴露敏感信息
- 关注用户体验：确保嵌入后的组件与宿主应用风格一致
- 做好监控：集成完成后监控API调用和性能指标
- 版本管理：关注BI平台的版本更新，及时适配新特性
资料与核验说明
内部资料用于梳理衡石能力与工程方法；竞品和版本信息按2026年8月26日可访问的官方页面复核。产品功能会受版本、地区、授权和部署模式影响，正式采购与发布前应再做一次现场确认。