koishi-plugin-docker-control 0.0.1

package/lib/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 插件入口 - 支持订阅机制的 Docker 管理插件
+ */
+import { Context, Schema } from 'koishi';
+import type { DockerControlConfig } from './types';
+export declare const name = "docker-control";
+export declare const inject: {
+    required: string[];
+    optional: string[];
+};
+interface DockerControlSubscription {
+    id: number;
+    platform: string;
+    channelId: string;
+    nodeId: string;
+    containerPattern: string;
+    eventTypes: string;
+    enabled: boolean;
+    createdAt: number;
+}
+declare module 'koishi' {
+    interface Context {
+        puppeteer?: {
+            render: (html: string, callback?: (page: any, next: (handle?: any) => Promise<string>) => Promise<string>) => Promise<string>;
+        };
+    }
+    interface Tables {
+        'docker_control_subscriptions': DockerControlSubscription;
+    }
+}
+export declare const Config: Schema<Schemastery.ObjectS<{
+    requestTimeout: Schema<number, number>;
+    debug: Schema<boolean, boolean>;
+    imageOutput: Schema<boolean, boolean>;
+    defaultLogLines: Schema<number, number>;
+    monitor: Schema<Schemastery.ObjectS<{
+        debounceWait: Schema<number, number>;
+        flappingWindow: Schema<number, number>;
+        flappingThreshold: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        debounceWait: Schema<number, number>;
+        flappingWindow: Schema<number, number>;
+        flappingThreshold: Schema<number, number>;
+    }>>;
+    credentials: Schema<Schemastery.ObjectS<{
+        id: Schema<string, string>;
+        name: Schema<string, string>;
+        username: Schema<string, string>;
+        authType: Schema<"key" | "password", "key" | "password">;
+        password: Schema<string, string>;
+        privateKey: Schema<string, string>;
+        passphrase: Schema<string, string>;
+    }>[], Schemastery.ObjectT<{
+        id: Schema<string, string>;
+        name: Schema<string, string>;
+        username: Schema<string, string>;
+        authType: Schema<"key" | "password", "key" | "password">;
+        password: Schema<string, string>;
+        privateKey: Schema<string, string>;
+        passphrase: Schema<string, string>;
+    }>[]>;
+    nodes: Schema<Schemastery.ObjectS<{
+        id: Schema<string, string>;
+        name: Schema<string, string>;
+        tags: Schema<string[], string[]>;
+        host: Schema<string, string>;
+        port: Schema<number, number>;
+        credentialId: Schema<string, string>;
+    }>[], Schemastery.ObjectT<{
+        id: Schema<string, string>;
+        name: Schema<string, string>;
+        tags: Schema<string[], string[]>;
+        host: Schema<string, string>;
+        port: Schema<number, number>;
+        credentialId: Schema<string, string>;
+    }>[]>;
+}>, Schemastery.ObjectT<{
+    requestTimeout: Schema<number, number>;
+    debug: Schema<boolean, boolean>;
+    imageOutput: Schema<boolean, boolean>;
+    defaultLogLines: Schema<number, number>;
+    monitor: Schema<Schemastery.ObjectS<{
+        debounceWait: Schema<number, number>;
+        flappingWindow: Schema<number, number>;
+        flappingThreshold: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        debounceWait: Schema<number, number>;
+        flappingWindow: Schema<number, number>;
+        flappingThreshold: Schema<number, number>;
+    }>>;
+    credentials: Schema<Schemastery.ObjectS<{
+        id: Schema<string, string>;
+        name: Schema<string, string>;
+        username: Schema<string, string>;
+        authType: Schema<"key" | "password", "key" | "password">;
+        password: Schema<string, string>;
+        privateKey: Schema<string, string>;
+        passphrase: Schema<string, string>;
+    }>[], Schemastery.ObjectT<{
+        id: Schema<string, string>;
+        name: Schema<string, string>;
+        username: Schema<string, string>;
+        authType: Schema<"key" | "password", "key" | "password">;
+        password: Schema<string, string>;
+        privateKey: Schema<string, string>;
+        passphrase: Schema<string, string>;
+    }>[]>;
+    nodes: Schema<Schemastery.ObjectS<{
+        id: Schema<string, string>;
+        name: Schema<string, string>;
+        tags: Schema<string[], string[]>;
+        host: Schema<string, string>;
+        port: Schema<number, number>;
+        credentialId: Schema<string, string>;
+    }>[], Schemastery.ObjectT<{
+        id: Schema<string, string>;
+        name: Schema<string, string>;
+        tags: Schema<string[], string[]>;
+        host: Schema<string, string>;
+        port: Schema<number, number>;
+        credentialId: Schema<string, string>;
+    }>[]>;
+}>>;
+export declare function apply(ctx: Context, config: DockerControlConfig): void;
+export {};

