一、为什么现有检测容易被绕过

FinalSuspect 的检测失败链路如下：

检测逻辑在 IL 层
    ↓
dnSpy 可以直接反编译看到
    ↓
直接把方法体改成 ret
    ↓
检测逻辑永远不执行

根本问题是检测代码和被检测的环境在同一个进程、同一个信任层里。任何在托管代码里写的检测，理论上都可以被同样在托管层运行的代码绕过。下面从弱到强介绍五个加固层级。

二、层级 1：混淆 + 字符串加密

FinalSuspect 已经用了 XOR 加密字符串，但逻辑本身没有混淆，反编译后整体结构一目了然。更进一步的做法是用 ConfuserEx 或 Obfuscar 在编译后对 DLL 做整体混淆。

<project>
  <rule pattern="true">

    <protection id="ctrl flow" />

    <protection id="constants" />

    <protection id="ref proxy" />

    <protection id="anti tamper" />

    <protection id="anti debug" />
  </rule>
</project>

**局限：**混淆只是提高反编译成本，不能从根本上阻止修改。有经验的人依然可以动态调试绕过。

三、层级 2：完整性自校验（Anti-Tamper）

让 DLL 在运行时校验自身的 IL hash。如果有人修改了某个方法的指令，hash 就对不上，直接退出。

internal static class IntegrityChecker
{
    // 编译时预先计算好关键方法的 hash，硬编码进来
    // 注意：这些 hash 本身也要混淆存储，不能明文
    private static readonly Dictionary<string, byte[]> _expectedHashes = new()
    {
        // MethodToken → 预期的 IL bytes 的 SHA256
        { "DllChecker.OnInitialization", new byte[] { 0x3A, 0xF1, ... } },
        { "Git.Prefix",                  new byte[] { 0x7C, 0x2B, ... } },
    };

    internal static void Verify()
    {
        var asm = Assembly.GetExecutingAssembly();

        foreach (var type in asm.GetTypes())
        {
            foreach (var method in type.GetMethods(
                BindingFlags.Public | BindingFlags.NonPublic |
                BindingFlags.Static | BindingFlags.Instance))
            {
                string key = $"{type.Name}.{method.Name}";
                if (!_expectedHashes.TryGetValue(key, out byte[] expected))
                    continue;

                // 读取运行时实际的 IL bytes
                var body = method.GetMethodBody();
                if (body == null) { Quit(); return; }

                byte[] actual = SHA256.HashData(body.GetILAsByteArray());

                if (!actual.SequenceEqual(expected))
                {
                    // IL 被篡改，静默退出（不报错，防止攻击者定位触发点）
                    Quit();
                    return;
                }
            }
        }
    }

    private static void Quit()
    {
        // 故意延迟几秒再退出，让攻击者难以定位触发点
        Thread.Sleep(new Random().Next(2000, 8000));
        Application.Quit(1);
    }
}

关键点：

• Verify() 要在多个时机调用（启动时、进入游戏时、每隔一段时间），不能只在一处
• hash 值本身要混淆存储，否则攻击者直接改 hash 就绕过了
• 退出前故意加随机延迟，防止攻击者通过"哪里卡了"来定位检测代码

四、层级 3：把检测逻辑移到原生层

这是最关键的跨越。托管代码（C#）可以被 dnSpy 修改；原生代码（C++ DLL）需要 x64dbg + IDA，门槛高出一个数量级。

做法是写一个原生 DLL（C++），负责执行真正的检测逻辑，C# 只负责调用：

// NativeGuard.cpp（编译成 NativeGuard.dll）
#include <windows.h>
#include <tlhelp32.h>

// 扫描插件目录，发现白名单外的 DLL 返回 -1
extern "C" __declspec(dllexport)
int __stdcall ScanPluginDirectory(const wchar_t* pluginDir,
                                   const wchar_t** whitelist,
                                   int whitelistCount)
{
    WIN32_FIND_DATAW findData;
    wchar_t pattern[MAX_PATH];
    swprintf_s(pattern, L"%s\\*.dll", pluginDir);

    HANDLE hFind = FindFirstFileW(pattern, &findData);
    if (hFind == INVALID_HANDLE_VALUE) return 0;

    int count = 0;
    do {
        bool allowed = false;
        for (int i = 0; i < whitelistCount; i++) {
            if (wcscmp(findData.cFileName, whitelist[i]) == 0) {
                allowed = true;
                break;
            }
        }
        if (!allowed) {
            FindClose(hFind);
            return -1; // 发现非法 DLL
        }
        count++;
    } while (FindNextFileW(hFind, &findData));

    FindClose(hFind);
    return count;
}

// 检测已知调试器进程
extern "C" __declspec(dllexport)
bool __stdcall IsDebuggerRunning()
{
    // 方法 1：Windows API
    if (IsDebuggerPresent()) return true;

    // 方法 2：检查调试器进程名
    const wchar_t* debuggers[] = {
        L"dnSpy.exe", L"x64dbg.exe", L"cheatengine-x86_64.exe",
        L"ida64.exe", L"OllyDbg.exe", L"ProcessHacker.exe"
    };

    HANDLE snap = CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0);
    if (snap == INVALID_HANDLE_VALUE) return false;

    PROCESSENTRY32W pe = { sizeof(pe) };
    if (Process32FirstW(snap, &pe)) {
        do {
            for (auto& dbg : debuggers) {
                if (_wcsicmp(pe.szExeFile, dbg) == 0) {
                    CloseHandle(snap);
                    return true;
                }
            }
        } while (Process32NextW(snap, &pe));
    }
    CloseHandle(snap);
    return false;
}

在 C# 中调用：

internal static class NativeGuard
{
    [DllImport("NativeGuard.dll", CharSet = CharSet.Unicode)]
    private static extern int ScanPluginDirectory(
        string pluginDir,
        string[] whitelist,
        int whitelistCount);

    [DllImport("NativeGuard.dll")]
    private static extern bool IsDebuggerRunning();

    internal static void Check()
    {
        // 调试器检测
        if (IsDebuggerRunning())
        {
            SilentQuit();
            return;
        }

        // 插件目录扫描
        string pluginDir = Path.GetDirectoryName(
            Assembly.GetExecutingAssembly().Location)!;

        string[] whitelist = { "FinalSuspect.dll", "PolarNight.dll" };

        int result = ScanPluginDirectory(pluginDir, whitelist, whitelist.Length);
        if (result == -1)
        {
            SilentQuit();
        }
    }

    private static void SilentQuit()
    {
        Thread.Sleep(new Random().Next(3000, 10000));
        Application.Quit(1);
    }
}

**为什么有效：**攻击者要绕过这个，必须先找到原生 DLL（名字可以随便起，混在游戏 DLL 里），再用 x64dbg 动态调试原生层，最后找到具体函数并 patch。这个门槛比改 IL 高出一个数量级。

五、层级 4：分散检测时机 + 蜜罐

不要把检测集中在一个地方，分散到各个角落，让攻击者找不全：

// 在多个不相关的 Patch 里随机触发检测
[HarmonyPatch(typeof(HudManager), nameof(HudManager.Update))]
internal static class HudUpdatePatch
{
    private static int _frameCount = 0;

    public static void Postfix()
    {
        _frameCount++;
        // 每隔随机帧数触发一次检测，不规律、难预测
        if (_frameCount % (UnityEngine.Random.Range(800, 1200)) == 0)
        {
            IntegrityChecker.Verify();
            NativeGuard.Check();
        }
    }
}

[HarmonyPatch(typeof(AmongUsClient), nameof(AmongUsClient.OnGameJoined))]
internal static class JoinGamePatch
{
    public static void Prefix()
    {
        // 进游戏时也检测一次
        NativeGuard.Check();
    }
}

[HarmonyPatch(typeof(MeetingHud), nameof(MeetingHud.Start))]
internal static class MeetingStartPatch
{
    public static void Prefix()
    {
        // 每次开会议时也检测
        IntegrityChecker.Verify();
    }
}

配合蜜罐使用——故意留一个看起来像检测方法的"假靶子"，让攻击者优先清空它，真正的检测在别处：

// 这个方法什么都不做，就是个蜜罐
// 攻击者反编译后会优先清空"看起来最危险"的方法
internal static class FakeChecker
{
    public static void CheckPlugins() { }   // 空的，故意的
    public static void ScanDirectory() { }  // 空的，故意的
}

六、层级 5：服务端验证（最终形态）

如果你的模组有联网功能，可以把合规性验证放到服务端。检测逻辑不在客户端，本地改再多也没用：

客户端启动
    ↓
发送签名请求到服务器
（请求里包含插件目录的 hash 列表）
    ↓
服务器验证 hash 是否合规
    ↓
返回一次性 Token
    ↓
客户端没有 Token → 无法使用联网功能

internal static class ServerValidator
{
    private const string ValidateEndpoint = "https://your-server.com/api/validate";

    internal static async Task<bool> ValidateAsync()
    {
        string pluginDir = Path.GetDirectoryName(
            Assembly.GetExecutingAssembly().Location)!;

        // 计算插件目录所有 DLL 的 hash 列表
        var hashes = Directory
            .EnumerateFiles(pluginDir, "*.dll")
            .Select(f => new
            {
                name = Path.GetFileName(f),
                hash = Convert.ToHexString(
                    SHA256.HashData(File.ReadAllBytes(f)))
            });

        // 发送给服务端验证
        using var client = new HttpClient();
        var response = await client.PostAsJsonAsync(ValidateEndpoint, hashes);

        if (!response.IsSuccessStatusCode) return false;

        // 服务端返回一次性 Token，后续联网功能需要带上
        string token = await response.Content.ReadAsStringAsync();
        SessionToken.Set(token);
        return true;
    }
}

**代价：**需要维护一个服务器，且离线玩家无法使用联网功能。适合竞技或排行榜类场景。

七、各层级对比与选型建议

按需求选型：

• **提高普通用户绕过成本：**层级 1 + 层级 2
• **对抗有经验的逆向者：**层级 3 + 层级 4
• **竞技 / 排名场景：**层级 5

八、核心原则

没有 100% 防破解的方案，目标是让破解成本高于收益。

FinalSuspect 失败的原因不是技术不好，而是所有鸡蛋放在一个篮子里——找到检测代码在哪儿，一次性清空就结束了。真正有效的防护是多层、分散、跨信任层的组合。攻击者面对的不是"找到一个开关关掉"，而是"拆解整个防御体系的每一层"，破解成本自然就上去了。

**声明：**本文仅用于技术研究与个人学习。FinalSuspect 是开源项目，修改后仅供自己使用；共存后产生的模组兼容性问题需自行承担。

一、检测机制总览

通过 dnSpy 反编译，FinalSuspect 把"反其他模组"逻辑归进了 FinalAntiCheat（把装其他模组视为作弊行为）。一共有三处，采用"双保险 + 暗桩"设计：

1. DisableOtherPlugins：Harmony 补丁拦截插件加载
2. DllChecker：启动时扫描文件并强制退出
3. Git（伪装类）：进入主菜单后二次检测，字符串经过加密隐藏

