Oracle 23ai 的 Phantom Vector Memory 故障排除指南

发布: 1周前 (2025年12月17日 GMT+8 15:41)

14 min read

I’m happy to translate the article for you, but I’ll need the text of the article itself. Could you please paste the content you’d like translated (excluding the source link you’ve already provided)? Once I have the text, I’ll translate it into Simplified Chinese while preserving the formatting, markdown, and technical terms.

预飞检查清单

在我们滑行到跑道之前，这里是你的飞行计划。请随时查阅，以便顺利导航你的飞行路径。欢迎登上云端！

先决条件
Oracle 架构快速入门
任务：分配向量内存
第一次尝试：ALTER SYSTEM
障碍：两层问题
突破：docker exec 恢复
证明：信任启动日志，而非参数
理解 Oracle 参数和内存视图
恢复速查表
结论
“IAM 策略”：为何我们的 dev 用户需要授权

Introduction

作为我在 Oracle Cloud Infrastructure（OCI）及其强大数据库功能方面工作的组成部分，我一直在深入研究 Oracle Database 23ai 中全新的 AI Vector Search 功能。免费容器化版本是进行此类实验的完美实验室。

要开始使用高性能的 HNSW 索引，需要通过设置 vector_memory_size 参数来分配专用内存池。一次 SQL 命令加一次重启，就把我带入了充满神秘错误、误导性输出以及被锁定的数据库的“兔子洞”。这场精彩的故障排查过程让我对 Oracle 多租户架构的内部工作原理，尤其是免费版，有了宝贵的认识。

如果你曾经盯着顽固显示为 0 的 vector_memory_size，或是与恼人的 ORA‑12514 错误搏斗过，那么这篇我的故障排查日志正是为你准备的。

假设

你已经按照《The Ultimate Guide to Oracle 23ai on Apple Silicon》中描述的方式，安装并运行了 Oracle 23ai Free 容器。

第 1 部分 的环境已经启动并运行。如果你还没有设置 dev 用户，请在此暂停并返回去完成设置。

Oracle 术语速查

了解这些概念对于弄清问题产生的原因以及解决方案的工作原理至关重要。

Term	Description
CDB (Container Database)	主数据库，管理整个实例。在免费容器中其名称为 FREE。开发时很少直接连接此处，但主要的配置（例如内存分配）最终在这里管理。
PDB (Pluggable Database)	在 CDB 内部运行的独立、隔离的数据库。所有应用开发都连接到 PDB。我们案例中其名称为 FREEPDB1。ORA‑12514 错误发生是因为当主 CDB 实例宕机时该 PDB 不可用。
SGA (System Global Area)	数据库实例用于存储数据和控制信息的共享内存区域。当我们设置 `vector_memory_size` 时，告诉 Oracle 在 SGA 中专门划出一块用于向量索引。STARTUP 日志显示了 SGA 的实际组成，这也是它比 `SHOW PARAMETER` 命令更可靠的原因。

任务：分配向量内存

第一步是通过设置 vector_memory_size 参数，告诉 Oracle 为 AI 向量搜索预留专用的 RAM。

⚡ 注意
23ai 免费版的 RAM 限制为 2 GB。为向量分配过多内存可能会导致其他关键数据库进程资源不足。将其设置为 1 GB（≈ 总内存的 50 %）风险较大。更明智的做法是使用更保守的数值。

我决定从 500 M 开始。

ALTER SYSTEM

-- Connect using my sql-sys alias or as SYS
ALTER SYSTEM SET vector_memory_size = 500M SCOPE = SPFILE;

系统返回了令人安心的 “System altered.” 为使更改生效，需要重启数据库。使用 Docker 时最简单的方法是重启容器本身：

docker restart oracle-free

本应在此结束旅程。但实际上，这里才是麻烦的开始。

Source: …

第一道墙：权限

在容器重新启动后，开发者的自然第一步是以日常使用的 dev 用户连接，并检查 vector_memory_size 参数是否已生效。

-- 从第 1 部分以 dev 用户连接
SQL> SHOW PARAMETER vector_memory_size;
ORA-00942: table or view does not exist

教训 #1 – 我们的 dev 用户（拥有基本的 CONNECT 和 RESOURCE 角色）可以创建表，但 无法查看实例级别的配置。这是一项安全特性，而非错误。

