Oracle APEX 5.1安装全攻略：从数据库脚本到ORDS部署与排查

说起 Oracle APEX 5.1 的安装，很多人的第一反应是下载一个 zip 包，解压之后双击安装。等你真正动起手来才会发现，这个备受很多团队偏爱的低代码开发平台，本质上是一堆住在 Oracle 数据库里的表、包和视图，根本没有传统意义的图形安装界面。这篇文章直接给你们一条可以照着抄的安装路径，从部署方式选型、数据库侧脚本执行、ORDS 服务搭建，到常见的异常排查，一次说完整。适合正在接手 APEX 项目的 DBA、运维和全栈开发。

APEX 5.1 是一个很重要的基线版本，我见过不少生产系统直到现在还在跑 5.1，日常维护和大版本升级都绕不开它。如果你像我一样，经常在“装完就忘、忘了再查手册”的状态里反复折腾，那这份手册对你尤其有用——因为我会把脚本参数、表空间规划、ORDS 配置里那些文档不会明说的坑都摊开讲清楚。

1. 安装前，先把架构、版本和方案一次想清楚

APEX 的特殊之处在于，它不是一个独立运行的中间件，而是安装在 Oracle 数据库内部的一组数据字典对象。这意味着你安装 APEX 的时候，本质上是在向目标数据库执行一个庞大的 SQL 脚本集合，把 APEX 引擎、元数据、内置应用、示例数据集全部灌进去。外部再通过一个 HTTP 网关，把用户的浏览器请求转换成数据库内部的 PL/SQL 调用。

这种架构决定了安装方案的选型比安装本身更重要。很多人装到一半发现问题，最后往往不是脚本失败，而是网关方案从一开始就没选对。

1.1 版本和运行机制先对齐

Oracle APEX 5.1 官方支持 Oracle Database 11.2 及以上版本，包括标准版、企业版和 Express Edition。字符集方面，最稳妥的选择是 AL32UTF8，如果目标库是 ZHS16GBK 也不是完全不能跑，但后续做国际化或者升级高版本 APEX 时，会遇到一些编码相关的迁移成本，建议有条件还是统一到 AL32UTF8。

APEX 的表结构、包定义、应用元数据都存在数据库里，安装过程中还会往数据库的 JVM 里灌一些 Java 存储过程，用于分析和打印服务。所以目标数据库需要开启 Java 虚拟机组件。你在执行安装脚本前，最好用一条 SQL 确认一下数据库的组件情况：

SELECT comp_name, version, status FROM dba_registry WHERE comp_name LIKE '%JAVA%' OR comp_name LIKE '%APEX%';

如果 Java 组件状态不是 VALID，后续执行apexins.sql时会报类似 ORA-06553 的错误，让人误以为是脚本问题。这个检查在安装前做，能省掉很多不必要的折腾。

还有一个容易忽略的点：APEX 5.1 的主 schema 名是APEX_050100，安装完成后这个 schema 会出现在数据库中。DBA 做权限规划时不要随意锁定或删除它，否则 APEX 引擎会直接罢工。

1.2 三种网关方案，别一上来就选 EPG

APEX 本身不直接监听 HTTP 端口，它需要一个“翻译官”把浏览器的请求转发到数据库内部。常见的选择有三种：嵌入式 PL/SQL 网关 EPG、Oracle REST Data Services ORDS、Oracle HTTP Server 加 mod_plsql。

我当时第一次装 APEX 就图省事选了 EPG，开发机器上用得很舒服，等到要上生产环境时发现无法满足并发和统一纳管，又把整套方案推翻重来。所以我的建议很直接：如果是自己电脑上玩，用 EPG 没问题；只要这台机器将来要给别人访问，直接上 ORDS，别绕路。

1.3 安装前需要核对的环境参数

数据库参数里最影响 APEX 体验的是共享池、Java 池和 PGA 大小。APEX 是典型的元数据驱动应用，运行时会把大量页面定义、region 定义解析到共享池，共享池太小会导致页面响应慢、频繁出现内部错误。

我建议安装前至少检查这几个参数：

SELECT name, value, isdefault FROM v$parameter WHERE name IN ('shared_pool_size', 'java_pool_size', 'pga_aggregate_target', 'db_block_size');

如果共享池小于 300M，建议先调大。比如在一个 4G SGA 的测试库里，我会把共享池调到 500M，Java 池调到 128M，这样能明显减少 APEX 页面切换时的卡顿。表空间则要提前准备，虽然 APEX 安装脚本允许你把对象放到 SYSAUX，但更推荐建独立表空间，方便备份、迁移和空间审计。

