快速开始

本页面向第一次克隆 Spectra 的开发者和试用者，目标是在一台 Linux 或 Ubuntu/WSL 机器上启动后端和 Web 管理后台。完整的依赖说明、数据库初始化细节和所有质量命令见 环境搭建 与 常见命令。

启动前提

需要准备：

• Git、Bash、Python 3 和 mise。
• Temurin Java 25.0.2、Maven Wrapper 3.9.12、Node.js 24.14.0 和 pnpm 11.0.9。
• PostgreSQL 18 和 Redis 7.4.x。Redis 必须启用密码认证。
• 能够在本机保存被 Git 忽略的配置文件和开发证书。

CodeGraph、Obsidian 和 Agent 辅助脚本不是构建和启动的前置条件。

获取源码

推荐使用递归克隆：

git clone --recurse-submodules https://github.com/yangxj96/spectra-docs.git spectra
cd spectra
git submodule status

如果已经普通克隆根仓库：

git submodule update --init --recursive

输出中应能看到 spectra-admin、spectra-ui 和 logicflow-plugin-flowable 三个子项目。

安装工具链

分别在三个子项目中审查并安装 mise.toml 声明的版本：

(cd spectra-admin && mise trust && mise install)
(cd spectra-ui && mise trust && mise install)
(cd logicflow-plugin-flowable && mise trust && mise install)

mise trust 是一次性人工确认。执行前检查对应的 mise.toml，不要自动信任来源不明的配置。

检查版本：

(cd spectra-admin && mise exec -- ./mvnw --version)
(cd spectra-ui && mise exec -- node --version && mise exec -- pnpm --version)
(cd logicflow-plugin-flowable && mise exec -- node --version && mise exec -- pnpm --version)

创建本机配置

只从模板创建本机配置：

cp spectra-admin/.mise.local.toml.example spectra-admin/.mise.local.toml
cp spectra-ui/.env.example spectra-ui/.env.development

后端配置至少需要确认以下内容：

• DB_URL、DB_USERNAME 和 DB_PASSWORD 指向可连接的 PostgreSQL 数据库。
• REDIS_HOST、REDIS_PORT、REDIS_DB 和 REDIS_PASSWORD 指向可用的 Redis 服务。
• SERVER_PORT=4004、SERVER_SSL_ENABLED=true 与本机证书配置匹配。
• S3_* 使用文件上传功能时替换为真实的 S3 或 MinIO 连接信息。
• SPECTRA_SECURITY_SECRET_MASTER_KEY 仅通过本机或部署环境注入，不能写入公开文档或提交到 Git。

前端 .env.development 的默认值为：

VITE_API_URL=https://127.0.0.1:4004/

如果后端修改了协议、地址或端口，前端必须同步修改 VITE_API_URL。

准备数据库和 Redis

创建开发数据库：

createdb -h 127.0.0.1 -U postgres spectra_db

验证 Redis：

redis-cli -h 127.0.0.1 -p 6379 --askpass ping

Redis 应返回 PONG。后端启动时由 Flyway 按 spectra-admin/spectra-config/src/main/resources/db/migration/ 中的迁移初始化数据库结构。行政区域参考数据不是启动必需项，需要时再执行：

./scripts/import-regions.sh

安装前端和插件依赖

(cd logicflow-plugin-flowable && mise exec -- pnpm install && mise exec -- pnpm run build)
(cd spectra-ui && mise exec -- pnpm install)

后端使用 Maven Wrapper 下载依赖，不需要全局安装 Maven。

启动后端

从根目录执行：

cd spectra-admin
mise exec -- ./mvnw clean package -DskipTests
jar=$(find spectra-launch/target -maxdepth 1 -type f -name 'spectra-launch-*.jar' ! -name '*.jar.original' -print -quit)
test -n "$jar"
mise exec -- java --add-modules ALL-SYSTEM --enable-native-access=ALL-UNNAMED \
  -Dspring.profiles.active=dev -jar "$jar"

后端默认监听 https://127.0.0.1:4004，接口前缀为 /api。启动日志应出现 Started LaunchApplication。

启动 Web 管理后台

在另一个终端从根目录执行：

cd spectra-ui
mise exec -- pnpm start

打开 https://localhost:5173。本地开发证书可能需要在浏览器中手动信任；页面能打开但接口请求失败时，先检查后端进程、VITE_API_URL、协议、端口和浏览器证书信任状态。

首次进入系统

首次启动时访问 /initialization 完成系统初始化；初始化入口用于创建首个运维用户和建立基础安全状态。初始化完成后从 /login 登录，再根据账号权限进入首页、系统管理或 OA 等菜单。

菜单和按钮由后端返回的权限数据控制。账号没有对应权限时，页面可能不显示菜单，也可能在直接访问受保护路由时进入无权访问页面；这不是通过修改前端菜单即可绕过的限制。

验证服务

后端健康检查地址：

https://127.0.0.1:4004/api/actuator/health

完成以下检查即表示本机最小环境已启动：

1. 健康检查能够返回应用状态。
2. Web 页面可以打开登录页。
3. 初始化或登录请求能够到达后端。
4. 登录后能够进入首页；如果菜单为空，检查账号角色和菜单权限。

常见阻塞点

现象	优先检查
后端无法启动	PostgreSQL、Redis、本机配置、证书密码和端口
页面能打开但接口失败	VITE_API_URL 是否与后端协议和端口一致
登录或刷新失败	Redis 密码、Redis 连通性、HTTPS、Cookie 和 CSRF 配置
上传失败	S3 配置或本地存储目录、文件类型策略和上传权限
页面没有菜单	用户状态、RoleAssignment、菜单权限和数据范围
流程页面不可用	Workflow 模块是否装配、流程设计器构建产物和对应权限

更完整的处理顺序见 使用指南中的问题排查 和 部署运维文档。

下一步阅读

• 使用指南：按业务任务使用系统。
• 环境搭建：完整开发环境和配置分级。
• 前端总览：前端页面和请求层。
• 后端架构分层：后端模块和代码边界。
• 配置参考：spectra: 配置逐项说明。