谷雨开源 SaaS 平台（G2rain）

# g2rain-main-shell

License Node (opens new window) Vue (opens new window) Vite (opens new window) qiankun (opens new window)

g2rain-main-shell 是 G2rain 平台的主壳前端仓库，负责承载平台控制台主应用、子应用装载、统一导航与运行时交互能力，并与交互接入侧安全链路协同工作。

# 1. 徽标与状态标识

  • 平台定位：前端主壳应用
  • 仓库类型：交互接入层核心模块
  • 当前状态：稳定版本

# 2. 项目简介

g2rain-main-shell 不是普通的单体前端项目，而是 G2rain 平台“应用化接入模式”在前端侧的核心承载仓库。

它主要解决以下问题：

  • 如何把多个子应用组织成统一的平台入口
  • 如何在多应用场景下保持统一导航、路由、Tab 与工作区体验
  • 如何让主壳与 IAM、网关、OpenResty、Lua 协同形成前端到 API 的安全链路
  • 如何在开发阶段支持独立调试，在联调与交付阶段支持统一接入

# 3. 平台定位

在 G2rain“企业级 AI 原生开源 SaaS 平台”体系中，g2rain-main-shell 位于交互接入层，是平台“应用化接入模式”的核心承载仓库之一。

它主要承担以下角色：

  • 作为主应用承载平台控制台统一入口
  • 作为子应用装载容器承载微前端编排
  • 作为统一交互入口承载菜单、路由、Tab、SSO 与运行时状态
  • 作为交互接入层安全协同节点，与网关、OpenResty、Lua、IAM 共同形成前端与 API 的身份管理与安全链路

它与 g2rain-iam、g2rain-basis、g2rain-infra 等仓库协同，共同构成平台统一身份、统一交互、统一资源权限呈现与统一应用接入体系。

# 4. 核心能力

# 4.1 主壳入口与微前端装载编排

g2rain-main-shell 解决“平台如何把多个子应用组织成一个统一入口”的问题。

它通过 qiankun、single-spa、src/platform/apps 与 src/components/micro-app 统一装载子应用、传递运行时上下文，并承接主壳布局与工作区容器能力，是整个平台前端应用化落地的装载中枢。

# 4.2 SSO、Token 与登录回调主链路

它解决主壳与 IAM 之间的单点登录、令牌建立、登录回调跳转与登录态持久化问题。

相关能力通过以下部分协同完成：

  • src/runtime/auth
  • src/runtime/boot
  • src/platform/stores

这条链路是子应用共享统一身份能力的前提。

# 4.3 菜单、路由、Tab 与工作区交互组织

g2rain-main-shell 负责菜单、路由、Tab、工作区、重定向等统一交互组织，使用户在多应用、多页面场景中仍然保持一致体验。

相关能力主要位于：

  • src/runtime/router
  • src/runtime/navigation
  • src/shell/layout
  • src/shell/pages

# 4.4 前端与 API 安全协同链路

g2rain-main-shell 不只是页面容器，它还承担前端与 API 安全协同的一部分职责。

它通过：

  • src/components/http
  • lua/
  • nginx/
  • 运行时环境变量与签名脚本

与 OpenResty、Lua、IAM 协同，使前端请求进入平台既定身份与安全链路。

# 4.5 运行时状态与共享能力底座

主壳还承担平台前端长期复用的运行时状态、主题、类型、共享工具与平台抽象能力沉淀。

相关内容主要位于：

  • src/platform
  • src/shared
  • src/runtime/store

# 5. 核心能力结构说明

从平台视角看，g2rain-main-shell 承接的是“前端统一入口、统一身份协同与统一交互编排”三类能力。

# 5.1 主壳承载能力集合

  • 主壳布局
  • 菜单组织
  • 工作区承载
  • 统一入口呈现

# 5.2 子应用编排能力集合

  • 子应用注册
  • 子应用装载
  • 微前端容器管理
  • 独立运行与统一接入切换

# 5.3 运行时协同能力集合

  • 登录与 Token 状态管理
  • 路由与导航协同
  • HTTP 请求链路协同
  • 前端与平台身份体系协同

# 6. 核心业务流程

# 6.1 主壳装载与子应用编排主线

  1. 主壳先启动自身布局、菜单、路由和运行时状态
  2. 再根据平台资源与应用配置决定子应用何时被装载到工作区
  3. 子应用由主壳统一承接路径、容器、上下文与消息通道
  4. 最终形成“统一入口 + 多子应用”的平台前端结构

