Core Structure

项目结构

StackPanel 是一个 pnpm monorepo（无 Turborepo），workspace 配置在 pnpm-workspace.yaml。

顶层结构

StackPanel/
├── apps/
│   ├── web/               # Next.js 16 渲染 + BFF 转发
│   └── api/               # Fastify 5，所有业务 API
├── packages/
│   ├── db/                # @stackpanel/db Prisma schema + client
│   ├── sdk/               # @stackpanel/sdk 类型安全客户端 + 插件契约
│   ├── spec/              # @stackpanel/spec 契约单一来源（API 版本 / OpenAPI）
│   ├── ui/                # @stackpanel/ui 共享自定义组件
│   ├── mcp/               # @stackpanel/mcp MCP Server（stdio / HTTP 传输）
│   ├── net-guard/         # @stackpanel/net-guard 出站请求守卫
│   ├── themes/
│   │   └── default/       # @stackpanel/themes-default 默认主题
│   └── plugins/           # 随内核分发的内置插件（每个是独立 workspace 包）
│       ├── login/                 # 邮箱密码登录
│       ├── store/                 # 商品/订单 + 订单结算处理器
│       ├── store-wallet/          # 钱包（余额/充值/管理）
│       ├── store-product-server/  # 服务器类商品类型
│       └── store-product-card/    # 卡密类商品类型
├── data/                  # 运行时数据：已安装的插件/主题包、上传文件（不入库）
├── scripts/               # 构建、数据库、签名脚本
├── docs/                  # 文档
├── ecosystem.config.cjs   # PM2 部署配置
├── pnpm-workspace.yaml
└── package.json

内置插件清单由各插件包 package.json 的 stackpanel.builtin 声明派生（apps/api/src/lib/plugins.ts 运行时扫描），上表仅示意。市场安装的第三方插件不进入 workspace，安装后落在 data/plugins/<id>/，目录内含 manifest.json、dist/ 与可选 frontend/。

apps/api

API 服务（Fastify 5），所有业务逻辑在此。

apps/api/
├── src/
│   ├── server.ts          # API 进程入口
│   ├── worker.ts          # 独立 worker 入口（队列消费 + 唯一前端构建者）
│   ├── app.ts             # Fastify 实例构建
│   ├── plugin-host.ts     # 内核服务 + 插件运行时的统一装配（API/worker 共用）
│   ├── infra.ts           # Redis / 对象存储基础设施单例
│   ├── config/env.ts      # Zod 环境变量校验
│   ├── auth/              # 内核认证服务
│   ├── payments/          # 内核支付服务
│   ├── wallet/            # 内核钱包服务
│   ├── fx/                # 内核汇率服务
│   ├── notifications/     # 内核站内通知服务
│   ├── state/             # 内核共享状态（Redis-ready）
│   ├── extensions/        # Extension 引擎（自定义模型 / 自定义资源）
│   ├── jobs/              # BullMQ 任务运行时 + 内核 sweep
│   ├── media/             # 媒体与附件
│   ├── backup/            # 导出 / 导入
│   ├── reseller/          # SP-V1 渠道伙伴
│   ├── observability/     # 指标 / OTel 追踪
│   ├── mcp/               # MCP 传输适配
│   ├── runtime/           # 跨副本运行时一致性
│   ├── lib/               # 业务逻辑库（框架无关）
│   ├── plugins/           # Fastify 插件（运行时、派发、认证、密钥、审计…）
│   └── routes/            # 路由定义
│       └── admin/         # 管理后台路由
├── scripts/pack-plugin.ts # 插件打包脚本
├── tsup.config.ts
└── package.json

详见 架构概览。

apps/web

Next.js 16 前端 + BFF。

apps/web/
├── src/
│   ├── app/
│   │   ├── (user)/        # 公开/用户路由组
│   │   │   ├── [...slug]/ # 通用 catch-all 用户路由（插件前端页面）
│   │   │   ├── login/     # 登录
│   │   │   └── register/  # 注册
│   │   ├── (account)/account/  # 账户中心（notifications/security/api-keys）
│   │   ├── (admin)/admin/ # 管理后台路由组
│   │   ├── auth/oauth/    # 第三方登录回调
│   │   ├── api/           # BFF 转发路由（notifications/store/plugins）
│   │   ├── feed.xml/      # SEO feed
│   │   └── preview/       # 主题预览
│   ├── components/        # React 组件
│   │   └── ui/            # shadcn/ui 组件（复制式）
│   ├── i18n/              # 国际化
│   ├── lib/               # BFF、页面解析器等
│   └── proxy.ts           # /admin 鉴权（Next 16 替代 middleware）
└── package.json

packages/db

Prisma schema 与生成的 client。

packages/db/
├── prisma/
│   ├── schema.prisma      # 数据模型定义
│   └── migrations/        # 迁移文件
├── src/
│   ├── generated/prisma/  # Prisma Client（自动生成）
│   └── client.ts          # createPrismaClient 工厂 + 基础设施导出
└── package.json

packages/sdk

类型安全的 API 契约与客户端，运行时依赖 zod 与 sanitize-html。

packages/sdk/
├── src/
│   ├── index.ts           # 公共导出
│   ├── plugin.ts          # 插件类型契约（PluginDefinition / EXTENSION_POINTS 等）
│   ├── client.ts          # ApiClient 类型安全 HTTP 客户端
│   ├── frontend.ts        # 前端包类型与路径匹配
│   ├── schemas.ts         # zod response schemas
│   ├── types.ts           # 响应类型
│   ├── auth.ts / payments.ts / wallet.ts / fx.ts / notifications.ts / state.ts
│   ├── commerce.ts / jobs.ts / seo.ts / sales.ts / fulfillment.ts / upstream.ts
│   ├── mcp.ts             # MCP 契约
│   ├── extensions.ts / models.ts  # Extension 引擎契约
│   ├── key-prefixes.ts    # Redis key 前缀唯一来源
│   └── errors.ts          # ApiError / PluginError
└── package.json

packages/plugins/*

随内核分发的内置插件，每个是独立的 workspace 包。

packages/plugins/<name>/
├── src/
│   └── index.ts           # 插件入口（definePlugin）
├── frontend/              # 可选前端包
│   ├── src/
│   └── manifest.json
├── dist/                  # 编译产物（build-plugin.mjs）
├── tsconfig.json          # 类型检查
├── tsconfig.build.json    # 出声明
└── package.json

packages/themes/default

默认主题，配置化（无可执行代码）。

packages/themes/default/
├── theme.json             # 主题清单
├── theme.css              # CSS Token 声明
├── assets/                # 静态资源
└── frontend/              # 可选前端包

scripts/

脚本	说明
build-frontend.mjs	编译所有主题/插件的前端包并生成 web registry
build-plugin.mjs	编译单个插件的后端 dist（esbuild）
create-plugin.mjs	生成插件脚手架（pnpm plugin:create）
deploy.sh	默认档一键部署（api+worker+web+PG+Redis+MinIO）
install.sh	复用本机 PostgreSQL/Redis 的本地安装
frontend-supervisor.mjs	PM2 下 web 前端构建/重启监督
smoke-cluster.mjs	双副本集群冒烟（会话/限流/事件/任务/一致性）
verify-s2.mjs	对象存储 + Redis + 生产校验（S2）
verify-lb.mjs	Caddyfile LB 契约运行时验证（pnpm verify:lb）
verify-image.sh	发布镜像 cosign 验签
backup.sh / restore.sh / backup-drill.sh	PostgreSQL + 对象存储备份/恢复/演练
sign-package.mjs	Ed25519 包签名工具
licenses.sh	许可证检查脚本