超级应用快速入门

更新时间：2026-07-16 11:51:43

超级应用概述

什么是超级应用

超级应用是托管在观远 BI 中的前端应用。它可以复用 BI 的登录状态和数据能力，将数据分析、业务流程与 AI 能力组合成更贴合实际业务的应用。

适用场景

常见的超级应用包括：

场景	示例
数据驾驶舱	经营总览、专题分析、管理驾驶舱
业务工作台	数据查询、业务录入、审批或处置入口
AI 应用	智能问数、分析 Agent、业务决策助手
决策应用	指标监控、异常诊断、行动建议与结果跟踪
集成应用	连接观远 BI 数据与企业内部服务

核心能力

超级应用由以下能力共同支持：

• 超级应用工程模板：提供 React、TypeScript、Vite、开发配置、动态配置和发布页面等基础能力。
• GuanCLI + Skill：帮助 Coding Agent 创建工程、查询和理解 BI 资源，并将应用发布到 BI。
• 应用托管：在 BI 中统一管理应用文件、版本、访问地址和权限。
• 请求转发：为超级应用访问第三方服务提供受控的服务端转发能力。

能力边界

超级应用工程模板是一个纯前端单页应用（SPA）工程，不包含可独立部署的后端服务。

• 应用发布后由观远 BI 托管 index.html 和静态资源。
• 不支持需要独立服务器进程的 Node.js、Java、Python 等后端代码。
• 多页面应用可能无法正确处理刷新和路由，建议使用模板内置的 React Router 构建单页应用。
• 外部系统的密钥、Token 和账号密码不能写入前端代码或 settings.json。需要安全调用第三方服务时，请使用 请求转发。

使用前须知

免责条款

代码的灵活性也会带来潜在安全风险。在保存或启用相关代码前，建议管理员邀请企业内部技术专家和安全专家审阅、评估代码。观远数据（乙方）不承担因甲方错误或不当使用超级应用而引发的资产损失、数据损失、信息泄露等责任。

请勿直接复制或使用来源不明的第三方代码和软件包，也不要运行功能意图不明的代码。通过 AI 生成代码后，应在发布前完成代码审查和安全检查。

准备工作

开始前，请确认以下条件：

准备项	要求
观远 BI 环境	V8.2.0 或更高版本，已开放超级应用功能；发布页显示目标环境“支持发布”
本地运行环境	Node.js V22 或更高版本，并已安装 npm
Coding Agent	Codex、Cursor、Claude Code、Trae 等能够读取和修改本地工程的编程智能体
BI 账号	能登录目标环境，并具备所需的功能权限和应用资源权限
业务需求	明确应用目标、目标用户、需要使用的 BI 数据及验收标准

GuanCLI 的完整安装、登录、环境切换和命令说明，请参考 GuanCLI 使用指南。本文只介绍搭建超级应用所需的最短流程。

搭建流程概览

1. 安装 GuanCLI 和 Skill。
2. 使用 Coding Agent 创建并启动超级应用工程。
3. 在 /dev 页面配置 BI 环境和开发鉴权。
4. 让 Coding Agent 查询 BI 资源并开发应用。
5. 完成检查、构建和预览。
6. 使用 Coding Agent、GuanCLI、/publish 页面或 BI 管理中心发布应用。
7. 在 BI 管理中心维护应用和权限。

创建和开发应用

安装 GuanCLI 和 Skill

在终端中执行：

# 首次安装
npm install -g @guandata/guancli

# 已安装时更新到最新版本
npm update -g @guandata/guancli

# 验证安装
guancli version

# 安装或更新提供给 Coding Agent 的 Skill
guancli install-skill

也可以直接告诉 Coding Agent：

请帮我安装最新版 GuanCLI 和 GuanCLI Skill，并验证 guancli version 可以正常执行。

需要使用 GuanCLI 查询 BI 资源或发布应用时，还需先登录目标环境：

guancli auth login

注意

guancli auth login 保存的是 GuanCLI 环境配置，供 GuanCLI 命令使用；工程 /dev 页面保存的是当前项目的 .env 开发配置，供本地应用和 /publish 页面使用。两者互不替代。

创建并启动工程

方式一（推荐）：使用 Coding Agent 创建

在 Coding Agent 中输入：