# 6.2 SSO 登录与 Token 建立主线

  1. 主壳检查当前登录态与回调状态
  2. 与 IAM 协同完成登录跳转、授权回调与 Token 建立
  3. 恢复运行时状态并共享统一身份上下文
  4. 为后续子应用运行提供统一登录基础

# 6.3 菜单、Tab 与工作区组织主线

  1. 基于资源与权限组织菜单与页面入口
  2. 统一管理路由跳转、Tab 打开与工作区切换
  3. 维持用户跨应用访问时的统一体验

# 6.4 前端与 API 安全协同主线

  1. 主壳通过统一 HTTP 层发起请求
  2. 结合运行时配置、Lua 与 OpenResty 协同安全链路
  3. 接入 IAM 与平台网关既定的身份机制
  4. 让前端请求进入平台标准安全体系

# 7. 项目结构

g2rain-main-shell/
├── src/                   # 主壳应用源码、运行时、平台与组件能力
├── public/                # 公共静态资源
├── lua/                   # 前端/API 安全协同相关 Lua 脚本与密钥文件
├── nginx/                 # Nginx / OpenResty 启动与模板配置
├── build.sh               # 一键构建 Docker 镜像
├── Dockerfile             # 主壳容器化构建文件
├── vite.config.ts         # Vite 构建与代理配置
└── package.json           # 前端依赖与脚本入口

# 7.1 src

平台主逻辑目录，内部通常进一步划分为：

  • src/platform
  • src/runtime
  • src/shared
  • src/shell
  • src/views

# 7.2 lua 与 nginx

这两个目录是 g2rain-main-shell 与平台安全链路协同的关键组成部分：

  • nginx 作为默认运行环境模板
  • lua 用于 IAM 公钥获取、应用私钥签名等安全协同逻辑

# 7.3 build.sh 与 Dockerfile

用于把主壳前端产物打包为可交付容器镜像，支撑部署阶段统一交付。

# 8. 技术栈

  • Vue 3
  • TypeScript
  • Vite
  • qiankun
  • single-spa
  • Element Plus
  • Pinia
  • Vue Router
  • Axios
  • OpenResty
  • Lua
  • Nginx
  • Node 22+

# 9. 环境变量与运行模式

# 9.1 构建时变量

主要来自：

  • .env
  • .env.production

典型变量包括：

  • VITE_BUILD_MODE
  • VITE_APPLICATION_CODE
  • VITE_CONTEXT_PATH
  • VITE_BACKEND_ORIGIN
  • VITE_SSO_BASE_URL
  • VITE_TOKEN_END_POINT

# 9.2 运行时变量

运行时变量通过 env-config.js 与 nginx/docker-entrypoint.sh 注入，用于容器部署后的动态替换。

典型变量包括：

  • SSO_BASE_URL
  • CONTEXT_PATH
  • SERVER_PORT
  • GATEWAY_HOST
  • GATEWAY_PORT
  • IAM_HOST
  • IAM_PORT

# 9.3 运行模式说明

主壳及其子应用通常存在两种运行方式：

  • 开发阶段：独立运行，便于调试
  • 联调与交付阶段：接入主壳统一验证

# 10. 快速开始

# 10.1 环境要求

  • Node.js >= 22
  • npm >= 9
  • Docker（可选）

# 10.2 安装依赖

npm install

# 10.3 本地开发

npm run dev

# 10.4 生产构建

npm run build

# 10.5 容器镜像构建

docker build -t g2rain/g2rain-main-shell:latest .
./build.sh

# 11. 典型使用场景

  • 多子应用统一装载
  • 平台前端主入口建设
  • 子应用独立开发与统一联调
  • 前端与平台安全链路协同
  • 平台统一导航与工作区体验建设

# 12. 相关仓库

  • g2rain-manager-app
  • g2rain-infra-app
  • g2rain-cms-app
  • g2rain-department-app
  • g2rain-app-template
  • g2rain-app-cli
  • g2rain-iam
  • g2rain-basis

# 13. 使用建议

  • 适合作为平台统一主入口与子应用装载壳层使用
  • 新增子应用接入时，优先理解主壳装载、认证、导航与安全协同四条主线
  • 生产部署时优先通过运行时配置注入管理易变参数

# 14. 贡献指南

欢迎通过 Issue、文档改进、测试补充、代码优化与功能增强等形式参与贡献。

# 15. 许可证

本项目基于 Apache 2.0许可证 开源。

# 16. 联系我们

← g2rain-manager-app →