Crest 文档
开发指南

本地开发环境

Crest v1.5.7 本地开发环境搭建：拉代码、导数据库、配置本地变量、启动前后端、打包和排查常见问题。

本页适用于首次搭建 Crest v1.5.7 开发环境的开发者，说明源码获取、元数据库准备、本地配置、服务启动、打包和常见问题处理。

开发环境不要求本机有 Docker。只要本机或内网有一套可连接的 MySQL 8.x，就可以启动后端和前端。v1.5.7 延续前后端分离形态：仅改后端时，可以复用发布的前端镜像或已有前端环境；仅改前端时，可以复用发布的后端镜像或内网后端服务。

先分清两类数据库

Crest 本身需要一个 MySQL 元数据库，用来保存用户、权限、数据源配置、数据集、图表、仪表盘和大屏。你在页面里新建的“数据源”是业务数据源，可能是 MySQL、Oracle、OceanBase、Excel 或 API。开发环境里最先要准备的是 Crest 元数据库，不是业务数据源。

v1.5.7 支持前后端分离开发

前端开发只需要能访问一个可用后端；后端开发只需要能连接 Crest 元数据库。只有验证镜像、安装包、网关转发或发布流程时，才需要同时构建前端和后端。

最常用的开发流程

如团队已提供 v1.5.7 开发库 dump，建议按以下流程搭建：

拉代码

克隆 Crest，切到 v1.5.7，再从 tag 建自己的开发分支。

导入元数据库

新建本地 crest 库，把团队提供的 v1.5.7 dump 导进去。

写本地环境变量

新建 .local/crest-dev-env.sh。数据库地址、账号、密码、加密密钥、文件目录都写在这里，不改仓库里的 application*.yml。

关闭本地不需要的功能

导入完整 dump 后关闭 Flyway；本地不调 SSO 时关闭 SSO；业务数据源连不到时改成内网可访问地址。

启动服务

后端启动 io.crest.CoreApplication，前端启动 pnpm dev。本地默认访问 http://localhost:8080。

没有 dump 时，可以使用空库初始化。该方式由 Flyway 创建基础表结构，页面中只包含初始化数据和可选演示资源。

1. 准备工具

工具版本用途
JDK21编译和运行后端
Maven3.9.x构建 Java 模块
Node.js22.x前端开发和构建
pnpm11.1.2安装前端依赖
MySQL8.0 / 8.4Crest 元数据库
Docker可选只在构建镜像或验证安装包时需要

检查本机工具版本：

java -version
mvn -version
node -v
pnpm -v
mysql --version

没有 pnpm 时，用 Corepack 安装仓库要求的版本：

corepack enable
corepack prepare pnpm@11.1.2 --activate

Maven 命令统一使用仓库内的 settings：

mvn -s .mvn/settings.xml ...

不应为 Crest 修改全局 Maven 配置。全局配置会影响同一台机器上的其他 Java 项目。

2. 拉取 v1.5.7 源码

git clone https://github.com/sevoniva/Crest.git
cd Crest
git checkout v1.5.7
git switch -c feat/my-local-work

v1.5.7 是本页对应的版本。排查问题时不应混用 main、其他功能分支或旧版本 dump，避免数据库结构与代码版本不一致。

打开项目：

code .

VS Code 至少安装这些扩展：

扩展用途
Extension Pack for Java识别 Maven 模块、运行后端入口
Maven for Java查看 Maven 生命周期和依赖
Vue - OfficialVue 3 和 TypeScript 支持
ESLint前端代码检查
YAML编辑配置文件

如果后端调试较多，也可以用 IntelliJ IDEA 打开根目录 pom.xml。

3. 准备 Crest 元数据库

先创建一个独立元数据库。这里的 crest 是本地开发库名，可按团队规范调整为 crest_dev_<name>。

CREATE DATABASE IF NOT EXISTS crest
  DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_0900_ai_ci;

如果当前 MySQL 不支持 utf8mb4_0900_ai_ci，使用：

CREATE DATABASE IF NOT EXISTS crest
  DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_general_ci;

检查当前数据库是不是标准 MySQL：

SELECT VERSION();
SELECT @@version_comment;
SELECT GET_LOCK('crest_dev_check', 1);
SELECT RELEASE_LOCK('crest_dev_check');

GET_LOCK() 返回 1 时，适合使用 Flyway 自动初始化。若返回 FUNCTION GET_LOCK does not exist，通常说明当前数据库不是完整 MySQL 能力，或 MySQL 兼容层不支持命名锁。此时应更换标准 MySQL，或手工导入初始化 SQL 后关闭 Flyway。

4. 导入数据

