Core Prepare

准备工作

在开始 StackPanel 开发之前，请确保本地环境满足以下要求。

环境要求

依赖	最低版本	说明
Node.js	22+	推荐 26 LTS；项目 engines 要求 >=22
pnpm	11.5.1	包管理器，packageManager 字段锁定
PM2	7+	进程管理，随 devDependencies 安装

存储引擎唯一为 PostgreSQL（ADR-0019）。开发可用 bash scripts/deploy.sh 一键拉起内置 PostgreSQL/Redis/MinIO。

macOS / Linux 开发体验最佳。Windows 建议使用 WSL2。

安装依赖

git clone <repo-url> StackPanel
cd StackPanel
pnpm install

pnpm install 会自动执行 workspace 包的 prepare 脚本：生成 @stackpanel/db 的 Prisma Client 与 dist，并构建 @stackpanel/sdk、@stackpanel/spec、@stackpanel/ui 的 dist 产物。如果后续手动修改了 SDK 源码，需要重新构建：

pnpm --filter @stackpanel/sdk build

数据库初始化

默认使用 PostgreSQL（唯一存储引擎，ADR-0019）。首次运行前确保 DATABASE_URL 指向一个可达的 PostgreSQL，并应用迁移：

pnpm --filter @stackpanel/api prisma:deploy

这会把迁移应用到 DATABASE_URL 指向的 PostgreSQL 库。Prisma Client 由 @stackpanel/db 的 prepare/generate（prisma generate）生成，migrate deploy 不会触发。

开发回退：无 REDIS_URL 用进程内实现，STORAGE_DRIVER=local 落本地盘； 生产缺 Redis 或用本地盘会启动即失败（ADR-0017）。快速起一套依赖： bash scripts/deploy.sh（内置 PG/Redis/MinIO）。

配置环境变量

cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

编辑 .env 文件，至少确保以下值正确：

变量	说明
DATABASE_URL	PostgreSQL DSN（唯一引擎，ADR-0019）
JWT_SECRET	≥32 字符的随机字符串
SETTINGS_ENCRYPTION_KEY	≥32 字符，用于加密密钥存储
STACKPANEL_BOOTSTRAP_EMAIL	首启管理员邮箱
STACKPANEL_BOOTSTRAP_PASSWORD	留空则启动时随机生成并打印一次

生成强随机密钥：

openssl rand -base64 48

验证安装

pnpm typecheck   # TypeScript 类型检查
pnpm lint        # ESLint
pnpm test        # Vitest（需要可达的 PostgreSQL；测试库自动 drop/create）
pnpm build       # 构建全部产物

API 集成测试必须串行运行（vitest.config.ts 已设 fileParallelism: false），因为测试间共享数据库状态。

首次启动

pnpm pm2:start

PM2 会启动两个进程：

进程	端口	说明
stackpanel-api	3001	Fastify API 服务
stackpanel-web	3000	Next.js 前端 + BFF

验证：

curl http://127.0.0.1:3001/health   # {"status":"ok",...}
curl http://127.0.0.1:3001/ready    # {"status":"ready","database":"ok"}
curl http://127.0.0.1:3000/         # 前端页面

首次启动时，如果数据库中无用户，系统会自动创建 bootstrap 管理员。密码会在 API 日志中打印一次：

pm2 logs stackpanel-api --lines 20

常见问题

prisma:generate 找不到 client

确保 @stackpanel/db 已构建：

pnpm --filter @stackpanel/db build

apps/api 的 prebuild 和 pretypecheck 脚本会自动执行此步骤。

内置插件 seed 失败

内置插件的 dist 产物必须先构建。如果修改了插件源码，需要重新构建 API（会触发 prebuild → @stackpanel/db build）以及插件本身：

pnpm --filter @stackpanel/plugin-store build

API 启动时会比较 dist 内容哈希，自动重新 seed 变更的内置插件。

PM2 重启后插件状态被重置

多次重启后 DB 中内置插件 enabled 可能为 false。通过管理后台 /admin/plugins 重新启用，或调用 API：

curl -X PATCH http://127.0.0.1:3001/admin/plugins/store \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'