请使用 GuanCLI 在当前目录的上一级创建一个名为 sales-cockpit 的超级应用工程。
创建完成后安装依赖并启动开发服务，再告诉我本地访问地址。

安装 GuanCLI Skill 后，Agent 会识别“创建超级应用”的意图，并调用 guancli app create。

方式二：使用 GuanCLI 命令创建

也可以直接执行：

guancli app create --name <project_name> --path <parent_dir>

• --name 是新建的项目目录名。
• --path 是项目的父目录，不是最终项目目录。
• 命令会下载最新工程模板、创建项目并准备依赖，随后尝试启动本地开发服务。

如果项目没有自动启动，请进入包含 package.json 的项目目录后执行：

npm install
npm run dev

如果根目录中没有 .env，请先将 .env.template 复制为 .env，再重新启动开发服务。

启动成功后打开终端提示的本地地址，即可看到工程模板首页：

模板首页是工程占位页，正式开发时需要根据业务需求替换页面内容、样式、标题和图标。

配置 BI 环境和开发鉴权

在模板首页进入 /dev，填写配置后点击「保存并立即生效」。

配置项	说明
VITE_DEV_PORT	本地开发服务端口，默认值为 8000；端口冲突时可修改
VITE_BI_HOST	目标观远 BI 环境地址，需要包含 http:// 或 https://
鉴权配置	可以使用 UID Token，也可以配置目标环境的登录域、账号和密码，如何获取UID Token 和账密可参考 登录方式
VITE_APP_ID	当前工程绑定的 SuperApp ID；首次发布时留空，更新已有应用时填写

使用账号密码鉴权时，点击「配置账密」，填写登录域、账号和密码：

保存后，页面会将配置写入项目 .env 并使开发配置重新生效。也可以点击「重新读取配置」，重新加载磁盘中的值。

警告

• .env 中可能包含 UID Token 或账号密码，请勿提交到 Git、发送给无关人员或放入截图。
• UID Token 只用于本地开发鉴权。若 Token 已泄露，请立即使其失效并重新获取。
• 不要把 .env 中的凭据复制到业务代码、settings.json 或发布产物中。

使用 Coding Agent 开发

提出完整的开发需求

建议把业务目标、目标用户、数据口径和交互要求一次说明清楚。例如：

请把当前工程改造成“区域销售经营驾驶舱”：
1. 使用 GuanCLI 在当前 BI 环境中查找“销售订单”数据集，先确认字段和数据口径；
2. 展示销售额、订单数、客单价和同比，并支持按区域和月份筛选；
3. 页面需适配 1440px 桌面端和常见笔记本分辨率；
4. 将可变标题和帮助链接放入 settings.json；
5. 完成后运行检查和构建，并说明使用了哪些 BI 资源。

GuanCLI 负责查询和分析已有 BI 资源，Coding Agent 根据查询结果编写前端代码。需要了解资源查询、数据预览和多环境配置时，请查看 GuanCLI 使用指南。

应用生成效果示例：

开发规范

• 保留模板的单页应用结构、发布页面和相对路径配置。
• 不要把本地 /dev、/publish 和占位首页当作最终业务页面。
• 调用 BI 数据时，应以当前登录用户的 BI 权限为边界。
• 可在线调整的文案、链接和非敏感参数应放入 settings.json。
• 需要访问带有密钥的外部接口时，使用 请求转发，不要把密钥放在浏览器端。
• 发布前检查响应式布局、空数据、加载中、接口失败和无权限等状态。

发布应用

检查、构建和预览

工程模板包含面向 Coding Agent 的检查与构建说明。发布前可以告诉 Agent：

请先使用项目内的 review skill 做上线检查，修复发现的问题；
再执行构建并预览产物，确认首页、路由、BI 数据请求和 settings.json 均正常。
不要发布，先把检查结果告诉我。

至少确认以下项目：

• npm run build 成功，且没有阻断发布的错误。
• 构建产物根目录包含 index.html。
• 直接访问首页、刷新内部路由和返回首页均正常。
• 发布产物中不包含 .env、Token、账号密码或其他密钥。
• settings.json 是有效 JSON，页面可以正常读取。
• 目标 BI 版本和当前账号权限满足发布要求。

选择发布方式

可以让 Coding Agent 自动完成发布，也可以使用 GuanCLI 命令或模板 /publish 页面。

方式一（推荐）：使用 Coding Agent 发布

