feat: 添加浏览器指纹黑名单功能 (#757)

* feat: 添加浏览器指纹黑名单功能

- 前端集成 @fingerprintjs/fingerprintjs 库自动采集浏览器指纹
- 在所有 API 请求中通过 x-fingerprint header 传递指纹信息
- 将指纹黑名单集成到现有的 IP 黑名单功能中
- 支持精确匹配和正则表达式模式匹配指纹
- 在 App.vue mount 时预初始化指纹，避免首次请求延迟
- 使用 Vue 全局状态缓存指纹，避免重复生成
- 管理后台新增指纹黑名单配置，与 IP/ASN 黑名单统一管理
- 后端在限流 API 请求前检查指纹黑名单，返回 403 阻止访问

技术细节：
- 指纹生成时间：50-300ms（一次性）
- 缓存命中：<1ms
- 请求开销：~20 字节/请求
- 支持最多 1000 条指纹黑名单规则
- 完善的错误处理，失败时不阻塞正常请求

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: 优化浏览器指纹初始化逻辑

- 移除 App.vue 中的预初始化，改为在首次 API 调用时自动初始化
- 移除不必要的 clearFingerprintCache 函数
- 初始化失败时返回特殊值 'ERROR' 而非空字符串
- 失败值会被缓存，避免重复尝试失败

优势：
- 减少页面加载时的初始化开销
- 简化代码，去除不必要的函数
- 更清晰的错误标识

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

frontend/package.json

@@ -20,6 +20,7 @@
     "deploy:actions": "npm run build && wrangler pages deploy ./dist"
   },
   "dependencies": {
+    "@fingerprintjs/fingerprintjs": "^5.0.1",
     "@simplewebauthn/browser": "10.0.0",
     "@unhead/vue": "^1.11.20",
     "@vueuse/core": "^12.8.2",

frontend/pnpm-lock.yaml

@@ -8,6 +8,9 @@ importers:
 
   .:
     dependencies:
+      '@fingerprintjs/fingerprintjs':
+        specifier: ^5.0.1
+        version: 5.0.1
       '@simplewebauthn/browser':
         specifier: 10.0.0
         version: 10.0.0
@@ -963,6 +966,9 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@fingerprintjs/fingerprintjs@5.0.1':
+    resolution: {integrity: sha512-KbaeE/rk2WL8MfpRP6jTI4lSr42SJPjvkyrjP3QU6uUDkOMWWYC2Ts1sNSYcegHC8avzOoYTHBj+2fTqvZWQBA==}
+
   '@img/sharp-darwin-arm64@0.33.5':
     resolution: {integrity: sha512-UT4p+iz/2H4twwAoLCqfA9UH5pI6DggwKEGuaPy7nCVQ8ZsiY5PIcrRvD1DzuY3qYL07NtIQcWnBSY/heikIFQ==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
@@ -3955,6 +3961,8 @@ snapshots:
   '@esbuild/win32-x64@0.25.4':
     optional: true
 
+  '@fingerprintjs/fingerprintjs@5.0.1': {}
+
   '@img/sharp-darwin-arm64@0.33.5':
     optionalDependencies:
       '@img/sharp-libvips-darwin-arm64': 1.0.4

frontend/src/App.vue

@@ -23,7 +23,6 @@ const showAd = computed(() => !isMobile.value && adClient && adSlot);
 const gridMaxCols = computed(() => showAd.value ? 8 : 12);
 
 onMounted(async () => {
-
   try {
     await api.getUserSettings();
   } catch (error) {

frontend/src/api/index.js

@@ -3,6 +3,7 @@ import { h } from 'vue'
 import axios from 'axios'
 
 import i18n from '../i18n'
+import { getFingerprint } from '../utils/fingerprint'
 
 const API_BASE = import.meta.env.VITE_API_BASE || "";
 const {
@@ -20,6 +21,9 @@ const instance = axios.create({
 const apiFetch = async (path, options = {}) => {
     loading.value = true;
     try {
+        // Get browser fingerprint for request tracking
+        const fingerprint = await getFingerprint();
+
         const response = await instance.request(path, {
             method: options.method || 'GET',
             data: options.body || null,
@@ -29,6 +33,7 @@ const apiFetch = async (path, options = {}) => {
                 'x-user-access-token': userSettings.value.access_token,
                 'x-custom-auth': auth.value,
                 'x-admin-auth': adminAuth.value,
+                'x-fingerprint': fingerprint,
                 'Authorization': `Bearer ${jwt.value}`,
                 'Content-Type': 'application/json',
             },

frontend/src/store/index.js

@@ -111,6 +111,7 @@ export const useGlobalState = createGlobalState(
         const isTelegram = ref(!!window.Telegram?.WebApp?.initData);
         const userOauth2SessionState = useSessionStorage('userOauth2SessionState', '');
         const userOauth2SessionClientID = useSessionStorage('userOauth2SessionClientID', '');
+        const browserFingerprint = ref('');
         return {
             isDark,
             toggleDark,
@@ -148,6 +149,7 @@ export const useGlobalState = createGlobalState(
             userOauth2SessionClientID,
             useSimpleIndex,
             addressPassword,
+            browserFingerprint,
         }
     },
 )

frontend/src/utils/fingerprint.ts

@@ -0,0 +1,30 @@
+import FingerprintJS from '@fingerprintjs/fingerprintjs';
+import { useGlobalState } from '../store';
+
+const { browserFingerprint } = useGlobalState();
+
+/**
+ * Get browser fingerprint
+ * Uses cached value from global state if available to avoid unnecessary computation
+ * @returns Fingerprint visitor ID, or 'ERROR' if failed
+ */
+export const getFingerprint = async (): Promise<string> => {
+    // Return cached fingerprint if available
+    if (browserFingerprint.value) {
+        return browserFingerprint.value;
+    }
+
+    try {
+        const fp = await FingerprintJS.load();
+        const result = await fp.get();
+        browserFingerprint.value = result.visitorId;
+        return browserFingerprint.value;
+    } catch (error) {
+        console.error('Failed to get fingerprint:', error);
+        // Return special error value to prevent blocking requests
+        const errorValue = 'ERROR';
+        browserFingerprint.value = errorValue;
+        return errorValue;
+    }
+};
+

frontend/src/views/admin/IpBlacklistSettings.vue

@@ -12,7 +12,6 @@ const { t } = useI18n({
     messages: {
         en: {
             title: 'IP Blacklist Settings',
-            tip: 'Block specific IPs from accessing rate-limited APIs. Supports text matching (e.g., "192.168.1") or regex (e.g., "^10\\.0\\.0\\.5$").',
             manualInputPrompt: 'Type pattern and press Enter to add',
             save: 'Save',
             successTip: 'Save Success',
@@ -22,11 +21,14 @@ const { t } = useI18n({
             ip_blacklist_placeholder: 'Enter pattern (e.g., 192.168.1 or ^10\\.0\\.0\\.5$)',
             asn_blacklist: 'ASN Organization Blacklist',
             asn_blacklist_placeholder: 'Enter ASN organization (e.g., Google, Amazon)',
-            asn_tip: 'Block by ASN organization (ISP/provider). Case-insensitive text matching or regex.',
+            fingerprint_blacklist: 'Browser Fingerprint Blacklist',
+            fingerprint_blacklist_placeholder: 'Enter fingerprint ID (e.g., a1b2c3d4e5f6g7h8)',
+            tip_ip: 'IP Blacklist: Supports text matching (e.g., "192.168.1") or regex (e.g., "^10\\.0\\.0\\.5$").',
+            tip_asn: 'ASN Organization: Block by ISP/provider. Case-insensitive text matching or regex.',
+            tip_fingerprint: 'Browser Fingerprint: Block by browser fingerprint. Supports exact matching or regex patterns.',
         },
         zh: {
             title: 'IP 黑名单设置',
-            tip: '阻止特定 IP 访问限流 API。支持文本匹配（如 "192.168.1"）或正则表达式（如 "^10\\.0\\.0\\.5$"）。',
             manualInputPrompt: '输入匹配模式后按回车键添加',
             save: '保存',
             successTip: '保存成功',
@@ -36,7 +38,11 @@ const { t } = useI18n({
             ip_blacklist_placeholder: '输入匹配模式（例如：192.168.1 或 ^10\\.0\\.0\\.5$）',
             asn_blacklist: 'ASN 组织（运营商）黑名单',
             asn_blacklist_placeholder: '输入 ASN 组织名称（例如：Google, Amazon）',
-            asn_tip: '根据 ASN 组织（运营商/ISP）拉黑。支持不区分大小写的文本匹配或正则表达式。',
+            fingerprint_blacklist: '浏览器指纹黑名单',
+            fingerprint_blacklist_placeholder: '输入指纹 ID（例如：a1b2c3d4e5f6g7h8）',
+            tip_ip: 'IP 黑名单：支持文本匹配（如 "192.168.1"）或正则表达式（如 "^10\\.0\\.0\\.5$"）。',
+            tip_asn: 'ASN 组织：根据运营商/ISP 拉黑。支持不区分大小写的文本匹配或正则表达式。',
+            tip_fingerprint: '浏览器指纹：根据浏览器指纹拉黑。支持完全匹配或正则表达式。',
         }
     }
 });
@@ -44,6 +50,7 @@ const { t } = useI18n({
 const enabled = ref(false)
 const ipBlacklist = ref([])
 const asnBlacklist = ref([])
+const fingerprintBlacklist = ref([])
 
 const fetchData = async () => {
     try {
@@ -52,6 +59,7 @@ const fetchData = async () => {
         enabled.value = res.enabled || false
         ipBlacklist.value = res.blacklist || []
         asnBlacklist.value = res.asnBlacklist || []
+        fingerprintBlacklist.value = res.fingerprintBlacklist || []
     } catch (error) {
         message.error(error.message || "error");
     } finally {
@@ -68,6 +76,7 @@ const save = async () => {
                 enabled: enabled.value,
                 blacklist: ipBlacklist.value || [],
                 asnBlacklist: asnBlacklist.value || [],
+                fingerprintBlacklist: fingerprintBlacklist.value || [],
             })
         })
         message.success(t('successTip'))
@@ -94,7 +103,11 @@ onMounted(async () => {
 
             <n-space vertical :size="20">
                 <n-alert :show-icon="false" :bordered="false" type="info">
-                    <span>{{ t("tip") }}</span>
+                    <div style="line-height: 1.8;">
+                        <div>• {{ t("tip_ip") }}</div>
+                        <div>• {{ t("tip_asn") }}</div>
+                        <div>• {{ t("tip_fingerprint") }}</div>
+                    </div>
                 </n-alert>
 
                 <n-form-item-row :label="t('enable_ip_blacklist')">
@@ -136,11 +149,21 @@ onMounted(async () => {
                     </n-select>
                 </n-form-item-row>
 
-                <n-alert :show-icon="false" :bordered="false" type="default">
+                <n-form-item-row :label="t('fingerprint_blacklist')">
-                    <n-text depth="3" style="font-size: 12px;">
+                    <n-select
-                        {{ t('asn_tip') }}
+                        v-model:value="fingerprintBlacklist"
-                    </n-text>
+                        filterable
-                </n-alert>
+                        multiple
+                        tag
+                        :placeholder="t('fingerprint_blacklist_placeholder')"
+                        :disabled="!enabled">
+                        <template #empty>
+                            <n-text depth="3">
+                                {{ t('manualInputPrompt') }}
+                            </n-text>
+                        </template>
+                    </n-select>
+                </n-form-item-row>
             </n-space>
         </n-card>
     </div>

worker/src/admin_api/ip_blacklist_settings.ts

@@ -15,7 +15,8 @@ async function getIpBlacklistSettings(c: Context<HonoCustomType>): Promise<Respo
     return c.json(settings || {
         enabled: false,
         blacklist: [],
-        asnBlacklist: []
+        asnBlacklist: [],
+        fingerprintBlacklist: []
     });
 }
 
@@ -68,10 +69,30 @@ async function saveIpBlacklistSettings(c: Context<HonoCustomType>): Promise<Resp
             .filter(pattern => pattern.length > 0);
     }
 
+    // Validate and sanitize fingerprint blacklist if provided
+    let sanitizedFingerprintBlacklist: string[] = [];
+    if (settings.fingerprintBlacklist) {
+        if (!Array.isArray(settings.fingerprintBlacklist)) {
+            return c.text("Invalid fingerprintBlacklist value", 400);
+        }
+
+        if (settings.fingerprintBlacklist.length > MAX_BLACKLIST_SIZE) {
+            return c.text(
+                `Fingerprint blacklist exceeds maximum size (${MAX_BLACKLIST_SIZE} entries)`,
+                400
+            );
+        }
+
+        sanitizedFingerprintBlacklist = settings.fingerprintBlacklist
+            .map(pattern => pattern.trim())
+            .filter(pattern => pattern.length > 0);
+    }
+
     const sanitizedSettings: IpBlacklistSettings = {
         enabled: settings.enabled,
         blacklist: sanitizedBlacklist,
-        asnBlacklist: sanitizedAsnBlacklist
+        asnBlacklist: sanitizedAsnBlacklist,
+        fingerprintBlacklist: sanitizedFingerprintBlacklist
     };
 
     await saveSetting(

worker/src/ip_blacklist.ts

@@ -9,6 +9,7 @@ export type IpBlacklistSettings = {
     enabled: boolean;
     blacklist: string[];  // Array of regex patterns or plain strings
     asnBlacklist?: string[];  // Array of ASN organization patterns (e.g., "Google LLC", "Amazon")
+    fingerprintBlacklist?: string[];  // Array of browser fingerprint patterns
 }
 
 /**
@@ -94,7 +95,8 @@ export async function getIpBlacklistSettings(
         return {
             enabled: dbSettings.enabled || false,
             blacklist: dbSettings.blacklist || [],
-            asnBlacklist: dbSettings.asnBlacklist || []
+            asnBlacklist: dbSettings.asnBlacklist || [],
+            fingerprintBlacklist: dbSettings.fingerprintBlacklist || []
         };
     }
 
@@ -102,7 +104,8 @@ export async function getIpBlacklistSettings(
     return {
         enabled: false,
         blacklist: [],
-        asnBlacklist: []
+        asnBlacklist: [],
+        fingerprintBlacklist: []
     };
 }
 
@@ -149,6 +152,16 @@ export async function checkIpBlacklist(
             }
         }
 
+        // Check browser fingerprint blacklist
+        if (settings.fingerprintBlacklist && settings.fingerprintBlacklist.length > 0) {
+            const fingerprint = c.req.raw.headers.get("x-fingerprint");
+            // Check fingerprint with case-sensitive matching
+            if (fingerprint && isBlacklisted(fingerprint, settings.fingerprintBlacklist, true)) {
+                console.warn(`Blocked blacklisted fingerprint: ${fingerprint} (IP: ${reqIp}) for path: ${c.req.path}`);
+                return c.text(`Access denied: Browser fingerprint is blacklisted`, 403);
+            }
+        }
+
         return null;
     } catch (error) {
         // Log error but don't block request