基本介绍
lina-core是LinaPro的后端主框架，也是平台级能力的稳定底座。它负责承载HTTP入口、认证鉴权、权限治理、运行时配置、接口文档聚合、定时调度、国际化、多租户上下文、插件治理、集群协调和健康探针。
这篇文档只解释主框架在整体系统中的位置和协作方式，不展开每个能力的完整配置和使用细节。需要深入了解某个专题时，可以从后文的能力矩阵跳转到对应文档。
lina-core的核心原则是：主框架提供稳定公共能力，业务领域通过插件扩展。主框架不直接内置具体业务模块，而是通过pluginhost、pluginbridge和pluginservice发布稳定扩展接缝，让源码插件和WASM动态插件接入统一治理面。
主框架边界
主框架的职责不是“包含所有功能”，而是把跨业务的公共能力统一治理起来，并为业务插件提供可复用的运行时环境。
| 范围 | 主框架职责 | 边界 |
|---|---|---|
| 平台控制面 | 管理用户、角色、菜单、会话、配置、文件、插件、任务等基础资源 | 不承载具体行业或项目业务模型 |
| 请求链路 | 统一处理路由、中间件、认证、权限、租户上下文、数据范围和审计 | 不把业务规则写入全局中间件 |
| 接口扩展 | 向源码插件发布pluginhost和pluginservice，向动态插件发布pluginbridge和hostServices | 插件不能直接依赖主框架internal/实现 |
| 运行时治理 | 负责插件发现、安装、启用、禁用、升级、卸载、菜单权限同步和缓存刷新 | 插件自己的领域逻辑、前端页面和私有配置由插件维护 |
| 部署协调 | 在单机模式下提供进程内协调，在集群模式下接入集群协调器 | 业务数据仍由数据库和插件自己的表结构承载 |
运行时架构
一次请求进入主框架后，会先经过统一入口和治理链路，再落到主框架控制器或插件路由。插件看到的是经过主框架整理后的身份、租户、权限和配置上下文，而不是主框架内部实现对象。
主路径只表达请求如何被治理和分发，旁路依赖通过下表理解：
| 关系 | 说明 |
|---|---|
主框架服务 → PostgreSQL | 保存用户、角色、菜单、配置、插件治理、任务日志和会话投影等数据 |
插件处理器 → PostgreSQL | 读写插件自有表，表结构和业务数据由插件负责 |
插件处理器 → hostServices | 动态插件通过授权快照访问配置、存储、锁、通知等宿主能力 |
| 主框架服务 → 集群协调器 | 在集群模式下处理选主、分布式锁、缓存修订、在线会话热状态和跨节点事件 |
目录结构
lina-core的代码目录围绕契约、控制器、服务、声明资源和公开扩展接口组织：
apps/lina-core/
├── api/ # API DTO与路由契约
├── internal/
│ ├── cmd/ # 服务启动、路由绑定、插件扫描
│ ├── controller/ # HTTP控制器
│ ├── dao/ # 数据访问对象
│ ├── model/ # 数据模型
│ ├── packed/ # 嵌入的主框架资源
│ └── service/ # 主框架内部服务
│ ├── auth/ # 认证服务
│ ├── bizctx/ # 请求身份与租户上下文
│ ├── cron/ # 定时调度入口
│ ├── i18n/ # 国际化运行时
│ ├── plugin/ # 插件治理与生命周期
│ └── ... # 其他核心服务
├── manifest/
│ ├── config/ # 配置模板与框架元数据
│ ├── i18n/ # 主框架运行时语言包
│ └── sql/ # 主框架DDL与初始化数据
└── pkg/
├── pluginhost/ # 源码插件扩展接口
├── pluginbridge/ # WASM动态插件桥接协议
├── pluginservice/ # 基础能力实现
└── ... # 其他公共组件
目录边界也对应开发边界：主框架内部实现放在internal/中，插件只能依赖pkg/下发布的稳定契约。
内置平台能力
主框架内置的平台能力很多，但这篇文档只保留总览。每个专题的配置项、数据结构、开发方式和注意事项应放在对应专题页中维护。
| 能力 | 主框架职责 | 深入阅读 |
|---|---|---|
| 路由与中间件 | 注册主框架API路由，承载插件的统一入口，执行认证、权限、审计等中间件 | 路由与中间件 |
| 认证与权限 | 颁发和校验JWT，维护在线会话，按RBAC模型校验接口和菜单权限 | 权限管理策略 |
| 配置管理 | 加载宿主配置，提供公开宿主配置白名单，并为插件提供插件作用域配置服务 | 服务配置管理 |
| 接口文档 | 聚合主框架、源码插件和动态插件的OpenAPI契约，输出/api.json并供工作台调试 | 一体化接口文档 |
| 定时调度 | 管理持久化任务、任务处理器、执行日志、手动触发、集群执行范围和并发策略 | 定时任务调度与执行 |
| I18N国际化 | 加载主框架语言包，合并插件语言包，并为运行时文案和接口文档提供多语言资源 | 框架级I18N国际化 |
| 多租户基础 | 提供bizctx、身份快照、tenant_id过滤接口和插件多租户元数据 | 原生多租户能力 |
| 插件运行时 | 发现插件清单，执行生命周期，投影路由、菜单、权限、钩子、任务和公开静态资源 | 双模式插件系统 |
| 集群协调 | 在集群模式下通过协调器处理选主、分布式锁、缓存修订、键值缓存和跨节点事件 | 原生分布式架构 |
| 静态资源 | 托管主框架嵌入资源、管理工作台资源和插件显式声明的公开资源 | 静态资源与前端资产 |
启动与加载流程
主框架启动时会先建立宿主运行时，再把插件能力接入统一治理面。推荐从这个顺序理解主框架和插件之间的关系：
- 加载配置与框架元数据。
- 初始化数据库连接与
DDL。 - 加载主框架语言包。
- 扫描源码插件与动态插件声明。
- 执行插件依赖、版本和治理资源检查。
- 投影路由、菜单、权限、
Hook、Cron和公开资产。 - 构建运行时缓存与集群修订状态。
- 启动定时调度。
- 启动
HTTP服务与健康探针。
这个流程体现了主框架的编排职责：它先保证自身控制面可用，再把插件声明转化为运行时能力。插件启用、禁用、升级或卸载时，也会沿着同一条治理主链刷新路由、权限、菜单、语言包、接口文档和缓存。
与其他组件的关系
lina-core是后端运行时中心，但它不独占系统能力。它通过公开契约与其他组件协作：
| 组件 | 协作方式 |
|---|---|
| 管理工作台 | 通过主框架公开API读取菜单、权限、配置、插件状态、接口文档和任务数据 |
| 源码插件 | 随主框架编译，通过pluginhost注册路由、钩子、任务、生命周期回调和前端资产 |
WASM动态插件 | 作为运行时产物上传，通过pluginbridge处理请求，并通过hostServices访问授权能力 |
PostgreSQL | 保存主框架治理数据、插件治理数据、任务日志、会话投影和插件业务表 |
Redis协调器 | 在集群模式下承担选主、锁、缓存修订、在线会话热状态和跨节点事件 |
从依赖方向看，工作台和插件都依赖主框架的公开契约；主框架不反向依赖具体业务插件的内部实现。