二、第一重：DisableOtherPlugins —— 拦截加载

它给 BepInEx 的 IL2CPPChainloader.LoadPlugin 打了一个 Harmony 前置补丁。Prefix 返回 false 会跳过原方法，也就是阻止该插件被加载。逻辑上只放行 UnityExplorer，其余插件一律拦截：

[HarmonyPatch(typeof(IL2CPPChainloader), "LoadPlugin")]
public static class DisableOtherPlugins
{
    public static bool Prefix(
        [HarmonyArgument(0)] PluginInfo pluginInfo,
        [HarmonyArgument(1)] Assembly pluginAssembly)
    {
        // 仅当插件是 UnityExplorer 时返回 true（放行）
        // 其他所有插件返回 false → 跳过原方法 → 不加载
        return pluginInfo.Metadata.GUID == "com.sinai.unityexplorer";
    }
}

**解除方法：**让 Prefix 永远返回 true，放行所有插件。在 dnSpy 里编辑 IL，把方法体替换为两条指令：

ldc.i4.1   // 压入 true
ret        // 返回

三、第二重：DllChecker —— 扫描目录并闪退

这是闪退的直接来源。它在启动时扫描插件目录，只要发现 FinalSuspect.dll 和 PolarNight.dll 以外的任何文件，就调用 Application.Quit(1) 强制退出；另外还检查游戏根目录是否存在外挂文件（这部分属于正常反作弊）。

public static class DllChecker
{
    [PluginModuleInitializer(InitializePriority.High)]
    internal static void OnInitialization()
    {
        string[] blacklist = { "SickoMenu.dll", "version.dll" };
        string pluginDir = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
        string gameDir = Environment.CurrentDirectory;

        // ① 扫描 plugins 目录：白名单之外一律闪退
        if (pluginDir != null)
        {
            foreach (string file in Directory.EnumerateFiles(pluginDir, "*.*"))
            {
                string fileName = Path.GetFileName(file);
                bool isWhitelisted = fileName == "FinalSuspect.dll"
                                  || fileName == "PolarNight.dll";
                if (!isWhitelisted)
                {
                    FinalLogger.Error("检测到非法/模组文件: " + fileName + "！游戏将被强制终止。");
                    Application.Quit(1);   // ← 闪退元凶
                }
            }
        }

        // ② 检查游戏根目录的外挂文件（反作弊，建议保留）
        foreach (string dll in blacklist)
        {
            if (File.Exists(Path.Combine(gameDir, dll)))
            {
                FinalLogger.Error("检测到非法文件: " + dll + "！游戏将被强制终止。");
                Application.Quit(1);
            }
        }
    }
}

**解除方法：**在 dnSpy 里把 OnInitialization 的 IL 指令全部删除，只保留一条 ret。由于原方法含 foreach 循环，会生成 try/finally 异常处理块，必须同时在"异常处理程序"选项卡里删除所有条目，否则方法体无效、无法保存。

// 清空方法体，只保留：
ret

// 并清空"异常处理程序"选项卡中的所有条目

四、第三重：伪装的 Git 类 —— 加密暗桩

这是最隐蔽的一处。作者把同样的检测逻辑复制了一份，藏在一个名为 Git 的类里（起这个名字是为了迷惑查找者），并把所有敏感字符串用 XOR 加密隐藏。它作为 MainMenuManager.Start 的 Harmony 补丁，在进入主菜单后触发。

[HarmonyPatch(typeof(MainMenuManager), "Start")]
internal static class Git
{
    // XOR 解密：字符串常量都用密钥异或隐藏，防止被直接搜索到
    private static string Decrypt(byte[] data, byte key)
    {
        byte[] result = new byte[data.Length];
        for (int i = 0; i < data.Length; i++)
            result[i] = (byte)(data[i] ^ key);
        return Encoding.UTF8.GetString(result);
    }

    public static void Prefix(MainMenuManager __instance)
    {
        string[] rootBlacklist = { Git.A, Git.B };   // 解密后 = SickoMenu.dll / version.dll
        string pluginDir = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
        string gameDir = Environment.CurrentDirectory;

        // ① 与 DllChecker 相同的 plugins 目录白名单检测（这里是杀模组的关键）
        if (pluginDir != null)
        {
            foreach (string file in Directory.EnumerateFiles(pluginDir, "*.*"))
            {
                string fileName = Path.GetFileName(file);
                // Git.C / Git.D 解密后 = FinalSuspect.dll / PolarNight.dll
                if (fileName != Git.C && fileName != Git.D)
                {
                    FinalLogger.Error(Git.G, Git.J);   // "检测到非法/模组文件..."
                    Application.Quit(1);
                }
            }
        }

        // ② 检测外挂进程、外挂窗口，并挂一个每分钟一次的定时器（反作弊部分）
        if (Process.GetProcessesByName(Git.E).Length != 0) Application.Quit(1);
        if (FindWindow(null, Git.F) != IntPtr.Zero)        Application.Quit(1);
        // ...省略定时器逻辑
    }
}

加密字符串用密钥 85（0x55）异或后可还原为：

**解除方法：**同样把 Git.Prefix 的 IL 清空为一条 ret，并清空异常处理程序选项卡。注意此处会连带移除反外挂检测——不开挂即无影响。

五、修改后的连锁问题

解除检测后，模组虽能共存，但会暴露两个隐藏问题，需要一并处理：

1. 缺少 YamlDotNet 依赖导致无限卡加载

FinalSuspect 加载语言文件时依赖 YamlDotNet.dll。若使用自己搭建的 BepInEx 环境而非官方完整包，会因缺少依赖抛出异常、加载协程中断，表现为卡在加载界面。

FileNotFoundException: Could not load file or assembly 'YamlDotNet, Version=16.0.0.0'
   at FinalSuspect.Modules.Core.Plugin.Translator.LoadLangs()
   at FinalSuspect.Patches.System.LoadPatch.LoadEssentialResources(...)

**解决：**从官方完整发布包中提取以下 DLL，放入 BepInEx/core/：

YamlDotNet.dll        （必需，缺失会卡加载）
NAudio.dll
NAudio.Core.dll
NAudio.Wasapi.dll
NAudio.WinMM.dll
NAudio.Flac.dll
NAudio.Asio.dll       （音乐功能所需）

2. 更新检查卡死 / 未响应

进入主菜单时，VersionChecker 会连接更新源检查新版本，而这些源大多失效，导致主线程阻塞、游戏未响应。好在作者内置了离线模式开关，无需改 DLL，只需改配置文件。

// 触发更新检查的判断逻辑
bool flag = VersionChecker.FirstStart && !ConfigManager.OfflineMode.Value;
if (flag)
{
    VersionChecker.StartTasks();   // ← 联网检查更新，卡死源头
}

**解决：**编辑 BepInEx/config/cn.slok.finalsuspect.cfg（需在游戏关闭状态下修改）：

Offline Mode = true               # 跳过启动时的更新检查
Language Update Bypass = LongTerm # 长期跳过语言文件更新检查

六、操作步骤总结

1. 用 dnSpy 打开 FinalSuspect.dll，先备份原文件
2. 修改 DisableOtherPlugins.Prefix → ldc.i4.1 + ret
3. 清空 DllChecker.OnInitialization → 仅留 ret，并清空异常处理程序
4. 清空伪装类 Git.Prefix → 仅留 ret，并清空异常处理程序
5. 保存模块，覆盖回 BepInEx/plugins/
6. 补齐 BepInEx/core/ 下的 YamlDotNet 与 NAudio 依赖
7. 在配置文件中开启离线模式与语言更新绕过

七、注意事项

• 务必备份修改后的 DLL。模组自动更新或重装会覆盖修改，导致限制恢复。
• 切勿点击游戏内的更新按钮，否则修改会被覆盖。
• FinalSuspect 的反作弊与玩法类模组（如 TOHE）可能 Hook 同一批游戏方法，共存后如出现异常应优先怀疑模组冲突。
• 本文所述技术仅供个人研究，请遵守相关服务条款与社区规则。

这是通过博客后台写的第一篇文章。

• 支持 Markdown
• 支持 代码
• 写完点右上角「发布」即可上线

[!NOTE] 提示 本文按"准备阶段 → 检索阶段 → 范式升级"的顺序整理 10 种 RAG（Retrieval-Augmented Generation，检索增强生成）策略，覆盖分块、嵌入、索引、查询处理、混合检索、重排序与 Agentic RAG。每种策略统一按"问题 / 做法 / 原理 / 收益 / 局限 / 代价 / 结论"划分段落（按需取用），有论文来源的标注出处。

一、引子：RAG 死了吗

大模型回答不了个人笔记、企业内部资料相关的问题，这些内容不在训练数据里，接入外部知识是刚需。RAG 的做法是先检索相关片段，再交给模型生成回答。

2024 年以来，百万 token 级上下文窗口的模型逐步普及，"把资料全塞进上下文，RAG 已死"的说法随之出现。这个判断在三个约束下站不住：

1. 成本。 输入 token 按量计费。10 万 token 的文档全量输入与 2000 token 的相关片段相比，单次请求的输入成本差 50 倍；每次提问都携带整个文档库时，倍数随库规模继续放大。检索方案的成本只取决于本次召回多少片段，与文档库总量无关。提示缓存（prompt caching）能摊薄重复前缀的开销，但只在文档集固定、复用率高时生效，对每次命中不同片段的场景无效。

2. 延迟。 输入越长，prefill 阶段的计算量越大，模型开始输出越慢，首 token 延迟（TTFT）随之上涨，交互式问答对这一延迟敏感。

3. 准确性。 长上下文不是无损容器。Liu et al. 的《Lost in the Middle》（TACL 2024）实验显示：关键信息位于上下文开头或结尾时模型表现最好，位于中部时准确率明显下降，曲线呈 U 形。塞入的资料越多，关键信息落在中部被淹没的概率越大。

结论：在成本、延迟、准确性的约束下，只检索必要内容仍然优于全部塞进上下文。长上下文抬高的是 RAG 的容错下限（召回不够精准时还有兜底空间），不取消 RAG 本身。问题只剩怎么做好。

二、RAG 总体流程

RAG 分两大阶段：准备阶段离线执行（建库时一次，或随文档更新执行），检索阶段在每次提问时执行。十种策略在流程上的落位：

flowchart TB
    subgraph offline ["准备阶段（离线）"]
        A["Chunking 分块<br/>策略 1 语义分块 · 策略 2 命题分块<br/>增强：上下文增强分块"]
        B["Embedding 向量化<br/>策略 3 领域特化 Embedding"]
        C["Indexing 入库<br/>策略 4 元数据索引 · 策略 5 Graph RAG"]
        A --> B --> C
    end
    subgraph online ["检索阶段（在线）"]
        D["Query Processing 查询处理<br/>策略 6 查询改写 · 策略 7 假设文档检索"]
        E["Retrieval 检索<br/>策略 8 混合检索"]
        F["Re-rank 重排序<br/>策略 9 重排序"]
        D --> E --> F
    end
    C -.-> D
    F --> G["拼接上下文，交给 LLM 生成回答"]
    AG["策略 10 Agentic RAG：循环替代单次 pipeline"] -. 升级 .-> online