方案 A：有 v1.5.7 开发库 dump

这是团队协作场景下的推荐方式。dump 通常已经包含管理员、菜单、权限、示例数据源、数据集、仪表盘和数据大屏。

mysql -h127.0.0.1 -P3306 -uroot -p -e "
DROP DATABASE IF EXISTS crest;
CREATE DATABASE crest DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
"

mysql -h127.0.0.1 -P3306 -uroot -p crest < crest-v1.5.7-dev.sql

导入完整 dump 后，本地启动必须关闭 Flyway：

export SPRING_FLYWAY_ENABLED=false

同时确认运行密钥。dump 里的数据源密码、SSO Client Secret 等敏感配置是加密保存的，运行时密钥要和 dump 来源环境一致。

dump 来源本地要保留的密钥
标准加密模式CREST_AES_KEY、CREST_AES_IV
国密模式CREST_CRYPTO_MODE=sm-suite、CREST_SM4_KEY，同时保留原 AES 配置以兼容历史数据

密钥不一致时，后端可以启动，但保存过的业务数据源可能连接失败。

方案 B：没有 dump，空库初始化

没有开发库 dump 时，让 Flyway 在空库上初始化。

export SPRING_FLYWAY_ENABLED=true
export CREST_LOAD_DEMO=true
export CREST_FLYWAY_LOCATIONS='classpath:db/migration,classpath: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

如需最小化初始化，不加载演示数据：

export SPRING_FLYWAY_ENABLED=true
export CREST_LOAD_DEMO=false
export CREST_FLYWAY_LOCATIONS='classpath:db/migration'

首次启动成功后，元数据库里会出现 crest_schema_version 表。

方案 C：数据库不支持 GET_LOCK

仅在本地验证且无法更换标准 MySQL 时，才建议手工导入初始化 SQL：

mysql -h127.0.0.1 -P3306 -uroot -p crest \
  < core/core-backend/src/main/resources/db/migration/V1.5.0.1__initial_schema.sql

需要演示资源时再导入：

mysql -h127.0.0.1 -P3306 -uroot -p crest \
  < core/core-backend/src/main/resources/db/demo-migration/V1.5.0.2__demo_resources.sql

手动导入后也要关闭 Flyway：

export SPRING_FLYWAY_ENABLED=false

5. 写本地环境变量

本地配置放在 .local/crest-dev-env.sh。这个目录已经在 .gitignore 里，不会被提交。

mkdir -p .local .runtime/{excel,exportData,ehcache,logs}
touch .local/crest-dev-env.sh

把下面内容写进去。先按自己的数据库密码改 CREST_DB_PASSWORD。

export SPRING_PROFILES_ACTIVE=standalone
export SERVER_PORT=8100

export CREST_DB_URL='jdbc:mysql://127.0.0.1:3306/crest?autoReconnect=false&useUnicode=true&characterEncoding=UTF-8&characterSetResults=UTF-8&zeroDateTimeBehavior=convertToNull&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai'
export CREST_DB_USERNAME='root'
export CREST_DB_PASSWORD='your_mysql_password'

export CREST_ORIGIN_LIST='http://localhost:8080,http://127.0.0.1:8080,http://localhost:8100,http://127.0.0.1:8100'
export CREST_INITIAL_PASSWORD='Crest_dev_2026'

export CREST_PATH_EXCEL="$PWD/.runtime/excel"
export CREST_PATH_EXPORT_DATA="$PWD/.runtime/exportData"
export CREST_PATH_EHCACHE="$PWD/.runtime/ehcache"
export CREST_LOG_PATH="$PWD/.runtime/logs"

如导入团队 dump，在同一个文件里继续写：

export SPRING_FLYWAY_ENABLED=false
export CREST_LOAD_DEMO=false
export CREST_FLYWAY_LOCATIONS='classpath:db/migration'

export CREST_CRYPTO_MODE='standard'
export CREST_AES_KEY='replace_with_dump_source_aes_key'
export CREST_AES_IV='replace_with_dump_source_aes_iv'
export CREST_SM4_KEY=''

如使用空库初始化，在同一个文件里写：

export SPRING_FLYWAY_ENABLED=true
export CREST_LOAD_DEMO=true
export CREST_FLYWAY_LOCATIONS='classpath:db/migration,classpath:db/demo-migration'

export CREST_CRYPTO_MODE='standard'
export CREST_AES_KEY='12345678901234567890123456789012'
export CREST_AES_IV='1234567890123456'
export CREST_SM4_KEY=''

上面这组 AES 值只适合本机新库。共享环境、测试环境和生产环境必须使用独立密钥。

加载配置：