切换到 SYS

-- 现在以 SYS 身份连接（例如，通过 sql-sys 别名）
SQL> SHOW PARAMETER vector_memory_size;

NAME                 TYPE          VALUE
-------------------  ------------  ------------------------------
vector_memory_size   big integer   0

值仍然是 0 —— 我们的修改似乎已经消失。

第二层墙：配置层

-- 1️⃣ Check current container name
SQL> SHOW CON_NAME;

CON_NAME
--------
FREEPDB1

-- 2️⃣ Check if the parameter is PDB‑modifiable
SQL> SELECT NAME, ISPDB_MODIFIABLE
     FROM V$SYSTEM_PARAMETER
     WHERE NAME = 'vector_memory_size';

NAME                ISPDB_MODIFIABLE
------------------- ----------------
vector_memory_size  TRUE

解释 – 我连接的是 PDB (FREEPDB1)，并且该参数是可在 PDB 中修改的。然而 SHOW PARAMETER 仍然显示 0。存储的参数值与实际运行时分配之间的这种不一致是 Oracle Free 版的常见怪现象。

Source:

`dev` 用户的权限修复

非管理员用户需要显式授权才能查询 SHOW PARAMETER 所依赖的数据字典视图。

-- 以 SYS 身份运行
GRANT SELECT ON SYS.V_$PARAMETER          TO dev;
GRANT SELECT ON SYS.V_$SYSTEM_PARAMETER   TO dev;
GRANT CREATE INDEX                       TO dev;

这些授权允许 dev 用户查询由 SYS 拥有的 V$PARAMETER 和 V$SYSTEM_PARAMETER。

突破：使用 `docker exec` 检查启动日志

不再依赖 SHOW PARAMETER，我在容器内部检查了 启动日志，该日志准确反映了 SGA 的组成。

docker exec -it oracle-free bash
# Inside the container
cat $ORACLE_BASE/diag/rdbms/*/*/trace/alert*.log | grep -i vector_memory_size

日志显示向量内存池已正确分配为 500 M，证实 ALTER SYSTEM 命令已成功；问题仅在于 dev 会话的可见性。

恢复速查表

步骤	命令	目的
1	`ALTER SYSTEM SET vector_memory_size=500M SCOPE=SPFILE;`	持久地设置向量内存大小。
2	`docker restart oracle-free`	应用更改。
3	`SHOW CON_NAME;`	验证您已连接到正确的容器（CDB 与 PDB）。
4	`SELECT NAME, VALUE FROM V$PARAMETER WHERE NAME='vector_memory_size';`	检查存储的值（需要授权）。
5	`docker exec -it oracle-free cat $ORACLE_BASE/diag/rdbms///trace/alert*.log \| grep -i vector_memory_size`	通过启动日志验证运行时分配。
6	Grants (run as SYS)	`GRANT SELECT ON SYS.V_$PARAMETER TO dev;` `GRANT SELECT ON SYS.V_$SYSTEM_PARAMETER TO dev;` `GRANT CREATE INDEX TO dev;`
7	Re‑connect as `dev` and re‑run `SHOW PARAMETER`	确认授权后可见性。

结论

vector_memory_size 参数已应用；看似 “零” 值实际上是可见性问题导致的，原因包括：
1. 连接到 PDB 而不是 CDB。
2. dev 用户权限不足，无法查询底层 V$ 视图。
启动日志 是确认 Oracle 23ai Free 版内存分配的最可靠来源。
为 dev 用户授予相应的 SELECT 权限即可解决 “参数不可见” 的症状，使开发人员能够在无需完整 SYS 权限的情况下继续工作。

“IAM 策略”：为什么我们的 `dev` 用户需要 GRANT 权限

在 OCI 中，IAM 策略控制用户在云层面的操作权限，但在数据库内部我们仍然需要 SQL 级别的授权 来访问数据字典。dev 用户需要对 SYS.V_$PARAMETER 和 SYS.V_$SYSTEM_PARAMETER 进行显式的 SELECT 授权，以读取配置值，并且需要 CREATE INDEX 权限才能实际创建向量索引。

祝旅途愉快！