各策略解决的问题：

自适应路由（Adaptive Routing）是调度层，负责在上述策略间动态分流，不计入十种。固定长度分块、通用 Embedding、纯向量检索是各环节的基线选项，作为对照在下文一并说明。

三、准备阶段：策略 1-5

策略 1：语义分块（Semantic Chunking）

问题：基线是固定长度切分，每 N 个 token 切一刀，配一段 overlap（常见取值为 chunk 512-1024 token、overlap 10%-20%）。实现简单，但切口落在句子中间时会产生碎块，半句话既难以被 embedding 准确表达，也难以被 LLM 利用。

做法：逐句向量化，相邻句子相似度高于阈值则合并进同一块，低于阈值则在句间断开。阈值一般不写死，而是按分布取：相似度落差排在最末 5% 的位置断开（百分位法），或用标准差倍数、四分位距，避免固定阈值在文档长度与题材差异下失效。判定时通常还会把前后各 1-2 句纳入缓冲窗口，降低单句噪声的影响。

局限：一是分块依据只有向量相似度，两句向量距离远、逻辑上强关联（例如结论句与相隔较远的依据句）时仍会拆开，提升的是边界质量，不解决关联内容分散。二是收益未必覆盖成本，Qu et al.《Is Semantic Chunking Worth the Computational Cost?》（arXiv 2410.13070，2024）在多个检索与问答数据集上对比后认为，语义分块相对固定长度切分没有稳定一致的增益，而预处理开销（每句一次向量化，而非每块一次）是确定发生的。

结论：结构化文档优先按标题层级切分，成本最低且边界最可靠；无结构长文本再考虑语义分块，并用自己的评测集验证增益是否真实存在。

分块增强：上下文增强（Contextual Retrieval）

针对"关联内容分散"这条局限，Anthropic 在 2024 年 9 月提出上下文增强，作为分块环节的增强手段，不占编号，可与语义分块、命题分块叠加。

做法：入库前用 LLM 为每个块生成一段前缀，说明它在全文中的位置与指代（"本段出自 2023 年 Q2 财报，讨论的是 ACME 公司的营收情况"），把前缀拼在块正文之前再做向量化与关键词索引。

收益：官方公布的数据（top-20 召回失败率，基线 5.7%）：仅做上下文嵌入降至 3.7%（相对下降 35%）；叠加上下文 BM25 降至 2.9%（49%）；再加重排序降至 1.9%（67%）。

代价：与命题分块同源，全库每个块各需一次 LLM 调用。前缀生成只依赖原文，可以用提示缓存把重复读取整篇文档的开销压下来。

策略 2：命题分块（Proposition Chunking）

出自《Dense X Retrieval: What Retrieval Granularity Should We Use?》（Chen et al., EMNLP 2024）。论文提出了一种新的检索单元：命题（proposition），即原子化、自包含、封装单一事实的自然语言陈述。

做法：先按任意方式粗切，再把每个粗块拆解为命题，每个命题独立索引。论文没有靠提示词硬拆，而是训练了专用的拆解模型（Propositionizer），在 Wikipedia 语料上批量生成命题级索引。

拆分示例，原句：

《民法典》第五百八十六条规定，定金合同自实际交付定金时成立，定金数额不得超过主合同标的额的百分之二十。

拆为两条命题：

• 定金合同自实际交付定金时成立。
• 定金数额不得超过主合同标的额的 20%。

两条命题都补齐了主语，并去掉了"《民法典》第五百八十六条规定"这类需要跨句解析的引导成分。自包含是命题的硬要求，拆完仍带着"该条""前述"这类悬空指代的，等于没拆。

收益：检索粒度从段落细化到事实，命中更精确。论文结论是命题级检索单元在下游问答任务上达到或优于段落级。

局限：命题太短，单条往往不足以支撑生成。通行解法是"小块检索、大块生成"（small-to-big / parent document retrieval）：用命题做索引与匹配，命中后按父块 ID 回溯它所属的原始段落，把段落而非命题交给 LLM，索引粒度与生成粒度由此解耦。

代价：预处理引入全量 LLM 调用，成本随文档库规模上涨。

结论：适合准确性要求高、文档库相对稳定的场景（法规、合同、手册），不适合频繁变更的海量语料。

策略 3：领域特化 Embedding

通用 embedding 模型的代表：

• OpenAI text-embedding-3 系列（small / large），支持 dimensions 参数按 Matryoshka 表示学习截断维度，用精度换存储与检索速度
• 智源 BGE 系列，旗舰 bge-m3：100+ 语言、8192 token 上下文，单模型同时输出稠密 / 稀疏 / 多向量三种表示
• 阿里 Qwen3-Embedding：0.6B / 4B / 8B 三档，最小档即支持 32k 上下文，发布时位居 MTEB 多语言榜开源权重模型第一

问题：通用模型对专业术语的分辨率不足。法律场景的典型例子："定金"（担保性质，适用定金罚则，违约方可能丧失定金）与"订金"（预付款性质，原则上可退）在法律上是两回事，但两个词在通用模型的向量空间里距离很近，检索结果互相污染。

做法：术语密集的领域选用领域特化模型（如法律检索的 voyage-law-2），或在领域语料上微调通用底座。

代价：这项决策必须在建库前定。向量维度与语义空间由模型绑定，换 embedding 模型意味着全库重新向量化并重建索引，开销与首次建库同级，没有"先上通用模型，不行再换"的余地。

结论：判断标准是术语是否密集、术语间差异是否细微，满足则领域模型优先；通用语料下通用模型够用，省掉选型与维护成本。MTEB 名次不能直接当选型依据：榜单任务分布未必匹配自己的语料，落地前用自己的评测集跑一遍召回对比。

策略 4：结构化索引与元数据过滤

做法：存储选型按规模分两档：

选型注意：旧教程里常见的 sqlite-vss 已被作者停止维护（基于 Faiss 的 C++ 绑定存在集成问题），2024 年起由纯 C 实现、零外部依赖的 sqlite-vec 接替，新项目直接用 sqlite-vec。

每条记录存三样东西：向量、原文、元数据（日期、来源、类型、版本、父块 ID 等）。"只搜 2024 年之后、来源为 A 系统的合同条款"这类需求，向量相似度做不到，靠元数据过滤实现。

问题：元数据过滤与 ANN 索引存在冲突。近似最近邻索引按向量距离组织数据，不认识 WHERE 条件，过滤条件命中率低时，两种执行顺序都会出问题：

• 后过滤（先走 ANN 取 top k，再按条件筛）：筛完可能剩下不足 k 条，极端情况返回空结果，且这种召回缺失在接口层看不出异常
• 前过滤（先按条件全表筛，再暴力比距离）：条件宽松时退化为全表扫描，延迟随库规模线性上涨

pgvector 0.8.0 引入迭代索引扫描（iterative index scan）缓解后过滤的问题：结果不足时自动继续遍历索引，由 hnsw.iterative_scan / ivfflat.iterative_scan 与 hnsw.max_scan_tuples 等参数控制。上线前要用真实的过滤条件分布压一遍召回率，不要只测无过滤的场景。

局限：向量库以块为单位独立存储，块之间的引用关系丢失。合同第十二条引用第五条时，普通向量库不保留这条跨块引用，检索命中第十二条也无法自动带上第五条。

策略 5：Graph RAG（图结构检索）

做法：在块之外，用 LLM 从文档中抽取实体（条款、人物、概念）与关系（引用、因果、从属），存成图结构，节点是实体，边是关系。检索时先定位命中实体，再沿边扩展关联节点，召回一个相关上下文簇。跨块引用关系在图里天然保留，查第十二条时能顺着边走到第五条。

flowchart LR
    subgraph vec ["普通向量库：块独立存储，引用关系丢失"]
        B12["合同第十二条"]
        B5["合同第五条"]
        B3["合同第三条"]
    end
    subgraph kg ["Graph RAG：实体为节点，关系为边"]
        N12(("第十二条：命中"))
        N5(("第五条"))
        NC(("甲方主体"))
        N12 -->|引用| N5
        N12 -->|涉及| NC
        N5 -->|约束| NC
    end
    vec == 抽取实体与关系建图 ==> kg

收益：图的价值不止局部检索。微软的 GraphRAG（Edge et al., 2024，《From Local to Global》）在图上做社区检测（Leiden 算法），对聚出的社区逐层生成摘要，据此回答全局性问题（"这批文档的核心主题是什么"）。这类问题向量检索答不了：它只能召回与查询局部相似的块，而全局主题不存在于任何单个块里。GraphRAG 因此区分两种检索模式：局部搜索从命中实体出发扩展邻域，全局搜索走社区摘要做 map-reduce 式汇总。

代价：实体关系抽取需要 LLM 全量处理文档库，开销与命题分块同级或更高（每个块通常不止一次调用）；抽取质量受限于 LLM，错误的实体消歧与关系会污染检索结果；文档更新会触发局部乃至全图的社区重算，维护负担持续存在。

结论：只在关系密集、跨块引用是核心查询模式的文档（合同、规范、结构化知识库）上采用，先在单个文档集上试点，用评测集量出与"向量 + 元数据"基线的召回差距，确认收益后再全量铺开。若只需要全局摘要能力、不要求完整图谱，可评估微软后续的 LazyGraphRAG，它把大部分 LLM 开销从建库期推迟到查询期，官方给出的索引成本约为完整 GraphRAG 的 0.1%。

[!CAUTION] 定位 Graph RAG 属于高收益高风险策略。默认场景用策略 4 的向量库 + 元数据；确认跨块关系查询或全局摘要是刚需后，再引入图结构。

四、检索阶段：策略 6-9

策略 6：查询改写（Query Transformation）

问题：用户原始 query 往往口语化、缺主语、一词多义，或是多个子问题拼成的复合问题。

做法：改写有三个方向：

• 具体化：结合对话历史，把"这个怎么配"补成完整、明确的问题。多轮对话场景下这一步必须做，带指代的 query 直接向量化，几乎必然召回错误内容
• 拆解：复合问题拆成子问题分别检索后合并；也可以反向做抽象，用 step-back prompting（Zheng et al., ICLR 2024）先退一步问出上位概念，再检索原理性材料
• 扩展：生成多个查询变体各自检索，结果用 RRF 融合（即 RAG-Fusion），提升召回覆盖

代价：每次提问增加一轮 LLM 调用，延迟与成本同步上涨；多查询扩展还会把检索次数放大 3-5 倍。时延敏感的场景只保留多轮对话的指代消解，其余预算留给重排序。

策略 7：假设文档检索（HyDE）

出自《Precise Zero-Shot Dense Retrieval without Relevance Labels》（Gao et al., ACL 2023）。