package/lib/index.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = exports.inject = exports.name = void 0;
+exports.apply = apply;
+/**
+ * 插件入口 - 支持订阅机制的 Docker 管理插件
+ */
+const koishi_1 = require("koishi");
+const logger_1 = require("./utils/logger");
+const service_1 = require("./service");
+const monitor_1 = require("./service/monitor");
+const commands_1 = require("./commands");
+exports.name = 'docker-control';
+exports.inject = {
+    required: ['database'],
+    optional: ['puppeteer'],
+};
+// 导出配置 Schema
+exports.Config = koishi_1.Schema.object({
+    requestTimeout: koishi_1.Schema.number().default(30000).description('请求超时 (毫秒)'),
+    debug: koishi_1.Schema.boolean().default(false).description('调试模式'),
+    imageOutput: koishi_1.Schema.boolean().default(false).description('使用图片格式输出容器列表'),
+    defaultLogLines: koishi_1.Schema.number().default(100).description('默认日志显示的行数'),
+    // 监控策略
+    monitor: koishi_1.Schema.object({
+        debounceWait: koishi_1.Schema.number().default(60000).description('容器意外停止后等待重启的时间 (ms)，在此期间恢复不发送通知'),
+        flappingWindow: koishi_1.Schema.number().default(300000).description('检测抖动/频繁重启的时间窗口 (ms)'),
+        flappingThreshold: koishi_1.Schema.number().default(3).description('时间窗口内允许的最大状态变更次数，超过则报警'),
+    }).description('监控策略设置'),
+    credentials: koishi_1.Schema.array(koishi_1.Schema.object({
+        id: koishi_1.Schema.string().required(),
+        name: koishi_1.Schema.string().required(),
+        username: koishi_1.Schema.string().default('root'),
+        authType: koishi_1.Schema.union(['key', 'password']).default('key'),
+        password: koishi_1.Schema.string().role('secret'),
+        privateKey: koishi_1.Schema.string().role('textarea'),
+        passphrase: koishi_1.Schema.string().role('secret'),
+    })).description('SSH 凭证列表'),
+    nodes: koishi_1.Schema.array(koishi_1.Schema.object({
+        id: koishi_1.Schema.string().required(),
+        name: koishi_1.Schema.string().required(),
+        tags: koishi_1.Schema.array(koishi_1.Schema.string()).default([]),
+        host: koishi_1.Schema.string().required().description('SSH 主机地址'),
+        port: koishi_1.Schema.number().default(22).description('SSH 端口'),
+        credentialId: koishi_1.Schema.string().required().description('SSH 凭证 ID'),
+    })).description('Docker 节点列表'),
+});
+// 事件消息模板
+const EVENT_MESSAGES = {
+    'container.start': '已启动',
+    'container.stop': '已停止',
+    'container.restart': '已重启',
+    'container.die': '已异常退出',
+    'container.flapping': '运行状态不稳定 (频繁重启)',
+};
+function apply(ctx, config) {
+    // 表名
+    const TABLE_NAME = 'docker_control_subscriptions';
+    // 注册表结构
+    ctx.model.extend(TABLE_NAME, {
+        id: 'unsigned',
+        platform: 'string',
+        channelId: 'string',
+        nodeId: 'string',
+        containerPattern: 'string',
+        eventTypes: 'text',
+        enabled: 'boolean',
+        createdAt: 'integer',
+    }, {
+        autoInc: true,
+        primary: 'id',
+    });
+    // 安全检查
+    if (!config) {
+        logger_1.logger.info('Docker Control 配置未定义，跳过加载');
+        return;
+    }
+    // 验证配置
+    const errors = [];
+    const credentialIds = new Set(config.credentials?.map(c => c.id) || []);
+    for (const node of config.nodes || []) {
+        if (!credentialIds.has(node.credentialId)) {
+            errors.push(`节点 ${node.name} 引用的凭证 ${node.credentialId} 不存在`);
+        }
+    }
+    if (errors.length > 0) {
+        logger_1.logger.warn('配置验证失败:');
+        for (const error of errors) {
+            logger_1.logger.warn(`  - ${error}`);
+        }
+    }
+    // 如果没有配置节点，直接跳过初始化
+    if (!config.nodes || config.nodes.length === 0) {
+        logger_1.logger.info('Docker Control 未配置任何节点，跳过初始化');
+        (0, commands_1.registerCommands)(ctx, () => null);
+        return;
+    }
+    // 创建服务实例
+    const dockerService = new service_1.DockerService(ctx, config);
+    // 传入监控配置
+    const monitorManager = new monitor_1.MonitorManager(config.monitor || {});
+    // 插件就绪时初始化（异步，不阻塞 Koishi 启动）
+    setTimeout(() => {
+        dockerService.initialize().catch((e) => {
+            logger_1.logger.error(`初始化失败: ${e?.message || e}`);
+        });
+    }, 0);
+    // 注册基础指令
+    (0, commands_1.registerCommands)(ctx, () => dockerService, config);
+    // ==================== 订阅指令 ====================
+    ctx.command('docker.subscribe <node> <container>', '订阅容器状态变更通知')
+        .alias('docker订阅', '订阅', '容器订阅')
+        .option('events', '-e <events> 监听的事件类型，默认全部', { fallback: 'start,stop,restart,die' })
+        .action(async ({ options, session }, nodeSelector, containerPattern) => {
+        const { platform, channelId } = session;
+        // 检查服务是否可用
+        if (!dockerService) {
+            return '❌ Docker 服务未初始化';
+        }
+        // 验证必填参数
+        if (!nodeSelector || !containerPattern) {
+            return '❌ 缺少参数，用法: docker.subscribe <节点> <容器>\n   示例: docker.subscribe yun myapp\n   示例: docker.subscribe all all';
+        }
+        // 验证节点
+        const nodes = dockerService.getNodesBySelector(nodeSelector);
+        if (nodes.length === 0) {
+            return `❌ 找不到节点: ${nodeSelector}`;
+        }
+        const nodeId = nodeSelector === 'all' ? '' : nodes[0].id;
+        const eventTypes = options.events.split(',').map(e => e.trim()).filter(Boolean);
+        const targetContainerPattern = containerPattern === 'all' ? '' : containerPattern;
+        // 查询是否已存在相同订阅
+        const existing = await ctx.model.get(TABLE_NAME, {
+            platform,
+            channelId,
+            nodeId,
+            containerPattern: targetContainerPattern,
+        });
+        if (existing.length > 0) {
+            // 更新已有订阅
+            await ctx.model.set(TABLE_NAME, { id: existing[0].id }, {
+                eventTypes: JSON.stringify(eventTypes),
+                enabled: true,
+            });
+            logger_1.logger.info(`更新订阅: ${platform}:${channelId} ${nodeId || '*'} ${targetContainerPattern || '*'}`);
+        }
+        else {
+            // 创建新订阅
+            await ctx.database.create(TABLE_NAME, {
+                platform,
+                channelId,
+                nodeId,
+                containerPattern: targetContainerPattern,
+                eventTypes: JSON.stringify(eventTypes),
+                enabled: true,
+                createdAt: Date.now(),
+            });
+            logger_1.logger.info(`创建订阅: ${platform}:${channelId} ${nodeId || '*'} ${targetContainerPattern || '*'}`);
+        }
+        const nodeDesc = nodeSelector === 'all' ? '所有节点' : nodes[0].name;
+        const containerDesc = containerPattern === 'all' ? '所有容器' : containerPattern;
+        return `✅ 已更新订阅\n   节点: ${nodeDesc}\n   容器: ${containerDesc}\n   事件: ${eventTypes.join(', ')}`;
+    });
+    // 取消订阅
+    ctx.command('docker.unsubscribe <id>', '取消订阅')
+        .alias('docker取消订阅', '取消订阅')
+        .action(async (_, id) => {
+        const subId = Number(id);
+        if (isNaN(subId) || subId <= 0) {
+            return '❌ 请提供有效的订阅 ID，使用 docker订阅列表 查看';
+        }
+        await ctx.model.remove(TABLE_NAME, { id: subId });
+        return `✅ 已取消订阅 ${subId}`;
+    });
+    // 查看订阅列表
+    ctx.command('docker.subscriptions', '查看当前订阅')
+        .alias('docker订阅列表', '订阅列表')
+        .action(async ({ session }) => {
+        const { platform, channelId } = session;
+        const rows = await ctx.model.get(TABLE_NAME, { platform, channelId });
+        if (rows.length === 0) {
+            return '暂无订阅，使用 docker.subscribe <节点> <容器> 添加订阅';
+        }
+        const lines = ['=== 我的订阅 ==='];
+        for (const row of rows) {
+            const nodeDesc = row.nodeId ? `(节点: ${row.nodeId})` : '(所有节点)';
+            const containerDesc = row.containerPattern || '(所有容器)';
+            const eventTypes = JSON.parse(row.eventTypes || '[]');
+            lines.push(`[${row.id}] ${nodeDesc} ${containerDesc}`);
+            lines.push(`    事件: ${eventTypes.join(', ')}`);
+        }
+        return lines.join('\n');
+    });
+    // ==================== 事件监听 ====================
+    // 1. 将 DockerService 的原始事件喂给 MonitorManager
+    dockerService.onNodeEvent((event, nodeId) => {
+        const node = dockerService.getNode(nodeId);
+        if (node) {
+            monitorManager.processEvent(node, event);
+        }
+    });
+    // 2. 监听 MonitorManager 处理后的"智能"事件
+    const eventUnsub = monitorManager.onProcessedEvent(async (processedEvent) => {
+        const { eventType, action, nodeName, containerName, nodeId } = processedEvent;
+        // [调试日志]
+        logger_1.commandLogger.debug(`[推送] 准备发送通知: [${nodeName}] ${containerName} -> ${action}`);
+        // 获取所有订阅并发送通知
+        const subs = await ctx.model.get(TABLE_NAME, {});
+        if (subs.length === 0) {
+            logger_1.commandLogger.debug(`[推送] 无订阅`);
+            return;
+        }
+        for (const sub of subs) {
+            if (!sub.enabled)
+                continue;
+            // 1. 检查事件类型
+            const eventTypes = JSON.parse(sub.eventTypes || '[]');
+            // 特殊逻辑：如果订阅了 'restart' 或 'die'，通常也希望能收到 'flapping' 报警
+            const effectiveEventTypes = [...eventTypes];
+            if (effectiveEventTypes.includes('die') || effectiveEventTypes.includes('restart')) {
+                effectiveEventTypes.push('flapping');
+            }
+            if (!effectiveEventTypes.includes(action)) {
+                logger_1.commandLogger.debug(`  - 订阅[${sub.id}] 忽略: 事件类型不匹配 (订阅: ${eventTypes.join(', ')}, 收到: ${action})`);
+                continue;
+            }
+            // 2. 检查节点匹配
+            if (sub.nodeId && sub.nodeId !== nodeId) {
+                logger_1.commandLogger.debug(`  - 订阅[${sub.id}] 忽略: 节点不匹配`);
+                continue;
+            }
+            // 3. 检查容器名称匹配
+            if (sub.containerPattern) {
+                const pattern = sub.containerPattern
+                    .replace(/\*/g, '.*')
+                    .replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+                const regex = new RegExp(`^${pattern}$`, 'i');
+                if (!regex.test(containerName)) {
+                    logger_1.commandLogger.debug(`  - 订阅[${sub.id}] 忽略: 容器名不匹配`);
+                    continue;
+                }
+            }
+            // 构建消息
+            const emoji = {
+                start: '🟢',
+                stop: '🔴',
+                restart: '🟡',
+                die: '⚠️',
+                flapping: '💥',
+                kill: '💀',
+                health_status: '💚',
+            };
+            const actionText = EVENT_MESSAGES[eventType] || action;
+            const emojiChar = emoji[action] || '📦';
+            const message = `${emojiChar} 【${nodeName}】${containerName} ${actionText}`;
+            // 发送
+            try {
+                const bots = ctx.bots.filter(b => b.platform === sub.platform);
+                if (bots.length === 0) {
+                    logger_1.commandLogger.warn(`  - 订阅[${sub.id}] 失败: 找不到平台 ${sub.platform} 的 Bot`);
+                    continue;
+                }
+                for (const bot of bots) {
+                    await bot.sendMessage(sub.channelId, message);
+                    logger_1.commandLogger.info(`[通知] 已推送到 ${sub.channelId}: ${message}`);
+                }
+            }
+            catch (e) {
+                logger_1.commandLogger.error(`通知发送失败: ${e}`);
+            }
+        }
+    });
+    // ==================== 调试指令 ====================
+    if (config.debug) {
+        const debugLevel = koishi_1.Logger.DEBUG || 4;
+        logger_1.logger.level = debugLevel;
+        logger_1.nodeLogger.level = debugLevel;
+        logger_1.commandLogger.level = debugLevel;
+        logger_1.logger.info(`[DEBUG] 调试模式已启用 (Level: ${debugLevel})`);
+        ctx.command('docker.debug', '调试指令').action(async () => {
+            const nodes = dockerService.getAllNodes();
+            const online = dockerService.getOnlineNodes();
+            const subs = await ctx.model.get(TABLE_NAME, {});
+            const lines = [
+                '=== Docker Control 调试信息 ===',
+                `节点总数: ${nodes.length}`,
+                `在线节点: ${online.length}`,
+                `离线节点: ${nodes.length - online.length}`,
+                `订阅总数: ${subs.length}`,
+                '',
+            ];
+            lines.push('--- 节点详情 ---');
+            for (const n of nodes) {
+                const status = n.status === 'connected' ? '🟢' : n.status === 'connecting' ? '🟡' : '🔴';
+                lines.push(`${status} ${n.name} (${n.id})`);
+            }
+            lines.push('');
+            lines.push('--- 订阅列表 ---');
+            for (const sub of subs) {
+                lines.push(`[${sub.id}] ${sub.platform}:${sub.channelId} ${sub.nodeId || '*'} ${sub.containerPattern || '*'}`);
+            }
+            return lines.join('\n');
+        });
+    }
+    logger_1.logger.info('Docker Control 插件已加载');
+    // 插件卸载时清理
+    ctx.on('dispose', async () => {
+        logger_1.logger.info('Docker Control 插件正在卸载...');
+        eventUnsub();
+        await dockerService.stopAll();
+    });
+}