现在你拥有了一条清晰、可复现的路径来分配向量内存、进行验证，并避免常见的陷阱——这些陷阱可能让你面对 ORA‑12514 错误或神秘的 “0” 值。祝旅途安全！ 🚀

概览

以下记录了对一个 Oracle Free Docker 容器的故障排查过程，该容器在进行 CDB 范围的配置更改后变得不可用。

问题

在 CDB 根层应用 向量内存 更改并执行完整的 SHUTDOWN/STARTUP 后，实例未能启动：

Database closed.
Database dismounted.
ORACLE instance shut down.
ERROR:
ORA-12514: Cannot connect to database. Service freepdb1 is not registered with
the listener at host 127.0.0.1 port 1521.

使用 sql-sys 别名尝试重新连接时出现相同错误：

>>> sql-sys 

Copyright (c) 1982, 2025, Oracle. All rights reserved. 
ERROR: ORA-12514: Cannot connect to database. 
Service freepdb1 is not registered with the listener at host 127.0.0.1 port 1521. 
(CONNECTION_ID=Qgik7CZCByPgYwIAEaywBw==) 
Help: https://docs.oracle.com/error-help/db/ora-12514/ 

Enter user-name:

快速检查 Docker 容器状态确认了问题：

docker ps

状态
Up 19 minutes (unhealthy)

容器被标记为 unhealthy，表明内部数据库未完全运行。

ORA‑12514 真正的含义

ORA‑12514 表示服务名（freepdb1）未向监听器注册。这通常发生在以下情况：

CDB 实例已停止，或
可插拔数据库 (PDB) 已关闭。

在免费版中，CDB 重启后 PDB 不会自动打开，所以 FREEPDB1 保持关闭状态，未向监听器注册。

注意 – 在第 1 部分我们重启了容器，这也导致 PDB 被关闭。因此我们现在必须手动打开它。

恢复步骤

1. 以 `SYSDBA` 重新进入容器

docker exec -it oracle-free sqlplus / as sysdba

您将看到：

Connected to an idle instance.

2. 启动数据库

STARTUP;

3. 打开可插拔数据库

ALTER PLUGGABLE DATABASE ALL OPEN;

4. （可选）切换到您的 PDB

ALTER SESSION SET CONTAINER = FREEPDB1;

5. 验证向量内存分配

SELECT pool, alloc_bytes, used_bytes
FROM V$VECTOR_MEMORY_POOL;

6. 验证整体 SGA 分布

SHOW SGA;

授权语句（参考）

这些 GRANT 语句为开发人员提供所需的特定只读访问权限，而无需将其设为管理员。

GRANT SELECT ON v$vector_memory_pool TO dev_user;
GRANT SELECT ON v$pdbs               TO dev_user;
GRANT SELECT ON v$system_parameter   TO dev_user;

TL;DR

Shutdown CDB 导致 PDB 关闭 → 监听器无法注册 FREEPDB1。
以 SYSDBA 重新进入容器，STARTUP 实例。
打开 PDB（ALTER PLUGGABLE DATABASE ALL OPEN）。
通过 V$VECTOR_MEMORY_POOL 和 SHOW SGA 验证向量内存分配情况。

向量内存池现已正确分配（约 512 MB），数据库已全面正常运行。

理解 Oracle 向量内存视图

`V$PARAMETER`

显示系统参数的预期配置。ISPDB_MODIFIABLE 列指示参数是否可以在 PDB 级别进行更改。

`V$SYSTEM_PARAMETER`

与 V$PARAMETER 类似，但显示当前会话的实际值。对于像 vector_memory_size 这样的系统级参数，其值通常会与 V$PARAMETER 中的相同。

`V$SGA`

提供 系统全局区 (SGA) 各组件及其大小的细分。成功使用配置好的 vector_memory_size 启动后，应该能看到列出 Vector Memory Area 以及其分配的大小。

SQL> SHOW SGA;

示例摘录

Total System Global Area   1603373280 bytes
Fixed Size                  5007584 bytes
Variable Size             352321536 bytes
Database Buffers          704643072 bytes
Redo Buffers                4530176 bytes
Vector Memory Area        536870912 bytes

`V$VECTOR_MEMORY_POOL`

确认 活动向量内存分配 的最直接来源。

SELECT pool, alloc_bytes, used_bytes
FROM V$VECTOR_MEMORY_POOL;