做法：先让 LLM 针对问题生成一篇假设答案，不要求事实正确，只要像一篇真正的回答；再用假设答案的向量去检索，替代原始 query 的向量。论文的具体做法是生成多篇假设文档，把它们的向量与原 query 向量一起取平均，用平均向量检索，摊薄单篇幻觉的影响。

原理：query 与目标文档之间存在表达鸿沟：问题短、口语化，文档长、书面化，两者在向量空间中的分布本就不重合。假设答案与真实文档同为"文档"，分布更接近，检索更准。论文结论：HyDE 的零样本检索效果优于当时的无监督稠密检索器 Contriever。

局限：冷门领域 LLM 缺乏背景知识，生成的假设文档偏离事实，会把检索方向带偏：召回内容与问题完全不相关，且从最终答案表面不易察觉（模型会基于错误上下文流畅作答）。应对：冷门或专有领域慎用；启用时与混合检索的关键词通道并行，保留原始 query 的检索结果做兜底；在评测集上分别记录开启与关闭 HyDE 的召回率，按语料实测决定。

策略 8：混合检索（Hybrid Search）

问题：纯向量检索语义匹配强、精确区分弱。"1 型糖尿病"与"2 型糖尿病"在向量空间距离很近，语义检索可能把两者混着返回，对医学检索来说就是事实性错误。

做法：同时跑两路：

• 稠密向量检索：负责语义相关，能命中同义表达与改述
• 稀疏检索：负责精确 token 匹配，硬性区分"1 型 / 2 型"这类词面差异。这里要分清两个概念：BM25 是打分函数（按词频、逆文档频率与文档长度归一化计算得分），倒排索引是支撑它的数据结构，两者不是并列关系

工程上有两条路：主流存储都已提供混合检索能力（pgvector 配合 PostgreSQL 全文检索、Elasticsearch / OpenSearch、Qdrant、Milvus）；也可以用 bge-m3 这类单模型同时产出稠密与稀疏表示，省掉维护两套索引的负担。

原理：两路的分数不能直接相加：余弦相似度落在 [-1, 1]，BM25 无上界，量纲不同。加权融合要先做分数归一化，而归一化对分数分布敏感、跨查询不稳定。RRF（Reciprocal Rank Fusion）绕开了这个问题，它只用排名不用分数：

$$ \text{score}(d) = \sum_{r \in R} \frac{1}{k + \text{rank}_r(d)} $$

$R$ 是各路检索器的集合，$\text{rank}_r(d)$ 是文档 $d$ 在第 $r$ 路结果中的排名，$k$ 是平滑常数（原论文取 60，用于抑制头部排名之间的权重落差）。无需调参、无需归一化，这是 RRF 成为默认融合方案的原因。确实需要给不同通道加权时，再换加权融合并自行处理归一化。

结论：收益最大的语料是专有名词、编号、术语密集的类型（法规条文号、零件型号、药品名）。

策略 9：重排序（Re-ranking）

做法：初筛与精排用不同架构的模型：

交叉编码器对每一对（query, 候选）都要完整前向计算，全库跑一遍成本不可接受。工程惯例是"先召后排"：bi-encoder 或混合检索做初筛，cross-encoder 只对几十条候选精排，把费用与延迟锁在候选层。ColBERT（Khattab & Zaharia, SIGIR 2020）代表的迟交互是两者之间的折中：文档侧仍可预计算，匹配保留 token 粒度，代价是每篇文档存一组向量、存储明显放大，bge-m3 的多向量模式属于这一路。

模型选择：商用 API 的代表是 Cohere Rerank；自托管常用 BGE-Reranker 或 Jina Reranker 系列。另有让 LLM 对候选列表整体排序的做法（listwise，如 RankGPT），精度上限更高，但延迟与成本随候选数量线性上涨，通常只用于离线评测或候选极少的场景。

结论：真正影响效果的参数是两个数：初筛候选数（决定召回上限，取小了重排无从挑选）与重排后送入 LLM 的条数。后者不是越多越好：受 Lost in the Middle 的位置效应影响，塞 20 条往往不如精准的 5 条。这两个数要在评测集上一起调。

五、范式升级：策略 10 与组合策略

单次 pipeline 隐含的假设是一次检索就能召回全部所需信息，而实际的查资料过程往往不是这样：查到一半发现缺一块，换个关键词再查。

策略 10：Agentic RAG

做法：把单次 pipeline 换成循环，由 agent 决定每一轮做什么：

flowchart TB
    subgraph pipeline ["单次 Pipeline"]
        Q1["提问"] --> R1["检索一次"] --> A1["直接生成"]
    end
    subgraph loop ["Agentic 循环"]
        Q2["提问"] --> R2["Agent 决定调用哪个工具"]
        R2 --> E{"信息足够？"}
        E -->|是| A2["生成回答"]
        E -->|否| L{"达到轮数上限？"}
        L -->|否| W["改写查询，继续检索"]
        W --> R2
        L -->|是| A3["按已有信息生成<br/>并标注信息不完整"]
    end

Agent 的工具箱不限于语义检索：关键词检索、执行代码、读取原文、查元数据都可以作为工具挂载，多轮调用直至信息足以支撑回答。工具描述的质量直接决定调用准确率，写清楚每个工具的适用场景与参数含义，比增加工具数量更有效。

收益：召回侧，多轮探索能补上单次检索遗漏的信息；工程侧，传统 pipeline 需要硬编码策略分支（什么时候改写、什么时候拆问题），Agentic 模式把这些决策交给 agent 判断，主流程只剩一个循环。

局限：最大的风险是循环不收敛，agent 反复用近似的 query 检索同一批内容，token 消耗与延迟随轮数线性上涨，极端情况下打满上下文窗口后失败，成本无法预测、做不了容量规划。防护要做硬：

• 最大轮数上限（工程上常取 5-8 轮）与单次问答的 token 预算，超限则用已有信息强制生成并标注"信息可能不完整"
• 每轮把已检索过的 query 与块 ID 记入状态，重复命中时直接终止
• 对多轮累积的上下文做去重与压缩，只保留被引用的片段

结论：简单问题跑 agent 循环不经济，查一个 API 用法用不着探索三轮。

组合策略：自适应路由（Adaptive Routing）

做法：在入口处用轻量分类器评估问题难度，简单问题走传统 pipeline（混合检索 + 重排序），复杂问题升级为 Agentic RAG。

论文出处：Adaptive-RAG（Jeong et al., NAACL 2024）。原始设计是三档路由：简单问题不检索、由 LLM 直接回答；中等复杂度单步检索；复杂问题多步迭代检索。分类器不依赖人工标注，而是用各档位的实际问答结果做弱监督训练（哪一档最先答对，样本就归到那一档）。工程上常简化为两档：简单走 pipeline，复杂走 agent 循环。

局限：误判是主要风险，尤其是把复杂问题判成简单：复杂问题走单次检索，召回不足直接答错，且路由决策发生在检索之前，后续环节没有纠正机会。对策：分类阈值向"判复杂"一侧倾斜（误判为复杂只是多花成本，误判为简单会答错）；生成后加一道自检，答案置信度低或引用不足时回退到 agent 路径。

六、十种策略速览与选型

新项目默认配置，按顺序落地：

1. 分块：结构化文档按标题层级切分，无结构长文本用语义分块；chunk 目标 512-1024 token，overlap 10%-20%
2. Embedding：通用模型起步（text-embedding-3 / bge-m3 / Qwen3-Embedding），但必须在建库前定下来
3. 存储：sqlite-vec 或 pgvector，第一天就把元数据做全（日期、来源、版本、父块 ID）
4. 检索：混合检索 + RRF + 重排序，这组在成本与收益上性价比最高
5. 评测：与第 4 步同步搭起来，不要等策略调完再补
6. 查询处理：多轮对话的指代消解先上；改写与 HyDE 等延迟预算允许后再加

第 4 步是整套里最值得先做对的部分。骨架如下，省略了检索器与重排模型的具体实现：

def rrf_fuse(rankings: list[list[str]], k: int = 60) -> list[str]:
    """按 RRF 融合多路检索结果，输入为各路的有序 chunk_id 列表。"""
    scores: dict[str, float] = {}
    for ranking in rankings:
        for rank, chunk_id in enumerate(ranking, start=1):
            scores[chunk_id] = scores.get(chunk_id, 0.0) + 1.0 / (k + rank)
    return sorted(scores, key=lambda cid: scores[cid], reverse=True)


def retrieve(query: str, *, filters: dict, top_k: int = 5) -> list[str]:
    # 1. 两路初筛，候选数取远大于 top_k 的值，给重排留出挑选空间
    dense_hits = dense_search(query, filters=filters, limit=100)
    sparse_hits = bm25_search(query, filters=filters, limit=100)

    # 2. RRF 融合，只用排名，不做分数归一化
    candidates = rrf_fuse([dense_hits, sparse_hits])[:60]

    # 3. 交叉编码器精排，计算成本锁在候选层
    reranked = cross_encoder_rerank(query, candidates)[:top_k]

    # 4. 命中的是命题或小块时，回溯父段落再交给 LLM（small-to-big）
    return [load_parent_text(cid) for cid in reranked]

三个数字需要在评测集上一起调：初筛 limit（决定召回上限）、送进重排的候选数（决定重排成本）、最终 top_k（受位置效应约束）。

升级触发条件：

• 文档关系密集、跨块引用或全局摘要类查询多：评估 Graph RAG，先小规模试点
• 复杂问题占比高、多轮探索的收益在评测集上可见：Agentic RAG，配合自适应路由与轮数上限控制成本
• 领域术语密集、通用模型检索互相污染：换领域特化 Embedding，同时加强关键词通道与布尔约束
• 带过滤条件的召回率明显低于无过滤：调 ANN 索引参数或改用前过滤，见策略 4

flowchart TB
    D["新项目默认配置<br/>语义分块 / 标题层级切分 · 通用 Embedding<br/>sqlite-vec / pgvector + 元数据<br/>混合检索 + RRF + 重排序 + 评测集"]
    D -->|领域术语密集，检索互相污染| E1["领域特化 Embedding"]
    D -->|文档关系密集，跨块引用查询多| E2["Graph RAG（先小规模试点）"]
    D -->|复杂问题占比高，多轮探索收益明显| E3["Agentic RAG + 自适应路由"]
    D -->|块脱离全文后指代不明| E4["上下文增强分块"]

七、质量与工程考量

成本与延迟：

• 只召回必要内容，控制输入上下文长度
• 重排放在初筛之后，只对候选层计算
• 时延敏感路径不引入额外的 LLM 预处理：查询改写与 HyDE 各要一轮调用，直接加在 TTFT 上
• Agentic 路径必须有轮数与 token 上限，否则单次问答成本不可预测

准确性与上下文稀释：

• 分块质量是地基，chunk 语义不完整时，后面的策略都救不回来
• 混合检索 + 重排提升相关性；对召回结果做去重（不同块可能包含同一事实），减少上下文噪音
• 注意 Lost in the Middle 的位置效应：重要内容不要埋在长上下文中部，重排后的顺序要真的用上
• 要求模型给出引用来源，答案与召回块能对齐，幻觉才能被发现