首次发布前输入：

请使用项目内的发布流程，把当前超级应用发布到已登录的 BI 环境。
发布前先完成 review、构建和产物检查；需要我确认应用名称、描述或版本号时再停下来询问。
发布成功后返回访问地址和 SuperApp ID。

更新已有应用时，应同时提供 SuperApp ID，并明确要求更新原应用，避免误建新应用。

方式二：使用 GuanCLI 命令发布

首次发布时，--app-id 留空，GuanCLI 会创建应用：

guancli app publish --path . --app-name "区域销售经营驾驶舱" --description "面向区域负责人的销售经营分析应用"

更新已有应用时，必须传入原应用的 SuperApp ID：

guancli app publish --path . --app-id <SuperApp_ID>

需要指定其他已登录环境时，可以增加全局参数 --profile <profile_name>。

说明

GuanCLI 首次创建应用后会返回 SuperApp ID，但不会自动写入项目 VITE_APP_ID。请保存该 ID，并在后续发布时通过 --app-id 指定；如果还要使用模板 /publish 页面更新同一应用，也应把该 ID 写入 /dev 页面的 VITE_APP_ID。

方式三：使用 /publish 页面发布

1. 从模板首页进入 /publish，点击「打包发布」并完成构建。

   

2. 在压缩包列表中检查文件名、版本、大小和目标 BI 状态，再点击「上传发布」。

   

3. 首次发布时填写应用名称和描述，确认版本号后点击「确认并上传发布」。

   

4. 发布成功后，页面会返回并绑定正确的 SuperApp ID。后续从同一工程发布时将更新已绑定的应用。

   

说明

• VITE_APP_ID 为空时，/publish 页面按首次发布处理：创建应用，并将返回的 SuperApp ID 写回项目配置。
• VITE_APP_ID 有值时，/publish 页面更新对应应用。发布前请在 BI 应用列表中核对目标应用 ID；错填另一个有编辑权限的有效 ID 会覆盖该应用，填入不存在或无权限的 ID 会导致更新失败。

方式四：在 BI 管理中心手动发布

也可以将构建产物压缩为 ZIP，再进入「管理中心 > 开放平台 > 超级应用 > 应用列表」进行发布。

• 首次发布：点击「新建应用」，填写名称、描述和版本号后上传 ZIP。

  新建应用时，需要填写应用信息并上传代码压缩包：

  

• 更新应用：找到目标应用，点击「更新应用文件」，上传新的 ZIP。

  更新已有应用时，需要确认目标应用和当前版本，再填写新版本号并上传代码压缩包：

  

上传文件需要满足以下要求：

• 文件格式为 ZIP。
• 建议解压后的根目录直接包含 index.html。服务端也兼容唯一一层外层目录，但不支持多层嵌套或多个候选应用目录。
• 文件大小不超过 100 MB。
• 版本号、应用名称和描述符合团队发布规范。

手动新建应用后，请从应用列表复制并保存 SuperApp ID。后续如果改用 GuanCLI 更新，应通过 --app-id 指定该 ID；如果改用模板 /publish 页面更新，应先在 /dev 页面的 VITE_APP_ID 中填写并保存该 ID。

管理已发布应用

查看应用列表和详情

进入「管理中心 > 开放平台 > 超级应用 > 应用列表」，可以搜索和管理当前账号有权查看的应用。

功能	说明
搜索、筛选与排序	按应用名称或 ID 搜索，按所有者筛选，并按修改时间排序
预览详情	查看应用预览、基础信息、创建信息和权限信息
查看	在新页面打开应用
更新应用文件	上传新版本 ZIP，更新应用代码和版本
复制地址	复制应用访问地址并分享给有访问权限的用户
编辑应用信息	修改应用名称和描述
配置应用	在线编辑 settings.json
权限管理	管理应用的所有者、协作者和访问者
下载	下载当前应用压缩包
删除	永久删除应用、权限关系和托管文件；没有回收站，删除前请先备份

点击应用卡片或「预览详情」，可以查看应用预览和基础信息：

编辑应用名称和描述

在应用菜单中点击「编辑应用信息」，可以修改应用名称和描述：

配置运行时参数（settings.json）

settings.json 适合保存应用标题、说明文案、跳转链接、功能开关和非敏感接口地址等运行时配置。在线修改后无需重新构建应用。

