# StackRivet-Server

**Repository Path**: xtym/stackrivet-server

## Basic Information

- **Project Name**: StackRivet-Server
- **Description**: 开源 AI 原生 Java 企业应用后端 / Spring Boot 后台管理系统框架，内置 RBAC、代码生成、OpenAPI、审计、资产存储、异步任务，适合 SaaS 与企业中后台快速开发。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# StackRivet Server

[![License](https://img.shields.io/badge/license-Apache--2.0-5E63E0)](LICENSE)
[![JDK](https://img.shields.io/badge/JDK-21-5E63E0)](pom.xml)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.0.6-5E63E0)](stackrivet-bom/pom.xml)
[![Docs](https://img.shields.io/badge/docs-stackrivet.zkthink.com-5E63E0)](https://stackrivet.zkthink.com/zh/docs)

[English](README.md) | 简体中文

面向 Spring Boot 和 Vue 团队的 AI 原生 Java 企业应用后端。

StackRivet Server 是 StackRivet Community 版的开源后端：一个模块化单体工程基座，帮助 Java 团队交付带 RBAC、行级数据权限、审计日志、带治理的代码生成、Asset Service、异步任务、可观测性和 AI 可读工程规则的真实企业应用。

[官网](https://stackrivet.zkthink.com/zh/) · [文档](https://stackrivet.zkthink.com/zh/docs) · [管理端 UI](https://github.com/zkmall/stackrivet-admin-ui) · [在线演示](https://stackrivet-admin.zkthink.com) · [English Docs](https://stackrivet.zkthink.com/docs)

> 生成带治理的业务模块，而不是松散 CRUD。把架构、权限、审计、OpenAPI、测试、对象存储和可升级路径放在同一条交付流里。

## 为什么是 StackRivet Server

大多数 Java 后台框架都能生成 CRUD。真实项目需要的是更多确定性。

- **AI 工程护栏**：`AGENTS.md`、`llms.txt`、模块规则和开发标准，让 Codex、Cursor、Claude Code 在明确边界内工作。
- **带治理的代码生成**：后端代码、前端页面、菜单、权限、OpenAPI 注解和测试骨架一起生成。
- **企业级访问控制**：Spring Security、JWT、RBAC、菜单 / 按钮 / API 权限和行级数据权限强制。
- **生产级 Asset Service**：Local、S3 兼容、阿里云 OSS、签名 URL、元数据校验和分片上传路径。
- **可观测交付基线**：traceId、Actuator、Micrometer、可选 OpenTelemetry profile、SBOM 和 CI 门禁。
- **可升级二开路径**：Flyway 迁移、模块 manifest、生成文件纪律和清晰的架构规则。

## 快速开始

启动后端数据存储，构建 Maven reactor，并运行启动应用。

```bash
# Redis 用于 JWT 吊销和 actuator 健康检查。
docker compose up -d mysql redis

mvn install -DskipTests=true
mvn -pl stackrivet-app spring-boot:run
```

然后在相邻仓库启动管理端 UI：

```bash
cd ../stackrivet-admin-ui
pnpm install
pnpm dev
```

打开管理控制台：`http://127.0.0.1:5173/`。

OpenAPI 位于 `/v3/api-docs` 和 `/swagger-ui`，但需要 bearer token。管理端口默认独立且绑定本机回环地址：

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

推荐按公开文档走完整路径：

- [快速开始](https://stackrivet.zkthink.com/zh/docs/getting-started/quick-start)
- [安装指南](https://stackrivet.zkthink.com/zh/docs/getting-started/installation)
- [生成一个模块](https://stackrivet.zkthink.com/zh/docs/guides/generate-a-module)
- [部署](https://stackrivet.zkthink.com/zh/docs/guides/deployment)

## 开箱即带什么

| 能力域 | Community 版包含 |
| --- | --- |
| 运行时 | JDK 21、Spring Boot 4.0.6、Spring Security、MyBatis-Plus、Flyway |
| 架构 | 模块化单体、Maven reactor、架构边界测试 |
| 系统管理 | 用户、部门、岗位、角色、菜单、字典、参数 |
| 安全 | JWT、RBAC、菜单 / 按钮 / API 权限、行级数据权限 |
| 审计 | 登录日志、操作日志、异常日志、traceId 关联 |
| 代码生成 | 表导入、类型映射、模板渲染、带治理写入 |
| Asset Service | Local、S3 兼容、阿里云 OSS、签名 URL、分片上传路径 |
| 导入导出 | 框架无关的 CSV / XLSX 导入导出核心，可与异步任务组合 |
| 异步任务 | 任务状态机、进度、重试 / 取消状态、本地执行桥 |
| 可观测性 | Actuator、Micrometer、traceId、可选 OpenTelemetry profile |
| 插件基座 | 模块 manifest 加载、权限 / 菜单 / 字典注册 |
| 交付 | Docker Compose、Dev Container、CLI doctor、SBOM、CI workflows |

## 模块地图

Reactor 构建 16 个 Maven 模块。默认应用会把核心模块装配进 `stackrivet-app`；SnailJob adapter 会参与构建以保证兼容性，但除非主动接入，否则不进入默认运行时。

| 模块 | 职责 |
| --- | --- |
| `stackrivet-bom` | 集中管理 Spring Boot、MyBatis-Plus、springdoc、对象存储 SDK、EasyExcel 和 ArchUnit 版本 |
| `stackrivet-parent` | Parent POM、编译器 `release=21`、插件管理和依赖规则 |
| `stackrivet-common` | `R<T>`、`PageR<T>`、traceId holder、业务异常和共享基础类型 |
| `stackrivet-security` | 登录、JWT、RBAC、数据权限上下文和 token 管理 |
| `stackrivet-system` | 用户、部门、岗位、角色、菜单、字典和参数 |
| `stackrivet-audit` | 操作日志、登录日志、异常日志和 traceId 关联 |
| `stackrivet-asset` | Asset 元数据、存储适配器、签名 URL 和分片上传 |
| `stackrivet-generator` | 数据库内省、类型映射、模板渲染和带治理写入 |
| `stackrivet-import-export` | 框架无关的 CSV / XLSX 导入导出核心；XLSX 使用 EasyExcel，CSV 使用纯 JDK 路径 |
| `stackrivet-task` | 异步任务状态机、本地执行桥、调度 SPI 和 job handler registry |
| `stackrivet-observability` | Actuator、Micrometer、traceId 和可选 OpenTelemetry profile |
| `stackrivet-plugin` | 模块 manifest 加载、权限 / 菜单 / 字典注册 |
| `stackrivet-cli` | 轻量 CLI；当前提供 `doctor` |
| `stackrivet-demo` | 工单 CRUD 示例和定时任务 handler 示例 |
| `stackrivet-scheduler-snailjob` | 可选 SnailJob adapter；不是 `stackrivet-app` 的默认依赖 |
| `stackrivet-app` | Spring Boot 入口、运行时装配和 ArchUnit 架构边界测试 |

架构边界由 [`ArchitectureTest`](stackrivet-app/src/test/java/com/stackrivet/app/architecture/ArchitectureTest.java) 强制。

## 工程规则

改代码前先读：

- [`AGENTS.md`](AGENTS.md)
- [`llms.txt`](llms.txt)
- [`docs/development-standards.md`](docs/development-standards.md)
- [`CONTRIBUTING.md`](CONTRIBUTING.md)

核心规则简版：

- Controller -> Service -> Domain -> Mapper，不跨层。
- Entity 不离开持久化边界；API 使用 DTO / VO。
- 受保护接口必须声明 `@PreAuthorize(...)`。
- 数据库变更必须走 Flyway。
- 业务表存 `asset_id`，不要存原始文件 URL。
- 不记录密钥、密码、token 或 signed URL。
- 生成模块应走产品内生成器流程，不做自由复制粘贴。

## 开发校验

```bash
mvn -pl stackrivet-<module> -am test
mvn -pl stackrivet-app test -Dtest=ArchitectureTest
mvn verify
```

CI 覆盖 JDK 21 + JDK 25 兼容性、CodeQL、Dependabot 和发布信任检查。

## Community 与商业版本

本仓库包含 Apache-2.0 授权的 Community 后端。公开 Community 文档托管在 StackRivet 官网：

- [中文文档](https://stackrivet.zkthink.com/zh/docs)
- [English docs](https://stackrivet.zkthink.com/docs)
- [价格与版本边界](https://stackrivet.zkthink.com/zh/pricing)

Pro 和 Enterprise 资料会单独交付给授权客户，不属于本公开仓库。

## License

Apache License 2.0。详见 [`LICENSE`](LICENSE) 和 [`NOTICE`](NOTICE)。