评测要分层，检索层与生成层分开测量，否则出问题定位不到环节：

固定一批问题与期望召回的文档做评测集，每次调整策略跑一遍。规模不必大，50-100 条覆盖典型查询类型即可起效；关键是每次只动一个变量，否则无法归因。检索指标能用脚本自动算，生成指标可用 RAGAS 一类框架做 LLM-as-judge，但要抽样人工校准判分标准。没有评测集的策略调优是在赌方向。

维护与迭代：

• 元数据从第一天做全（日期、来源、版本、父块 ID），后续的过滤、增量更新、small-to-big 回溯都依赖它
• 增量更新按内容哈希判断块是否变化，只重算变化的块；Graph RAG 的更新流程单独设计，增量还是全图重算直接决定维护成本
• 把 embedding 模型与分块参数写进索引的元信息，换配置时能识别出哪些块属于旧版本

八、结语

RAG 解决的是"如何召回信息"这一个问题。十种策略分布在准备与检索两个阶段，各管一段，没有通吃的那一种。

其中只有两件事值得无条件先做：混合检索加重排序（收益稳定、成本锁在候选层），以及在动手调策略之前先有评测集。其余都是带触发条件的加法：语义分块的增益争议、HyDE 在冷门领域的反作用、Graph RAG 的维护成本，都得靠自己的语料实测才知道，不要因为某个策略看起来更先进就默认启用。

检索只是 agent 的地基，往上还有 memory 设计、行为评估、数据闭环，那是另一套问题。

九、参考资料

• Gao et al. Precise Zero-Shot Dense Retrieval without Relevance Labels（HyDE，arXiv 2212.10496，ACL 2023）
• Chen et al. Dense X Retrieval: What Retrieval Granularity Should We Use?（arXiv 2312.06648，EMNLP 2024）
• Edge et al. From Local to Global: A Graph RAG Approach to Query-Focused Summarization（arXiv 2404.16130，2024）
• Jeong et al. Adaptive-RAG: Learning to Adapt Retrieval-Augmented Large Language Models through Question Complexity（NAACL 2024）
• Liu et al. Lost in the Middle: How Language Models Use Long Contexts（arXiv 2307.03172，TACL 2024）
• Qu et al. Is Semantic Chunking Worth the Computational Cost?（arXiv 2410.13070，2024）
• Khattab & Zaharia. ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction over BERT（arXiv 2004.12832，SIGIR 2020）
• Zheng et al. Take a Step Back: Evoking Reasoning via Abstraction in Large Language Models（arXiv 2310.06117，ICLR 2024）
• Cormack et al. Reciprocal Rank Fusion Outperforms Condorcet and Individual Rank Learning Methods（SIGIR 2009，RRF 原始论文）
• Anthropic：Introducing Contextual Retrieval（2024-09）
• Microsoft Research：LazyGraphRAG — Setting a New Standard for Quality and Cost
• pgvector（GitHub，含 HNSW / IVFFlat 与迭代索引扫描说明）
• sqlite-vec（GitHub，sqlite-vss 的继任者）
• Voyage AI：Domain-Specific Embeddings — Legal Edition（voyage-law-2）
• Ragas 文档（检索与生成侧评测指标）
• MTEB Leaderboard（Hugging Face）

[!NOTE] 提示 性能优化的手段多且杂，本文把它们归拢到「字节、往返、距离、主线程」四个变量上，按先测量后动手的顺序展开十项主流实践。每项统一说明问题原因、处理方法、提升幅度与注意事项，文末附端到端 Nginx 配置、踩坑清单与方法总览表，关键数据标注了来源。

引子

一个常见场景：一个日均 PV 几千的内容型站点，4G 网络下首屏耗时 4 秒开外，Lighthouse 跑分不到 50。排查结果很典型：文章配图是没压缩的 2 MB 原图；静态资源全都没有缓存头，回访用户每次重新下载；服务器部署在境外，TTFB 接近 800 ms。三个问题对应三类浪费：字节太多、往返太多、距离太远。

业务侧的代价有数据口径：Google 的移动端速度研究显示，页面加载时间从 1 s 涨到 3 s，跳出概率上升 32%（来源：Google/SOASTA 研究，业界广泛引用）。

性能优化的每一项手段，最终都落在少数几个变量上。本文按「先测量，再动手」的顺序整理十项主流实践：性能分析、传输协议、传输压缩、HTTP 缓存、CDN、Nginx 配置、加载策略、图片、字体、JS 执行，每项按问题原因、处理方法、提升幅度、注意事项展开，数据来源统一列在参考资料。

背景知识：度量框架与优化变量

Core Web Vitals 是 Google 定义的三项真实用户体验指标，同时是搜索排名信号（web.dev）：

页面加载耗时可以近似拆成三段：资源体积除以带宽、请求数乘以往返时间（RTT）、服务端处理时间。后文的方法都在改这几个变量：压缩和图片格式减少字节，缓存和协议升级减少往返，CDN 缩短 RTT 本身，JS 治理则发生在另一头的主线程上。

测量工具分两类：实验室数据（Lighthouse、WebPageTest，可复现，适合定位）与真实用户数据（CrUX、RUM，反映真实设备与网络）。PageSpeed Insights 两者都提供。优化决策以真实用户数据为准。

十项主流优化方法

一、性能分析：先测量，再优化

问题原因：性能瓶颈很少符合直觉。没测过基线就动手，优化的大概率不是真正的瓶颈，改完也无法证明有没有效果。

处理方法：

• 实验室工具：Lighthouse（Chrome DevTools 内置，快速出分并给出审计清单）、WebPageTest（瀑布图最细，可选测试地区、设备与网络节流）、Chrome DevTools Performance 面板（定位长任务与强制重排）。
• 真实用户数据：PageSpeed Insights 自带 CrUX 字段数据；自建 RUM 可用 web-vitals 库在页面内上报指标。
• 工作流固定为三步：字段数据找问题，实验室数据定位原因，改完再用字段数据验收。

提升幅度：不直接产生提升，作用是把优化清单按预期收益排序。先看 TTFB（良好阈值 800 ms，web.dev）再看前端资源，避免服务端已经拖后腿时去抠前端字节。

注意事项：Lighthouse 单次跑分有波动，同一页面两次能差几分，结论基于多次运行取中位数；CrUX 有流量门槛，小站点可能查不到字段数据，只能靠实验室工具加本地节流。

二、HTTP 协议升级：HTTP/2、TLS 1.3 与 HTTP/3

问题原因：HTTP/1.1 同一 TCP 连接一次只能处理一个请求，浏览器靠每个域名开 6 个连接缓解队头阻塞，每个连接都要独立的 TCP 加 TLS 握手；TLS 1.2 握手需要 2 个 RTT。

处理方法：

• 全站 HTTPS（HTTP/2 的前提），Nginx 1.25.1 起用 http2 on; 指令开启。
• 启用 TLS 1.3（需 OpenSSL 1.1.1+）：握手降到 1-RTT，会话恢复 0-RTT。
• 有条件再上 HTTP/3（Nginx 1.25+ 支持 QUIC），通过 Alt-Svc 响应头让浏览器自动协商。

提升幅度：TLS 1.3 每次握手省 1 个 RTT。HTTP/3 的收益集中在弱网：CloudPanel 实测 4G 加 15% 丢包环境下，页面加载比 HTTP/2 快约 55%；DebugBear 的结论是收益具有场景性，稳定高速网络下提升有限。

注意事项：QUIC 走 UDP，部分企业防火墙会拦截，必须保留 HTTP/2 兜底（浏览器按 Alt-Svc 自动降级）；HTTP/2 多路复用后，HTTP/1.1 时代的域名分片、雪碧图合并变成负优化，见踩坑一节。

三、传输压缩：gzip、Brotli 与 Zstandard

问题原因：HTML/CSS/JS 是高度冗余的文本。不压缩时，一个 300 KB 的 JS 文件在 10 Mbps 带宽下纯传输就要 240 ms，还没算握手与排队。

处理方法：

• 基线：Nginx 开 gzip，覆盖 JS、CSS、JSON、SVG、XML 等文本类型。
• 进阶：Brotli（ngx_brotli 模块），压缩率更高，主流浏览器全支持。
• 关键取舍：静态资源在构建期预压缩成 .br/.gz 文件（brotli_static/gzip_static），可以用最高压缩级别；动态内容实时压缩只敢用中低级别，此时 zstd 的速度优势明显。

提升幅度：gzip 通常压掉文本资产体积的 60-75%（Blazing CDN 数据）；Brotli 最高级别再比 gzip 小 15-25%（Paul Calvano 测试）。压缩速度决定实时压缩的选型：zstd 约 510 MB/s、Brotli 约 290 MB/s、gzip 约 105 MB/s（OpenResty 数据）。

注意事项：gzip_comp_level 超过 6 后体积收益递减、CPU 线性上涨；图片、视频、woff2 这类已压缩格式不要二次压缩，纯烧 CPU；CDN 场景必须回带 Vary: Accept-Encoding，否则可能把压缩版发给不支持解压的客户端。

四、HTTP 缓存：让重复访问零请求

问题原因：默认行为下浏览器每次都问服务器「变了没」。回访用户重复下载没改过的 JS/CSS，每个未命中都是一次完整往返。

处理方法：资源分两类，各给一种策略：

• 带指纹的静态资源（如 app.3f8a9c.js）：Cache-Control: public, max-age=31536000, immutable，一年内浏览器不发任何验证请求。Vite、webpack、Astro 等构建工具默认输出带 hash 的文件名，指纹机制是现成的。
• HTML 入口页：Cache-Control: no-cache 加 ETag 协商，内容没变返回 304（几百字节的响应头）。
• 进阶方向是 Service Worker 加 Cache API 做细粒度控制与离线，成本更高，内容型站点按需选。

提升幅度：命中强缓存的请求耗时趋近于 0。指纹化模式下，回访页面只剩 HTML 一个必发请求，其余静态资源全部来自本地；HTML 协商未变时，全量响应退化为 304。

注意事项：长 max-age 只能配指纹化文件名，否则用户拿不到更新；Nginx 的 ETag由 mtime 和文件大小算出，多机部署时 mtime 不一致会让同一文件算出不同 ETag，命中率反常下降；HTTP Archive 统计里，使用 immutable 的站点绝大多数搭配 365 天以上的 max-age，属于成熟模式。

五、CDN：把字节搬到用户旁边

问题原因：光速是硬约束。用户到源站的物理距离直接加进 TTFB：跨国 RTT 轻松超过 200 ms，页面几十个请求每个都要走完全程；源站带宽有限，静态下载还会挤占动态接口。

处理方法：图片、JS、CSS、字体这些静态资源接入 CDN，DNS 指向边缘节点；配置回源策略，边缘未命中才回源，开启中间层缓存（如 Origin Shield）降低回源量；缓存头沿用上一节的方案，CDN 会尊重 Cache-Control。