磁盘方面，APEX 5.1 的安装包解压后接近 1G，数据库 schema 对象安装完大概占用 500M 到 800M 空间，再加上以后的业务数据、工作表空间，最好预留 3G 以上可用空间。不要小看这个数字，我见过有人用 512M 的 /u01 分区装 APEX，装到一半磁盘直接被打满，整个环境处于不可用状态。

2. 数据库侧安装：从解压到跑完脚本的完整动作

这一节是数据库侧的安装骨架。APEX 的安装命令并不复杂，但每一步都有它存在的意义，少跑一个脚本，后面就可能多排查半小时。

2.1 先把安装包解压到服务器，认准目录结构

从官网下载的apex_5.1.zip，解压后对应到一个apex目录。你可以放在任意 DBA 有权限的路径下，但建议统一放到 ORACLE 安装目录之外，比如/u01/soft/apex，避免和数据库软件目录混在一起。

mkdir -p /u01/soft unzip apex_5.1.zip -d /u01/soft/ ls -l /u01/soft/apex

解压后的apex目录里，apexins.sql是核心安装脚本，apxchpwd.sql用于配置 APEX 内置管理员密码，apex_rest_config.sql用于创建 RESTful Service 所需的用户，apex_epg_config.sql则是用来配嵌入式网关的。还有一个images子目录，这个目录会被 APEX 页面作为静态资源目录引用，后面会反复提到。

这里要给一个操作习惯：安装前先确认你当前用户的权限。APEX 的核心脚本必须由具有 DBA 角色或 SYSDBA 权限的用户执行，普通 schema 用户跑来跑脚本，会在第一步就报一堆权限不足。通常我们用sqlplus / as sysdba进入，也可以用具有 SYSDBA 权限的专用账号。

2.2 建表空间：宁可多建一个，不要硬挤 SYSAUX

很多安装文档会直接让你跑@apexins.sql SYSAUX SYSAUX TEMP /i/，把 APEX 对象全部塞进 SYSAUX。这样的确能减少建表空间的步骤，但生产环境我不建议这么干。原因很简单：SYSAUX 是数据库自身管理组件常用的表空间，APEX 对象多而且有大量 LOB 文件，和数据库组件挤在一起，后续做表空间管理、空间回收、迁移的时候会很被动。

我比较推荐 5.1 安装时创建三个对象，一个主表空间、一个文件表空间、一个临时表空间：

CREATE TABLESPACE apex_main_ts DATAFILE '/u01/app/oracle/oradata/ORCL/apex_main_01.dbf' SIZE 1G AUTOEXTEND ON NEXT 200M MAXSIZE 3G; CREATE TABLESPACE apex_files_ts DATAFILE '/u01/app/oracle/oradata/ORCL/apex_files_01.dbf' SIZE 500M AUTOEXTEND ON NEXT 100M MAXSIZE 2G; CREATE TEMPORARY TABLESPACE apex_temp_ts TEMPFILE '/u01/app/oracle/oradata/ORCL/apex_temp_01.dbf' SIZE 200M AUTOEXTEND ON NEXT 50M MAXSIZE 1G;

如果你在容器数据库环境里，改成在对应 PDB 内执行。表空间名称可以自定义，但一定要把路径规划好，特别是AUTOEXTEND的MAXSIZE，别让数据文件无限扩大。APEX 安装过程中会产生大量中间对象，临时表空间不够会导致安装脚本中途失败，这部分不能省。

2.3 执行 apexins.sql，看懂四个参数再回车

进入apex目录后用 SQL*Plus 连接数据库，开始执行安装脚本：

cd /u01/soft/apex sqlplus / as sysdba @apexins.sql apex_main_ts apex_files_ts apex_temp_ts /i/

这里四个参数分别是 APEX 数据表空间、APEX 文件表空间、临时表空间、Images 虚拟目录前缀。最后一个/i/是 URL 前缀，不是本地路径，这个很容易混淆。APEX 页面里引用的图片路径默认以/i/开头，之后由网关把请求映射到真实的images目录。

脚本执行期间不要中断，也不要同时开其他 DDL 操作。它会创建上百个对象、执行大量 PL/SQL 包，正常情况下会跑几分钟到十几分钟。执行完后，屏幕上会有Application Express ... installed类似的提示，同时生成一个install.log文件。我习惯在跑完后先看一遍末尾有没有ORA-字样，确认没有隐藏错误再继续配置管理员密码。

2.4 配置管理员密码和 RESTful Service 用户

安装脚本跑完不等于 APEX 可用，还要执行三个配套脚本。

