环境搭建
本页面向需要完整本地开发环境的开发者。第一次克隆项目并启动最小服务请先阅读 快速开始；本页再补充依赖、配置、数据库、联调和质量检查细节。命令统一使用 Bash、POSIX 路径和 mise。
运行边界
spectra-admin 是由 spectra-launch 组合的 Spring Boot 单体后端；启动只需要本机配置、PostgreSQL 和 Redis，不需要服务注册中心或远程配置中心。安全 Redis 是 Token、Session、验证码、防重放和登录失败锁定的事实源，不可用时必须 fail-closed。
| 配置/状态来源 | 内容 | 事实源 |
|---|---|---|
| 本地 YAML | application-dev.yml、application-prod.yml 的默认值和绑定 | spectra-admin/spectra-config/src/main/resources/ |
| 环境变量 | 数据库、Redis、S3、端口、TLS、CORS 和安全策略的环境差异 | mise 本机配置、进程环境或部署 Secret |
| PostgreSQL | 业务数据、系统配置、Flyway history 和安全审计热数据 | Flyway 迁移后的目标数据库 |
| Redis | Token、Session、验证码、防重放和登录失败锁定等安全运行态 | 安全 Redis；不可用时保持 fail-closed |
业务模块通过 spectra-launch 显式依赖和装配，不通过注册中心发现；模块扩展沿用同一单体组合根边界。
127.0.0.1 和 localhost 表示服务与客户端位于同一台机器。数据库、Redis 或后端放在容器、虚拟机、局域网或远程服务器时，必须换成实际可访问地址。
前置依赖
| 依赖 | 版本/要求 |
|---|---|
| Git、Bash、find、rg、Python 3 | 脚本和检查工具 |
| mise | 在 Bash 中可执行 |
| Java | Temurin 25.0.2，由 spectra-admin/mise.toml 固定 |
| Node.js / pnpm | 24.14.0 / 11.0.9，由两个 Node 项目的 mise.toml 固定 |
| Maven | 3.9.12，使用 spectra-admin/mvnw |
| PostgreSQL / Redis | 宿主机或远程服务；Redis 必须支持密码认证 |
项目不要求全局 Maven；后端 Wrapper 和 Java 版本均由 mise 管理。CodeGraph、Obsidian 和下文的 Agent 检查脚本都是可选工具，不是构建前置条件。
检查工具链：
mise --version
(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)1. 克隆并初始化
git clone --recurse-submodules https://github.com/yangxj96/spectra-docs.git spectra
cd spectra
git submodule status普通克隆补齐子模块：
git submodule update --init --recursive首次进入项目时审查并信任各自 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 信任是一次性人工安全决定。若本机配置文件变更后 mise 再次提示信任，先审查文件，再在对应子项目目录重新执行 mise trust；不要自动信任未知配置。
2. 恢复本机配置
cp spectra-admin/.mise.local.toml.example spectra-admin/.mise.local.toml
cp spectra-ui/.env.example spectra-ui/.env.development已有安全备份时直接恢复到上述路径。真实密码、Token、私钥、P12 和其他凭据只能保存在 Git 忽略的本机文件。
后端证书路径约定为 spectra-admin/files/ssl/keystore.p12，并需在本机配置中设置匹配的 SSL_PASSWORD、SSL_TYPE=PKCS12 和 SSL_ALIAS。详见 03-SSL证书配置。
后端本机配置中的变量按以下级别处理：
| 级别 | 变量 | 要求 |
|---|---|---|
| 启动必须真实可用 | DB_URL、DB_USERNAME、DB_PASSWORD、REDIS_HOST、REDIS_PORT、REDIS_DB、REDIS_PASSWORD | PostgreSQL 和 Redis 必须能连接 |
| 启动必须存在，功能启用时必须真实可用 | S3_* | 验证上传前接入真实对象存储 |
| 本机策略 | SERVER_PORT、SERVER_SSL_ENABLED、SSL_* | 模板默认 4004 + HTTPS；P12 和密码必须匹配 |
不要配置共享的 DEFAULT_PASSWORD 或把 SPECTRA_AGENT_* 回退变量写进公共文件。用户和密码重置使用随机临时凭证；接口加解密、通知开关和运行时密钥按系统设置引导管理。
3. 准备 PostgreSQL 与 Redis
createdb -h 127.0.0.1 -U postgres devops00_spectra_db
redis-cli -h 127.0.0.1 -p 6379 --askpass ping预期 Redis 返回 PONG。数据库结构和普通种子唯一由 spectra-admin/spectra-config/src/main/resources/db/migration/ 下的 Flyway 迁移管理。行政区划数据需要显式导入时执行：
./scripts/import-regions.sh新环境由 Flyway 按版本顺序初始化结构和普通种子；不要让 schema.sql/data.sql 与 Flyway 并行维护结构。约 66.5 万行区域 JSON 是独立参考数据包，只有在确认目标为隔离开发库后才运行导入脚本。已经执行过其他迁移链的数据库不属于直接升级范围，遇到历史版本缺失或 checksum mismatch 时应重建开发库或执行经过审查的一次性迁移，不能只用 flyway repair 掩盖差异。
Redis 建议使用带密码认证的 7.4.x 服务；不要求集群、哨兵、TLS 或持久化。当前流程不自动启动服务，也不使用 Docker/Compose。
4. 安装依赖
(cd logicflow-plugin-flowable && mise exec -- pnpm install && mise exec -- pnpm run build)
(cd spectra-ui && mise exec -- pnpm install)5. 启动后端和 Web
后端：
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"Web：
cd spectra-ui
mise exec -- pnpm start默认地址：后端 https://127.0.0.1:4004/api，Web https://localhost:5173。
Web 前端本机配置应保持：
# spectra-ui/.env.development
VITE_API_URL=https://127.0.0.1:4004/后端端口或部署位置变化时同步修改 API URL，并保持协议一致。
后端成功日志应包含 Started LaunchApplication 并显示 4004 端口。若前端页面能打开但接口失败，优先检查后端协议、端口、Web 环境文件和浏览器对开发证书的信任状态。
6. 可选质量检查
./scripts/agent-context.sh --facts
./scripts/check-agent-context.sh
./scripts/check-docs.sh
./scripts/check-module-boundaries.sh这些检查不负责激活 mise、安装依赖或启动服务。