提升幅度：真实案例中改善区间常见 20-50%：Cloudflare 的 Pacsun 案例接入后整体快 27%。源站越远、用户分布越广，收益越大。

注意事项：CDN 的价值取决于缓存命中率，缓存键（query string、header）配置不当会把命中率打到很低，性能反而不如直连源站；HTML 一般不进 CDN 长缓存，用短 TTL 或纯回源；静态资源用独立域名可以甩掉 Cookie，但 HTTP/2 下不要为分片拆太多域名。

六、Nginx 与服务器配置

问题原因：默认配置按通用场景偏保守。静态文件默认经过用户态缓冲，多两次内存拷贝；短连接每个请求重新握手；TLS 参数保守时握手慢、加密套件低效。

处理方法：

sendfile on;             # 内核态直接发文件，省掉用户态拷贝
tcp_nopush on;           # 配合 sendfile，攒满一个包再发，适合静态文件
tcp_nodelay on;          # 禁用 Nagle，keepalive 连接上的小包立即发
keepalive_timeout 65;    # 连接复用，减少重复握手

• TLS：ssl_session_cache 复用会话；OCSP Stapling 由服务器预取证书状态随握手下发，客户端不用再单独问 CA。
• 内核层：TCP 拥塞控制升级为 BBR，高丢包链路吞吐改善明显，应用层无需改动。

提升幅度：sendfile 减少内存拷贝与上下文切换，静态大文件吞吐提升明显；keepalive 让同连接的后续请求免掉整个 TCP 加 TLS 握手；OCSP Stapling 为客户端省一次对 CA 的查询（百毫秒级）。这几项属于消除明显浪费，具体提升幅度取决于基线有多差。

注意事项：worker_processes auto 按核数配齐；改一项测一项，Nginx 配置错误直接 502；BBR 需要内核 4.9+，改内核参数前先确认宿主机支持。

七、加载策略：资源提示与关键渲染路径

问题原因：浏览器的默认发现机制有结构性延迟：CSS 阻塞渲染，<script> 默认阻塞解析；CSS 里引用的字体要等 CSS 下载解析完才发起请求；跨域关键资源要现做 DNS、TCP、TLS。

处理方法：

• 脚本：默认 defer（不阻塞解析，DOM 建好后按序执行），独立的第三方脚本用 async。
• 资源提示按用途选：
  • preconnect：提前完成 DNS 加 TCP 加 TLS，只给确定马上要用的关键源（字体、CDN），字体必须带 crossorigin。
  • preload：当前页高优先级资源（LCP 图、关键字体），必须写 as 属性。
  • prefetch：下一跳页面的资源，空闲期低优先级拉取。
  • fetchpriority：修正浏览器自己排错的优先级，典型用法是给 LCP 图标 high。
• 首屏关键 CSS 内联，其余样式异步加载。

提升幅度：preconnect 省掉 1-3 个 RTT（按网络质量约 50-300 ms）；preload 字体消除「CSS 下载、发现字体、再下载字体」的串行瀑布；defer 消除脚本对解析的阻塞。

注意事项：资源提示过用会反噬，preload 所有资源等于没有优先级，preconnect 控制在 4 个以内；prefetch 的资源可能在使用前被逐出，只适合大概率发生的导航。

八、图片优化

问题原因：图片通常是页面字节的大头。没约束的原图、桌面端大图塞进手机、缺少尺寸属性引起的布局偏移，是三类最常见的浪费。

处理方法：

• 格式升级：<picture> 里 AVIF 打头、WebP 兜底、JPEG 收尾。
• 响应式：srcset 加 sizes，按视口宽度给不同分辨率。
• width/height 属性写死，浏览器提前算出宽高比，同时收获 CLS 收益。
• LCP 主图：fetchpriority="high"，绝不懒加载；折叠以下图片一律 loading="lazy"。
• 用构建期图像管线（sharp、Astro 图像服务）统一转码，不靠手工。

提升幅度：WebP 比 JPEG 小 25-35%，AVIF 约 50%（Google 数据，web.dev）。格式升级加响应式，是单点收益最大的一类优化。

注意事项：懒加载 LCP 图会直接推迟 LCP，首屏图务必排除；AVIF 编码慢，构建时间会变长；压缩质量过低时，伪影先出现在纯色渐变和文字边缘。

九、字体优化

问题原因：字体请求排在 CSS 之后，天然串行；字体未就绪时浏览器要么空白（FOIT）要么替换闪烁（FOUT）；中文字体全量动辄数 MB。

处理方法：

• 统一 WOFF2；关键字体加 preload，带 crossorigin。
• font-display: swap，先用回退字体渲染，字体就绪后替换。
• swap 带来的布局偏移，用 size-adjust/ascent-override/line-gap-override 把回退字体度量对齐到 webfont，可压到接近零 CLS。
• unicode-range 分片按需下载；中文场景做子集化，只保留实际用到的字符。
• 能用系统字体栈的场景优先系统字体，零请求零偏移。

提升幅度：WOFF2 相比 TTF 减约 60%、相比 WOFF 减约 30%；preload 消除字体请求的串行等待；中文子集化通常是数量级级别的缩减。

注意事项：swap 必然有一次替换闪烁，正文可接受，强视觉的品牌标题慎用；子集化要覆盖动态内容的字符集，后到的字符会回退渲染；字体自托管比第三方托管省一次跨域连接。

十、JavaScript 执行：长任务治理

问题原因：下载只是 JS 成本的开始，解析、编译、执行都占主线程，而主线程同一时刻只能跑一个任务。超过 50 ms 的任务定义为长任务（web.dev），长任务期间页面无法响应交互，这是 INP 不达标的首要原因。

处理方法：

• 少发：Tree-shaking 去死代码；按路由拆包（代码分割）；交互后再动态 import() 非关键模块。
• 不阻塞：非关键脚本 defer，或延迟到首次交互后加载。
• 拆任务：scheduler.yield()（或退化为 setTimeout）把长任务切成小块让出主线程；纯计算挪进 Web Worker。
• 高频事件（scroll、resize、mousemove）防抖节流；回调里读写分离，避免强制同步布局。

提升幅度：收益定性但方向明确：发送的字节越少，解析编译时间越短；长任务拆开后交互不再排队，目标是把 INP 压进 200 ms。

注意事项：分割过细会产生大量碎片请求，按路由或交互边界拆；Web Worker 通信有序列化成本，不适合高频小任务；INP 要在真实设备上测，桌面开发机的性能会掩盖问题。

实战演示：静态站点的端到端配置

把前面几节落到一份 Nginx 配置（服务端部分）：

http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;

    gzip on;
    gzip_comp_level 6;
    gzip_types text/css application/javascript application/json image/svg+xml text/plain application/xml;
    gzip_static on;              # 优先发送构建期预压缩的 .gz
    # brotli on;                 # 安装 ngx_brotli 后启用
    # brotli_comp_level 6;
    # brotli_static on;
}

server {
    listen 443 ssl;
    http2 on;                    # Nginx 1.25.1+ 新语法
    listen 443 quic reuseport;   # HTTP/3，Nginx 1.25+
    add_header Alt-Svc 'h3=":443"; ma=86400' always;

    ssl_protocols TLSv1.3 TLSv1.2;
    ssl_session_cache shared:SSL:10m;
    ssl_stapling on;
    ssl_stapling_verify on;

    # 指纹化静态资源：一年强缓存
    location ~* \.(js|css|woff2|png|jpe?g|webp|avif|svg|ico)$ {
        add_header Cache-Control "public, max-age=31536000, immutable";
    }

    # HTML：协商缓存
    location / {
        add_header Cache-Control "no-cache";
        try_files $uri $uri/index.html =404;
    }
}

注意 add_header 不继承：location 里只要出现一个 add_header，server 级的全部失效（见踩坑五），需要把 Alt-Svc 在各 location 内重复声明。

HTML 侧的资源提示与图片标记：

<head>
  <!-- 关键第三方源提前建连 -->
  <link rel="preconnect" href="https://cdn.example.com" crossorigin>
  <!-- 关键字体提前加载，打断 CSS 到字体的串行瀑布 -->
  <link rel="preload" href="/fonts/main.woff2" as="font" type="font/woff2" crossorigin>
  <!-- LCP 主图提前加载并提高优先级 -->
  <link rel="preload" as="image" href="/images/hero.avif" fetchpriority="high">
  <script defer src="/app.js"></script>
</head>

<body>
  <!-- LCP 图：高优先级、绝不懒加载、带尺寸防布局偏移 -->
  <img src="/images/hero.avif" width="1200" height="600" fetchpriority="high" alt="">
  <!-- 折叠以下：懒加载 -->
  <img src="/images/inline.webp" width="800" height="450" loading="lazy" alt="">
</body>

踩坑点 & 注意事项

坑 1：HTTP/1.1 时代的优化在 HTTP/2 下反向

域名分片、雪碧图、内联小文件是 6 连接时代的产物。HTTP/2 单连接多路复用后，分片破坏优先级调度，反而变慢。升级协议后要清理这批遗留手段。

坑 2：只看 Lighthouse 分数

实验室分不等于真实体验：跑分环境是快速桌面网络，真实用户在移动弱网。搜索排名用的是 CrUX 字段数据。正确的分工是实验室定位问题、字段数据验收效果。

坑 3：一次改五项，无法归因

五项一起上，指标变好说不清是谁的功劳，变差也拆不出谁拖累。性能优化按单变量迭代，每项改动前后对比同一指标、同一环境。

坑 4：HTML 被长缓存

immutable 加指纹文件名的模式只对静态资源成立。HTML 引用的是文件名，文件名不变时用户会长期拿到旧页面。HTML 必须保持 no-cache 协商。

坑 5：Nginx add_header 不继承

location 中只要出现一个 add_header，server 级的所有 add_header 对该 location 失效。上面配置里 Cache-Control 与 Alt-Svc 同用就会踩到，需要在 location 内重复声明。

优化方法总览

总结

顺序比方法重要：先测量建立基线，再按「字节、往返、距离、主线程」四个变量逐项处理。对多数站点，收益最大的三件事是缓存策略、图片格式升级和传输压缩；协议升级与 CDN 是一次性投入、长期受益的基础设施项。手段会过时，FID 已被 INP 取代，HTTP/3 正在普及，但「先测量、单变量迭代、用真实用户数据验收」的流程不会变。最后一条经验：性能优化最贵的不是漏掉某个技巧，而是把时间花在不是瓶颈的环节上。

参考资料

