Oracle SHARED POOL RESERVED FREE LIST 配 TaoToken：settings.json 骨架与报错排查

1. 当 ORA-04031 撞上 RESERVED FREE LIST：一个 DBA 的真实排查现场

Oracle SHARED POOL 里的 RESERVED FREE LIST 是个容易被忽略、但一出事就很要命的东西。简单说，它是共享池里专门划出来的一块保留内存区域，用来兜底那些大块内存分配请求。当会话不断从 SHARED POOL 里拿内存，完整连续的空闲区域会越来越碎，这时候如果突然来个需要大块内存的请求，普通 FREE LIST 给不出来，就会去 RESERVED FREE LIST 里找。这个保留区的大小由SHARED_POOL_RESERVED_SIZE控制，最小 5000 字节，最大不能超过 SHARED POOL 的一半。

问题就出在这：不是所有对象都能进 RESERVED FREE LIST。只有大于隐含参数_shared_pool_reserved_min_alloc（默认 4400 字节）的 CURSOR 才有资格进去。所以你会看到一个很反直觉的现象——SHARED POOL 明明还有几百 MB 空闲，进程却报 ORA-04031 分配失败。典型报错长这样：

ORA-00604: error occurred at recursive SQL level 1 ORA-04031: unable to allocate 4116 bytes of shared memory ("shared pool","JOB$SYS","KGLS heap","KGLS MEM BLOCK")

注意这里要的是 4116 字节，低于 4400 的阈值，进不了保留区，而普通 FREE LIST 又碎得给不出连续 4116 字节，于是失败。这篇就围绕这个机制，把 RESERVED FREE LIST 的观察方法、参数调整，以及用 TaoToken 统一 Key 通道在 AI 工具侧做 settings.json 配置骨架、报错定位的完整流程讲清楚。适合正在处理共享池碎片、ORA-04031 的 DBA，以及想把 AI 编码工具接进日常运维工作流的人。

2. TaoToken 前置：统一 Key 与 API 通道准备

在动手排查之前，先把工具侧的接入通道搭好。TaoToken 在这里的角色是统一 Key 和 API 通道——你不用为每个 AI 工具单独管理一套凭证，一个 Key 走同一个 API 入口，排查脚本、日志分析助手、编码 Agent 都能复用。

先到官网注册并拿到 Key：

• 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API 基地址：https://taotoken.net/api （这个地址不加 UTM 参数）

拿 Key 的具体页面在 console 里：

• 控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

进去之后新建一个 Key，复制出来先存到环境变量里，别直接写死在配置文件里。我习惯这样：

export TAOTOKEN_API_KEY="sk-你的key"

验证 Key 是否可用，最直接的方式是走一次模型对话接口：

• 模型对话：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

如果你打算长期用 AI 做编码和 Agent 任务，比如让它帮你写 AWR 分析脚本、解析 trace 文件，那 Coding Plan 更划算：

• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

接入文档在这里，配置字段有疑问随时查：

• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

如果你用的是 Claude Code 这类工具，Anthropic 兼容通道的说明也单独有页：

• ClaudeCodeAnthropic：https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

3. settings.json 骨架：可复制的配置片段

AI 工具侧的 settings.json 是接入的核心。不同工具字段名略有差异，但骨架逻辑一致：base_url 指向 TaoToken 的 API 地址，api_key 从环境变量读，model 指定你要用的模型。下面给一份通用骨架，你可以直接复制改。

{ "api": { "base_url": "https://taotoken.net/api", "api_key": "${TAOTOKEN_API_KEY}", "timeout": 60, "max_retries": 3 }, "model": { "default": "claude-sonnet-4-20250514", "fallback": "gpt-4o-mini" }, "tools": { "coding_agent": { "enabled": true, "workspace": "./oracle_scripts", "auto_context": true } }, "logging": { "level": "info", "file": "./logs/taotoken_client.log" } }

几个关键点说明一下。base_url必须是https://taotoken.net/api，不要带末尾斜杠，也不要加 UTM 参数，否则部分客户端会拼接出错误路径。api_key用${TAOTOKEN_API_KEY}这种环境变量引用方式，避免 Key 泄漏到版本库。timeout设 60 秒是因为分析大 trace 文件时响应可能偏慢，设太短会频繁超时重试。

如果你用的是 Claude Code 的配置格式，字段名会变成ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这类环境变量风格，对应关系如下表：

配置写完后，先做一次语法校验，避免 JSON 格式错误导致工具启动失败：

python3 -c "import json;json.load(open('settings.json'));print('JSON OK')"

输出JSON OK就说明格式没问题。这一步看着简单，但实际排查中相当一部分“工具连不上”其实是 settings.json 多了个逗号或者少了引号。

4. 验证请求与成功结果：从 Key 到 ORA-04031 定位

配置就绪后，先验证 API 通道是否通。用 curl 打一次模型对话接口：

curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer ${TAOTOKEN_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "ping"}] }' | head -c 300

返回里能看到choices字段和内容，就说明 Key 和通道都正常。如果返回 401，检查 Key 是否复制完整；返回 404，检查 base_url 是不是写成了带路径的地址。

通道通了之后，回到 Oracle 侧。观察 RESERVED FREE LIST 状态，10.2 之前因为 BUG 3669074，直接查V$SHARED_POOL_RESERVED可能不准，用下面这个脚本更稳：