在应用菜单中点击「配置应用」，可以在线查看和编辑 settings.json：

使用时请注意：

• 文件内容必须是有效 JSON；新增自定义字段后，业务代码也需要读取对应字段。
• settings.json 会被浏览器访问，不能存放密码、Token、API Key 等敏感信息。
• 更新应用文件会整体替换托管目录，可能覆盖线上 settings.json。发布前应比较本地文件与线上配置，并将需要保留的配置同步到发布包。

可以让 Coding Agent 帮助维护：

请把应用标题、帮助链接和功能开关改为从 public/settings.json 读取，
提供默认值和读取失败时的降级处理，并确保文件中不包含任何密钥。

权限与访问控制

超级应用同时受功能权限和应用资源权限控制：

• 用户需要具备应用列表的相应功能权限，才能进入管理页面或执行新建、编辑、授权等操作。
• 应用所有者和协作者在具备“编辑”功能权限时，可以维护应用；访问者只能访问应用。
• 打开应用访问地址的用户必须拥有该应用的访问权限。所有者和协作者也具备访问权限。
• 应用页面中使用的数据集、卡片、页面等 BI 资源，仍按当前登录用户原有的 BI 数据权限校验。拥有应用访问权限不代表自动拥有全部数据权限。

完整的角色配置、所有者、协作者和访问者说明，请参考 超级应用的权限管理。

常见问题

找不到 guancli 命令怎么办？

先执行 npm list -g @guandata/guancli 确认是否已安装，再检查 npm 全局命令目录是否已加入系统 PATH。详细处理方法请参考 GuanCLI 使用指南。

Coding Agent 没有调用 GuanCLI 怎么办？

执行 guancli install-skill 更新 Skill，然后重新打开 Coding Agent。也可以在提示词中明确要求“先使用 GuanCLI 查询 BI 资源，再修改代码”。

本地应用无法连接 BI 怎么办？

依次检查：

1. VITE_BI_HOST 是否包含正确协议、域名和端口。
2. UID Token 或账号密码是否仍然有效，账号是否能正常登录该环境。
3. 修改 .env 后是否保存并重新加载配置。
4. 浏览器开发者工具中是否有跨域、401、403 或接口地址错误。

发布按钮不可用或发布失败怎么办？

检查 /publish 页面显示的目标 BI 版本和“支持发布”状态，并确认：

• 当前环境已开放超级应用能力。
• 新建应用时，当前应用数量未达到授权额度上限；达到上限后不能继续新建，但仍可更新已有应用。
• 当前账号具备新建或编辑所需的功能权限。
• 普通用户更新应用时，当前账号是应用所有者或协作者；管理员可按管理权限更新应用。
• ZIP 解压后根目录直接包含 index.html，或仅有一层外层目录且该目录包含 index.html；文件不超过 100 MB。

更新应用时为什么新建了一个应用？

通常是因为发布时没有指定原应用的 SuperApp ID：

• 使用 GuanCLI 时，更新命令必须带 --app-id <SuperApp_ID>。
• 使用 /publish 页面时，确认 /dev 中的 VITE_APP_ID 已填写并保存。

更新后为什么丢失了线上配置？

更新应用文件会整体替换托管目录，新包中的 settings.json 可能覆盖线上配置。发布前应在「配置应用」中复制或记录线上 JSON，将需要保留的值同步到本地 public/settings.json 后再构建。应用的「下载」功能用于下载原发布包，不一定包含后来在线修改的配置。

发布后出现白屏或刷新子路由失败怎么办？

确认应用仍使用模板的单页路由和相对资源路径，没有改成多页面构建；再检查构建产物根目录是否包含 index.html、静态资源路径是否正确，以及浏览器控制台是否有加载错误。

分享链接后，其他用户为什么看不到应用或数据？

• 看不到应用：确认该用户已成为应用访问者，或具备所有者、协作者权限。
• 能打开应用但看不到数据：检查该用户对页面所使用的数据集、卡片等 BI 资源是否有权限。

如何安全调用第三方接口？

不要在前端保存第三方服务密钥。请在 BI 中配置 请求转发，由 BI 服务端完成凭据注入、权限校验、请求转发和审计。

相关文档

• GuanCLI 使用指南
• GuanCLI 工具套件概述
• 请求转发
• 超级应用的权限管理