source .local/crest-dev-env.sh

本页涉及的核心变量来自这些源码配置：

变量源码位置说明
CREST_DB_URLcore/core-backend/src/main/resources/application-standalone.yml后端连接 Crest 元数据库
SPRING_FLYWAY_ENABLEDSpring Boot 标准变量控制 spring.flyway.enabled
CREST_FLYWAY_LOCATIONSapplication-standalone.yml控制是否加载演示迁移
CREST_LOAD_DEMOapplication.yml、application-standalone.yml控制演示资源开关
CREST_AES_KEY / CREST_AES_IVapplication.yml标准模式下加密敏感配置
CREST_CRYPTO_MODE / CREST_SM4_KEYapplication.yml国密模式配置
CREST_INITIAL_PASSWORDapplication.yml空库初始化时的管理员初始密码

6. 本地常用关闭项

项什么时候关怎么关
Flyway已经导入完整 dumpSPRING_FLYWAY_ENABLED=false
演示数据dump 里已有数据，或只想要纯净库CREST_LOAD_DEMO=false
演示迁移目录不需要演示资源CREST_FLYWAY_LOCATIONS=classpath:db/migration
SSO本地不调单点登录在本地库里关闭 SSO
旧业务数据源地址dump 里的源库本机连不上到页面里把数据源改成可访问的内网地址

关闭本地库里的 SSO：

UPDATE sys_setting SET pval = 'false' WHERE pkey = 'sso.enabled';
UPDATE auth_sso_provider SET enabled = 0;

以上 SQL 仅用于本地开发库，不应在共享测试库或生产库直接执行。

7. 启动后端

入口类：

core/core-backend/src/main/java/io/crest/CoreApplication.java

VS Code 启动

最稳的方式是在 VS Code 终端里启动。这样 .local/crest-dev-env.sh 一定能生效。

source .local/crest-dev-env.sh
mvn -s .mvn/settings.xml \
  -pl :core-backend -am \
  spring-boot:run \
  -Dspring-boot.run.profiles=standalone \
  -Dmaven.antrun.skip=true

如使用 VS Code 的 Run 按钮启动后端，可以新建 .vscode/launch.json。.vscode 已被仓库忽略，不应提交。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Crest Backend",
      "request": "launch",
      "mainClass": "io.crest.CoreApplication",
      "projectName": "core-backend",
      "env": {
        "SPRING_PROFILES_ACTIVE": "standalone",
        "SERVER_PORT": "8100",
        "CREST_DB_URL": "jdbc:mysql://127.0.0.1:3306/crest?autoReconnect=false&useUnicode=true&characterEncoding=UTF-8&characterSetResults=UTF-8&zeroDateTimeBehavior=convertToNull&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai",
        "CREST_DB_USERNAME": "root",
        "CREST_DB_PASSWORD": "your_mysql_password",
        "SPRING_FLYWAY_ENABLED": "false",
        "CREST_LOAD_DEMO": "false",
        "CREST_CRYPTO_MODE": "standard",
        "CREST_AES_KEY": "replace_with_dump_source_aes_key",
        "CREST_AES_IV": "replace_with_dump_source_aes_iv",
        "CREST_SM4_KEY": "",
        "CREST_INITIAL_PASSWORD": "Crest_dev_2026",
        "CREST_ORIGIN_LIST": "http://localhost:8080,http://127.0.0.1:8080",
        "CREST_PATH_EXCEL": "${workspaceFolder}/.runtime/excel",
        "CREST_PATH_EXPORT_DATA": "${workspaceFolder}/.runtime/exportData",
        "CREST_PATH_EHCACHE": "${workspaceFolder}/.runtime/ehcache",
        "CREST_LOG_PATH": "${workspaceFolder}/.runtime/logs"
      }
    }
  ]
}

如使用空库初始化，将 SPRING_FLYWAY_ENABLED 和 CREST_LOAD_DEMO 改成 true，并将 AES 值替换为本机新库使用的值。

IDEA 启动

用 IntelliJ IDEA 打开根目录 pom.xml 后，新建 Spring Boot 运行配置：

配置项值
Main classio.crest.CoreApplication
Active profilesstandalone
JDK21
Environment variables粘贴 .local/crest-dev-env.sh 中的变量
Working directory项目根目录

启动后检查：

curl http://localhost:8100/v3/api-docs

能返回 OpenAPI JSON，说明后端服务已启动。浏览器也可以访问：

http://localhost:8100/doc.html

JAR 方式启动

仅在验证打包产物时需要使用该方式启动。

source .local/crest-dev-env.sh
./run.sh start
tail -f logs/stdout.log

停止：

./run.sh stop

