joaopedro08-dev/StackForge
GitHub: joaopedro08-dev/StackForge
一个基于 Node.js + Express 的 API 脚手架生成器，专注于安全认证与多环境快速交付。
Stars: 0 | Forks: 0
# StackForge
StackForge，Node.js + Express 的 API 脚手架生成器，包含：
- 注册
- 登录
- 检查登录会话
- 刷新令牌轮换
- 登出
## 技术栈
- Node.js（ESM）
- Express 5
- JWT（访问令牌）
- 存储在 `httpOnly` Cookie 中的刷新令牌
- 使用 bcrypt 进行密码哈希
- 使用 Zod 进行验证
- 使用 lowdb 的本地持久化（JSON 文件）
- 仓库层已准备好演进为关系型或非关系型数据库
## 本地运行
1. 安装依赖：
```
pnpm install
```
2. 从示例创建 `.env`：
```
node -e "require('node:fs').copyFileSync('.env.example', '.env')"
```
3. 启动开发模式：
```
pnpm dev
```
或以普通模式运行：
```
pnpm start
```
## 开发者引导
在默认工作区文件夹中创建新的认证 API 项目：
```
pnpm dev:new-project -- your-api-name
```
项目创建于 `developers/projects/your-api-name`。
配置：
- `lite`（默认）：启动更快的精简模板
- `full`：包含测试、文档和 CI
示例：
```
pnpm dev:new-project -- your-api-name --full
pnpm dev:new-project -- your-api-name --lang=typescript
pnpm dev:new-project -- your-api-name --ts
pnpm dev:new-project -- your-api-name --full --lang=typescript
pnpm dev:new-project -- your-api-name --db=mysql
pnpm dev:new-project -- your-api-name --db=sqlite
pnpm dev:new-project -- your-api-name --db=sqlserver
pnpm dev:new-project -- your-api-name --db=json
pnpm dev:new-project -- your-api-name --architecture=mvc
pnpm dev:new-project -- your-api-name --architecture=clean
pnpm dev:new-project -- your-api-name --api=graphql
pnpm dev:new-project -- your-api-name --api=hybrid
pnpm dev:new-project -- your-api-name --pm=npm
pnpm dev:new-project -- your-api-name --pm=yarn
pnpm dev:new-project -- your-api-name --pm=bun
pnpm dev:new-project -- your-api-name --features=both
pnpm dev:new-project -- your-api-name --features=none
pnpm dev:new-project -- --interactive
```
使用 `--lang=typescript` 时，生成的项目会为核心应用代码使用 `.ts` 文件，并通过省略 `scripts` 文件夹保持脚手架精简。
生成保证：
- `--lang=javascript`：生成 JavaScript 运行时文件（`index.js`、`src/**/*.js`），Vitest 配置为 `.mjs`，不包含 TypeScript 项目产物。
- `--lang=typescript`：生成 TypeScript 运行时文件（`index.ts`、`src/**/*.ts`），导入与 TS 兼容且运行时启动与 Docker 兼容（`pnpm start`）。
- 通过 `pnpm start` 保持与语言无关的 Docker 启动，避免硬编码 `index.js` 漂移。
数据库选项：
- `--db=json`：本地 JSON 数据库（生成的项目中不包含 Prisma 依赖）
- `--db=postgresql|mysql|sqlite|sqlserver`：为选定提供者配置 Prisma 的关系型模式
架构选项：
- `--architecture=layered`：分层模块/仓库流程（默认）
- `--architecture=mvc`：在 `src/` 下生成 `config`、`controllers`、`db`、`middlewares`、`models`、`routes`、`utils` 和 `views`，并添加 MVC 架构指南
- `--architecture=clean`：添加清洁架构文件夹和指南
API 风格选项：
- `--api=rest`：仅 REST 端点（默认）
- `--api=graphql`：GraphQL 端点脚手架（`/graphql`）
- `--api=hybrid`：REST + GraphQL 一起
包管理器选项：
- `--pm=pnpm`：保留 pnpm 命令和锁文件（默认）
- `--pm=npm`：为 npm 使用重写生成的命令/脚本
- `--pm=yarn`：为 yarn 使用重写生成的命令/脚本
- `--pm=bun`：为 bun 使用重写生成的命令/脚本
运行时烟雾测试说明：
- `yarn` 烟雾测试在可用时通过 `corepack` 运行。
- `bun` 烟雾测试需要环境支持 bun 运行时，若不可用则跳过。
功能集选项：
- `--features=auth`：仅认证脚手架（默认）
- `--features=email`：仅邮件配置脚手架
- `--features=both`：认证 + 邮件配置
- `--features=none`：仅健康/文档基线（不包含认证路由）
脚手架维护路由：
- `DELETE /api/scaffold/projects/downloads`：移除服务器上的生成下载产物
现代认证基线（在生成的项目中）：
- 短时访问令牌 + 轮换刷新令牌流程
- 刷新令牌存储在安全的 `httpOnly` Cookie 中
- Cookie 基础会话流程的 CSRF 保护
- 登录节流/速率限制中间件
- 结构化日志和请求上下文用于可观测性
面向未来演进的集成就绪架构：
- 分层模块（`controllers`、`services`、`repositories`）
- 为关系型提供者准备 Prisma + 模式管理
- OpenAPI 文档脚手架和集成测试入口点
- 环境驱动的配置，用于云和容器工作流
快速团队指南：
- `developers/README.md`
## 项目规范
- 贡献指南：`CONTRIBUTING.md`
- 安全策略：`SECURITY.md`
- 行为准则：`CODE_OF_CONDUCT.md`
- PR 模板：`.github/pull_request_template.md`
- 问题模板：`.github/ISSUE_TEMPLATE/`
## 质量与 CI
本地质量命令：
```
pnpm lint
pnpm format:check
pnpm typecheck
pnpm test
pnpm audit
```
CI 流水线：
- 文件：`.github/workflows/ci.yml`
- 触发条件：`push`（main/master）和 `pull_request`
- 阶段：安装、Lint、测试、安全审计
## 生产环境
运行手册：
- `docs/production-runbook.md`
部署前最低检查清单：
- 从 `.env.production.example` 开始
- 定义强 JWT 密钥（`JWT_ACCESS_SECRET`、`JWT_ACCESS_SECRETS`）
- 使用 `DATABASE_PROVIDER=postgresql` 并配置真实的 `DATABASE_URL`
- 将 `CORS_ALLOWED_ORIGINS` 限制为真实前端域名
- 在 HTTPS/反向代理后运行
### Railway + Vercel
后端（Railway）：
- 从仓库根目录部署
- 启动命令：`pnpm start`
- 必需变量：
- `NODE_ENV=production`
- `PORT`（由 Railway 提供）
- `DATABASE_PROVIDER=postgresql`
- `DATABASE_URL=`
- `JWT_ACCESS_ACTIVE_KID=v1`
- `JWT_ACCESS_SECRETS=v1:`
- `JWT_ACCESS_SECRET=`
- `CORS_ORIGIN=https://your-web-name.vercel.app`
- `CORS_ALLOWED_ORIGINS=https://your-web-name.vercel.app`
前端（Vercel）：
- 根目录：`web`
- 框架预设：Vite
- 构建命令：`npm run build`
- 输出目录：`dist`
- 必需变量：
- `VITE_API_BASE_URL=https://your-api-name.up.railway.app`
### 使用 Docker Compose 部署
组合文件：`docker-compose.production.yml`。
启动堆栈（API + PostgreSQL）：
```
docker compose -f docker-compose.production.yml up -d
```
在依赖项或 Dockerfile 变更时完全重建：
```
docker compose -f docker-compose.production.yml up -d --build
```
停止堆栈：
```
docker compose -f docker-compose.production.yml down
```
推荐的本地流程（启动 + 验证）：
```
pnpm prod:deploy:local
```
辅助命令：
```
pnpm prod:up
pnpm prod:up:build
pnpm prod:up:dbport -- 55432
pnpm prod:ps
pnpm prod:smoke
pnpm prod:smoke:auth
pnpm prod:verify
pnpm prod:recovery:test
pnpm prod:down
pnpm prod:reset
pnpm perf:docker:du
pnpm perf:docker:clean
pnpm perf:docker:clean:volumes
pnpm perf:docker:maintain
```
说明：
- `prod:up` 默认避免镜像重建。仅在需要时使用 `prod:up:build`。
- API 容器在服务器启动前运行 `pnpm prisma:bootstrap`（`db push`）以保持模式一致。
- 替换 `change_me` 值为真实密钥。
- 优先在托管环境中通过密钥管理器注入密钥。
- 如果 `3000` 被占用，请在 `.env.production` 中设置 `APP_HOST_PORT`。
- 为外部数据库工具（DBeaver、DataGrip、脚本）设置 `.env.production` 中的 `POSTGRES_HOST_PORT`。
- 若要在不编辑 `.env.production` 的情况下快速测试自定义主机端口，请使用 `pnpm prod:up:dbport -- 55432`。
- 容器日志轮换配置为 `DOCKER_LOG_MAX_SIZE` 和 `DOCKER_LOG_MAX_FILE`。
## 环境变量
参见 `.env.example`：
- `NODE_ENV`（`development`、`test`、`production`）
- `PORT`（API 端口）
- `DOCKER_LOG_MAX_SIZE`（最大容器日志文件大小，例如 `10m`）
- `DOCKER_LOG_MAX_FILE`（每个容器的最大日志文件数）
- `CORS_ORIGIN`（前端来源，例如 `http://localhost:5173`
- `CORS_ALLOWED_ORIGINS`（逗号分隔的允许列表）
- `DATABASE_PROVIDER`（`json`、`mysql`、`postgresql`、`sqlite`、`sqlserver`）
- `DATABASE_URL`（关系型数据库连接字符串；如果为空，则根据提供者和 `DB_PORT_*` 推导默认值）
- `POSTGRES_HOST_PORT`（生产组合中发布的 PostgreSQL 主机端口）
- `DB_PORT_MYSQL`（默认 `3306`）
- `DB_PORT_POSTGRESQL`（默认 `5432`）
- `DB_PORT_SQLITE`（SQLite 不使用网络端口，保留 `0`）
- `DB_PORT_SQLSERVER`（默认 `1433`）
- `AUTH_RATE_LIMIT_WINDOW_MINUTES`
- `AUTH_RATE_LIMIT_MAX_REQUESTS`
- `LOGIN_ATTEMPT_WINDOW_MINUTES`
- `LOGIN_MAX_FAILED_ATTEMPTS`
- `LOGIN_BLOCK_DURATION_MINUTES`
- `LOGIN_BLOCK_BACKOFF_MULTIPLIER`
- `LOGIN_MAX_BLOCK_DURATION_MINUTES`
- `CSRF_TOKEN_TTL_MINUTES`
- `JWT_ACCESS_ACTIVE_KID`
- `JWT_ACCESS_SECRETS`（`kid:secret,kid2:secret2`）
- `JWT_ACCESS_SECRET`
- `ACCESS_TOKEN_EXPIRES_IN`（例如 `15m`）
- `REFRESH_TOKEN_TTL_DAYS`
## 工具配置
- 格式化：`prettier.config.cjs`
- 类型检查基线：`tsconfig.json`
- 单体仓库就绪任务图：`turbo.json`
- Vitest 项目配置：`vitest.config.mjs`
- Vitest 工作区配置：`vitest.workspace.mjs`
## 许可证与发布
- 许可证：`LICENSE`
- 变更历史：`CHANGELOG.md`
## 端点
基础 URL：`http://localhost:3000`
### API 文档
- `GET /openapi.json`
- `GET /docs`
### 健康检查
- `GET /health/liveness`
- `GET /health/readiness`
- `GET /health`（别名，用于就绪检查）
### 认证
- `POST /auth/register`
- `POST /auth/login`
- `GET /auth/me`
- `POST /auth/refresh-token`
- `POST /auth/logout`
注册示例负载：
```
{
"name": "John Smith",
"email": "john@email.com",
"password": "StrongPass123",
"confirmPassword": "StrongPass123"
}
```
## 安全要点
- 基于 IP + 邮箱的渐进式持续登录锁定
- 刷新令牌族轮换与重复使用检测
- 刷新/登出时的 CSRF 保护
- 启用 `helmet` 强化
- 通过 `CORS_ALLOWED_ORIGINS` 的多源 CORS 允许列表
- 支持带 `kid` 的 JWT 密钥轮换
标签：API 生成, API 脚手架, Bcrypt, CI, Clean 架构, CMS安全, ESM, Express, GNU通用公共许可证, GraphQL, Hakrawler, HttpOnly Cookie, JavaScript, JSON 持久化, JSON 文件存储, JWT, LNA, MITM代理, MVC, Node.js, pnpm, Refresh Token 轮换, REST, SEO, SQLite, SQL Server, TypeScript, Zod 校验, 会话管理, 低数据库, 全功能模板, 关键词, 分层架构, 可替换数据库层, 在线状态检查, 安全插件, 密码哈希, 开发模式, 开发者脚手架, 快速启动, 文档, 本地开发, 模板生成, 注销, 测试, 环境变量, 生产模式, 登录注册, 自定义脚本, 认证, 访问令牌, 轻量模板, 鉴权, 项目生成器