befly 3.3.5 → 3.4.1

package/checks/conflict.ts

@@ -5,7 +5,7 @@
 
 import { relative, basename } from 'pathe';
 import { Logger } from '../lib/logger.js';
-import { paths } from '../paths.js';
+import { projectPluginDir, coreTableDir, projectTableDir, projectApiDir } from '../paths.js';
 import { scanAddons, getAddonDir, addonDirExists } from '../util.js';
 
 /**
@@ -41,7 +41,7 @@ async function collectCorePlugins(registry: ResourceRegistry): Promise<void> {
     try {
         const glob = new Bun.Glob('*.ts');
         for await (const file of glob.scan({
-            cwd: paths.projectPluginDir,
+            cwd: projectPluginDir,
             onlyFiles: true,
             absolute: true
         })) {
@@ -77,7 +77,7 @@ async function collectAddonResources(addonName: string, registry: ResourceRegist
         const glob = new Bun.Glob('*.json');
 
         for await (const file of glob.scan({
-            cwd: paths.rootTableDir,
+            cwd: addonTablesDir,
             onlyFiles: true,
             absolute: true
         })) {
@@ -183,7 +183,7 @@ async function collectUserResources(registry: ResourceRegistry): Promise<string[
     const conflicts: string[] = [];
 
     // 收集用户表定义
-    const userTablesDir = paths.projectTableDir;
+    const userTablesDir = projectTableDir;
     try {
         const glob = new Bun.Glob('*.json');
         for await (const file of glob.scan({
@@ -219,7 +219,7 @@ async function collectUserResources(registry: ResourceRegistry): Promise<string[
     }
 
     // 收集用户 API 路由
-    const userApisDir = paths.projectApiDir;
+    const userApisDir = projectApiDir;
     try {
         const glob = new Bun.Glob('**/*.ts');
         for await (const file of glob.scan({
@@ -255,7 +255,7 @@ async function collectUserResources(registry: ResourceRegistry): Promise<string[
     }
 
     // 收集用户插件
-    const userPluginsDir = paths.projectPluginDir;
+    const userPluginsDir = projectPluginDir;
     try {
         const glob = new Bun.Glob('*.ts');
         for await (const file of glob.scan({

package/checks/table.ts

@@ -6,7 +6,7 @@
 import { basename } from 'pathe';
 import { Logger } from '../lib/logger.js';
 import { parseRule } from '../util.js';
-import { paths } from '../paths.js';
+import { projectTableDir } from '../paths.js';
 import { scanAddons, getAddonDir } from '../util.js';
 
 /**
@@ -69,7 +69,7 @@ export default async function (): Promise<boolean> {
 
         // 收集项目表字段定义文件
         for await (const file of tablesGlob.scan({
-            cwd: paths.projectTableDir,
+            cwd: projectTableDir,
             absolute: true,
             onlyFiles: true
         })) {

package/commands/build.ts

@@ -28,20 +28,24 @@ interface BuildOptions {
 export async function buildCommand(options: BuildOptions) {
     try {
         const projectRoot = getProjectRoot();
-        const mainFile = join(projectRoot, 'main.ts');
 
-        if (!existsSync(mainFile)) {
-            Logger.error('未找到 main.ts 文件');
+        // 验证是否在项目目录下
+        const packageJsonPath = join(projectRoot, 'package.json');
+        if (!existsSync(packageJsonPath)) {
+            Logger.error('未找到 package.json 文件，请确保在项目目录下');
             process.exit(1);
         }
 
+        // 使用内置默认入口文件
+        const entryFile = join(import.meta.dir, '..', 'entry.ts');
+
         const spinner = ora({
             text: '正在构建项目...',
             color: 'cyan',
             spinner: 'dots'
         }).start();
 
-        const args = ['build', mainFile, '--outdir', options.outdir, '--target', 'bun'];
+        const args = ['build', entryFile, '--outdir', options.outdir, '--target', 'bun'];
 
         if (options.minify) {
             args.push('--minify');

package/commands/dev.ts

@@ -5,6 +5,7 @@
 import { join } from 'pathe';
 import { existsSync } from 'node:fs';
 import { Logger } from '../lib/logger.js';
+import { Befly } from '../main.js';
 
 interface DevOptions {
     port: string;
@@ -27,10 +28,11 @@ function getProjectRoot(): string {
 export async function devCommand(options: DevOptions) {
     try {
         const projectRoot = getProjectRoot();
-        const mainFile = join(projectRoot, 'main.ts');
 
-        if (!existsSync(mainFile)) {
-            Logger.error('未找到 main.ts 文件，请确保在 Befly 项目目录下');
+        // 验证是否在 Befly 项目目录下
+        const packageJsonPath = join(projectRoot, 'package.json');
+        if (!existsSync(packageJsonPath)) {
+            Logger.error('未找到 package.json 文件，请确保在项目目录下');
             process.exit(1);
         }
 
@@ -54,38 +56,25 @@ export async function devCommand(options: DevOptions) {
             Logger.info(`环境变量文件: .env.development\n`);
         }
 
-        // 使用 Bun.spawn 启动开发服务器（不使用 --watch 避免监听 node_modules）
+        // 直接启动 Befly 实例
+        const app = new Befly();
+        const server = await app.listen();
 
-        const proc = Bun.spawn(['bun', '--env-file=.env.development', 'run', mainFile], {
-            cwd: projectRoot,
-            stdout: 'inherit',
-            stderr: 'inherit',
-            stdin: 'inherit',
-            env: {
-                // ...process.env,
-                // NODE_ENV: 'development',
-                // APP_PORT: options.port,
-                // APP_HOST: options.host,
-                // LOG_DEBUG: options.verbose ? '1' : process.env.LOG_DEBUG,
-                // FORCE_COLOR: '1'
-            }
-        });
-
-        // 添加信号处理，确保优雅关闭
-        const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+        // 设置信号处理，确保优雅关闭
+        const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGINT'];
         signals.forEach((signal) => {
-            process.on(signal, () => {
-                console.log(`\nShutting down dev server (${signal})...`);
-                proc.kill(signal);
-                setTimeout(() => {
-                    proc.kill('SIGKILL');
+            process.on(signal, async () => {
+                Logger.info(`\n收到 ${signal} 信号，正在关闭开发服务器...`);
+                try {
+                    server.stop(true);
+                    Logger.info('开发服务器已关闭');
+                    process.exit(0);
+                } catch (error) {
+                    Logger.error('关闭开发服务器失败:', error);
                     process.exit(1);
-                }, 5000); // 5 秒强制关闭
+                }
             });
         });
-
-        const exitCode = await proc.exited;
-        process.exit(exitCode || 0);
     } catch (error) {
         Logger.error('启动开发服务器失败:');
         console.error(error);

package/commands/start.ts

@@ -6,6 +6,7 @@ import { join } from 'pathe';
 import { existsSync } from 'node:fs';
 import { Logger } from '../lib/logger.js';
 import { ClusterManager } from '../lifecycle/cluster.js';
+import { Befly } from '../main.js';
 
 function getProjectRoot(): string {
     let current = process.cwd();
@@ -28,10 +29,11 @@ interface StartOptions {
 export async function startCommand(options: StartOptions) {
     try {
         const projectRoot = getProjectRoot();
-        const mainFile = join(projectRoot, 'main.ts');
 
-        if (!existsSync(mainFile)) {
-            Logger.error('未找到 main.ts 文件');
+        // 验证是否在项目目录下
+        const packageJsonPath = join(projectRoot, 'package.json');
+        if (!existsSync(packageJsonPath)) {
+            Logger.error('未找到 package.json 文件，请确保在项目目录下');
             process.exit(1);
         }
 
@@ -49,8 +51,7 @@ export async function startCommand(options: StartOptions) {
                 instances,
                 startPort: parseInt(options.port),
                 host: options.host,
-                projectRoot,
-                mainFile
+                projectRoot
             });
 
             await clusterManager.start();
@@ -67,10 +68,25 @@ export async function startCommand(options: StartOptions) {
                 Logger.info(`环境变量文件: .env.production\n`);
             }
 
-            // 直接导入并运行 main.ts（Bun 会自动加载 .env.production）
-            await import(mainFile);
+            // 直接启动 Befly 实例
+            const app = new Befly();
+            const server = await app.listen();
 
-            // 注意：正常情况下不会执行到这里，因为 main.ts 会启动服务器并持续运行
+            // 设置信号处理，确保优雅关闭
+            const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGINT'];
+            signals.forEach((signal) => {
+                process.on(signal, async () => {
+                    Logger.info(`\n收到 ${signal} 信号，正在关闭生产服务器...`);
+                    try {
+                        server.stop(true);
+                        Logger.info('生产服务器已关闭');
+                        process.exit(0);
+                    } catch (error) {
+                        Logger.error('关闭生产服务器失败:', error);
+                        process.exit(1);
+                    }
+                });
+            });
         }
     } catch (error) {
         Logger.error('启动失败:');

package/commands/syncDb/index.ts

@@ -14,7 +14,7 @@ import { Env } from '../../config/env.js';
 import { scanAddons, addonDirExists, getAddonDir } from '../../util.js';
 import { Database } from '../../lib/database.js';
 import checkTable from '../../checks/table.js';
-import { paths } from '../../paths.js';
+import { coreTableDir, projectTableDir } from '../../paths.js';
 
 // 导入模块化的功能
 import { ensureDbVersion } from './version.js';
@@ -81,9 +81,9 @@ export const SyncDb = async (): Promise<void> => {
         const tablesGlob = new Bun.Glob('*.json');
         const directories: Array<{ path: string; type: 'core' | 'app' | 'addon'; addonName?: string }> = [
             // 1. core 框架表（core_ 前缀）
-            { path: paths.coreTableDir, type: 'core' },
+            { path: coreTableDir, type: 'core' },
             // 2. 项目表（无前缀）
-            { path: paths.projectTableDir, type: 'app' }
+            { path: projectTableDir, type: 'app' }
         ];
 
         // 添加所有 addon 的 tables 目录（addon_{name}_ 前缀）

package/commands/syncDb/table.ts

@@ -80,7 +80,7 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
 
                 if (isStringOrArrayType(fieldType) && existingColumns[dbFieldName].length) {
                     if (existingColumns[dbFieldName].length! > fieldMax) {
-                        Logger.warn(`[跳过危险变更] ${tableName}.${dbFieldName} 长度收缩 ${existingColumns[dbFieldName].length} -> ${fieldMax} 已被跳过（设置 SYNC_DISALLOW_SHRINK=0 可放开）`);
+                        Logger.warn(`[跳过危险变更] ${tableName}.${dbFieldName} 长度收缩 ${existingColumns[dbFieldName].length} -> ${fieldMax} 已被跳过`);
                     }
                 }
 

package/commands/syncMenu.ts

@@ -3,13 +3,14 @@
  * 说明：根据 menu.json 配置文件增量同步菜单数据（最多2级：父级和子级）
  *
  * 流程：
- * 1. 读取 core 和 tpl 两个配置文件，core 优先覆盖 tpl
- * 2. 合并菜单配置（根据 path 匹配，core 覆盖 tpl）
- * 3. 子级菜单自动追加父级路径作为前缀
- * 4. 根据菜单的 path 字段检查是否存在
- * 5. 存在则更新其他字段（name、icon、sort、type、pid）
- * 6. 不存在则新增菜单记录
- * 7. 强制删除配置中不存在的菜单记录
+ * 1. 读取 core/config/menu.json 和项目根目录的 menu.json 配置文件
+ * 2. core 配置优先覆盖项目配置（根据 path 匹配）
+ * 3. 文件不存在或格式错误时默认为空数组
+ * 4. 子级菜单自动追加父级路径作为前缀
+ * 5. 根据菜单的 path 字段检查是否存在
+ * 6. 存在则更新其他字段（name、icon、sort、type、pid）
+ * 7. 不存在则新增菜单记录
+ * 8. 强制删除配置中不存在的菜单记录
  * 注：state 字段由框架自动管理（1=正常，2=禁用，0=删除）
  */
 
@@ -17,7 +18,7 @@ import { Logger } from '../lib/logger.js';
 import { Database } from '../lib/database.js';
 import { join } from 'pathe';
 import { existsSync } from 'node:fs';
-import { paths } from '../paths.js';
+import { coreDIr, projectDir } from '../paths.js';
 
 interface SyncMenuOptions {
     plan?: boolean;
@@ -34,35 +35,46 @@ interface MenuConfig {
 
 /**
  * 读取菜单配置文件
+ * 如果文件不存在或不是数组格式，返回空数组
  */
 async function readMenuConfig(filePath: string): Promise<MenuConfig[]> {
     try {
         if (!existsSync(filePath)) {
+            Logger.warn(`菜单配置文件不存在: ${filePath}，使用空数组`);
             return [];
         }
+
         const file = Bun.file(filePath);
-        return await file.json();
+        const content = await file.json();
+
+        // 验证是否为数组
+        if (!Array.isArray(content)) {
+            Logger.warn(`菜单配置文件格式错误（非数组）: ${filePath}，使用空数组`);
+            return [];
+        }
+
+        return content;
     } catch (error: any) {
-        Logger.warn(`读取菜单配置失败: ${filePath}`, error.message);
+        Logger.warn(`读取菜单配置失败: ${filePath}，使用空数组`, error.message);
         return [];
     }
 }
 
 /**
- * 合并菜单配置（core 优先覆盖 tpl）
+ * 合并菜单配置（core 优先覆盖项目）
  * 支持二级菜单结构：父级和子级
  */
-function mergeMenuConfigs(tplMenus: MenuConfig[], coreMenus: MenuConfig[]): MenuConfig[] {
+function mergeMenuConfigs(projectMenus: MenuConfig[], coreMenus: MenuConfig[]): MenuConfig[] {
     const menuMap = new Map<string, MenuConfig>();
 
-    // 1. 先添加 tpl 菜单
-    for (const menu of tplMenus) {
+    // 1. 先添加项目菜单
+    for (const menu of projectMenus) {
         if (menu.path) {
             menuMap.set(menu.path, { ...menu });
         }
     }
 
-    // 2. core 菜单覆盖同 path 的 tpl 菜单
+    // 2. core 菜单覆盖同 path 的项目菜单
     for (const menu of coreMenus) {
         if (menu.path) {
             menuMap.set(menu.path, { ...menu });
@@ -78,10 +90,10 @@ function mergeMenuConfigs(tplMenus: MenuConfig[], coreMenus: MenuConfig[]): Menu
         if (menu.children && menu.children.length > 0) {
             const childMap = new Map<string, MenuConfig>();
 
-            // 先添加 tpl 的子菜单
-            const tplMenu = tplMenus.find((m) => m.path === menu.path);
-            if (tplMenu?.children) {
-                for (const child of tplMenu.children) {
+            // 先添加项目的子菜单
+            const projectMenu = projectMenus.find((m) => m.path === menu.path);
+            if (projectMenu?.children) {
+                for (const child of projectMenu.children) {
                     if (child.path) {
                         childMap.set(child.path, { ...child });
                     }
@@ -269,8 +281,8 @@ export async function syncMenuCommand(options: SyncMenuOptions = {}) {
     try {
         if (options.plan) {
             Logger.info('[计划] 同步菜单配置到数据库（plan 模式不执行）');
-            Logger.info('[计划] 1. 读取 core 和 tpl 两个配置文件');
-            Logger.info('[计划] 2. 合并菜单配置（core 优先覆盖 tpl）');
+            Logger.info('[计划] 1. 读取 core/config/menu.json 和项目根目录 menu.json');
+            Logger.info('[计划] 2. 合并菜单配置（core 优先覆盖项目）');
             Logger.info('[计划] 3. 子级菜单自动追加父级路径前缀');
             Logger.info('[计划] 4. 根据 path 检查菜单是否存在');
             Logger.info('[计划] 5. 存在则更新，不存在则新增');
@@ -283,21 +295,21 @@ export async function syncMenuCommand(options: SyncMenuOptions = {}) {
 
         // 1. 读取两个配置文件
         Logger.info('=== 步骤 1: 读取菜单配置文件 ===');
-        const tplMenuPath = join(paths.projectConfigDir, 'menu.json');
-        const coreMenuPath = join(paths.rootConfigDir, 'menu.json');
+        const projectMenuPath = join(projectDir, 'menu.json');
+        const coreMenuPath = join(coreDIr, 'menu.json');
 
-        Logger.info(`  tpl 路径: ${tplMenuPath}`);
+        Logger.info(`  项目路径: ${projectMenuPath}`);
         Logger.info(`  core 路径: ${coreMenuPath}`);
 
-        const tplMenus = await readMenuConfig(tplMenuPath);
+        const projectMenus = await readMenuConfig(projectMenuPath);
         const coreMenus = await readMenuConfig(coreMenuPath);
 
-        Logger.info(`✅ tpl 配置: ${tplMenus.length} 个父级菜单`);
+        Logger.info(`✅ 项目配置: ${projectMenus.length} 个父级菜单`);
         Logger.info(`✅ core 配置: ${coreMenus.length} 个父级菜单`);
 
         // 2. 合并菜单配置
-        Logger.info('\n=== 步骤 2: 合并菜单配置（core 优先覆盖 tpl） ===');
-        const mergedMenus = mergeMenuConfigs(tplMenus, coreMenus);
+        Logger.info('\n=== 步骤 2: 合并菜单配置（core 优先覆盖项目） ===');
+        const mergedMenus = mergeMenuConfigs(projectMenus, coreMenus);
         Logger.info(`✅ 合并后共有 ${mergedMenus.length} 个父级菜单`);
 
         // 打印合并后的菜单结构

package/config/env.ts

@@ -116,16 +116,6 @@ export interface EnvConfig {
     MAIL_SENDER: string;
     /** 发件人地址 */
     MAIL_ADDRESS: string;
-
-    // ========== 同步脚本配置 ==========
-    /** 是否合并 ALTER 语句 */
-    SYNC_MERGE_ALTER: string;
-    /** 是否同步在线索引 */
-    SYNC_ONLINE_INDEX: string;
-    /** 是否禁止字段缩小 */
-    SYNC_DISALLOW_SHRINK: string;
-    /** 是否允许类型变更 */
-    SYNC_ALLOW_TYPE_CHANGE: string;
 }
 
 /**
@@ -208,11 +198,5 @@ export const Env: EnvConfig = {
     MAIL_USER: getEnv('MAIL_USER', ''),
     MAIL_PASS: getEnv('MAIL_PASS', ''),
     MAIL_SENDER: getEnv('MAIL_SENDER', ''),
-    MAIL_ADDRESS: getEnv('MAIL_ADDRESS', ''),
-
-    // ========== 同步脚本配置 ==========
-    SYNC_MERGE_ALTER: getEnv('SYNC_MERGE_ALTER', 'false'),
-    SYNC_ONLINE_INDEX: getEnv('SYNC_ONLINE_INDEX', 'false'),
-    SYNC_DISALLOW_SHRINK: getEnv('SYNC_DISALLOW_SHRINK', 'true'),
-    SYNC_ALLOW_TYPE_CHANGE: getEnv('SYNC_ALLOW_TYPE_CHANGE', 'false')
+    MAIL_ADDRESS: getEnv('MAIL_ADDRESS', '')
 };

package/lifecycle/checker.ts

@@ -6,7 +6,7 @@
 import { join, basename } from 'pathe';
 import { Logger } from '../lib/logger.js';
 import { calcPerfTime } from '../util.js';
-import { paths } from '../paths.js';
+import { coreCheckDir } from '../paths.js';
 import { scanAddons, getAddonDir, addonDirExists } from '../util.js';
 
 /**
@@ -31,7 +31,7 @@ export class Checker {
 
             // 1. 优先执行资源冲突检测（如果存在）
             try {
-                const conflictCheckPath = join(paths.rootCheckDir, 'conflict.ts');
+                const conflictCheckPath = join(coreCheckDir, 'conflict.ts');
                 const conflictCheckFile = Bun.file(conflictCheckPath);
 
                 if (await conflictCheckFile.exists()) {
@@ -71,7 +71,7 @@ export class Checker {
 
             // 2. 检查目录列表：先核心，后项目，最后 addons
             // 检查所有 checks 目录
-            const checkDirs = [{ path: paths.rootCheckDir, type: 'core' as const }]; // 添加所有 addon 的 checks 目录
+            const checkDirs = [{ path: coreCheckDir, type: 'core' as const }]; // 添加所有 addon 的 checks 目录
             const addons = scanAddons();
             for (const addon of addons) {
                 if (addonDirExists(addon, 'checks')) {

package/lifecycle/cluster-worker.ts

@@ -0,0 +1,49 @@
+/**
+ * Cluster Worker 入口
+ * 由 ClusterManager 启动的子进程入口文件
+ */
+
+import { Befly } from '../main.js';
+import { Logger } from '../lib/logger.js';
+
+// 启动 Befly 实例
+const app = new Befly();
+const server = await app.listen();
+
+// Bun 原生信号处理：当收到 SIGTERM/SIGINT 时优雅关闭
+const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGINT'];
+
+signals.forEach((signal) => {
+    process.on(signal, async () => {
+        const workerId = process.env.CLUSTER_WORKER_ID || 'unknown';
+        Logger.info(`Worker ${workerId} 收到 ${signal} 信号，正在关闭...`);
+
+        try {
+            // Bun Server 的 stop() 方法：关闭服务器
+            // 参数 true 表示强制关闭（不等待现有连接）
+            server.stop(true);
+            Logger.info(`Worker ${workerId} HTTP 服务器已关闭`);
+
+            // 给予短暂时间让资源清理完成
+            await Bun.sleep(100);
+
+            process.exit(0);
+        } catch (error) {
+            Logger.error(`Worker ${workerId} 关闭失败:`, error);
+            process.exit(1);
+        }
+    });
+});
+
+// 处理未捕获的异常，防止进程意外退出
+process.on('uncaughtException', (error) => {
+    const workerId = process.env.CLUSTER_WORKER_ID || 'unknown';
+    Logger.error(`Worker ${workerId} 发生未捕获异常:`, error);
+    // 不退出进程，让 ClusterManager 决定是否重启
+});
+
+process.on('unhandledRejection', (reason) => {
+    const workerId = process.env.CLUSTER_WORKER_ID || 'unknown';
+    Logger.error(`Worker ${workerId} 发生未处理的 Promise 拒绝:`, reason);
+    // 不退出进程，让 ClusterManager 决定是否重启
+});

package/lifecycle/cluster.ts

@@ -6,6 +6,7 @@
 import { join } from 'pathe';
 import type { Subprocess } from 'bun';
 import { Logger } from '../lib/logger.js';
+import { Befly } from '../main.js';
 
 export interface ClusterOptions {
     /** 实例数量（数字或 'max'） */
@@ -16,8 +17,6 @@ export interface ClusterOptions {
     host: string;
     /** 项目根目录 */
     projectRoot: string;
-    /** main.ts 文件路径 */
-    mainFile: string;
     /** 环境变量 */
     env?: Record<string, string>;
 }
@@ -88,14 +87,14 @@ export class ClusterManager {
      * 启动单个 Worker
      */
     private spawnWorker(id: number, port: number): void {
-        const { projectRoot, mainFile, host, env = {} } = this.options;
+        const { projectRoot, host, env = {} } = this.options;
 
         Logger.info(`启动 Worker ${id} (端口 ${port})...`);
 
-        // 检查环境变量文件
-        const envFile = join(projectRoot, '.env.production');
+        // 使用内置的 worker 入口文件
+        const workerFile = join(import.meta.dir, 'cluster-worker.ts');
 
-        const proc = Bun.spawn(['bun', 'run', '--env-file=.env.production', mainFile], {
+        const proc = Bun.spawn(['bun', 'run', '--env-file=.env.production', workerFile], {
             cwd: projectRoot,
             stdout: 'inherit',
             stderr: 'inherit',
@@ -208,24 +207,38 @@ export class ClusterManager {
         // 向所有 Worker 发送 SIGTERM
         for (const [id, worker] of this.workers.entries()) {
             Logger.info(`关闭 Worker ${id} (端口 ${worker.port})...`);
-            worker.process.kill('SIGTERM');
+            try {
+                worker.process.kill('SIGTERM');
+            } catch (error) {
+                Logger.warn(`无法向 Worker ${id} 发送 SIGTERM:`, error);
+            }
         }
 
-        // 等待所有进程退出，最多 5 秒
+        // 等待所有进程退出，最多 3 秒（Bun 的 server.stop() 很快）
         const timeout = setTimeout(() => {
-            Logger.warn('等待超时，强制关闭所有 Worker');
+            Logger.warn('等待超时（3秒），强制关闭所有 Worker');
             for (const worker of this.workers.values()) {
-                worker.process.kill('SIGKILL');
+                try {
+                    worker.process.kill('SIGKILL');
+                } catch (error) {
+                    // 忽略 SIGKILL 失败（进程可能已退出）
+                }
             }
+            // 强制退出主进程
+            setTimeout(() => process.exit(1), 500);
+        }, 3000);
+
+        try {
+            // 等待所有进程退出
+            await Promise.all(Array.from(this.workers.values()).map((w) => w.process.exited));
+            clearTimeout(timeout);
+            Logger.info('集群已安全关闭');
+            process.exit(0);
+        } catch (error) {
+            clearTimeout(timeout);
+            Logger.error('等待 Worker 退出时发生错误:', error);
             process.exit(1);
-        }, 5000);
-
-        // 等待所有进程退出
-        await Promise.all(Array.from(this.workers.values()).map((w) => w.process.exited));
-
-        clearTimeout(timeout);
-        Logger.info('集群已安全关闭');
-        process.exit(0);
+        }
     }
 
     /**

package/lifecycle/lifecycle.ts

@@ -37,7 +37,7 @@ export class Lifecycle {
      * @param appContext - 应用上下文
      * @param callback - 启动完成后的回调函数
      */
-    async start(appContext: BeflyContext, callback?: (server: Server) => void): Promise<void> {
+    async start(appContext: BeflyContext, callback?: (server: Server) => void): Promise<Server> {
         const serverStartTime = Bun.nanoseconds();
         Logger.info('开始启动 Befly 服务器...');
 
@@ -61,7 +61,7 @@ export class Lifecycle {
         const totalStartupTime = calcPerfTime(serverStartTime);
         Logger.info(`服务器启动准备完成，总耗时: ${totalStartupTime}`);
 
-        await Bootstrap.start(
+        return await Bootstrap.start(
             {
                 apiRoutes: this.apiRoutes,
                 pluginLists: this.pluginLists,

package/lifecycle/loader.ts

@@ -7,7 +7,7 @@ import { relative, basename } from 'pathe';
 import { isPlainObject } from 'es-toolkit/compat';
 import { Logger } from '../lib/logger.js';
 import { calcPerfTime } from '../util.js';
-import { paths } from '../paths.js';
+import { corePluginDir, projectPluginDir, coreApiDir, projectApiDir } from '../paths.js';
 import { scanAddons, getAddonDir, addonDirExists } from '../util.js';
 import type { Plugin } from '../types/plugin.js';
 import type { ApiRoute } from '../types/api.js';
@@ -98,7 +98,7 @@ export class Loader {
             // 扫描核心插件目录
             const corePluginsScanStart = Bun.nanoseconds();
             for await (const file of glob.scan({
-                cwd: paths.rootPluginDir,
+                cwd: corePluginDir,
                 onlyFiles: true,
                 absolute: true
             })) {
@@ -262,7 +262,7 @@ export class Loader {
             // 扫描用户插件目录
             const userPluginsScanStart = Bun.nanoseconds();
             for await (const file of glob.scan({
-                cwd: paths.projectPluginDir,
+                cwd: projectPluginDir,
                 onlyFiles: true,
                 absolute: true
             })) {
@@ -393,11 +393,11 @@ export class Loader {
             let apiDir: string;
 
             if (where === 'core') {
-                apiDir = paths.rootApiDir;
+                apiDir = coreApiDir;
             } else if (where === 'addon') {
                 apiDir = getAddonDir(addonName, 'apis');
             } else {
-                apiDir = paths.projectApiDir;
+                apiDir = projectApiDir;
             }
 
             let totalApis = 0;

package/main.ts

@@ -32,8 +32,8 @@ export class Befly {
      * 启动服务器
      * @param callback - 启动完成后的回调函数
      */
-    async listen(callback?: (server: Server) => void): Promise<void> {
-        await this.lifecycle.start(this.appContext, callback);
+    async listen(callback?: (server: Server) => void): Promise<Server> {
+        return await this.lifecycle.start(this.appContext, callback);
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.3.5",
+    "version": "3.4.1",
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "type": "module",
     "private": false,
@@ -64,6 +64,7 @@
         "tsconfig.json",
         "LICENSE",
         "main.ts",
+        "menu.json",
         "paths.ts",
         "util.ts",
         "package.json",
@@ -80,5 +81,5 @@
         "ora": "^9.0.0",
         "pathe": "^2.0.3"
     },
-    "gitHead": "c2f3a7f31ca73cf114fc206a799b78c68ec73c2b"
+    "gitHead": "3131d53e72d22577a42c02620249f39c8930e621"
 }

package/paths.ts

@@ -1,6 +1,31 @@
 /**
  * Befly 框架路径配置
- * 提供统一的路径变量，供整个框架使用
+ *
+ * 提供统一的路径常量，供整个框架使用
+ * 所有路径常量采用具名导出方式，避免通过对象访问
+ *
+ * 路径分类：
+ * - root* 系列：Core 框架内部路径（packages/core/*）
+ * - project* 系列：用户项目路径（process.cwd()/*）
+ *
+ * 目录结构：
+ * ```
+ * packages/core/           (coreDir)
+ *   ├── scripts/           (coreScriptDir)
+ *   ├── config/            (coreConfigDir)
+ *   ├── checks/            (coreCheckDir)
+ *   ├── plugins/           (corePluginDir)
+ *   ├── apis/              (coreApiDir)
+ *   └── tables/            (coreTableDir)
+ *
+ * project/                 (projectDir)
+ *   ├── scripts/           (projectScriptDir)
+ *   ├── config/            (projectConfigDir)
+ *   ├── checks/            (projectCheckDir)
+ *   ├── plugins/           (projectPluginDir)
+ *   ├── apis/              (projectApiDir)
+ *   └── tables/            (projectTableDir)
+ * ```
  */
 
 import { fileURLToPath } from 'node:url';
@@ -13,22 +38,103 @@ const __dirname = dirname(__filename);
 // 项目根目录（befly 框架的使用方项目）
 const projectRoot = process.cwd();
 
+// ==================== Core 框架路径 ====================
+
+/**
+ * Core 框架根目录
+ * @description packages/core/
+ */
+export const coreDir = __dirname;
+
+/**
+ * Core 框架脚本目录
+ * @description packages/core/scripts/
+ * @usage 存放框架级别的脚本工具
+ */
+export const coreScriptDir = join(__dirname, 'scripts');
+
+/**
+ * Core 框架配置目录
+ * @description packages/core/config/
+ * @usage 存放框架默认配置（env.ts, fields.ts 等）
+ */
+export const coreConfigDir = join(__dirname, 'config');
+
+/**
+ * Core 框架检查目录
+ * @description packages/core/checks/
+ * @usage 存放启动检查模块（返回 boolean 的 default 函数）
+ */
+export const coreCheckDir = join(__dirname, 'checks');
+
+/**
+ * Core 框架插件目录
+ * @description packages/core/plugins/
+ * @usage 存放内置插件（db, logger, redis, tool 等）
+ */
+export const corePluginDir = join(__dirname, 'plugins');
+
+/**
+ * Core 框架 API 目录
+ * @description packages/core/apis/
+ * @usage 存放框架级别的 API 接口
+ */
+export const coreApiDir = join(__dirname, 'apis');
+
+/**
+ * Core 框架表定义目录
+ * @description packages/core/tables/
+ * @usage 存放框架核心表定义（JSON 格式）
+ */
+export const coreTableDir = join(__dirname, 'tables');
+
+// ==================== 用户项目路径 ====================
+
+/**
+ * 项目根目录
+ * @description process.cwd()
+ * @usage 用户项目的根目录
+ */
+export const projectDir = projectRoot;
+
+/**
+ * 项目脚本目录
+ * @description {projectDir}/scripts/
+ * @usage 存放用户自定义脚本工具
+ */
+export const projectScriptDir = join(projectRoot, 'scripts');
+
+/**
+ * 项目配置目录
+ * @description {projectDir}/config/
+ * @usage 存放用户项目配置（覆盖框架默认配置）
+ */
+export const projectConfigDir = join(projectRoot, 'config');
+
 /**
- * 系统路径配置对象
- */
-export const paths = {
-    rootDir: __dirname,
-    rootScriptDir: join(__dirname, 'scripts'),
-    rootConfigDir: join(__dirname, 'config'),
-    rootCheckDir: join(__dirname, 'checks'),
-    rootPluginDir: join(__dirname, 'plugins'),
-    rootApiDir: join(__dirname, 'apis'),
-    coreTableDir: join(__dirname, 'tables'),
-    projectDir: projectRoot,
-    projectScriptDir: join(projectRoot, 'scripts'),
-    projectConfigDir: join(projectRoot, 'config'),
-    projectCheckDir: join(projectRoot, 'checks'),
-    projectPluginDir: join(projectRoot, 'plugins'),
-    projectApiDir: join(projectRoot, 'apis'),
-    projectTableDir: join(projectRoot, 'tables')
-} as const;
+ * 项目检查目录
+ * @description {projectDir}/checks/
+ * @usage 存放用户自定义启动检查模块
+ */
+export const projectCheckDir = join(projectRoot, 'checks');
+
+/**
+ * 项目插件目录
+ * @description {projectDir}/plugins/
+ * @usage 存放用户自定义插件
+ */
+export const projectPluginDir = join(projectRoot, 'plugins');
+
+/**
+ * 项目 API 目录
+ * @description {projectDir}/apis/
+ * @usage 存放用户业务 API 接口
+ */
+export const projectApiDir = join(projectRoot, 'apis');
+
+/**
+ * 项目表定义目录
+ * @description {projectDir}/tables/
+ * @usage 存放用户业务表定义（JSON 格式）
+ */
+export const projectTableDir = join(projectRoot, 'tables');

package/router/static.ts

@@ -4,7 +4,7 @@
  */
 
 import { join } from 'pathe';
-import { paths } from '../paths.js';
+import { projectDir } from '../paths.js';
 import { No } from '../util.js';
 import { setCorsOptions } from '../lib/middleware.js';
 import { Logger } from '../lib/logger.js';
@@ -16,7 +16,7 @@ import { Env } from '../config/env.js';
 export async function staticHandler(req: Request): Promise<Response> {
     const corsOptions = setCorsOptions(req);
     const url = new URL(req.url);
-    const filePath = join(paths.projectDir, 'public', url.pathname);
+    const filePath = join(projectDir, 'public', url.pathname);
 
     try {
         // OPTIONS预检请求

package/util.ts

@@ -22,7 +22,7 @@ import { isEmpty, isPlainObject } from 'es-toolkit/compat';
 import { snakeCase, camelCase, kebabCase } from 'es-toolkit/string';
 import { Env } from './config/env.js';
 import { Logger } from './lib/logger.js';
-import { paths } from './paths.js';
+import { projectDir } from './paths.js';
 import type { KeyValue } from './types/common.js';
 import type { JwtPayload, JwtSignOptions, JwtVerifyOptions } from './types/jwt';
 import type { Plugin } from './types/plugin.js';
@@ -241,7 +241,7 @@ export const parseRule = (rule: string): ParsedFieldRule => {
  * 扫描所有可用的 addon
  */
 export const scanAddons = (): string[] => {
-    const beflyDir = join(paths.projectDir, 'node_modules', '@befly-addon');
+    const beflyDir = join(projectDir, 'node_modules', '@befly-addon');
 
     if (!existsSync(beflyDir)) {
         return [];
@@ -270,7 +270,7 @@ export const scanAddons = (): string[] => {
  * 获取 addon 的指定子目录路径
  */
 export const getAddonDir = (addonName: string, subDir: string): string => {
-    return join(paths.projectDir, 'node_modules', '@befly-addon', addonName, subDir);
+    return join(projectDir, 'node_modules', '@befly-addon', addonName, subDir);
 };
 
 /**