快速开始

本指南在本地跑起 StackRivet：后端、健康检查和 Vue 管理端。每个配置项的完整解释见安装。

前置条件

• JDK 21（默认支持的大版本；重大框架升级使用独立分支）
• Maven 3.9+
• Docker —— 用于在本地运行 MySQL 和 Redis
• Node.js 24 + pnpm 11 —— 用于运行管理端

0. 获取代码

把后端和管理端作为同级目录放在一起：

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

Gitee 镜像见安装。

1. 启动数据存储

默认 profile 使用 MySQL + Redis。Redis 支撑 JWT 吊销和 Actuator 健康检查，因此是必需的。

docker compose up -d mysql redis

仅当设置 STACKRIVET_DB_VENDOR=postgresql 时才需加 postgres；仅当设置 STACKRIVET_STORAGE_TYPE=s3 时才需加 minio。常用环境变量见配置。

2. 构建 reactor

后端是由 16 个 Maven 模块组成的模块化单体。先整体构建一次：

./mvnw -pl stackrivet-app -am install -DskipTests

3. 运行应用

stackrivet-app 是 Spring Boot 入口，把每个业务模块装配成可运行的应用：

./mvnw -pl stackrivet-app spring-boot:run

4. 确认后端

应用启动后，确认管理端口上的健康检查：

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

应返回 {"status":"UP"}。OpenAPI 也可用，但受认证保护；先登录，再带 bearer token 调用 /v3/api-docs。

5. 运行管理端

保持后端运行。在第二个终端里，从 stackrivet-admin-ui 仓库启动前端。Vite 会把 /api/* 代理到 8080 端口的后端；健康检查保留在独立的 9090 管理端口。需要 Node 24；用 Corepack 装 pnpm 11：

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

6. 登录

打开 http://127.0.0.1:5173/，用本地开发种子账号登录：

• 用户名： admin
• 密码： stackrivet2026

你应该进入管理后台 dashboard——这就是 StackRivet 端到端跑通了。

仅限本地开发： 上述凭据由数据库迁移为全新的本地数据库创建，不是在线 Demo 凭据。不要在保留种子密码时暴露或部署实例；生产级 profile 会拒绝该密码并要求轮换（见部署）。在线 Demo 请以其登录页上的说明为准。

如果卡住

现象	检查
MySQL 或 Redis 没起来	在 stackrivet-server 里执行 docker compose ps
后端占用不了 8080	停掉占用端口的旧进程
管理端提示 API 错误	确认后端仍在 127.0.0.1:8080 运行
没有 pnpm	先执行上面的 Corepack 命令，再重试 pnpm install

下一步

• 项目结构 —— 仓库和模块如何组合在一起。
• 生成第一个模块 —— 建一张小表，生成一个带治理的模块。

第一个模块跑通后，再继续看对象存储和部署。