安装

这是完整的本地安装：前置条件、获取代码、运行后端与 Vue 管理端。如果你只想用最短路径跑起本地全栈，快速开始 更短。

前置条件

工具	版本	用于
JDK	21	后端（必需运行时；发布检查同时覆盖 JDK 25 前瞻兼容）
Maven	3.9+	构建后端
Docker	任意较新版本	MySQL + Redis（可选 PostgreSQL / MinIO）
Node.js	24（>=24 <27）	管理端
pnpm	11	管理端包管理器

获取代码

StackRivet 是多仓库工作区：后端与管理端是两个独立的 git 仓库，并排克隆。（这与项目”不做 monorepo”的结构一致——每个仓库有自己的发布节奏和许可。）

git clone https://github.com/zkmall/stackrivet-server.git
git clone https://github.com/zkmall/stackrivet-admin-ui.git

也可以使用 Gitee 镜像：

git clone https://gitee.com/zkmall/stackrivet-server.git
git clone https://gitee.com/zkmall/stackrivet-admin-ui.git

把两个仓库作为同级目录放在同一父文件夹下；管理端默认后端就在其同级目录。

1. 启动数据存储

在 stackrivet-server 中启动 MySQL 和 Redis。Redis 支撑 JWT 吊销和 Actuator 健康检查，因此是必需的。

cd stackrivet-server
docker compose up -d mysql redis

仅当设置 STACKRIVET_DB_VENDOR=postgresql 时才加 postgres；仅当设置 STACKRIVET_STORAGE_TYPE=s3 时才加 minio。

2. 构建并运行后端

./mvnw -pl stackrivet-app -am install -DskipTests # 一次性构建应用及其 reactor 依赖
./mvnw -pl stackrivet-app spring-boot:run # 运行 Spring Boot 应用

API 在 8080 端口启动。通过管理端口上的健康检查确认后端：

curl http://127.0.0.1:9090/actuator/health

应返回 {"status":"UP"}。OpenAPI 位于 8080 端口的 /v3/api-docs，且需要 bearer token；见 API 约定。

3. 运行管理端

保持后端运行。在同一父目录下打开第二个终端，启动管理端：

cd stackrivet-admin-ui
corepack enable && corepack prepare pnpm@11 --activate   # 没装 pnpm 11 的话先跑这条
pnpm install
pnpm dev          # http://127.0.0.1:5173/

dev server 把 /api/* 代理到 8080 端口的后端，所以先启动后端。健康检查保留在独立的 9090 管理端口。你也可以打开设计系统展示页 http://127.0.0.1:5173/design-system。

4. 登录

打开 http://127.0.0.1:5173/，使用快速开始中全新本地数据库的种子账号登录。你应该进入管理后台 dashboard，这就是全栈端到端跑通了。该本地种子账号不是在线 Demo 凭据；生产级 profile 会拒绝种子密码并要求轮换（见部署）。

配置

后端从环境变量读取数据库和存储设置，并带合理的本地默认值：

变量	用途	示例
STACKRIVET_DB_VENDOR	数据库方言	mysql（默认）/ postgresql
STACKRIVET_STORAGE_TYPE	Asset Service 后端	local（默认）/ s3 / aliyun_oss

常用环境变量见配置。

下一步

• 项目结构 —— 仓库和模块如何组合在一起。
• 架构 —— 模块化单体设计与模块边界。