• web.dev：Web Vitals（LCP / INP / CLS 阈值定义）
• web.dev：Resource hints（preconnect / preload / prefetch 用法）
• web.dev：Image performance（AVIF 节省 50%+ 的出处）
• web.dev：Optimize long tasks（50 ms 长任务定义与拆分）
• web.dev：HTTP cache（指纹化 URL 与协商缓存）
• web.dev：Optimize web fonts
• Paul Calvano：Choosing Between gzip, Brotli and zStandard Compression
• SpeedVitals：ZSTD vs Brotli vs GZip 对比
• OpenResty Edge：Zstd Compression（压缩速度对比）
• Blazing CDN：CDN Compression Performance（Brotli vs gzip）
• CloudPanel：HTTP/3 vs HTTP/2（弱网实测 55%）
• DebugBear：HTTP/3 vs HTTP/2 performance（收益场景性结论）
• CSS Wizardry：Cache-Control for Civilians（缓存头详解）
• HTTP Archive 讨论：Cache-Control immutable, A Year Later
• Cloudflare：What is a CDN（原理与 Pacsun 案例）
• Chrome for Developers：Lighthouse overview
• 晨鹤部落格：Nginx HTTPS 性能优化（OCSP Stapling）
• Huckabuy：Page Speed Statistics（加载 1s 到 3s 跳出率 +32% 口径）

[!NOTE] 提示 如果这篇文章对你有帮助，欢迎点赞收藏。有问题欢迎评论区交流。

[!NOTE] 提示 本文面向需要在生产环境配置 Java 线程池的开发者。核心目标：将 ThreadPoolExecutor 的七个参数、任务调度流程、CPU/IO 场景差异、线程数估算方法、队列选型原则、监控指标与动态调优方案整理为可执行的工程规范。重点审查项：线程数是否受下游资源约束、拒绝策略是否可观测、容器环境是否正确读取 CPU 核数。

一、核心摘要

• 问题：手动创建线程存在资源失控、创建开销大、缺乏背压与降级机制三类风险。
• 方案：使用 ThreadPoolExecutor 显式配置核心线程数、最大线程数、队列、拒绝策略与线程工厂，并通过监控指标闭环调优。
• 关键约束：corePoolSize 不应超过下游最小连接池容量；必须使用有界队列；拒绝策略必须可观测。
• 目标：读完本文后，能够针对 CPU 密集、IO 密集、混合型三种业务场景给出初始配置，并设计压测与监控方案。

适用边界：本文讨论应用内任务执行器，不覆盖消息队列消费者并发度、数据库连接池配置和 JVM GC 调优的完整方案。线程池参数必须以压测数据和下游容量为依据。

二、为什么需要线程池

手动为每个请求创建线程，存在以下三类问题：

线程池提供的核心能力：

1. 线程复用：降低线程创建与销毁开销。
2. 有界队列：提供背压机制，防止无限堆积。
3. 拒绝策略：在容量耗尽时执行降级或告警。

三、ThreadPoolExecutor 核心参数

ThreadPoolExecutor 的构造函数包含七个参数，必须整体理解：

new ThreadPoolExecutor(
    corePoolSize,                         // 1. 核心线程数
    maximumPoolSize,                      // 2. 最大线程数
    keepAliveTime,                        // 3. 非核心线程空闲存活时间
    TimeUnit.SECONDS,                     // 4. 时间单位
    new LinkedBlockingQueue<>(1000),      // 5. 工作队列
    new NamedThreadFactory("order-exec"), // 6. 线程工厂
    new ThreadPoolExecutor.CallerRunsPolicy() // 7. 拒绝策略
);

1、corePoolSize 与 maximumPoolSize

两种典型策略：

• 固定大小：corePoolSize = maximumPoolSize。无弹性，依赖队列缓冲流量波动。
• 弹性伸缩：corePoolSize < maximumPoolSize。队列满后扩容，空闲线程超时回收。

2、keepAliveTime 与 TimeUnit

• 控制非核心线程的空闲回收时间。
• 建议值 30~120 秒。过短导致线程频繁创建销毁，引起 CPU 抖动；过长导致资源闲置。

3、工作队列

队列类型决定排队行为与弹性空间，必须与线程数一起决策。详见第六章。

4、线程工厂

生产环境必须自定义线程工厂，原因：

• jstack 或 arthas 排查时，"pool-1-thread-1" 无法判断业务归属；
• 命名清晰的线程（如 "order-exec-1"）可快速定位问题线程池。

public class CustomThreadFactory implements ThreadFactory {
    private final String prefix;
    private final AtomicInteger counter = new AtomicInteger(1);

    public CustomThreadFactory(String prefix) {
        this.prefix = prefix;
    }

    @Override
    public Thread newThread(Runnable r) {
        Thread t = new Thread(r, prefix + "-" + counter.getAndIncrement());
        t.setDaemon(false);
        t.setUncaughtExceptionHandler((thread, ex) ->
            log.error("线程 {} 发生未捕获异常", thread.getName(), ex));
        return t;
    }
}

5、拒绝策略

当工作队列满且线程数达到 maximumPoolSize 时，新任务触发拒绝策略：

生产建议：优先实现自定义拒绝策略，记录指标、触发告警、执行降级。

四、任务提交与执行流程

flowchart TD
    A[提交任务]
    A --> B{当前线程数 < corePoolSize?}
    B -->|是| C[创建核心线程并执行]
    B -->|否| D[将任务放入工作队列]
    D --> E{工作队列是否已满?}
    E -->|否| F[任务在队列中等待]
    E -->|是| G{当前线程数 < maximumPoolSize?}
    G -->|是| H[创建非核心线程并执行]
    G -->|否| I[触发拒绝策略]

关键认知：只有工作队列满了，线程池才会创建非核心线程。若使用无界队列，maximumPoolSize 永远不会生效。

五、CPU 密集型与 IO 密集型任务

线程池大小最核心的决策依据是阻塞比（W/C），即等待时间与计算时间的比值。

1、CPU 密集型

典型场景：加密解密、数据压缩、图像处理、复杂排序、JSON 序列化。

• 线程大部分时间占用 CPU 执行指令。
• 阻塞比 W/C 约等于 0。
• 线程切换是纯损耗，不会提升吞吐。
• 线程数建议：N_cpu + 1。

2、IO 密集型

典型场景：数据库查询、HTTP 远程调用、文件读写、消息队列消费。

• 线程大量时间处于 IO 等待状态。
• 阻塞比 W/C 可达几倍到几十倍。
• CPU 空闲期间可调度更多线程，提升资源利用率。
• 线程数建议：根据 Goetz 公式估算，并受下游连接池约束。

3、混合型任务

典型 Web 请求链路示例：

混合场景应分段分析，或通过压测统计整体阻塞比，避免直接套用单一公式。

六、线程数估算方法

1、Little's Law

系统稳态下的基本关系：

平均并发数 L = 到达率 λ × 平均响应时间 W

推导出线程数下界：

N_threads ≥ λ × T_response

示例：峰值 QPS = 500，平均 RT = 200ms = 0.2s，则最低需要 500 × 0.2 = 100 个并发线程维持吞吐。

2、Brian Goetz 公式

出处：《Java 并发编程实战》

N_threads = N_cpu × U_cpu × (1 + W/C)

示例：8 核机器，目标利用率 80%，IO 等待 200ms，计算 20ms。

• W/C = 200 / 20 = 10
• N = 8 × 0.8 × (1 + 10) = 70.4，取 72

3、公式的局限

1. 阻塞比难以准确测量：不同流量时段、不同数据量下差异巨大，单次测量值可能误导。
2. 忽略下游瓶颈：数据库连接池上限 50 时，设 200 个线程只会造成大量线程等待连接，反而劣化延迟。
3. 假设任务同质：同一池处理轻量查询与重量报表时，平均 W/C 失去意义。

4、估算流程

1. 用 Goetz 公式或 Little's Law 得出理论初始值
2. 对比下游资源上限（DB 连接池、HTTP 连接池），取较小值
3. 结合机器内存校验：线程数 × 1MB（默认栈）不超过可用堆外内存的 50%
4. 以该值作为压测起点，做阶梯加压验证

5、常见场景参考值

七、工作队列选型

生产红线：禁止使用 Executors.newFixedThreadPool() 与 Executors.newCachedThreadPool()。

• newFixedThreadPool 使用无界 LinkedBlockingQueue，任务堆积可导致 OOM。
• newCachedThreadPool 的 maximumPoolSize 为 Integer.MAX_VALUE，突发流量下线程数失控。

八、常见反模式

1、全局共用一个线程池

核心链路与非核心链路共享线程池时，非核心任务突发会挤占核心任务资源。

// 错误：所有任务共用
@Bean("globalExecutor")
ThreadPoolExecutor global() { ... }

// 正确：按业务隔离
@Bean("paymentExecutor")   // 核心链路
ThreadPoolExecutor payment() { ... }

@Bean("logExecutor")       // 非核心，允许丢弃
ThreadPoolExecutor log() { ... }

2、不考虑下游限制盲目设大

下游 MySQL 连接池上限 50 时，设 500 个线程会导致 450 个线程空等连接，增加上下文切换与排队延迟。

正确做法：corePoolSize ≤ 下游最小连接池上限。

3、keepAliveTime 设置过短

流量波动场景下，keepAliveTime 过短（如 1 秒）会导致非核心线程频繁创建销毁，造成 CPU 与内存抖动。

正确做法：建议 30~120 秒。

4、任务中嵌套提交任务

// 危险：父任务等待子任务，子任务无法入队 → 死锁
executor.submit(() -> {
    Future<?> child = executor.submit(() -> { /* 子任务 */ });
    child.get();
});

正确做法：使用 ForkJoinPool 处理父子依赖任务，或为子任务使用独立线程池。

5、容器环境不修正 CPU 核数

Docker 容器限制 2 核时，旧版 JDK 的 Runtime.getRuntime().availableProcessors() 可能返回宿主机 32 核，导致线程数虚高。

// 问题版本
int cores = Runtime.getRuntime().availableProcessors();

// 安全版本：读取容器 CPU 配额
private int getCpuCores() {
    String cpuLimit = System.getenv("CPU_LIMIT");
    if (cpuLimit != null) return Integer.parseInt(cpuLimit);

    try {
        Path quotaPath = Paths.get("/sys/fs/cgroup/cpu/cpu.cfs_quota_us");
        Path periodPath = Paths.get("/sys/fs/cgroup/cpu/cpu.cfs_period_us");
        long quota = Long.parseLong(Files.readString(quotaPath).trim());
        long period = Long.parseLong(Files.readString(periodPath).trim());
        if (quota > 0) return (int) Math.ceil((double) quota / period);
    } catch (Exception ignored) {}

    return Runtime.getRuntime().availableProcessors();
}

6、线程未命名

jstack 中 "pool-1-thread-1" 无法判断业务归属，应使用 "order-exec-1" 等命名。

九、企业级配置案例

1、需求分析清单

配置线程池前必须明确：

1. 峰值 QPS、平均 RT、P99 RT 是多少？
2. 任务是否存在外部依赖？下游连接池上限是多少？
3. SLA 要求：能否丢任务？允许多大延迟？
4. 容器 / Pod 分配的 CPU 核数是多少？

2、订单查询服务配置示例

场景：8 核 Pod，DB 查询 60ms，本地计算 5ms，W/C ≈ 12，目标 CPU 利用率 80%，DB 连接池上限 50。

计算过程：