package/lib/service/agent.d.ts

@@ -0,0 +1,28 @@
+import http from 'http';
+/**
+ * SSH Agent Option Interface
+ */
+export interface SSHAgentOptions extends http.AgentOptions {
+    /**
+     * Provides the raw stream (SSH Channel)
+     * MUST return a Promise that resolves to a stream
+     */
+    getStream: () => Promise<any>;
+}
+/**
+ * Custom SSH Agent
+ * Adapts an SSH Stream (ClientChannel) to work with Node.js http.Agent
+ * Overrides createConnection to use the provided stream factory.
+ */
+export declare class SSHAgent extends http.Agent {
+    private getStream;
+    constructor(options: SSHAgentOptions);
+    /**
+     * Override createConnection to inject our SSH stream
+     */
+    createConnection(options: any, callback: (err: Error | null, stream: any) => void): any;
+    /**
+     * Patch the stream with missing methods (e.g., setTimeout)
+     */
+    private patchStream;
+}

package/lib/service/agent.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSHAgent = void 0;
+const http_1 = __importDefault(require("http"));
+const koishi_1 = require("koishi");
+const logger = new koishi_1.Logger('docker-control-agent');
+/**
+ * Custom SSH Agent
+ * Adapts an SSH Stream (ClientChannel) to work with Node.js http.Agent
+ * Overrides createConnection to use the provided stream factory.
+ */
+class SSHAgent extends http_1.default.Agent {
+    constructor(options) {
+        super({
+            keepAlive: true,
+            timeout: 30000, // Agent level timeout
+            ...options
+        });
+        this.getStream = options.getStream;
+    }
+    /**
+     * Override createConnection to inject our SSH stream
+     */
+    createConnection(options, callback) {
+        this.getStream()
+            .then(stream => {
+            // Patch the stream to satisfy net.Socket interface required by http.ClientRequest
+            this.patchStream(stream);
+            // Emit 'connect' event as expected by http.Agent
+            setImmediate(() => {
+                stream.emit('connect');
+            });
+            callback(null, stream);
+        })
+            .catch(err => {
+            callback(err, null);
+        });
+    }
+    /**
+     * Patch the stream with missing methods (e.g., setTimeout)
+     */
+    patchStream(stream) {
+        // ssh2 stream lacks setTimeout, which is required by http module
+        if (typeof stream.setTimeout !== 'function') {
+            stream.setTimeout = (msecs, callback) => {
+                if (callback) {
+                    setTimeout(callback, msecs);
+                }
+                return stream;
+            };
+        }
+        // Some libraries might check for ref/unref
+        if (typeof stream.ref !== 'function') {
+            stream.ref = () => stream;
+        }
+        if (typeof stream.unref !== 'function') {
+            stream.unref = () => stream;
+        }
+    }
+}
+exports.SSHAgent = SSHAgent;