第一个是管理员密码脚本：

@apxchpwd.sql

它会提示你输入新管理员密码。这个密码是 APEX 实例管理员的密码，不是数据库密码，后面通过/ords/apex_admin登录时就靠它。密码建议至少 8 位，包含大小写和数字，和数据库账号密码分开管理。

第二个是 RESTful Service 配置脚本：

@apex_rest_config.sql

脚本会创建APEX_LISTENER和APEX_REST_PUBLIC_USER两个数据库用户，并让你分别设置这两个用户的密码。密码要记住并记录在专门的密码文件里，ORDS 配置时会用到。如果以后要升级 APEX，这两个用户的密码是否一致也会影响升级效率，所以最好一开始就统一规范。

第三个是 EPG 专用脚本，如果你打算用嵌入式网关验证环境，可以执行：

@apex_epg_config.sql /u01/soft/apex

注意这里传的参数是解压后的apex目录路径，脚本会自动找到下面的images子目录。它会把 HTTP 请求的/i/路径映射到服务器上的静态文件目录，同时创建访问控制。这个脚本可以在有“XDB”组件且开了 HTTP 服务的标准版数据库上运行，Oracle XE 尤其常见。

2.5 如何用脚本验证数据库侧有没有装对

有些同事喜欢装完直接开浏览器，没问题，但我更习惯先做一层数据库侧的验证，免得把“网络配置问题”和“APEX 安装问题”搅在一起。

用 SYSDBA 身份查一下几个关键 schema 是否存在：

SELECT username, account_status FROM dba_users WHERE username IN ('APEX_050100', 'APEX_PUBLIC_USER', 'APEX_LISTENER', 'APEX_REST_PUBLIC_USER');

正常情况下APEX_050100和APEX_PUBLIC_USER都会存在，状态为 OPEN。APEX_LISTENER和APEX_REST_PUBLIC_USER也会存在，但要确认不是 LOCKED。如果 APEX_PUBLIC_USER 被锁住，后面 ORDS 或者 EPG 调用时会出现 503 或认证失败类错误。

再查一下版本视图确认安装完成的版本：

SELECT version_no FROM apex_release;

这里显示的应该是 5.1.x。如果只能查到旧版或者查不到数据，说明安装脚本没有执行完，回头继续查install.log才是正路。数据库侧验证通过后，再进入网关配置，问题就会清晰很多。

3. 更推荐的 ORDS 部署方式：生产环境该这样搭

数据库侧的 APEX 对象装好后，生产环境下一步就是搭 ORDS。ORDS 本质是一个运行在 Java 环境里的轻量 HTTP 服务，它负责接收浏览器请求、认证用户、调用 APEX 的 PL/SQL 包，然后把 HTML 页面返回给浏览器。

3.1 准备 JDK 和 ORDS 安装包

APEX 5.1 年代的 ORDS，一般选 3.0.x 版本，太新的 ORDS 可能和 APEX 5.1 的 RESTful 接口有兼容性差异。ORDS 需要 JDK 8 及以上版本，我建议装一个独立的 JDK 8，避免和系统里其他 Java 应用抢默认版本。

export JAVA_HOME=/usr/java/jdk1.8.0_202 export PATH=$JAVA_HOME/bin:$PATH java -version

确认java -version输出正常后，把ords.war放到/u01/ords目录，并创建 ORDS 配置目录：

mkdir -p /u01/ords/{config,logs} export ORDS_CONFIG=/u01/ords/config

这个ORDS_CONFIG环境变量很重要，后面每次启动 ORDS 都要用它，不然 ORDS 会把配置写到$HOME/.ords下，换用户启动时配置就找不到了。养成习惯，把配置目录明确化。

3.2 初始化 ORDS 并回答数据库连接问题

第一次启动 ORDS 时会进入引导式配置，它会询问数据库连接信息、APEX 公共用户密码、静态资源目录等。命令行下的交互提示并没有那么友好，我一般先把配置目录绑定好：

java -jar ords.war configdir /u01/ords/config java -jar ords.war

接下来按提示依次填写数据库主机名、监听端口、服务名、数据库用户名和密码。注意这里的“服务名”通常是你数据库的SERVICE_NAME，不是 SID。如果填错，ORDS 启动后会报 ORA-12514，提示监听不识别服务。想确认服务名可以直接在数据库上执行：

SELECT value FROM v$parameter WHERE name = 'service_names';

配置过程中还会让你配置 APEX 静态资源目录，指向之前解压目录的images子目录即可，例如/u01/soft/apex/images。确认完成后，ORDS 会生成defaults.xml和apex_pu.xml等配置文件，保存数据库连接信息。