./run.sh start 依赖 core/core-backend/target/CoreApplication.jar，所以要先完成后端打包。

8. 启动前端

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

访问：

http://localhost:8080

如果 8080 被占用，Vite 可能自动切到 8081 或其他本地端口。v1.5.6 已兼容本地开发端口变化，登录请求不应因为端口从 8080 切到 8081 就被 CORS 拦截。若使用自定义域名、内网 IP 或代理地址访问前端，再按实际访问地址补充 CREST_ORIGIN_LIST。

开发代理在：

core/core-frontend/config/dev.ts

默认代理到：

target: 'http://localhost:8100'

如果后端部署在内网机器，例如 http://192.168.1.20:8100，可临时修改该 target。提交前必须确认未提交个人内网地址：

git diff -- core/core-frontend/config/dev.ts

登录账号：

数据来源登录方式
导入团队 dump用 dump 里的管理员密码
空库初始化用户名 admin，密码为 CREST_INITIAL_PASSWORD

如果页面跳到 SSO 登录，先按前文 SQL 关闭本地 SSO。

v1.5.6 起统一登录入口。本地账号、管理员账号和应急登录都从同一登录页进入；旧 token 损坏或过期时，刷新页面后应回到登录页，而不是停留在空白页面。

v1.5.7 本地联调建议额外验证：

功能验证方式
MySQL 数据集缓存创建 MySQL 数据源和数据集，切换缓存读取，执行立即更新，检查源数据行数、缓存行数和一致性状态
增量缓存选择增量字段，执行一次同步；切换增量字段或更新方式后，确认水位按新配置重新计算
API JsonPath配置返回路径为 $data.dataList 的 API 表，确认字段按子节点解析且字段选择可编辑
API Authorization在请求头中配置标准 Authorization，确认测试请求和数据集预览都能返回
公开分享链接登录后台后访问 /link/:uuid，确认进入分享展示页，而不是跳转工作台

9. v1.5.7 前后端分离开发场景

只改前端

前端开发需要一个可访问后端。后端可来自三种来源：

后端来源适合场景前端需要做什么
本机后端同时调接口和页面保持 target: 'http://localhost:8100'
内网后端只改页面、样式、交互把 config/dev.ts 的 target 改成内网后端地址
发布后端镜像本机有 Docker，但不想编译 Java运行 ghcr.io/sevoniva/crest-service:v1.5.7，前端代理到该服务

提交前应确认未提交个人内网地址：

git diff -- core/core-frontend/config/dev.ts

只改后端

后端开发不要求本机有 Node.js、pnpm 或前端 dist。按前文配置好 MySQL、Flyway、加密密钥和文件目录后，可以直接启动 io.crest.CoreApplication。

如果需要浏览器页面配合验证，有两种方式：

方式说明
使用已有前端环境前端代理到你的后端端口
使用发布前端镜像运行 ghcr.io/sevoniva/crest-web:v1.5.7，让网关转发到你的后端

后端独立打包时使用 -Dcrest.copy.frontend.skip=true，避免 Maven 因为没有前端 dist 而失败。

验证前后端分离镜像

需要验证镜像、Nginx 转发、WebSocket、健康检查或监控时，再同时构建前端和后端：

cd core/core-frontend
pnpm install --frozen-lockfile
pnpm run build:base

cd ../..
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 crest-service:local .
docker build -f Dockerfile.frontend -t crest-web:local .

本机没有 Docker 时，不影响前端或后端源码开发。镜像构建可以交给 CI 或具备 Docker 的构建环境。

10. 开发时经常要改什么

场景改哪里注意事项
本地 MySQL 密码变了.local/crest-dev-env.sh 的 CREST_DB_PASSWORD不改 application-standalone.yml
后端端口不是 8100SERVER_PORT 和前端 config/dev.ts两边端口要一致
dump 来自国密环境CREST_CRYPTO_MODE=sm-suite、CREST_SM4_KEY密钥必须和 dump 来源一致
业务数据源连不上Crest 页面里的“数据源”配置避免把 Crest 元数据库当成业务数据源修改
不加载演示资源CREST_LOAD_DEMO=false、CREST_FLYWAY_LOCATIONS=classpath:db/migration只对空库初始化有意义
导入完整 dumpSPRING_FLYWAY_ENABLED=false防止重复迁移
文件上传或导出路径报错CREST_PATH_EXCEL、CREST_PATH_EXPORT_DATA、CREST_PATH_EHCACHE指向 .runtime，避免写入 /opt/crest

开发业务页面时，优先在系统里改数据源连接、数据集和仪表盘配置。只有确认是产品逻辑问题，再改代码。

