Core Run

运行项目

StackPanel 有两种启动方式：PM2 常驻运行（api + web 两个进程）与 watch 开发模式（API、Web 分别热重载）。

PM2 模式（推荐）

PM2 配置在 ecosystem.config.cjs 中，启动两个进程：

pnpm pm2:start    # 启动 api(:3001) + web(:3000)
pnpm pm2:stop     # 停止并移除所有进程

查看日志：

pm2 logs                          # 全部日志
pm2 logs stackpanel-api --lines 50  # API 日志
pm2 monit                         # 资源监控面板

PM2 配置了 autorestart: true 和 max_memory_restart: 512M，进程崩溃或内存超限时自动重启。日志写入 logs/ 目录。

开发模式（热重载）

开发时分别启动 API 和 Web 的 watch 模式，获得热重载：

# 终端 1：API 热重载（tsx watch）
pnpm --filter @stackpanel/api dev

# 终端 2：Web 热重载（Next.js Turbopack）
pnpm --filter @stackpanel/web dev

API 使用 tsx watch src/server.ts，源码修改后自动重启。Web 使用 Next.js Turbopack，前端修改即时生效。

开发模式下不需要 PM2。确保 DATABASE_URL 等环境变量已正确配置：API 通过 dotenv 读取其进程工作目录下的 apps/api/.env（根 .env 仅由 Prisma CLI 读取，不会被 API 进程自动加载）。

日志脱敏

Fastify logger 配置了 redact，自动屏蔽请求中的敏感头：

{
  "redact": {
    "paths": ["req.headers.authorization", "req.headers.cookie"],
    "censor": "[REDACTED]"
  }
}

日志级别通过 API_LOG_LEVEL 环境变量控制（fatal/error/warn/info/debug/trace/silent）。

数据库迁移

数据库为 PostgreSQL（唯一存储引擎）。仓库约定手写 migration.sql、用 migrate deploy 应用，不得使用 migrate dev（它会隐式生成基线、污染迁移历史）。

# 修改 packages/db/prisma/schema.prisma 后，生成增量 SQL（对当前库与目标 schema 取差集；人工审阅后落到新迁移目录）
# 注意：--from-migrations 在 Prisma 7 需要 prisma.config.ts 配置 shadowDatabaseUrl，本仓库未配，改用当前库作为基准。
pnpm --filter @stackpanel/db exec prisma migrate diff \
  --from-config-datasource \
  --to-schema prisma/schema.prisma --script

pnpm --filter @stackpanel/api prisma:status     # 查看迁移状态
pnpm --filter @stackpanel/api prisma:deploy     # 应用已有迁移（开发/生产一致）

本地起一个 PostgreSQL（默认档由 compose 提供）：

docker run -d --name sp-pg -e POSTGRES_USER=stackpanel \
  -e POSTGRES_PASSWORD=stackpanel -e POSTGRES_DB=stackpanel \
  -p 5432:5432 postgres:16-alpine

停止与清理

pnpm pm2:stop       # 停止 PM2 进程
pm2 kill            # 完全停止 PM2 守护进程

数据目录 data/（插件/主题文件）与 PostgreSQL 数据库都不会被自动清理。如需重建数据库（开发环境，慎用），对目标库执行 DROP SCHEMA public CASCADE; CREATE SCHEMA public; 后重新应用迁移：

pnpm --filter @stackpanel/api prisma:deploy