3.3 Standalone 模式快速启动和验证

对于大多数中小项目，Standalone 模式已经够用。它不需要外部 Tomcat，ORDS 自己监听一个端口，默认是 8080。启动命令：

java -jar ords.war standalone

看到类似INFO: Oracle REST Data Services initialized的输出，然后打开浏览器访问http://服务器IP:8080/ords/，如果一切正常，会返回一个 ORDS 欢迎页或者 APEX 登录页。这时可以通过http://服务器IP:8080/ords/apex_admin进入 APEX 实例管理员界面，用前面配置的管理员密码登录。

初次登录后建议立刻创建一个工作空间和第一个开发账号。APEX 的层级是实例管理员管工作空间，工作空间管应用开发者。没有工作空间，就算登录成功也进不去应用构建器。

3.4 把 ORDS 注册成系统服务，避免手工启动

Standalone 模式虽然方便，但总不能每次重启机器都手动敲命令。我在生产环境会把 ORDS 包成一个 systemd 服务，这样开机自启、状态查看、日志管理都规整很多。

一个简单的 systemd 单元文件可以是这样：

[Unit] Description=Oracle REST Data Services After=network.target oracle.service [Service] User=oracle Environment=JAVA_HOME=/usr/java/jdk1.8.0_202 Environment=ORDS_CONFIG=/u01/ords/config ExecStart=/usr/java/jdk1.8.0_202/bin/java -jar /u01/ords/ords.war standalone Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target

注意服务启动用户不能是 root，用专门的 oracle 用户或者应用用户。另外，如果数据库和 ORDS 在同一台机器，建议在单元文件里加上 After 依赖，确保数据库先启动。重启 ORDS 的命令就是systemctl restart ords，日志用journalctl -u ords -f查看，比直接看控制台输出稳定得多。

如果服务器已经装了 Tomcat，也可以把ords.war直接丢到 Tomcat 的webapps目录，启动 Tomcat 后 ORDS 会以应用方式运行。这种方式方便和现有 Java Web 应用统一管理，但配置路径和静态资源映射会更绕一点。我个人的建议是：能 Standalone 就别引入 Tomcat，少一个中间层就少一组需要排查的故障点。

4. 安装过程中常见问题速查：全是现场实录

APEX 安装出问题的概率不低，大多数是环境问题，不是脚本问题。我把这些年踩过的、帮别人排查过的典型问题整理成速查表，基本覆盖 80% 的安装失败场景。

4.1 为什么 404 特别容易出现，先说透

APEX 的页面依赖静态资源非常多，只要路径映射错一个层级，浏览器就拿不到 CSS 和 JS，页面表现通常是能登录但丑得一塌糊涂，或者说只有纯文本没有布局。EPG 模式下的映射靠的是apex_epg_config.sql的参数，这个参数必须是images的父目录，不是images本身。

ORDS 模式下，配置向导里的静态资源目录要填到真实的images目录，同时 ORDS 会自动按http://host:port/ords/...的路由来处理 APEX 请求。如果你看到请求路径里出现了/i/但返回 404，多半是 ORDS 进程没有权限读取那个目录。解决办法：确认运行用户对目录有读权限，然后重启 ORDS。

4.2 数据库侧“看起来装好了”但登录页报 503 的排查顺序

503 一般不是 APEX 本身的问题，而是网关在连接数据库时被拒绝。先看 ORDS 日志，如果看到Connection refused，基本就是监听地址或服务名配错了。如果看到ORA-28000: the account is locked，那就是APEX_PUBLIC_USER或APEX_LISTENER被锁了。

解锁命令很简单：

ALTER USER APEX_PUBLIC_USER ACCOUNT UNLOCK; ALTER USER APEX_LISTENER ACCOUNT UNLOCK;

但我特别提醒：不要只解锁完就去访问，要先确认密码有没有过期。如果password_lifetime策略比较严格，刚刚解锁的账号可能还是处于需要改密码的状态。最稳妥的做法是安装完直接给这几个服务账号设置一个长期不过期的密码策略，避免半夜出这种问题。

4.3 安装脚本想重跑，先清理现场再执行

很多人安装脚本跑挂后第一反应是重新执行一遍apexins.sql，结果反而报一堆对象已存在。APEX 安装脚本不是无序的幂等脚本，报错后必须先把已创建的对象清理干净。最省事的办法是从一个干净的备份库上重来，或者在重新安装前手动 drop 掉APEX_050100等四个 schema。

