webaiapi 0.0.0-stage → 0.1.0

package/dist/server/app.js

@@ -0,0 +1,292 @@
+/**
+ * Fastify 应用组装 —— `legacy-python/src/main.py` 的移植。
+ *
+ * ## ⚠️ 一处**有意修复**的偏差（必须知道）
+ * Python 的 `verify_api_key` 是个 FastAPI **依赖**，但**从来没有被任何路由
+ * `Depends()` 引用**（`grep -rn "Depends(" src` 只有它自己的签名）。
+ * 也就是说：Python 版里 API Key 认证**从来没生效过** —— `main.py` 往管理器里塞了密钥、
+ * 设了 `required`，但没有任何地方去查。
+ *
+ * TS 版把它**接上了**（`onRequest` 钩子），但保持完全相同的放行语义：
+ * - `API_KEYS` 为空 → 强制为「不校验」（与 Python 的日志「API Key 认证已禁用」一致）；
+ * - `API_KEY_REQUIRED=false`（默认）→ 不带密钥也放行，**现有用户零感知**；
+ * - 只有显式 `API_KEY_REQUIRED=true` 时才真正拦 401。
+ *
+ * ## 其他差异
+ * - CORS 用**手写钩子**而不是 `@fastify/cors`：少一个运行时依赖，
+ *   且能正确实现「`allow_credentials` + 通配来源」这个 FastAPI 写法其实不合法、
+ *   浏览器会拒绝的组合（这里回显请求方 Origin）。
+ */
+import { execFileSync } from 'node:child_process';
+import Fastify, {} from 'fastify';
+import { getApiKeys, settings } from '../config.js';
+import { getHistoryDb } from '../controllers/history-db.js';
+import { getModelRouter } from '../controllers/router.js';
+import { resetApiLog } from '../log/api-logger.js';
+import { logger } from '../log/logger.js';
+import { disposeAllChannels, disposeSharedBrowser } from '../browser/manager.js';
+import { registerChatRoutes } from '../routes/chat.js';
+import { registerMetaRoutes, runStartupTasks, startPeriodicHistoryCleanup } from '../routes/meta.js';
+import { waitForBackgroundTasks } from '../routes/compress.js';
+import { errorMessage } from '../utils/errors.js';
+import { getApiKeyManager, makeApiKeyHook, verifyApiKey } from './middleware/api-key.js';
+import { makeRateLimitHook } from './middleware/rate-limit.js';
+import { makeTimeoutHook } from './middleware/timeout.js';
+/** 关服时挂起的清理句柄。 */
+let periodicCleanup = null;
+/**
+ * 初始化 API Key 管理器。
+ *
+ * 与 Python `main()` 的语义一致：**没有配置任何密钥时视为禁用认证**
+ * （即使 `API_KEY_REQUIRED=true` 也不拦 —— 否则等于把自己锁在门外）。
+ */
+export function initApiKeys() {
+    const manager = getApiKeyManager();
+    const keys = getApiKeys();
+    if (keys.size === 0) {
+        manager.required = false;
+        logger.info('API Key 认证已禁用（未配置密钥）');
+        return;
+    }
+    for (const key of keys)
+        manager.addKey(key);
+    manager.required = settings.apiKeyRequired;
+    logger.info(`API Key 认证已配置: ${keys.size} 个密钥` +
+        `（${settings.apiKeyRequired ? '强制校验' : '仅记录，不拦截'}）`);
+}
+/**
+ * 创建 Fastify 应用（不监听端口）。
+ *
+ * 中间件顺序与原实现一致：CORS → 超时 → 限流 → 认证 → 路由。
+ */
+export async function createApp() {
+    const app = Fastify({
+        // ⚠️ 不用 Fastify 内建 logger：项目统一走 pino 单例（`src/log/logger.ts`），
+        //    避免同一条日志被两套格式化器各打一遍。
+        logger: false,
+        trustProxy: true, // 让 `request.ip` 取到反向代理后的真实 IP（限流按 IP 时很关键）
+        bodyLimit: 64 * 1024 * 1024, // 上下文可能很大（几十万字符的历史）
+    });
+    initApiKeys();
+    const prefix = settings.apiPrefix || '';
+    /* ===== CORS（手写，见文件头说明）===== */
+    app.addHook('onRequest', async (request, reply) => {
+        const origin = request.headers['origin'];
+        if (typeof origin === 'string' && origin) {
+            reply.header('access-control-allow-origin', origin);
+            reply.header('access-control-allow-credentials', 'true');
+            reply.header('vary', 'Origin');
+        }
+        else {
+            reply.header('access-control-allow-origin', '*');
+        }
+        reply.header('access-control-allow-methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
+        reply.header('access-control-allow-headers', request.headers['access-control-request-headers'] || '*');
+        // 预检直接结束，不进业务逻辑
+        if (request.method === 'OPTIONS') {
+            void reply.code(204).send();
+        }
+    });
+    /* ===== 超时（必须在业务路由之前，才能把 deadline 传给下游）===== */
+    const skipPaths = new Set([
+        `${prefix}/health`,
+        `${prefix}/status`,
+        '/health',
+        '/status',
+        '/',
+    ]);
+    app.addHook('onRequest', makeTimeoutHook({ timeoutSeconds: settings.requestTimeout, skipPaths }));
+    /* ===== 限流 ===== */
+    app.addHook('onRequest', makeRateLimitHook({
+        requestsPerMinute: settings.rateLimitPerMinute,
+        enabled: settings.rateLimitEnabled,
+        skipPaths,
+    }));
+    /* ===== API Key 认证 =====
+     * 只在「配了密钥**且**要求强制」时才真的校验（见文件头说明）。 */
+    const apiKeyManager = getApiKeyManager();
+    if (apiKeyManager.required) {
+        app.addHook('onRequest', makeApiKeyHook(skipPaths));
+    }
+    else {
+        // 未强制时也解析一次密钥：便于限流按 key 分组（但不拦截）
+        app.addHook('onRequest', async (request) => {
+            verifyApiKey(request);
+        });
+    }
+    /* ===== 路由 ===== */
+    await app.register(async (instance) => {
+        registerMetaRoutes(instance);
+        registerChatRoutes(instance);
+    }, prefix ? { prefix } : {});
+    // 根路径（便于确认服务活着）
+    app.get('/', async () => ({
+        name: settings.appName,
+        version: settings.appVersion,
+        docs: `${prefix}/models`,
+    }));
+    /* ===== 404 ===== */
+    app.setNotFoundHandler((request, reply) => {
+        void reply.code(404).send({
+            error: {
+                message: `Not Found: ${request.method} ${request.url}`,
+                type: 'invalid_request_error',
+                code: 'not_found',
+            },
+        });
+    });
+    /* ===== 全局异常处理 ===== */
+    app.setErrorHandler((error, _request, reply) => {
+        // Fastify 的 body 解析错误（JSON 语法错等）自带 4xx 状态码
+        const err = error;
+        const statusCode = typeof err.statusCode === 'number' ? err.statusCode : 500;
+        const message = err.message ?? '内部服务器错误';
+        if (statusCode >= 500) {
+            logger.error(`未处理的异常: ${message}`);
+        }
+        const payload = statusCode >= 500
+            ? { message: '内部服务器错误', type: 'server_error', code: 'internal_error' }
+            : { message, type: 'invalid_request_error', code: err.code ?? null };
+        void reply.code(statusCode >= 500 ? 500 : statusCode).send({ error: payload });
+    });
+    return app;
+}
+/**
+ * 启动服务（含启动任务与优雅关闭）。
+ *
+ * 返回的 Promise 在服务关闭后 resolve（与 `uvicorn.run` 的阻塞语义一致）。
+ */
+/* ==================================================================== */
+/* 端口占用诊断                                                        */
+/* ==================================================================== */
+/** 判断错误是不是「端口被占用」。 */
+function isAddrInUse(error) {
+    const code = error?.['code'];
+    if (typeof code === 'string' && code === 'EADDRINUSE')
+        return true;
+    return String(error).includes('EADDRINUSE');
+}
+/**
+ * 尽力找出占用指定端口的进程 PID（找不到返回 `null`）。
+ *
+ * ⚠️ 这里的输出**只用于给用户一句提示**，所以任何失败都必须静默放弃 ——
+ * 绝不能因为「`ss`/`lsof` 不存在、输出格式变了、没权限看别人的进程」
+ * 而把启动流程搞挂。同用户的进程才能看到 pid，而我们提示的恰恰是
+ * 「另一个同用户实例」这种最常见的情况，所以够用。
+ */
+function pidListeningOn(port) {
+    const tryRead = (cmd, args, pattern) => {
+        try {
+            const out = execFileSync(cmd, args, { encoding: 'utf8', timeout: 3000 });
+            const match = pattern.exec(out);
+            return match ? Number(match[1]) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // `ss -ltnp`：LISTEN 0 511 0.0.0.0:8631 ... users:(("MainThread",pid=78002,fd=24))
+    const bySs = tryRead('ss', ['-ltnp'], new RegExp(`:${port}\\b.*pid=(\\d+)`));
+    if (bySs !== null)
+        return bySs;
+    // `lsof -ti :PORT`：每行一个 pid
+    return tryRead('lsof', ['-ti', `:${port}`], /^(\d+)$/m);
+}
+/**
+ * 启动服务并阻塞直到进程收到退出信号。
+ *
+ * @returns 进程退出码：`0` 正常 / `1` 启动失败（如端口被占用）。
+ *   ⚠️ 返回退出码而不是在函数里设 `process.exitCode` —— CLI 侧的
+ *   `process.exitCode = await runCli()` 会覆盖它（实测踩过：报错信息是对的，
+ *   退出码却是 0，脚本会误判成功）。
+ */
+export async function startServer() {
+    const app = await createApp();
+    // ===== 启动任务 =====
+    resetApiLog();
+    logger.info('API 请求日志已重置');
+    await runStartupTasks();
+    periodicCleanup = startPeriodicHistoryCleanup();
+    // 预热模型路由器（会打印账号分配与辅助通道状态，是排查「多账号有没有生效」的第一现场）
+    getModelRouter();
+    /* ===== 浏览器二进制预检（**非致命**，只警告）=====
+     * Playwright 不随包分发浏览器（Firefox 约 80MB），这是 npm 安装后最常见的
+     * 「装好了但跑不起来」。浏览器是**首次请求时才懒加载**的，若不在这里提前告警，
+     * 用户会在第一次对话失败时才发现 —— 那时错误信息埋在日志里，很难定位。
+     * 所以启动时查一次并给出可复制的修复命令，但**不阻断启动**
+     * （健康检查、/v1/models 等不需要浏览器）。 */
+    try {
+        const { firefox } = await import('playwright');
+        const { existsSync } = await import('node:fs');
+        const exe = firefox.executablePath();
+        if (!existsSync(exe)) {
+            logger.warn('⚠️ 未找到 Playwright 的 Firefox 二进制，真实对话会失败。' +
+                '请运行 `npx playwright install firefox` 下载（约 80MB，只需一次）。');
+        }
+    }
+    catch (error) {
+        logger.warn(`浏览器预检失败: ${errorMessage(error)}`);
+    }
+    const url = `http://${settings.apiHost}:${settings.apiPort}${settings.apiPrefix}`;
+    try {
+        await app.listen({ host: settings.apiHost, port: settings.apiPort });
+    }
+    catch (error) {
+        // ⚠️ 必须拦下来翻译成人话：`listen` 失败时 Node 抛的是一整段堆栈
+        //    （`UVExceptionWithHostPort ... code: 'EADDRINUSE'`），用户看不出
+        //    「其实是有另一个实例在跑」—— 实测就有这样的困惑。
+        //    而且此时启动已经做了不少事（注册 Provider、启用辅助通道、
+        //    打开浏览器），堆栈会把真正的原因淹没在里面。
+        if (isAddrInUse(error)) {
+            const pid = pidListeningOn(settings.apiPort);
+            logger.error(`端口 ${settings.apiPort} 已被占用（${pid ? `进程 ${pid}` : '可能有另一个实例在跑'}）。` +
+                '\n  处理方式任选：' +
+                '\n  1. 直接用已在跑的那个实例（`webapi status` 可查看）；' +
+                `\n  2. 停掉它再启动：kill ${pid ?? '<pid>'}；` +
+                `\n  3. 换个端口：API_PORT=${settings.apiPort + 1} webapi start`);
+            // ⚠️ 返回退出码而不是设 `process.exitCode`：CLI 侧会执行
+            //    `process.exitCode = await runCli()`，把这里设的值**覆盖回 0**
+            //    （实测确实发生了：报错信息对了，退出码却是 0，脚本会误判成功）。
+            return 1;
+        }
+        throw error;
+    }
+    logger.info(`服务已启动: ${url}`);
+    // ===== 优雅关闭 =====
+    const shutdown = async (signal) => {
+        logger.info(`收到 ${signal}，正在关闭...`);
+        try {
+            await app.close();
+        }
+        catch (error) {
+            logger.warn(`关闭 HTTP 服务失败: ${errorMessage(error)}`);
+        }
+        periodicCleanup?.stop();
+        await waitForBackgroundTasks();
+        try {
+            await disposeAllChannels();
+            await disposeSharedBrowser();
+            logger.info('浏览器资源已清理');
+        }
+        catch (error) {
+            logger.warn(`清理浏览器失败: ${errorMessage(error)}`);
+        }
+        try {
+            getHistoryDb().close();
+        }
+        catch {
+            // 忽略
+        }
+        logger.info('应用已关闭');
+    };
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.once(signal, () => {
+            void shutdown(signal).then(() => process.exit(0));
+        });
+    }
+    await new Promise((resolve) => {
+        app.server.once('close', () => resolve());
+    });
+    return 0;
+}
+//# sourceMappingURL=app.js.map

package/dist/server/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/server/app.ts"],"names":[],"mappings":"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"}

package/dist/server/middleware/api-key.d.ts

@@ -0,0 +1,61 @@
+/**
+ * API Key 认证 —— `legacy-python/src/middleware/auth.py` 的移植（OpenAI 兼容）。
+ *
+ * 认证方式（优先级与原实现一致）：
+ * 1. `Authorization: Bearer {key}`
+ * 2. `x-api-key: {key}`
+ *
+ * 配置：`API_KEYS=key1,key2` / `API_KEY_REQUIRED=true`（默认 false，兼容无认证模式）。
+ *
+ * 与原实现的差异：
+ * - FastAPI 的 `Depends(security)` → 显式调用 {@link verifyApiKey}（由路由自行调用或
+ *   交给 `onRequest` 钩子）。
+ * - Python 的 `import hmac` 从未被使用（`key in self.keys` 是普通集合查找）。
+ *   TS 侧同样用 Set，但**保留一个说明**：这不是恒定时间比较，若将来把 API Key
+ *   当成真正的密钥用，应改为 `timingSafeEqual`。
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+/** 从请求头里取 API Key（`Authorization: Bearer` 优先，其次 `x-api-key`）。 */
+export declare function extractApiKey(request: FastifyRequest): string | null;
+/** API Key 管理器。 */
+export declare class ApiKeyManager {
+    private keys;
+    /** 是否强制认证（未配置密钥时自动为 false）。 */
+    required: boolean;
+    /**
+     * 校验密钥。
+     *
+     * ## 语义（三条，顺序有意义）
+     * 1. **一个密钥都没配（`keys.size === 0`）且不强制 → 认证功能整体关闭，
+     *    忽略请求里带的任何 Key**。
+     *    ⚠️ 旧实现在这里会 401（理由是「传了错密钥说明客户端有意图，静默放行
+     *    会掩盖配置错误」）。但 OpenAI 兼容客户端**几乎总会**带一个
+     *    `Authorization` 头（不少还强制要求填非空值），于是出现两边各说各话：
+     *    服务端日志说「认证已禁用」，客户端却收到 401「API Key 无效或已过期」
+     *    —— 实测 xzh 就是这么死的。**「禁用」必须真的禁用。**
+     * 2. 配了密钥但没传 → 按 `required` 决定（不强制则放行）。
+     * 3. 配了密钥且传了 → 必须在集合里（真认证，传错一定 401）。
+     */
+    isValid(key: string | null | undefined): boolean;
+    /** 添加密钥。 */
+    addKey(key: string): void;
+    /** 移除密钥（返回是否真的移除了）。 */
+    removeKey(key: string): boolean;
+    /** 已配置的密钥数量。 */
+    get count(): number;
+}
+/** 获取 API Key 管理器（单例）。 */
+export declare function getApiKeyManager(): ApiKeyManager;
+/**
+ * 校验请求的 API Key，返回使用的密钥（未传且不强制时返回 null）。
+ *
+ * 失败时抛 {@link AuthenticationError}（401，`invalid_api_key`）。
+ */
+export declare function verifyApiKey(request: FastifyRequest): string | null;
+/**
+ * Fastify 钩子：认证所有请求（除豁免路径）。
+ *
+ * 豁免名单与原实现一致：健康检查 / 状态 / 根路径。
+ */
+export declare function makeApiKeyHook(skipPaths: ReadonlySet<string>): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/server/middleware/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/api-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK5D,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CASpE;AAED,mBAAmB;AACnB,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAqB;IAEjC,+BAA+B;IAC/B,QAAQ,UAAS;IAEjB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAI/C;IAED,YAAY;IACZ,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CASxB;IAED,uBAAuB;IACvB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9B;IAED,gBAAgB;IAChB,IAAI,KAAK,IAAI,MAAM,CAElB;CACF;AAID,0BAA0B;AAC1B,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAenE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAKjE"}

package/dist/server/middleware/api-key.js

@@ -0,0 +1,95 @@
+import { logger } from '../../log/logger.js';
+import { AuthenticationError } from '../../utils/errors.js';
+/** 从请求头里取 API Key（`Authorization: Bearer` 优先，其次 `x-api-key`）。 */
+export function extractApiKey(request) {
+    const auth = request.headers['authorization'];
+    if (typeof auth === 'string' && auth.startsWith('Bearer ')) {
+        const key = auth.slice(7).trim();
+        if (key)
+            return key;
+    }
+    const xApiKey = request.headers['x-api-key'];
+    if (typeof xApiKey === 'string' && xApiKey)
+        return xApiKey;
+    return null;
+}
+/** API Key 管理器。 */
+export class ApiKeyManager {
+    keys = new Set();
+    /** 是否强制认证（未配置密钥时自动为 false）。 */
+    required = false;
+    /**
+     * 校验密钥。
+     *
+     * ## 语义（三条，顺序有意义）
+     * 1. **一个密钥都没配（`keys.size === 0`）且不强制 → 认证功能整体关闭，
+     *    忽略请求里带的任何 Key**。
+     *    ⚠️ 旧实现在这里会 401（理由是「传了错密钥说明客户端有意图，静默放行
+     *    会掩盖配置错误」）。但 OpenAI 兼容客户端**几乎总会**带一个
+     *    `Authorization` 头（不少还强制要求填非空值），于是出现两边各说各话：
+     *    服务端日志说「认证已禁用」，客户端却收到 401「API Key 无效或已过期」
+     *    —— 实测 xzh 就是这么死的。**「禁用」必须真的禁用。**
+     * 2. 配了密钥但没传 → 按 `required` 决定（不强制则放行）。
+     * 3. 配了密钥且传了 → 必须在集合里（真认证，传错一定 401）。
+     */
+    isValid(key) {
+        if (this.keys.size === 0 && !this.required)
+            return true;
+        if (!key)
+            return !this.required;
+        return this.keys.has(key);
+    }
+    /** 添加密钥。 */
+    addKey(key) {
+        const trimmed = key.trim();
+        if (!trimmed)
+            return;
+        this.keys.add(trimmed);
+        logger.info(trimmed.length > 12
+            ? `API Key 已添加: ${trimmed.slice(0, 8)}...${trimmed.slice(-4)}`
+            : `API Key 已添加: ${trimmed}`);
+    }
+    /** 移除密钥（返回是否真的移除了）。 */
+    removeKey(key) {
+        return this.keys.delete(key);
+    }
+    /** 已配置的密钥数量。 */
+    get count() {
+        return this.keys.size;
+    }
+}
+let manager = null;
+/** 获取 API Key 管理器（单例）。 */
+export function getApiKeyManager() {
+    manager ??= new ApiKeyManager();
+    return manager;
+}
+/**
+ * 校验请求的 API Key，返回使用的密钥（未传且不强制时返回 null）。
+ *
+ * 失败时抛 {@link AuthenticationError}（401，`invalid_api_key`）。
+ */
+export function verifyApiKey(request) {
+    const mgr = getApiKeyManager();
+    const apiKey = extractApiKey(request);
+    if (!apiKey && mgr.required) {
+        throw new AuthenticationError('缺少 API Key。请设置 Authorization: Bearer {key} 或 x-api-key: {key}');
+    }
+    if (apiKey && !mgr.isValid(apiKey)) {
+        throw new AuthenticationError('API Key 无效');
+    }
+    return apiKey;
+}
+/**
+ * Fastify 钩子：认证所有请求（除豁免路径）。
+ *
+ * 豁免名单与原实现一致：健康检查 / 状态 / 根路径。
+ */
+export function makeApiKeyHook(skipPaths) {
+    return async (request, _reply) => {
+        if (skipPaths.has(request.url.split('?')[0] ?? ''))
+            return;
+        verifyApiKey(request);
+    };
+}
+//# sourceMappingURL=api-key.js.map

package/dist/server/middleware/api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.js","sourceRoot":"","sources":["../../../src/server/middleware/api-key.ts"],"names":[],"mappings":"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"}

package/dist/server/middleware/rate-limit.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 速率限制中间件 —— `legacy-python/src/middleware/rate_limit.py` 的移植。
+ *
+ * 令牌桶算法，按客户端标识（API Key 优先，否则 IP）分别限流。
+ *
+ * 配置：`RATE_LIMIT_PER_MINUTE=60` / `RATE_LIMIT_ENABLED=true`
+ *
+ * 与原实现的差异：
+ * - `BaseHTTPMiddleware.dispatch` → Fastify `onRequest` 钩子的工厂函数。
+ * - Python 用 `time.monotonic()`（不受系统时间调整影响）；TS 用
+ *   `performance.now()` 达到同样效果（`Date.now()` 会被 NTP 调时影响）。
+ * - `asyncio.Lock` → {@link Mutex}：JS 是单线程，`consume()` 本身不需要锁，
+ *   但清理与取桶的「读改写」序列仍需要原子化，保留锁以免将来加入 await 时出错。
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+/** 令牌桶。 */
+export declare class TokenBucket {
+    /** 令牌生成速率（每秒）。 */
+    private readonly rate;
+    /** 桶容量。 */
+    private readonly capacity;
+    private tokens;
+    private lastTime;
+    constructor(
+    /** 令牌生成速率（每秒）。 */
+    rate: number, 
+    /** 桶容量。 */
+    capacity: number, now?: () => number);
+    /** 尝试消费 1 个令牌。 */
+    consume(now?: () => number): boolean;
+    /** 最后使用时间（清理过期桶用）。 */
+    get lastUsed(): number;
+}
+/** 速率限制选项。 */
+export interface RateLimitOptions {
+    requestsPerMinute: number;
+    enabled: boolean;
+    /**
+     * 不参与限流的路径。默认与 Python 版一致：
+     * `/health`、`/status`、`/v1/health`、`/v1/status`、`/`。
+     */
+    skipPaths?: ReadonlySet<string>;
+}
+/** 限流器（可在测试中直接实例化，不依赖 Fastify）。 */
+export declare class RateLimiter {
+    private readonly requestsPerMinute;
+    private readonly buckets;
+    private readonly lock;
+    private lastCleanup;
+    /** 清理间隔（秒）。 */
+    private readonly cleanupInterval;
+    /** 判定是否放行（纯逻辑，便于单测）。 */
+    allow(clientKey: string): Promise<boolean>;
+    /** 清理超过 5 分钟未使用的桶。 */
+    private cleanup;
+    constructor(requestsPerMinute: number);
+}
+/**
+ * 取客户端标识：API Key 优先，否则回退到 IP。
+ *
+ * 与服务端反向代理的配合：Fastify 默认不信任 `X-Forwarded-For`，
+ * 需要时在 `app.ts` 里设置 `trustProxy`，届时 `request.ip` 会自动取真实 IP。
+ */
+export declare function clientKeyOf(request: FastifyRequest): string;
+/** 构造 Fastify `onRequest` 钩子。 */
+export declare function makeRateLimitHook(options: RateLimitOptions): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/server/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAU5D,WAAW;AACX,qBAAa,WAAW;IAMpB,kBAAkB;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,WAAW;IACX,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO,CAAC,QAAQ,CAAS;IAEzB;IACE,kBAAkB;IACD,IAAI,EAAE,MAAM;IAC7B,WAAW;IACM,QAAQ,EAAE,MAAM,EACjC,GAAG,GAAE,MAAM,MAAoB,EAIhC;IAED,kBAAkB;IAClB,OAAO,CAAC,GAAG,GAAE,MAAM,MAAoB,GAAG,OAAO,CAUhD;IAED,sBAAsB;IACtB,IAAI,QAAQ,IAAI,MAAM,CAErB;CACF;AAED,cAAc;AACd,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC;AAID,mCAAmC;AACnC,qBAAa,WAAW;IA2CV,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IA1C9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IAEpC,OAAO,CAAC,WAAW,CAAiB;IAEpC,eAAe;IACf,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAO;IAEvC,wBAAwB;IAClB,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa/C;IAED,sBAAsB;IACtB,OAAO,CAAC,OAAO;IAgBf,YAA6B,iBAAiB,EAAE,MAAM,EAAI;CAC3D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAU3D;AAED,iCAAiC;AACjC,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,gBAAgB,GACxB,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CA4BjE"}