如果此视图显示了您配置的大小，则可以确信向量搜索内存已处于激活状态。

当出现 ORA‑12514 锁定时的恢复步骤

检查 Docker 容器状态（可能不健康）。
```
docker ps
```

连接到空闲实例

docker exec -it oracle-free sqlplus / as sysdba

启动数据库
```
STARTUP;
```
打开可插拔数据库
```
ALTER PLUGGABLE DATABASE ALL OPEN;
```

（可选）验证向量内存池分配

SELECT pool, alloc_bytes, used_bytes
FROM V$VECTOR_MEMORY_POOL;

（可选）验证整体 SGA 分布
```
SHOW SGA;
```

⚡️ 权限说明

上述故障排除步骤是使用 SYSDBA 权限执行的。这体现了 最小特权原则：

日常开发人员不应有权限修改系统参数或重启数据库。
管理任务保留给超级用户，以确保安全的工作流，将实验性访问与运营性访问分离。

关键要点

信任 startup log、V$SGA 和 V$VECTOR_MEMORY_POOL，它们提供了 SGA 中实际发生情况的真实信息。
SHOW PARAMETER 和 V$SYSTEM_PARAMETER 对于预期配置很有用，但启动顺序和直接的内存池查询揭示了真实的运行时分配。
了解 CDB 和 PDB 的角色，并掌握 Docker‑exec 工作流，可防止被锁定并简化向量内存的供应。

Oracle 23ai 的 Phantom Vector Memory 故障排除指南

预飞检查清单

目录

Introduction

Oracle 术语速查

任务：分配向量内存

ALTER SYSTEM

第一道墙：权限

切换到 SYS

第二层墙：配置层

`dev` 用户的权限修复

突破：使用 `docker exec` 检查启动日志

恢复速查表

结论

“IAM 策略”：为什么我们的 `dev` 用户需要 GRANT 权限

祝旅途愉快！

概览

问题

ORA‑12514 真正的含义

恢复步骤

1. 以 `SYSDBA` 重新进入容器

2. 启动数据库

3. 打开可插拔数据库

4. （可选）切换到您的 PDB

5. 验证向量内存分配

6. 验证整体 SGA 分布

授权语句（参考）

TL;DR

理解 Oracle 向量内存视图

`V$PARAMETER`

`V$SYSTEM_PARAMETER`

`V$SGA`

`V$VECTOR_MEMORY_POOL`

当出现 ORA‑12514 锁定时的恢复步骤

⚡️ 权限说明

相关文章

用构建真实项目取代手机成瘾

仓库利用的权威指南

CinemaSins：18分钟内揭露《Red One》的一切错误

摄取1亿次心跳：在不破产的情况下扩展可穿戴技术

预飞检查清单

目录

Introduction

Oracle 术语速查

任务：分配向量内存

ALTER SYSTEM

第一道墙：权限

切换到 SYS

第二层墙：配置层

dev 用户的权限修复

突破：使用 docker exec 检查启动日志

恢复速查表

结论

“IAM 策略”：为什么我们的 dev 用户需要 GRANT 权限

祝旅途愉快！

概览

问题

ORA‑12514 真正的含义

恢复步骤

1. 以 SYSDBA 重新进入容器

2. 启动数据库

3. 打开可插拔数据库

4. （可选）切换到您的 PDB

5. 验证向量内存分配

6. 验证整体 SGA 分布

授权语句（参考）

TL;DR

理解 Oracle 向量内存视图

V$PARAMETER

V$SYSTEM_PARAMETER

V$SGA

V$VECTOR_MEMORY_POOL

当出现 ORA‑12514 锁定时的恢复步骤

⚡️ 权限说明

相关文章

用构建真实项目取代手机成瘾

仓库利用的权威指南

CinemaSins：18分钟内揭露《Red One》的一切错误

摄取1亿次心跳：在不破产的情况下扩展可穿戴技术

`dev` 用户的权限修复

突破：使用 `docker exec` 检查启动日志

“IAM 策略”：为什么我们的 `dev` 用户需要 GRANT 权限

1. 以 `SYSDBA` 重新进入容器

`V$PARAMETER`

`V$SYSTEM_PARAMETER`

`V$SGA`

`V$VECTOR_MEMORY_POOL`