如果表空间不大，我通常会把apex_main_ts和apex_files_ts一起 drop 掉再重建，确保没有残留：

DROP USER APEX_050100 CASCADE; DROP USER APEX_PUBLIC_USER CASCADE; DROP USER APEX_LISTENER CASCADE; DROP USER APEX_REST_PUBLIC_USER CASCADE; DROP TABLESPACE apex_main_ts INCLUDING CONTENTS AND DATAFILES; DROP TABLESPACE apex_files_ts INCLUDING CONTENTS AND DATAFILES;

注意这里不能直接 drop SYSAUX，如果是放在 SYSAUX 里的环境，只能恢复备份。这也是我坚持用独立表空间的另一个理由，它让重装成本变得很低。

5. 安装完后的顺手加固和日常维护

装完并跑到这一步，环境应该能用了，但别急着松一口气。APEX 环境能稳定跑一年，靠的是安装完之后的这几个维护动作。

5.1 给服务账号做最小化授权和密码策略

ORDS 连接数据库使用的账号，不需要 SYSDBA，也不需要有 DBA 角色，它只需要 APEX 相关 schema 的访问权限即可。安装脚本会处理好这些授权，你要做的是不要把数据库超级账号填进 ORDS 配置文件里。

密码方面，APEX_LISTENER、APEX_REST_PUBLIC_USER、APEX_PUBLIC_USER 这几个账号，建议单独建密码表管理，并且纳入数据库密码过期提醒。特别是 ORDS 配置里的密码，一旦和数据库侧不一致，服务会在用户无感知的情况下悄然失效，表现成偶尔能登、偶尔不能登，非常诡异。

5.2 备份时别忘了 APEX schema

很多团队的数据库备份只备份业务 schema，忽略了 APEX 自身的 schema。先不说 APEX 应用定义全部存在APEX_050100里，光是维护过的用户、工作空间、开发人员账号，也都是数据。如果哪天要做容灾演练，恢复出一个没有 APEX 元数据的库，应用层就只剩一个空壳。

建议备份策略里包含APEX_050100、APEX_PUBLIC_USER、APEX_LISTENER、APEX_REST_PUBLIC_USER，同时考虑用数据泵按 schema 导出，定期做一次冷备份验证。APEX 版本升级前，必须有一份可回滚的完整备份，否则升级中途出问题，很难回头。

5.3 URL 前缀和端口规范要提前统一

如果你部门里有多套环境，比如开发、测试、预发、生产，建议从安装那一刻就统一 APEX 的访问路径，例如/ords/apex_admin、/ords/应用别名。否则每套环境的 context path 都不一样，开发写 RESTful 接口或者集成外部系统时，代码里到处要改路径，维护成本直线上升。

端口方面，ORDS Standalone 默认 8080，容易和本机其他 Web 服务冲突。遇到端口占用时可以这样调整：

java -jar ords.war standalone --port 8181

或者在defaults.xml里配置standalone.http.port。我建议统一约定一个专用端口，比如 8181，并写入系统服务文件，让运维和开发一眼就能看出哪套环境用哪个端口。

5.4 工作空间和开发账号的一开始规划

APEX 的权限模型是三层：实例管理员管理整个 APEX 实例，工作空间管理员管理某块业务下的所有应用和开发人员，普通开发人员只能访问被授权的工作空间。安装完不要急着把管理员密码发给所有人，应该先建好工作空间，再按角色建账号。

我一般会按项目维度建工作空间，例如“销售系统”、“运营后台”，并在每个工作空间里指定一个负责人。这样后续统计应用数量、做资源隔离、控制发布权限时都很清晰。如果一上来只有一个公共工作空间，所有人共用管理员，后面想拆分要搬迁所有应用，工作量大很多。

6. 最后聊一点我的真实体会

Oracle APEX 5.1 的安装并不难，难的是你对整套运行链路的理解。很多问题看似是 APEX 的锅，实际是数据库参数、监听服务、静态资源目录、服务账号锁定这些环节出了问题。我自己在项目上吃过最大的亏，就是图省事跳过 ORDS，直接用 EPG 部署到生产，结果遇到并发上来后页面明显变慢，最后还要花时间迁移到 ORDS。所以你在起步阶段多花二十分钟把 ORDS 配好，后面能少熬两个夜。

另外一个小技巧：安装完成后，把用过的所有命令、脚本参数、密码记录单独存一份到项目文档里。APEX 升级或者迁移到新机器时，照着当时的记录执行，成功率远高于临时翻官网。这个版本虽然已经有年头了，但只要掌握了它的安装思路，以后装更高的版本基本是同一套逻辑。