11. 打包

没有 Docker，只打后端 JAR

只验证后端产物时，不需要构建前端：

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

产物：

core/core-backend/target/CoreApplication.jar

需要内嵌前端静态资源

只有验证旧式内嵌静态资源 JAR 时，才先构建前端：

cd core/core-frontend
pnpm install --frozen-lockfile
pnpm run build:base
cd ../..

再打后端包，不使用 -Dcrest.copy.frontend.skip=true：

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

产物：

core/core-backend/target/CoreApplication.jar

这种方式会把 core/core-frontend/dist 复制到后端静态资源目录。v1.5.7 的正式发布镜像采用前后端分离，日常后端开发一般不需要这样打包。

只做后端编译检查

改动 Java 代码后，如仅需编译校验：

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

有 Docker，构建前后端镜像

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

构建前端镜像前，必须先执行 pnpm run build:base，确保 core/core-frontend/dist 已存在。

12. 常见问题

启动时报 FUNCTION GET_LOCK does not exist

Flyway 在 MySQL 上会用 GET_LOCK() 做迁移锁。当前数据库不支持这个函数时，迁移会失败。

处理顺序：

  1. 优先换标准 MySQL 8.x。
  2. 如果只是本地临时验证，手动导入初始化 SQL。
  3. 手动导入后设置 SPRING_FLYWAY_ENABLED=false。
  4. 不应自行创建同名函数绕过迁移锁。

导入 dump 后业务数据源连接失败

按这个顺序查：

  1. CREST_AES_KEY 和 CREST_AES_IV 是否与 dump 来源一致。
  2. dump 是否来自国密环境；如果是，CREST_SM4_KEY 是否一致。
  3. 数据源地址是否是旧内网地址，本机是否能访问。
  4. 数据源账号是否限制来源 IP。

建议在 Crest 的“数据源”页面打开对应数据源，改为当前内网可访问地址，重新填写密码并保存。

后端能启动，前端接口全部失败

先确认后端：

curl http://localhost:8100/v3/api-docs

再确认前端代理：

core/core-frontend/config/dev.ts

后端如果不是 8100，前端 target 也要改。

登录后一直跳 SSO

本地库里关闭 SSO：

UPDATE sys_setting SET pval = 'false' WHERE pkey = 'sso.enabled';
UPDATE auth_sso_provider SET enabled = 0;

然后重启后端，刷新前端页面。

空库初始化后管理员密码不对

空库初始化时，管理员 admin 的密码来自 CREST_INITIAL_PASSWORD。如果启动时没有配置该变量，后端会拒绝创建初始密码。

确认当前终端已经加载本地配置：

echo $CREST_INITIAL_PASSWORD

打包时报前端 dist 不存在

仅打后端 JAR 时，优先加上 -Dcrest.copy.frontend.skip=true。只有打内嵌静态资源 JAR 或构建前端镜像时，才需要先生成前端 dist。

生成前端 dist：

cd core/core-frontend
pnpm install --frozen-lockfile
pnpm run build:base
cd ../..

再执行对应的 Maven 打包或前端镜像构建命令。

13. 提交前检查

这些内容不能提交：

.local/
.runtime/
logs/
*.pid
core/core-frontend/node_modules/
core/core-frontend/dist/
core/core-backend/target/
.vscode/
.idea/
.flattened-pom.xml

提交前执行：

git status --short
git diff --stat

确认没有提交数据库密码、Token、证书、个人内网地址、临时 dump、运行日志和打包产物。

开发总览

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

问题索引

Crest 安装登录、权限、数据可视化、单点登录和 Kubernetes 常见问题索引。

本页目录

最常用的开发流程拉代码导入元数据库写本地环境变量关闭本地不需要的功能启动服务1. 准备工具2. 拉取 v1.5.7 源码3. 准备 Crest 元数据库4. 导入数据方案 A：有 v1.5.7 开发库 dump方案 B：没有 dump，空库初始化方案 C：数据库不支持 GET_LOCK5. 写本地环境变量6. 本地常用关闭项7. 启动后端VS Code 启动IDEA 启动JAR 方式启动8. 启动前端9. v1.5.7 前后端分离开发场景只改前端只改后端验证前后端分离镜像10. 开发时经常要改什么11. 打包没有 Docker，只打后端 JAR需要内嵌前端静态资源只做后端编译检查有 Docker，构建前后端镜像12. 常见问题启动时报 FUNCTION GET_LOCK does not exist导入 dump 后业务数据源连接失败后端能启动，前端接口全部失败登录后一直跳 SSO空库初始化后管理员密码不对打包时报前端 dist 不存在13. 提交前检查