Goetz 公式：8 × 0.8 × (1 + 12) = 83.2 → 取 84
约束检查：DB 连接池上限 50 → 线程数不应超过 50
内存检查：50 × 1MB = 50MB，在 2GB Pod 内可接受

最终决策：
  corePoolSize    = 50
  maximumPoolSize = 60
  queue           = LinkedBlockingQueue(300)
  keepAliveTime   = 60 秒
  拒绝策略         = 自定义（记录指标 + 抛异常）

代码实现：

@Bean("orderExecutor")
public ThreadPoolExecutor orderExecutor() {
    int cores = Runtime.getRuntime().availableProcessors();
    int effectiveCores = Math.min(cores, Integer.parseInt(
        System.getenv().getOrDefault("CPU_LIMIT", String.valueOf(cores))));

    int dbPoolSize = 50;
    int coreSize = Math.min(effectiveCores * 10, dbPoolSize);
    int maxSize = (int) (coreSize * 1.2);
    int queueCap = coreSize * 6;

    ThreadPoolExecutor executor = new ThreadPoolExecutor(
        coreSize, maxSize,
        60L, TimeUnit.SECONDS,
        new LinkedBlockingQueue<>(queueCap),
        new CustomThreadFactory("order-exec"),
        new MetricsRejectedHandler("order")
    );
    executor.allowCoreThreadTimeOut(false);
    return executor;
}

自定义拒绝处理器：

public class MetricsRejectedHandler implements RejectedExecutionHandler {
    private final String poolName;

    public MetricsRejectedHandler(String poolName) {
        this.poolName = poolName;
    }

    @Override
    public void rejectedExecution(Runnable r, ThreadPoolExecutor e) {
        Metrics.counter("threadpool.rejected", "pool", poolName).increment();
        log.error("[{}] 任务被拒绝，队列积压:{} 活跃线程:{} 最大线程:{}",
            poolName, e.getQueue().size(), e.getActiveCount(), e.getMaximumPoolSize());
        throw new RejectedExecutionException("Pool " + poolName + " is saturated");
    }
}

3、压测验证方案

阶梯加压节奏：

10 并发  → 稳定 2 分钟 → 记录基准
50 并发  → 稳定 2 分钟 → 记录吞吐 / RT / 队列深度
100 并发 → 稳定 2 分钟 → 观察是否积压
150 并发 → 稳定 2 分钟 → 观察 P99 劣化点
200 并发 → 稳定 2 分钟 → 寻找拒绝临界点

压测期间重点采集：

pool.getActiveCount();          // 当前活跃线程数
pool.getQueue().size();         // 排队任务数
pool.getCompletedTaskCount();   // 已完成任务总数
pool.getLargestPoolSize();      // 历史最大线程数
pool.getTaskCount();            // 提交的总任务数

十、动态线程池

1、动态调整原理

ThreadPoolExecutor 支持运行时修改核心参数：

executor.setCorePoolSize(newCoreSize);
executor.setMaximumPoolSize(newMaxSize);

结合 Apollo / Nacos 配置中心可实现秒级热更新。

2、实现示例

@Component
public class DynamicThreadPoolManager {

    @Autowired
    private ThreadPoolExecutor orderExecutor;

    @NacosConfigListener(dataId = "thread-pool-config", groupId = "DEFAULT_GROUP")
    public void onConfigChange(String configJson) {
        ThreadPoolConfig cfg = JSON.parseObject(configJson, ThreadPoolConfig.class);

        int newCore = cfg.getCoreSize();
        int newMax = cfg.getMaxSize();

        // 扩大时先改 max，缩小时先改 core
        if (newCore > orderExecutor.getMaximumPoolSize()) {
            orderExecutor.setMaximumPoolSize(newMax);
            orderExecutor.setCorePoolSize(newCore);
        } else {
            orderExecutor.setCorePoolSize(newCore);
            orderExecutor.setMaximumPoolSize(newMax);
        }

        log.info("线程池动态调整完成 pool=order core={} max={}", newCore, newMax);
    }
}

3、队列容量动态修改

标准 BlockingQueue 容量在构造时固定。如需动态队列，可选：

1. 自实现 ResizableLinkedBlockingQueue：重写 capacity setter，加锁保证并发安全。
2. 开源方案：
   • dynamic-tp（京东开源）：支持参数热更新、监控、告警一体化。
   • Hippo4j（美团团队维护）：企业级动态线程池框架，支持多注册中心。

十一、可观测性：监控与告警

1、Prometheus 指标暴露

public static void registerToPrometheus(ThreadPoolExecutor pool, String name) {
    MeterRegistry registry = Metrics.globalRegistry;

    Gauge.builder("threadpool.active", pool, ThreadPoolExecutor::getActiveCount)
         .tag("pool", name).description("活跃线程数").register(registry);

    Gauge.builder("threadpool.pool_size", pool, ThreadPoolExecutor::getPoolSize)
         .tag("pool", name).description("当前线程总数").register(registry);

    Gauge.builder("threadpool.queue_size", pool, p -> p.getQueue().size())
         .tag("pool", name).description("队列积压任务数").register(registry);

    Gauge.builder("threadpool.utilization", pool,
             p -> (double) p.getActiveCount() / p.getCorePoolSize())
         .tag("pool", name).description("核心线程利用率").register(registry);

    Gauge.builder("threadpool.largest_pool_size", pool, ThreadPoolExecutor::getLargestPoolSize)
         .tag("pool", name).description("历史最大线程数").register(registry);
}

2、AlertManager 告警规则

groups:
  - name: threadpool_alerts
    rules:
      - alert: ThreadPoolHighUtilization
        expr: threadpool_utilization > 0.85
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "线程池 {{ $labels.pool }} 利用率超过 85%"

      - alert: ThreadPoolQueueBacklog
        expr: threadpool_queue_size / threadpool_queue_capacity > 0.7
        for: 1m
        labels:
          severity: warning
        annotations:
          summary: "线程池 {{ $labels.pool }} 队列积压超过 70%"

      - alert: ThreadPoolRejection
        expr: increase(threadpool_rejected_total[1m]) > 0
        for: 0m
        labels:
          severity: critical
        annotations:
          summary: "线程池 {{ $labels.pool }} 出现任务拒绝"

      - alert: ThreadPoolMaxSizeReached
        expr: threadpool_pool_size >= threadpool_max_size
        for: 3m
        labels:
          severity: warning
        annotations:
          summary: "线程池 {{ $labels.pool }} 线程数触达最大值，持续 3 分钟"

3、告警阈值参考

十二、性能调优建议

1、线程数调优

• 初始值：使用 Goetz 公式或历史 QPS/RT 数据估算。
• 约束校验：确保 corePoolSize ≤ min(DB 连接池, HTTP 连接池, 内存可承载线程数)。
• 压测验证：以阶梯加压找到吞吐拐点，将 corePoolSize 设置在拐点并发量的 70%~80%。
• 动态调整：流量波动明显的服务接入动态线程池。

2、队列深度调优

• 队列容量不宜过大：过大会隐藏延迟问题，导致 P99 劣化。
• 经验公式：queueCapacity = corePoolSize × 平均 RT（秒） × 安全系数（2~3）。
• 需要背压的场景使用有界队列，拒绝策略选择 CallerRunsPolicy 或自定义策略。

3、GC 与内存调优

• 关注线程栈内存占用：默认 1MB/线程，可通过 -Xss 调整。
• 高频创建/销毁线程会增加 Native Memory 分配压力，尽量复用线程。
• 容器环境开启 -XX:+UseContainerSupport（JDK 8u191+）。

4、上下文切换调优

• 当 cs（上下文切换次数）/ 任务数 持续升高时，说明线程数过多。
• 使用 vmstat、pidstat -w 监控上下文切换频率。
• 在线程饱和前扩容机器或优化任务计算逻辑。

十三、常见问题解答（FAQ）

1、Q1：corePoolSize 和 maximumPoolSize 应该设成一样吗？

A：不一定。固定大小（core = max）适合负载稳定的场景，实现简单；弹性伸缩（core < max）适合流量波动大、需要应对突发的场景。生产环境更推荐后者，配合有界队列使用。

2、Q2：为什么线程池达到了 maximumPoolSize 但 CPU 使用率仍然很低？

A：可能原因：

1. 线程大部分时间阻塞在 IO 等待，CPU 未被有效利用；
2. 下游服务（数据库、缓存、HTTP 接口）成为瓶颈；
3. 锁竞争严重，线程实际并行度不足。

应通过 APM 或 Profiler 定位具体阻塞点，而不是简单增加线程数。

3、Q3：任务被拒绝时应该选择哪种策略？

A：核心链路推荐 AbortPolicy 或自定义策略（记录指标 + 抛异常），让调用方感知并降级；非核心但不可丢任务的场景可选 CallerRunsPolicy；可丢弃的非关键任务可选 DiscardPolicy 或 DiscardOldestPolicy。

4、Q4：使用 CompletableFuture 时如何指定自定义线程池？

A：CompletableFuture 默认使用 ForkJoinPool.commonPool()，可能不适合业务场景。应显式传入：

CompletableFuture.supplyAsync(() -> fetchOrder(orderId), orderExecutor)
    .thenApplyAsync(this::enrichOrder, orderExecutor);

5、Q5：Spring 的 @Async 默认线程池有什么问题？

A：Spring 默认使用 SimpleAsyncTaskExecutor，每次任务都新建线程，且队列无界。生产环境应通过 ThreadPoolTaskExecutor 自定义：

@Bean("taskExecutor")
public ThreadPoolTaskExecutor taskExecutor() {
    ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
    executor.setCorePoolSize(16);
    executor.setMaxPoolSize(32);
    executor.setQueueCapacity(200);
    executor.setThreadNamePrefix("async-");
    executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
    executor.initialize();
    return executor;
}

6、Q6：如何优雅关闭线程池？

A：使用 shutdown() + awaitTermination() 组合：

executor.shutdown();
try {
    if (!executor.awaitTermination(60, TimeUnit.SECONDS)) {
        executor.shutdownNow();
    }
} catch (InterruptedException e) {
    executor.shutdownNow();
    Thread.currentThread().interrupt();
}

7、Q7：allowCoreThreadTimeOut(true) 是否推荐？

A：适合流量波动极大的场景，可在低峰期回收核心线程节省资源。但会增加高峰期线程创建开销，核心链路建议保持默认 false。

十四、决策速查表

十五、总结

1. 永远不用 Executors 工厂方法，必须显式构造 ThreadPoolExecutor。
2. 必须使用有界队列，无界队列是 OOM 隐患。
3. corePoolSize 不超过下游最小连接池，这是物理约束。
4. 拒绝策略必须可观测，静默丢弃在生产环境等于数据黑洞。
5. 暴露监控指标并设置告警，线程池问题不能靠感觉发现。

合理工程流程：

flowchart LR
    A[公式估算] --> B[约束校验] --> C[压测验证] --> D[监控落地] --> E[动态调整]

十六、参考资料

• 《Java 并发编程实战》Brian Goetz
• 阿里巴巴《Java 开发手册》
• dynamic-tp
• Hippo4j