create-skweb 3.1.1 → 3.3.0

package/templates/ts/.env.example

@@ -38,29 +38,25 @@ REDIS_DB=0
 # (Production is always disabled to avoid exposing internal API details.)
 SWAGGER_ENABLED=true
 
-# ---------- Auth Provider ----------
-# 'static' (default): use a shared secret (HS256)
-# 'jwks': verify via JWKS endpoint (Keycloak / Auth0 / generic OIDC)
-AUTH_PROVIDER={{auth}}
-
-# ---------- JWT (static mode) ----------
+{{#if_eq auth "static"}}
+# ---------- Auth: static (HS256 shared secret) ----------
 # [REQUIRED in production] Use a strong random string, e.g. `openssl rand -hex 32`
 JWT_SECRET=please-change-this-in-production
 JWT_EXPIRES_IN=7d
-
-# ---------- JWT (jwks mode, OIDC compatible) ----------
+{{else}}
+# ---------- Auth: jwks (OIDC compatible) ----------
 # Works with any OIDC-compliant IdP. Common issuer formats:
 #   Keycloak:  https://kc.example.com/realms/myrealm
 #   Auth0:     https://your-tenant.auth0.com/
 #   Okta:      https://your-domain.okta.com/oauth2/default
 #   Authing:   https://your-app.authing.cn/oauth2/default
-#   Keycloak Realm: https://kc.example.com/auth/realms/myrealm
 # `audience` is the client id of this API in the IdP (recommended).
 # JWKS URI is auto-derived as ${OIDC_ISSUER}/.well-known/jwks.json
 # unless OIDC_JWKS_URI is set explicitly.
 OIDC_ISSUER=
 OIDC_AUDIENCE=
 OIDC_JWKS_URI=
+{{/if_eq}}
 
 # ---------- Logging ----------
 # error | warn | info | http | verbose | debug | silly

package/templates/ts/ecosystem.config.js

@@ -2,7 +2,7 @@ module.exports = {
   apps: [
     {
       name: '{{name}}-web',
-      script: 'src/index.ts',
+      script: 'src/web-app.ts',
       interpreter: 'npx',
       interpreter_args: 'tsx',
       instances: 'max',
@@ -18,7 +18,7 @@ module.exports = {
     },
     {
       name: '{{name}}-cron',
-      script: 'src/cronWorker.ts',
+      script: 'src/cron-app.ts',
       interpreter: 'npx',
       interpreter_args: 'tsx',
       instances: 1,

package/templates/ts/package.json

@@ -9,8 +9,8 @@
     "restart": "pm2 restart all",
     "delete": "pm2 delete all",
     "logs": "pm2 logs",
-    "web:dev": "npx dotenvx run -- tsx watch src/index.ts",
-    "cron:dev": "npx dotenvx run -- tsx watch src/cronWorker.ts",
+    "web:dev": "npx dotenvx run -- tsx watch src/web-app.ts",
+    "cron:dev": "npx dotenvx run -- tsx watch src/cron-app.ts",
     "seed": "npx dotenvx run -- tsx src/commands/seed.ts",
     "migrate": "npx dotenvx run -- tsx src/commands/migrate.ts",
     "build": "tsc && rollup -c rollup.config.mjs",
@@ -24,14 +24,14 @@
   "dependencies": {
     "@dotenvx/dotenvx": "^1.75.1",
     "http-errors": "^2.0.1",
-    "skweb-express": "^2.0.3",
+    "skweb-express": "^2.0.4",
     "skweb-express-jwt": "^3.0.0",
     "skweb-express-logger": "^2.0.0",
     "skweb-sequelize": "^2.0.0",
     "skweb-redis": "^2.0.0",
     "skweb-cron": "^2.0.0",
-    "skweb-framework": "^2.1.0",
-    "skweb-plugin": "^2.1.0",
+    "skweb-framework": "^2.1.1",
+    "skweb-plugin": "^2.1.1",
     "skweb-util": "^2.0.0",
     "winston": "^3.19.0",
     "sequelize": "^6.37.8",

package/templates/ts/src/controllers/user.ts

@@ -1,7 +1,7 @@
 import createHttpError from 'http-errors'
-import { db } from '../services/database.js'
+import { framework } from '../web-framework.js'
 
-const { SysUser } = db.sequelize.models
+const { SysUser } = framework.models
 
 /**
  * @swagger

package/templates/ts/src/cron-app.ts

@@ -0,0 +1,45 @@
+import 'dotenv/config'
+
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { framework } from './cron-framework.js'
+import logger from './utils/logger.js'
+import { checkRequiredEnv } from './utils/config.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+async function startCronWorker(): Promise<void> {
+  logger.info('[cron-worker] Starting cron worker process...')
+
+  if (!checkRequiredEnv()) {
+    logger.error('[cron-worker] Configuration validation failed, exiting...')
+    process.exit(1)
+  }
+
+  await framework.setup({
+    modelsDir: path.join(__dirname, './models'),
+    cronActionsDir: path.join(__dirname, './cronActions')
+  })
+  await framework.start()
+  logger.info('[cron-worker] Cron worker started')
+
+  process.on('uncaughtException', (err) => {
+    logger.error(`[cron-worker] uncaughtException: ${err.stack || err.message}`)
+    process.exit(1)
+  })
+  process.on('unhandledRejection', (reason) => {
+    logger.error(`[cron-worker] unhandledRejection: ${reason instanceof Error ? reason.stack : String(reason)}`)
+    process.exit(1)
+  })
+}
+
+const isMainModule = import.meta.url === `file://${process.argv[1]}`
+if (isMainModule) {
+  startCronWorker().catch((err) => {
+    logger.error('[cron-worker] Fatal error:', err)
+    process.exit(1)
+  })
+}
+
+export { startCronWorker }

package/templates/ts/src/cron-framework.ts

@@ -0,0 +1,44 @@
+// @ts-nocheck
+import { CronFramework } from 'skweb-framework'
+import logger from './utils/logger.js'
+
+const framework = new CronFramework({
+  db: {
+    host: process.env.DB_HOST || '127.0.0.1',
+    port: Number(process.env.DB_PORT) || 3306,
+    username: process.env.DB_USER || 'root',
+    password: process.env.DB_PASS || '',
+    database: process.env.DB_NAME || 'test-project',
+    dialect: (process.env.DB_DIALECT as any) || 'mysql',
+    charset: process.env.DB_CHARSET || 'utf8mb4',
+    underscored: true,
+    logging: process.env.DEBUG_DB === 'true'
+  },
+  redis: {
+    host: process.env.REDIS_HOST || '127.0.0.1',
+    port: Number(process.env.REDIS_PORT) || 6379,
+    password: process.env.REDIS_PASSWORD || undefined
+  },
+  channel: 'cron:task:cmd',
+  logger,
+  onSaveTask: async (taskData: { taskId: string; cache: unknown; data: unknown }) => {
+    const SysCronTask = framework.dbInstance?.sequelize?.models.SysCronTask as any
+    if (SysCronTask) {
+      await SysCronTask.update(
+        { cache: taskData.cache, data: taskData.data },
+        { where: { id: taskData.taskId } }
+      )
+    }
+  },
+  loadTasks: async () => {
+    const SysCronTask = framework.dbInstance?.sequelize?.models.SysCronTask as any
+    if (!SysCronTask) return []
+    return (await SysCronTask.findAll()).map((t: any) => ({
+      id: String(t.id),
+      cronTime: t.cronTime,
+      method: t.method
+    }))
+  }
+})
+
+export { framework }

package/templates/ts/src/swagger.ts

@@ -1,3 +1,4 @@
+// @ts-nocheck
 import path from 'path'
 import { fileURLToPath } from 'url'
 import swaggerJSDoc from 'swagger-jsdoc'
@@ -5,22 +6,6 @@ import swaggerJSDoc from 'swagger-jsdoc'
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
-/**
- * 构建 OpenAPI 3.0 规范对象。
- *
- * 控制器中应使用 @swagger JSDoc 注释描述端点，例如：
- *
- *   /**
- *    * @swagger
- *    * /api/users:
- *    *   get:
- *    *     summary: 获取用户列表
- *    *     tags: [Users]
- *    *     responses:
- *    *       200:
- *    *         description: OK
- *    *\/
- */
 export function buildOpenApiSpec(): object {
   return swaggerJSDoc({
     definition: {
@@ -36,16 +21,25 @@ export function buildOpenApiSpec(): object {
       ],
       components: {
         securitySchemes: {
+          {{#if_eq auth "static"}}
           bearerAuth: {
             type: 'http',
             scheme: 'bearer',
-            bearerFormat: 'JWT',
-            description: 'Paste a JWT token here (only needed when AUTH_PROVIDER=static)'
+            bearerFormat: 'JWT'
           }
+          {{else}}
+          oidcAuth: {
+            type: 'openIdConnect',
+            openIdConnectUrl: process.env.OIDC_JWKS_URI
+              ? process.env.OIDC_JWKS_URI.replace(/\/jwks\.json$/, '/.well-known/openid-configuration')
+              : (process.env.OIDC_ISSUER
+                  ? `${process.env.OIDC_ISSUER.replace(/\/$/, '')}/.well-known/openid-configuration`
+                  : undefined)
+          }
+          {{/if_eq}}
         }
       }
     },
-    // 扫描 controllers 目录与 src 根下的 JSDoc 注释
     apis: [
       path.join(__dirname, 'controllers', '*.ts'),
       path.join(__dirname, 'controllers', '*.js')

package/templates/ts/src/utils/config.ts

@@ -1,3 +1,4 @@
+// @ts-nocheck
 import logger from './logger.js'
 
 interface ConfigValidationResult {
@@ -18,10 +19,6 @@ export function validateConfig(): ConfigValidationResult {
     logger.warn('[config] DB_USER not set, using default: root')
   }
 
-  if (process.env.JWT_SECRET === 'please-change-this-in-production') {
-    logger.warn('[config] WARNING: JWT_SECRET is using default value, please change in production!')
-  }
-
   if (!process.env.REDIS_HOST) {
     logger.warn('[config] REDIS_HOST not set, using default: 127.0.0.1')
   }
@@ -47,22 +44,41 @@ export function validateConfig(): ConfigValidationResult {
   }
 }
 
+{{#if_eq auth "static"}}
+export function checkJwtSecret(): boolean {
+  if (process.env.JWT_SECRET === 'please-change-this-in-production' || !process.env.JWT_SECRET) {
+    if (process.env.NODE_ENV === 'production') {
+      logger.error('[config] JWT_SECRET must be set in production!')
+      return false
+    }
+    logger.warn('[config] WARNING: JWT_SECRET is using default value, please change in production!')
+  }
+  return true
+}
+{{else}}
+export function checkOIDCConfig(): boolean {
+  const issuer = process.env.OIDC_ISSUER
+  const jwksUri = process.env.OIDC_JWKS_URI
+  if (!issuer && !jwksUri) {
+    logger.error('[config] OIDC_ISSUER or OIDC_JWKS_URI must be set for jwks auth')
+    return false
+  }
+  if (process.env.NODE_ENV === 'production' && !process.env.OIDC_AUDIENCE) {
+    logger.warn('[config] OIDC_AUDIENCE is not set; audience verification will be skipped')
+  }
+  return true
+}
+{{/if_eq}}
+
 export function checkRequiredEnv(): boolean {
   const result = validateConfig()
-  
+
   if (result.errors.length > 0) {
     logger.error('[config] Configuration validation failed:')
     result.errors.forEach((err) => logger.error(`  - ${err}`))
     return false
   }
 
-  if (process.env.NODE_ENV === 'production') {
-    if (!process.env.JWT_SECRET || process.env.JWT_SECRET === 'please-change-this-in-production') {
-      logger.error('[config] JWT_SECRET must be set in production!')
-      return false
-    }
-  }
-
   logger.info('[config] Configuration validation passed')
   return true
-}
+}

package/templates/ts/src/{app.ts → web-app.ts}

@@ -1,50 +1,25 @@
+// @ts-nocheck
 import 'dotenv/config'
 
 import path from 'path'
 import { fileURLToPath } from 'url'
 import express from 'skweb-express'
 import expressLogger, { errorHandler as expressErrorHandler } from 'skweb-express-logger'
-import { WebFramework } from 'skweb-framework'
 import type { JWTOptions } from 'skweb-express-jwt'
 import swaggerUi from 'swagger-ui-express'
+import { framework } from './web-framework.js'
 import logger from './utils/logger.js'
-import { checkRequiredEnv } from './utils/config.js'
+import { checkRequiredEnv{{#if_eq auth "static"}}, checkJwtSecret{{/if_eq}}{{#if_eq auth "jwks"}}, checkOIDCConfig{{/if_eq}} } from './utils/config.js'
 import { buildOpenApiSpec } from './swagger.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
+{{#if_eq auth "static"}}
 /**
- * 构建 JWT 配置，支持两种模式：
- *  - 'static' (默认)：使用共享密钥（HS256/HS384/HS512），适用于自签 token
- *  - 'jwks'：通过 JWKS 端点动态获取公钥（RS256 等），适用于 Keycloak/Auth0 等 IdP
+ * JWT 配置（static 模式，HS256 共享密钥）。
  */
 function buildJwtOptions(): JWTOptions {
-  const provider = (process.env.AUTH_PROVIDER || 'static') as 'static' | 'jwks'
-
-  if (provider === 'jwks') {
-    const issuer = process.env.OIDC_ISSUER
-    const jwksUri = process.env.OIDC_JWKS_URI
-    const audience = process.env.OIDC_AUDIENCE
-    if (!issuer && !jwksUri) {
-      throw new Error('AUTH_PROVIDER=jwks requires OIDC_ISSUER or OIDC_JWKS_URI')
-    }
-    return {
-      provider: 'jwks',
-      algorithms: ['RS256'],
-      jwks: {
-        jwksUri,
-        issuer,
-        audience
-      },
-      verify: {
-        issuer,
-        audience
-      },
-      requestProperty: 'resolvedToken'
-    }
-  }
-
   return {
     provider: 'static',
     secret: process.env.JWT_SECRET || 'please-change-this-in-production',
@@ -52,12 +27,27 @@ function buildJwtOptions(): JWTOptions {
     sign: { expiresIn: (process.env.JWT_EXPIRES_IN || '7d') as any },
     requestProperty: 'resolvedToken'
   }
-}
-
+}{{else}}
 /**
- * Swagger UI 仅在 NODE_ENV 为 development / test，且 SWAGGER_ENABLED !== 'false' 时启用。
- * 生产环境（production / unset）默认禁用，避免暴露内部 API 细节。
+ * JWT 配置（jwks 模式，通过 OIDC 兼容的 JWKS 端点验证 RS256 签名）。
  */
+function buildJwtOptions(): JWTOptions {
+  const issuer = process.env.OIDC_ISSUER
+  const jwksUri = process.env.OIDC_JWKS_URI
+  const audience = process.env.OIDC_AUDIENCE
+  if (!issuer && !jwksUri) {
+    throw new Error('jwks mode requires OIDC_ISSUER or OIDC_JWKS_URI')
+  }
+  return {
+    provider: 'jwks',
+    algorithms: ['RS256'],
+    jwks: { jwksUri, issuer, audience },
+    verify: { issuer, audience },
+    requestProperty: 'resolvedToken'
+  }
+}
+{{/if_eq}}
+
 function shouldEnableSwagger(): boolean {
   const env = (process.env.NODE_ENV || '').toLowerCase()
   if (env !== 'development' && env !== 'test') return false
@@ -72,25 +62,17 @@ async function bootstrap(): Promise<void> {
     logger.error('[app] Configuration validation failed, exiting...')
     process.exit(1)
   }
-
-  const framework = new WebFramework({
-    db: {
-      host: process.env.DB_HOST || '127.0.0.1',
-      port: Number(process.env.DB_PORT) || 3306,
-      username: process.env.DB_USER || 'root',
-      password: process.env.DB_PASS || '',
-      database: process.env.DB_NAME || 'test-project',
-      dialect: (process.env.DB_DIALECT as 'mysql' | 'postgres' | 'sqlite' | 'mariadb') || 'mysql',
-      charset: process.env.DB_CHARSET || 'utf8mb4',
-      underscored: true,
-      logging: process.env.DEBUG_DB === 'true' ? (msg: string) => logger.debug(msg) : false
-    },
-    redis: {
-      host: process.env.REDIS_HOST || '127.0.0.1',
-      port: Number(process.env.REDIS_PORT) || 6379,
-      password: process.env.REDIS_PASSWORD || undefined
-    }
-  })
+  {{#if_eq auth "static"}}
+  if (!checkJwtSecret()) {
+    logger.error('[app] JWT configuration validation failed, exiting...')
+    process.exit(1)
+  }
+  {{else}}
+  if (!checkOIDCConfig()) {
+    logger.error('[app] OIDC configuration validation failed, exiting...')
+    process.exit(1)
+  }
+  {{/if_eq}}
 
   const app = framework.createApp() as express.Express & Record<string, any>
 
@@ -108,21 +90,19 @@ async function bootstrap(): Promise<void> {
   app.setOkCode(0)
   app.setOkMessage('success')
 
-  // JWT 配置（按 AUTH_PROVIDER 选择 static 或 jwks 模式）
   const jwtOptions = buildJwtOptions()
   app.setJWT('default', jwtOptions as any)
   app.setJwtHintHeader('JwtHint')
 
-  if (jwtOptions.provider === 'jwks') {
-    logger.info(`[app] JWT auth provider: jwks (issuer: ${jwtOptions.jwks.issuer || jwtOptions.jwks.jwksUri})`)
-  } else {
-    logger.info('[app] JWT auth provider: static (HS256)')
-  }
+  {{#if_eq auth "static"}}
+  logger.info('[app] JWT auth provider: static (HS256)')
+  {{else}}
+  logger.info(`[app] JWT auth provider: jwks (issuer: ${jwtOptions.jwks?.issuer || jwtOptions.jwks?.jwksUri})`)
+  {{/if_eq}}
 
   app.use(expressLogger())
   app.use(express.static(path.join(__dirname, '..', 'public')))
 
-  // 仅在 dev / test 环境挂载 Swagger UI（默认关闭，需显式 SWAGGER_ENABLED=true）
   if (shouldEnableSwagger()) {
     const openapiSpec = buildOpenApiSpec()
     app.get('/api-docs.json', (_req, res) => res.json(openapiSpec))
@@ -137,15 +117,12 @@ async function bootstrap(): Promise<void> {
 
   await framework.loadControllers()
 
-  // 错误日志中间件：挂在所有路由之后，记录业务错误并继续传递给默认错误处理。
   app.use(expressErrorHandler())
 
   framework.start(Number(process.env.PORT) || 3000)
 
   logger.info('[app] Initialization complete (web process)')
 
-  // 未捕获异常：打印堆栈后直接退出。OS / 进程管理器（pm2 / docker / k8s）
-  // 负责回收 socket / fd，框架不在此路径上做资源清理——简单可靠。
   process.on('uncaughtException', (err) => {
     logger.error(`[app] uncaughtException: ${err.stack || err.message}`)
     process.exit(1)

package/templates/ts/src/web-framework.ts

@@ -0,0 +1,23 @@
+// @ts-nocheck
+import { WebFramework } from 'skweb-framework'
+
+const framework = new WebFramework({
+  db: {
+    host: process.env.DB_HOST || '127.0.0.1',
+    port: Number(process.env.DB_PORT) || 3306,
+    username: process.env.DB_USER || 'root',
+    password: process.env.DB_PASS || '',
+    database: process.env.DB_NAME || 'test-project',
+    dialect: (process.env.DB_DIALECT as any) || 'mysql',
+    charset: process.env.DB_CHARSET || 'utf8mb4',
+    underscored: true,
+    logging: process.env.DEBUG_DB === 'true'
+  },
+  redis: {
+    host: process.env.REDIS_HOST || '127.0.0.1',
+    port: Number(process.env.REDIS_PORT) || 6379,
+    password: process.env.REDIS_PASSWORD || undefined
+  }
+})
+
+export { framework }