@onebots/core 0.5.0 → 1.0.4

package/lib/base-app.js

@@ -6,21 +6,32 @@ import { writeFileSync } from "fs";
 import log4js from "log4js";
 import { createServer } from "http";
 import yaml from "js-yaml";
-import KoaBodyParser from "koa-bodyparser";
-import basicAuth from "koa-basic-auth";
+import KoaBody from "koa-body";
+import koaStatic from "koa-static";
 const { configure, connectLogger, getLogger } = log4js;
-import { deepClone, deepMerge, readLine } from "./utils.js";
+import { deepClone, deepMerge } from "./utils.js";
 import { Router } from "./router.js";
 import * as path from "path";
 import process from "process";
 import { SqliteDB } from "./db.js";
+import pkg from "../package.json" with { type: "json" };
 import { AdapterRegistry } from "./registry.js";
+import { ConfigValidator, BaseAppConfigSchema } from "./config-validator.js";
+import { LifecycleManager } from "./lifecycle.js";
+import { ErrorHandler, ConfigError } from "./errors.js";
+import { createLogger } from "./logger.js";
+import { initSecurityAudit, securityAudit, closeSecurityAudit } from "./middleware/security-audit.js";
+import { defaultRateLimit } from "./middleware/rate-limit.js";
+import { metricsCollector } from "./middleware/metrics-collector.js";
+import { metrics } from "./metrics.js";
 export { configure, yaml, connectLogger };
 export class BaseApp extends Koa {
     config;
     httpServer;
     isStarted = false;
     logger;
+    enhancedLogger;
+    lifecycle;
     static get configPath() {
         return path.join(BaseApp.configDir, "config.yaml");
     }
@@ -32,10 +43,8 @@ export class BaseApp extends Koa {
     }
     db;
     adapters = new Map();
-    ws;
     router;
     get info() {
-        const pkg = require(path.resolve(__dirname, "../../package.json"));
         const free_memory = os.freemem();
         const total_memory = os.totalmem();
         return {
@@ -58,35 +67,241 @@ export class BaseApp extends Koa {
     }
     constructor(config = {}) {
         super(config);
-        this.config = deepMerge(deepClone(BaseApp.defaultConfig), config);
+        // 初始化生命周期管理器
+        this.lifecycle = new LifecycleManager();
+        // 合并配置并验证
+        const mergedConfig = deepMerge(deepClone(BaseApp.defaultConfig), config);
+        try {
+            this.config = ConfigValidator.validateWithDefaults(mergedConfig, BaseAppConfigSchema);
+        }
+        catch (error) {
+            const configError = ErrorHandler.wrap(error, { config: mergedConfig });
+            throw new ConfigError('Configuration validation failed', {
+                context: { originalError: configError.toJSON() },
+                cause: configError,
+            });
+        }
         this.init();
     }
     init() {
-        this.logger = getLogger("[OneBots]");
-        this.db = new SqliteDB(path.resolve(BaseApp.dataDir, this.config.database));
+        // 初始化传统日志（保持兼容性）
+        this.logger = getLogger("[onebots]");
         this.logger.level = this.config.log_level;
+        // 初始化增强日志
+        this.enhancedLogger = createLogger("[onebots]", this.config.log_level);
+        // 注册数据库资源到生命周期管理器
+        this.db = new SqliteDB(path.resolve(BaseApp.dataDir, this.config.database));
+        this.lifecycle.register('database', () => {
+            // 数据库清理逻辑（如果需要）
+        });
+        // 创建 HTTP 服务器
         this.httpServer = createServer(this.callback());
-        this.router = new Router(this.httpServer, { prefix: this.config.path });
-        this.use(KoaBodyParser({}))
+        this.router = new Router(this.httpServer);
+        // 注册路由清理
+        this.lifecycle.register('router', () => {
+            return this.router.cleanupAsync();
+        });
+        // 注册 HTTP 服务器清理
+        this.lifecycle.register('httpServer', () => {
+            return new Promise((resolve) => {
+                this.httpServer.close(() => resolve());
+            });
+        });
+        // 初始化安全审计日志
+        initSecurityAudit(path.join(BaseApp.dataDir, 'audit'));
+        // 注册健康检查端点（无需认证）
+        this.setupHealthEndpoints();
+        // 用户配置的站点根静态目录（需在 Router 等功能路由之前，便于 GET /xxx.txt 等直出）
+        const publicStaticDir = this.resolvePublicStaticDirectory();
+        if (publicStaticDir) {
+            this.enhancedLogger.info('已启用站点根静态目录', { dir: publicStaticDir });
+            this.use(koaStatic(publicStaticDir));
+        }
+        // 中间件链（multipart：管理端上传站点静态文件等）
+        this.use(KoaBody({
+            multipart: true,
+            formidable: {
+                maxFileSize: 2 * 1024 * 1024,
+                keepExtensions: true,
+            },
+        }))
+            // 性能指标收集（最早执行，以便记录所有请求）
+            .use(metricsCollector())
+            // 安全审计日志
+            .use(securityAudit())
+            // 速率限制（在认证之前，防止暴力破解）
+            .use(defaultRateLimit)
+            .use(async (_ctx, next) => {
+            // 本层不做鉴权。管理端鉴权仅针对 /api（由 onebots 应用层负责）；各平台对外 API（如 /{platform}/{accountId}/onebot/v11/...）由各自协议/适配器单独鉴权。
+            return next();
+        })
             .use(this.router.routes())
-            .use(this.router.allowedMethods())
-            .use(async (ctx, next) => {
-            const adapter = ctx.path?.slice(1)?.split("/")[0];
-            if (this.adapters.has(adapter))
-                return next();
-            return basicAuth({
-                name: this.config.username,
-                pass: this.config.password,
-            })(ctx, next);
+            .use(this.router.allowedMethods());
+        this.enhancedLogger.info('Application initialized', {
+            username: this.config.username,
+            port: this.config.port,
         });
-        this.ws = this.router.ws("/");
         this.initAdapters();
     }
     getLogger(patform) {
-        const logger = getLogger(`[OneBots:${patform}]`);
+        const logger = getLogger(`[onebots:${patform}]`);
         logger.level = this.config.log_level;
         return logger;
     }
+    /**
+     * 获取增强的 Logger 实例
+     */
+    getEnhancedLogger(name) {
+        return createLogger(`[onebots:${name}]`, this.config.log_level);
+    }
+    /**
+     * 设置健康检查端点
+     */
+    setupHealthEndpoints() {
+        // /health - 基础健康检查（存活探针）
+        this.router.get('/health', (ctx) => {
+            ctx.body = {
+                status: 'ok',
+                timestamp: new Date().toISOString(),
+                uptime: process.uptime(),
+                version: pkg.version,
+            };
+        });
+        // /ready - 就绪检查（就绪探针）
+        this.router.get('/ready', (ctx) => {
+            const adaptersStatus = {};
+            let allReady = true;
+            let totalOnline = 0;
+            let totalAccounts = 0;
+            for (const [platform, adapter] of this.adapters) {
+                let online = 0;
+                let offline = 0;
+                for (const account of adapter.accounts.values()) {
+                    totalAccounts++;
+                    if (account.status === 'online') {
+                        online++;
+                        totalOnline++;
+                    }
+                    else {
+                        offline++;
+                    }
+                }
+                adaptersStatus[platform] = { online, offline, total: online + offline };
+                if (offline > 0)
+                    allReady = false;
+            }
+            ctx.status = allReady && this.isStarted ? 200 : 503;
+            ctx.body = {
+                ready: allReady && this.isStarted,
+                timestamp: new Date().toISOString(),
+                server: this.isStarted,
+                adapters: adaptersStatus,
+                summary: {
+                    total_adapters: this.adapters.size,
+                    total_accounts: totalAccounts,
+                    online_accounts: totalOnline,
+                },
+            };
+        });
+        // /metrics - Prometheus 格式指标
+        this.router.get('/metrics', (ctx) => {
+            const metricLines = [];
+            // 基础指标
+            metricLines.push(`# HELP onebots_info OneBots application info`);
+            metricLines.push(`# TYPE onebots_info gauge`);
+            metricLines.push(`onebots_info{version="${pkg.version}"} 1`);
+            metricLines.push(`# HELP onebots_uptime_seconds Application uptime in seconds`);
+            metricLines.push(`# TYPE onebots_uptime_seconds gauge`);
+            metricLines.push(`onebots_uptime_seconds ${process.uptime()}`);
+            metricLines.push(`# HELP onebots_started Whether the application is started`);
+            metricLines.push(`# TYPE onebots_started gauge`);
+            metricLines.push(`onebots_started ${this.isStarted ? 1 : 0}`);
+            // 内存使用
+            const memUsage = process.memoryUsage();
+            metricLines.push(`# HELP onebots_memory_bytes Memory usage in bytes`);
+            metricLines.push(`# TYPE onebots_memory_bytes gauge`);
+            metricLines.push(`onebots_memory_bytes{type="rss"} ${memUsage.rss}`);
+            metricLines.push(`onebots_memory_bytes{type="heapTotal"} ${memUsage.heapTotal}`);
+            metricLines.push(`onebots_memory_bytes{type="heapUsed"} ${memUsage.heapUsed}`);
+            metricLines.push(`onebots_memory_bytes{type="external"} ${memUsage.external}`);
+            // 适配器和账号指标
+            metricLines.push(`# HELP onebots_adapters_total Total number of adapters`);
+            metricLines.push(`# TYPE onebots_adapters_total gauge`);
+            metricLines.push(`onebots_adapters_total ${this.adapters.size}`);
+            metricLines.push(`# HELP onebots_accounts_total Total accounts by platform and status`);
+            metricLines.push(`# TYPE onebots_accounts_total gauge`);
+            for (const [platform, adapter] of this.adapters) {
+                let online = 0;
+                let offline = 0;
+                for (const account of adapter.accounts.values()) {
+                    if (account.status === 'online')
+                        online++;
+                    else
+                        offline++;
+                }
+                metricLines.push(`onebots_accounts_total{platform="${platform}",status="online"} ${online}`);
+                metricLines.push(`onebots_accounts_total{platform="${platform}",status="offline"} ${offline}`);
+            }
+            // 添加性能指标
+            const prometheusMetrics = metrics.exportPrometheus();
+            if (prometheusMetrics.trim()) {
+                metricLines.push('\n# Performance metrics');
+                metricLines.push(prometheusMetrics);
+            }
+            ctx.type = 'text/plain; charset=utf-8';
+            ctx.body = metricLines.join('\n') + '\n';
+        });
+    }
+    /**
+     * 解析 public_static_dir：相对路径基于配置文件目录（configDir），禁止相对路径穿越出 configDir；绝对路径按原样使用
+     */
+    resolvePublicStaticDirectory() {
+        const raw = this.config.public_static_dir;
+        if (raw == null || String(raw).trim() === '')
+            return null;
+        const trimmed = String(raw).trim();
+        const configDirResolved = path.resolve(BaseApp.configDir);
+        const abs = path.isAbsolute(trimmed)
+            ? path.resolve(trimmed)
+            : path.resolve(configDirResolved, trimmed);
+        if (!path.isAbsolute(trimmed)) {
+            const rel = path.relative(configDirResolved, abs);
+            // 禁止 `.`、等价空相对路径，避免整个配置目录被当作静态站点根
+            if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+                this.enhancedLogger.warn('public_static_dir 必须为配置目录下的子目录（不能为 . 或路径穿越），已忽略', {
+                    configured: trimmed,
+                    resolved: abs,
+                    configDir: configDirResolved,
+                });
+                return null;
+            }
+        }
+        let st;
+        try {
+            st = fs.statSync(abs);
+        }
+        catch {
+            try {
+                fs.mkdirSync(abs, { recursive: true });
+                st = fs.statSync(abs);
+            }
+            catch (e) {
+                this.enhancedLogger.warn('public_static_dir 无法创建或访问，静态托管已跳过', { abs, error: e });
+                return null;
+            }
+        }
+        if (!st.isDirectory()) {
+            this.enhancedLogger.warn('public_static_dir 不是目录，已忽略', { abs });
+            return null;
+        }
+        return abs;
+    }
+    /**
+     * 管理端 API：当前解析后的站点根静态目录（未配置或无效时为 null）
+     */
+    getPublicStaticRoot() {
+        return this.resolvePublicStaticDirectory();
+    }
     get adapterConfigs() {
         const map = new Map();
         Object.keys(this.config).forEach(key => {
@@ -166,127 +381,47 @@ export class BaseApp extends Koa {
             return this.adapters.get(platform);
         const adapter = AdapterRegistry.create(`${platform}`, this);
         this.adapters.set(platform, adapter);
+        this.onAdapterCreated(adapter);
         return adapter;
     }
+    /**
+     * 适配器首次创建后的钩子，子类可覆写以订阅该适配器事件（如 verification:request）
+     */
+    onAdapterCreated(_adapter) { }
     async start() {
-        this.httpServer.listen(this.config.port);
-        const fileListener = e => {
-            if (e === "change")
-                this.ws.clients.forEach(async (client) => {
-                    client.send(JSON.stringify({
-                        event: "system.log",
-                        data: await readLine(1, BaseApp.logFile),
-                    }));
+        const stopTimer = this.enhancedLogger.start('Application start');
+        try {
+            // 执行启动钩子
+            await this.lifecycle.start();
+            // 启动 HTTP 服务器
+            await new Promise((resolve, reject) => {
+                this.httpServer.once('error', reject);
+                this.httpServer.listen(this.config.port, () => {
+                    this.httpServer.removeListener('error', reject);
+                    resolve();
                 });
-        };
-        fs.watch(BaseApp.logFile, fileListener);
-        this.once("close", () => {
-            fs.unwatchFile(BaseApp.logFile, fileListener);
-        });
-        process.once("disconnect", () => {
-            fs.unwatchFile(BaseApp.logFile, fileListener);
-        });
-        this.ws.on("connection", async (client) => {
-            client.send(JSON.stringify({
-                event: "system.sync",
-                data: {
-                    config: fs.readFileSync(BaseApp.configPath, "utf8"),
-                    adapters: [...this.adapters.values()].map(adapter => {
-                        return adapter.info;
-                    }),
-                    app: this.info,
-                    logs: fs.existsSync(BaseApp.logFile) ? await readLine(100, BaseApp.logFile) : "",
-                },
-            }));
-            client.on("message", async (raw) => {
-                let payload = {};
+            });
+            this.enhancedLogger.mark(`Server listening at http://0.0.0.0:${this.config.port}/${this.config.path ? this.config.path : ""}`, { port: this.config.port, path: this.config.path });
+            // 启动所有适配器
+            for (const [platform, adapter] of this.adapters) {
                 try {
-                    payload = JSON.parse(raw.toString());
+                    await adapter.start();
+                    this.enhancedLogger.info(`Adapter started`, { platform });
                 }
-                catch {
-                    return;
+                catch (error) {
+                    const wrappedError = ErrorHandler.wrap(error, { platform });
+                    this.enhancedLogger.error(wrappedError, { platform });
+                    // 继续启动其他适配器
                 }
-                switch (payload.action) {
-                    case "system.input":
-                        // 将流的模式切换到“流动模式”
-                        process.stdin.resume();
-                        // 使用以下函数来模拟输入数据
-                        function simulateInput(data) {
-                            process.nextTick(() => {
-                                process.stdin.emit("data", data);
-                            });
-                        }
-                        simulateInput(Buffer.from(payload.data + "\n", "utf8"));
-                        // 模拟结束
-                        process.nextTick(() => {
-                            process.stdin.emit("end");
-                        });
-                        return true;
-                    case "system.saveConfig":
-                        return fs.writeFileSync(BaseApp.configPath, payload.data, "utf8");
-                    case "system.reload":
-                        const config = yaml.load(fs.readFileSync(BaseApp.configPath, "utf8"));
-                        return this.reload(config);
-                    case "bot.start": {
-                        const { platform, uin } = JSON.parse(payload.data);
-                        await this.adapters.get(platform)?.setOnline(uin);
-                        return client.send(JSON.stringify({
-                            event: "bot.change",
-                            data: this.adapters.get(platform).getAccount(uin).info,
-                        }));
-                    }
-                    case "bot.stop": {
-                        const { platform, uin } = JSON.parse(payload.data);
-                        await this.adapters.get(platform)?.setOffline(uin);
-                        return client.send(JSON.stringify({
-                            event: "bot.change",
-                            data: this.adapters.get(platform).getAccount(uin).info,
-                        }));
-                    }
-                }
-            });
-        });
-        this.router.get("/list", ctx => {
-            ctx.body = this.accounts.map(bot => {
-                return bot.info;
-            });
-        });
-        this.router.post("/add", (ctx, next) => {
-            const config = (ctx.request.body || {});
-            try {
-                this.addAccount(config);
-                ctx.body = `添加成功`;
             }
-            catch (e) {
-                ctx.body = e.message;
-            }
-        });
-        this.router.post("/edit", (ctx, next) => {
-            const config = (ctx.request.body || {});
-            try {
-                this.updateAccount(config);
-                ctx.body = `修改成功`;
-            }
-            catch (e) {
-                ctx.body = e.message;
-            }
-        });
-        this.router.get("/remove", (ctx, next) => {
-            const { uin, platform, force } = ctx.request.query;
-            try {
-                this.removeAccount(String(platform), String(uin), Boolean(force));
-                ctx.body = `移除成功`;
-            }
-            catch (e) {
-                console.log(e);
-                ctx.body = e.message;
-            }
-        });
-        this.logger.mark(`server listen at http://0.0.0.0:${this.config.port}/${this.config.path ? this.config.path : ""}`);
-        for (const [_, adapter] of this.adapters) {
-            await adapter.start();
+            this.isStarted = true;
+            stopTimer();
+        }
+        catch (error) {
+            const wrappedError = ErrorHandler.wrap(error);
+            this.enhancedLogger.fatal(wrappedError);
+            throw wrappedError;
         }
-        this.isStarted = true;
     }
     async reload(config) {
         await this.stop();
@@ -295,22 +430,40 @@ export class BaseApp extends Koa {
         await this.start();
     }
     async stop() {
-        for (const [_, adapter] of this.adapters) {
-            await adapter.stop();
+        const stopTimer = this.enhancedLogger.start('Application stop');
+        try {
+            // 执行停止钩子
+            await this.lifecycle.stop();
+            // 停止所有适配器
+            const stopPromises = [];
+            for (const [platform, adapter] of this.adapters) {
+                stopPromises.push(Promise.resolve(adapter.stop()).catch(error => {
+                    const wrappedError = ErrorHandler.wrap(error, { platform });
+                    this.enhancedLogger.error(wrappedError, { platform });
+                }));
+            }
+            await Promise.all(stopPromises);
+            this.adapters.clear();
+            // 清理资源
+            await this.lifecycle.cleanup();
+            // 关闭安全审计日志
+            closeSecurityAudit();
+            this.emit("close");
+            this.isStarted = false;
+            stopTimer();
+            this.enhancedLogger.info('Application stopped');
+        }
+        catch (error) {
+            const wrappedError = ErrorHandler.wrap(error);
+            this.enhancedLogger.error(wrappedError);
+            throw wrappedError;
         }
-        this.adapters.clear();
-        // this.ws.close()
-        this.httpServer.close();
-        this.emit("close");
-        this.isStarted = false;
     }
 }
 (function (BaseApp) {
     BaseApp.defaultConfig = {
         port: 6727,
         database: "onebots.db",
-        username: "admin",
-        password: "123456",
         timeout: 30,
         general: {},
         log_level: "info",

package/lib/circuit-breaker.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 熔断器模式实现
+ * 防止级联故障，提高系统稳定性
+ */
+export declare enum CircuitState {
+    /** 关闭状态：正常处理请求 */
+    CLOSED = "CLOSED",
+    /** 开启状态：拒绝所有请求 */
+    OPEN = "OPEN",
+    /** 半开状态：尝试恢复，允许部分请求通过 */
+    HALF_OPEN = "HALF_OPEN"
+}
+export interface CircuitBreakerOptions {
+    /** 失败阈值：连续失败多少次后开启熔断 */
+    failureThreshold?: number;
+    /** 成功阈值：半开状态下成功多少次后关闭熔断 */
+    successThreshold?: number;
+    /** 超时时间：开启状态持续多久后进入半开状态（毫秒） */
+    timeout?: number;
+    /** 监控窗口大小（毫秒） */
+    monitoringPeriod?: number;
+    /** 最小请求数：在监控窗口内至少需要多少请求才触发熔断 */
+    minimumRequests?: number;
+    /** 错误率阈值：错误率超过多少时开启熔断（0-1） */
+    errorRateThreshold?: number;
+}
+/**
+ * 熔断器类
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime;
+    private records;
+    private options;
+    constructor(options?: CircuitBreakerOptions);
+    /**
+     * 执行函数，带熔断保护
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 成功回调
+     */
+    private onSuccess;
+    /**
+     * 失败回调
+     */
+    private onFailure;
+    /**
+     * 判断是否应该开启熔断
+     */
+    private shouldOpen;
+    /**
+     * 获取错误率
+     */
+    private getErrorRate;
+    /**
+     * 获取最近的请求记录
+     */
+    private getRecentRequests;
+    /**
+     * 清理过期记录
+     */
+    private cleanupOldRecords;
+    /**
+     * 获取当前状态
+     */
+    getState(): CircuitState;
+    /**
+     * 获取统计信息
+     */
+    getStats(): {
+        state: CircuitState;
+        failureCount: number;
+        successCount: number;
+        errorRate: number;
+        totalRequests: number;
+    };
+    /**
+     * 手动重置熔断器
+     */
+    reset(): void;
+}
+/**
+ * 熔断器开启错误
+ */
+export declare class CircuitBreakerOpenError extends Error {
+    constructor(message: string);
+}
+/**
+ * 创建带熔断器的函数包装器
+ */
+export declare function withCircuitBreaker<T extends (...args: any[]) => Promise<any>>(fn: T, breaker: CircuitBreaker): T;