开发总览

Crest v1.5.7 开发指南入口，说明源码结构、开发边界、前后端分离开发方式、构建命令和提交前检查。

本章面向需要阅读 Crest 源码、搭建本地环境、扩展功能或参与发布维护的开发者。

首次接触项目时，建议先阅读本地开发环境。该页面按开发顺序说明源码获取、数据库导入、本地变量配置、Flyway/SSO 调整、服务启动和打包流程。

本地开发环境

从 v1.5.7 源码开始，完成本地开发环境启动。

源码结构

路径	说明
`core/core-backend`	Spring Boot 后端服务，包含接口、业务实现、Flyway 迁移和最终 JAR 打包入口
`core/core-frontend`	Vue 3.3、Vite、TypeScript、Element Plus、Pinia、vxe-table 前端工程
`sdk/api`	对内 API、DTO、VO 和接口契约
`sdk/common`	认证、通用模型、异常处理、工具类和 Spring 配置
`sdk/extensions/extensions-datasource`	JDBC 数据源扩展、数据源定义和方言能力
`sdk/extensions/extensions-view`	可视化视图相关扩展
`drivers`	随仓库维护的 JDBC 驱动
`installer`	单机安装脚本、Docker Compose 模板、控制脚本和离线包制作脚本
`deploy/kubernetes`	Kubernetes 部署清单，支持内置 MySQL 和外部 MySQL
`docs`	源码仓库内的开发、部署和专题说明

阅读代码时建议从页面操作反查调用链：页面调用哪个接口，接口进入哪个 Service，Service 访问哪些 Mapper、缓存、文件目录或外部数据源。

开发边界

Crest v1.5.7 主要维护这些能力：

领域	典型内容
数据准备	数据源、API 数据源、数据集、SQL 数据集、字段管理、MySQL 数据集缓存同步
可视化分析	图表、仪表盘、数据大屏、数据门户、分享、导出
数据治理	字段级数据血缘
平台管理	用户、组织、角色、权限、系统参数、站点设置、字体管理
安全能力	登录鉴权、审计、SSO、国密模式、敏感配置加密
部署交付	单机安装、离线包、Kubernetes、镜像构建

新增功能时应先确认所属领域，再补齐菜单、权限、接口、数据库迁移、审计、文档和截图。若仅调整前端入口，未同步后端权限和数据库结构，后续可能在刷新、分享、导出或升级时出现不一致。

工具链

工具	版本
JDK	21
Maven	3.9.x
Node.js	22.x
pnpm	11.1.2
MySQL	8.0 / 8.4
Docker	可选，构建镜像或安装包时使用

本地开发不强制依赖 Docker。没有 Docker 时，可以用本机或内网 MySQL 启动后端和前端；需要交付镜像时再交给 CI 或构建机处理。

v1.5.7 开发方式

当前发布形态已经拆成前端镜像和后端镜像：

ghcr.io/sevoniva/crest-web:v1.5.7
ghcr.io/sevoniva/crest-service:v1.5.7

开发时无需同时运行前后端。可按当前任务选择对应开发链路：

任务	本地需要运行	可以复用
改前端页面、样式、交互	`core/core-frontend` 的 `pnpm dev`	已部署的后端，或 `crest-service:v1.5.7`
改后端接口、权限、任务、数据逻辑	JDK 21、Maven、本地或内网 MySQL	`crest-web:v1.5.7` 前端网关
验证部署、网关、镜像和监控	Docker Compose 或 Kubernetes	发布镜像和 `deploy/split` 模板

前端开发时，确认 core/core-frontend/config/dev.ts 中的代理地址指向可用后端。后端开发时，确认元数据库、Flyway、加密密钥和初始密码已经按本地环境配置好。

常用构建命令

安装前端依赖：

cd core/core-frontend
pnpm install --frozen-lockfile

启动前端：

cd core/core-frontend
pnpm dev

构建前端：

cd core/core-frontend
pnpm run build:base

只检查后端编译：

mvn -s .mvn/settings.xml \
  -pl :core-backend -am \
  test-compile \
  -DskipTests \
  -Dmaven.test.skip=true \
  -Dmaven.antrun.skip=true

打后端 JAR：

mvn -s .mvn/settings.xml \
  -pl :core-backend -am \
  clean package \
  -Pstandalone \
  -DskipTests \
  -Dmaven.test.skip=true \
  -Dcrest.copy.frontend.skip=true

构建本地后端镜像：

docker build -f Dockerfile.backend -t ghcr.io/sevoniva/crest-service:local .

构建本地前端镜像：

docker build -f Dockerfile.frontend -t ghcr.io/sevoniva/crest-web:local .

前后端分离镜像打包时，后端 Maven 命令使用 -Dcrest.copy.frontend.skip=true，避免强依赖前端 dist。只有在验证旧式内嵌静态资源 JAR 时，才需要先构建前端并让 core-backend 复制 core/core-frontend/dist。

数据库迁移

后端使用 Flyway 管理初始化脚本。

目录	说明
`core/core-backend/src/main/resources/db/migration`	核心表结构和基础初始化数据
`core/core-backend/src/main/resources/db/demo-migration`	可选演示资源

当前版本的核心初始化脚本是：

core/core-backend/src/main/resources/db/migration/V1.5.0.1__initial_schema.sql

演示资源脚本是：

core/core-backend/src/main/resources/db/demo-migration/V1.5.0.2__demo_resources.sql

导入完整开发库 dump 后，本地要关闭 Flyway。空库初始化时再打开 Flyway。具体配置见本地开发环境。

国密调试

Crest 支持 standard 和 sm-suite 两种加密模式。需要验证国密能力时，本地环境变量至少包含：

export CREST_CRYPTO_MODE='sm-suite'
export CREST_SM4_KEY='0123456789abcdef'

如果数据库 dump 来自国密环境，CREST_SM4_KEY 必须使用来源环境的原值。密钥不一致时，已保存的数据源密码和 SSO Secret 可能无法解密。

提交前检查

提交前确认：

没有提交数据库密码、Token、证书、私有 dump、运行日志和个人内网地址。
没有提交 .local/、.runtime/、node_modules/、dist/、target/。
改了前端，至少跑过 pnpm run build:base 或对应检查命令。
改了后端，至少跑过相关模块的 Maven 编译。
改了表结构、菜单、权限、初始化数据，要补 Flyway 脚本。
改了页面入口、按钮、配置项、权限或操作流程，要同步更新文档和截图。

最后检查工作区：

git status --short
git diff --stat

开发总览

本地开发环境

本页目录