package/lib/service/connector.d.ts

@@ -0,0 +1,67 @@
+import type { NodeConfig, DockerControlConfig } from '../types';
+export declare class DockerConnector {
+    private config;
+    private fullConfig;
+    private sshClient;
+    constructor(config: NodeConfig, fullConfig: DockerControlConfig);
+    /**
+     * 执行 SSH 命令
+     */
+    exec(command: string): Promise<string>;
+    private execInternal;
+    /**
+     * 执行 docker ps 获取容器列表
+     */
+    listContainers(all?: boolean): Promise<string>;
+    /**
+     * 执行 docker start
+     */
+    startContainer(containerId: string): Promise<void>;
+    /**
+     * 执行 docker stop
+     */
+    stopContainer(containerId: string, timeout?: number): Promise<void>;
+    /**
+     * 执行 docker restart
+     */
+    restartContainer(containerId: string, timeout?: number): Promise<void>;
+    /**
+     * 获取容器日志
+     */
+    getLogs(containerId: string, tail?: number): Promise<string>;
+    /**
+     * 执行容器内命令
+     */
+    execContainer(containerId: string, cmd: string): Promise<string>;
+    /**
+     * 监听 Docker 事件流
+     * @param callback 每行事件数据的回调
+     * @returns 停止监听的方法
+     */
+    startEventStream(callback: (line: string) => void): Promise<() => void>;
+    private connected;
+    /**
+     * 标记连接状态
+     */
+    setConnected(status: boolean): void;
+    /**
+     * 销毁连接
+     */
+    dispose(): void;
+    /**
+     * 获取 SSH 连接
+     */
+    private getConnection;
+    /**
+     * 创建 SSH 连接
+     */
+    private createConnection;
+    /**
+     * 构建认证选项
+     */
+    private buildAuthOptions;
+    /**
+     * 获取凭证配置
+     */
+    private getCredential;
+}