select p.inst_id, p.free_space, p.avg_free_size, p.free_count, p.max_free_size, p.used_space, p.avg_used_size, p.used_count, p.max_used_size, s.requests, s.request_misses, s.last_miss_size, s.max_miss_size, s.request_failures, s.last_failure_size, s.aborted_request_threshold, s.aborted_requests, s.last_aborted_size from (select avg(x$ksmspr.inst_id) inst_id, sum(decode(ksmchcls,'R-free',ksmchsiz,0)) free_space, avg(decode(ksmchcls,'R-free',ksmchsiz,0)) avg_free_size, sum(decode(ksmchcls,'R-free',1,0)) free_count, max(decode(ksmchcls,'R-free',ksmchsiz,0)) max_free_size, sum(decode(ksmchcls,'R-free',0,ksmchsiz)) used_space, avg(decode(ksmchcls,'R-free',0,ksmchsiz)) avg_used_size, sum(decode(ksmchcls,'R-free',0,1)) used_count, max(decode(ksmchcls,'R-free',0,ksmchsiz)) max_used_size from x$ksmspr where ksmchcom not like '%reserved sto%') p, (select sum(kghlurcn) requests, sum(kghlurmi) request_misses, max(kghlurmz) last_miss_size, max(kghlurmx) max_miss_size, sum(kghlunfu) request_failures, max(kghlunfs) last_failure_size, max(kghlumxa) aborted_request_threshold, sum(kghlumer) aborted_requests, max(kghlumes) last_aborted_size from x$kghlu) s;

重点看request_failures和last_failure_size。如果request_failures是 2110 这种量级，last_failure_size是 4192，说明失败请求的大小低于默认阈值 4400，进不了保留区。这时候把_shared_pool_reserved_min_alloc调到 4100：

alter system set "_shared_pool_reserved_min_alloc"=4100 scope=spfile;

改完需要重启实例生效。重启后再跑一次上面的查询，观察request_failures是否停止增长。同时可以 dump 堆来确认 RESERVED FREE LIST 的桶分布：

alter session set events 'immediate trace name heapdump level 2';

在生成的 trace 文件里搜RESERVED FREE LISTS，能看到类似这样的桶结构：

RESERVED FREE LISTS: Reserved bucket 0 size=16 Reserved bucket 1 size=4400 Reserved bucket 2 size=8204 ... Reserved bucket 14 size=7968764 Total reserved free space = 3358260

Total reserved free space如果远小于SHARED_POOL_RESERVED_SIZE，说明保留区本身也碎得厉害，可能需要考虑调大SHARED_POOL_RESERVED_SIZE或者减少硬解析。

5. 本篇常见错排查

报错一：ORA-04031 但 SHARED POOL 明明有空闲。这是最典型的。原因就是请求大小没到_shared_pool_reserved_min_alloc阈值，进不了保留区，而普通 FREE LIST 碎片化严重给不出连续块。排查动作：查V$SHARED_POOL_RESERVED的last_failure_size，对比阈值，决定是否下调_shared_pool_reserved_min_alloc。

报错二：settings.json 改了但工具不生效。大概率是环境变量没导出，或者工具读的是另一个路径的配置文件。先确认echo $TAOTOKEN_API_KEY有输出，再用find . -name settings.json确认工具实际加载的文件位置。

报错三：API 返回 401 或 403。Key 复制时带了空格，或者用了已删除的 Key。到 API Keys 页面重新生成一个，注意复制时不要带首尾空白。

报错四：10.2 之前查 V$SHARED_POOL_RESERVED 结果异常。这是 BUG 3669074 导致的，别用这个视图，改用第 4 节里基于x$ksmspr和x$kghlu的脚本。

报错五：调整隐含参数后实例起不来。_shared_pool_reserved_min_alloc不能设得比SHARED_POOL_RESERVED_SIZE还大，也不能小于 0。改之前先确认当前值：

select a.ksppinm, b.ksppstvl from x$ksppi a, x$ksppcv b where a.indx = b.indx and a.ksppinm = '_shared_pool_reserved_min_alloc';

报错六：硬解析多导致 SHARED POOL LATCH 争用。这是另一个层面的问题，从 9i 开始共享池可以分多个子池（最多 7 个）来缓解。可以查V$SHARED_POOL_ADVICE看建议的保留区大小，结合子池数量一起调。

6. 把工具接入和报错定位串成一条线

实际运维里，我建议把 AI 工具直接接进排查流程：让模型帮你解析 trace 文件里的RESERVED FREE LISTS段落，或者根据V$SHARED_POOL_RESERVED的输出来判断该调哪个参数。这时候统一 Key 的价值就体现出来了——同一个 Key 既能跑编码 Agent 写分析脚本，又能走模型对话做日志解读，不用来回切换凭证。

长期做这类工作的，Coding Plan 比按次调用更省心：

• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

如果只是偶尔验证一下模型输出，用模型对话页面就够了：

• 模型对话：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

配置字段拿不准的时候，接入文档里对 base_url、鉴权头、超时参数都有说明：

• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

最后提醒一句：_shared_pool_reserved_min_alloc是隐含参数，调整前先在测试库验证，生产库改完记得记录变更。RESERVED FREE LIST 的桶分布和request_failures的增长趋势，比单次查询的绝对值更有参考价值——盯趋势，别盯快照。