企业官网建设流程全解析

前阵子在某项目现场做环境迁移，又要装一套 Oracle APEX 5.1，趁着这次操作把整个流程重新过了一遍。APEX 5.1 在 Oracle 数据库里的地位有点特殊：它不需要单独的应用服务器就能跑，装好后通过浏览器开发应用，能省掉不少前后端的工作量。这篇安装手册不是照搬官方文档，而是把我实际操作中验证过的步骤、参数、排错经验整理出来，给需要部署 APEX 5.1 的数据库管理员、后端开发和运维同学做个参考。

先说明一下读者定位：如果你是第一次接触 APEX，可以按章节顺序走；如果你已经在生产环境踩过坑，建议直接跳到最后两章，里面有不少东西是文档里写不到位的。整篇内容围绕“数据库端脚本安装 + ORDS 配置 + 访问验证 + 故障排查”这条主线展开，全部基于 Oracle APEX 5.1 在常见数据库环境下的实测结果，不含悬空的理论。

1. 安装方式选型与环境准备

1.1 APEX 5.1 的定位和两条部署路线

APEX 5.1 是 Oracle 官方提供的低代码应用开发平台，安装对象其实是数据库本身。它会把一系列表、视图、存储过程、程序包加载进数据库，然后通过一个 Web 网关把浏览器请求转发给数据库引擎处理。用户看到的页面、运行的业务逻辑、存的数据，全部都在数据库内部流转，所以部署的时候重点解决两件事：数据库对象装没装好，Web 网关能不能把请求接进来。

在 5.1 版本里，Web 网关有两条路线可选。第一条是内置的 PL/SQL 网关，也就是 EPG（Embedded PL/SQL Gateway），它是 Oracle XML DB HTTP Server 提供的功能，配置最简单，适合测试环境、快速 Demo、Oracle XE 等场景。第二条是用 ORDS（Oracle REST Data Services）作为独立中间层，这也是官方从 APEX 4.x 开始强烈推荐的方式，支持并发控制、RESTful Service、跨版本升级、更安全的 HTTPS 配置，生产环境基本都会选它。

我见过不少人在选型上反复纠结，其实判断很简单：个人学习用 EPG，省事；公司部署、多人使用、要上线跑业务，直接走 ORDS。后文会默认按 ORDS 路线写，EPG 只提关键脚本。

1.2 版本兼容性矩阵：先确认数据库版本再动手

APEX 5.1 对数据库版本有明确要求，不是装在哪个 Oracle 上都行。官方支持范围大致指向 11.2.0.4 及以上版本，我在项目里实际验证过 11.2.0.4、12.1.0.2、12.2.0.1 都能稳定安装运行。如果你手里的库是 11.2.0.3 或者更老，建议先别急着跑安装脚本，优先升级数据库，否则后面可能触发各种兼容性问题。

数据库版本查询很简单：

SELECT * FROM v$version;

另外还需要看compatible参数，通常 11.2.0.4 的库，compatible 也应该是 11.2.0.4 或更高。低于 APEX 要求时，脚本可能会在创建某些特性对象时报错。

这里特别提醒一下：APEX 5.1 和 ORDS 3.0 是同一时期的搭配，如果你拿新版 ORDS（比如 18.x、19.x）去对接 APEX 5.1，不是完全不能用，但初始化配置和静态文件处理方式变化较大，容易踩到意外问题。稳妥起见，生产环境用 3.0.x 即可。

1.3 需要准备的软件包与验证下载完整性

安装前把软件包准备齐全，能减少一半的临时抓狂。你需要的东西有：APEX 5.1 安装包（解压后里面有apexins.sql、apxchpwd.sql、apex_rest_config.sql等脚本和images目录）、ORDS 3.0.x 的 war 包、JDK 1.8。如果走 EPG 路线，ORDS 和 JDK 都不需要，但生产环境不建议省这一步。

下载完成后，先确认压缩包完整性，避免解压到一半报错。Linux 下用sha256sum对比官方校验值，Windows 下用 PowerShell 的Get-FileHash。APEX 安装包体积不小，网络传输容易损坏，这个检查不能跳过。

解压 APEX 包时建议放到一个固定路径，比如 Linux 下/opt/apex，Windows 下E:\apex。后面 ORDS 配置静态文件路径、EPG 配置目录都要用这个绝对路径，路径随手乱放，后面配置时很容易找不到地方。

2. 数据库端安装：APEX Schema 的创建细节

2.1 解压安装包：这些文件分别有什么用途

APEX 安装包解压后是一个典型的数据库脚本目录，核心文件就那几个。apexins.sql是主安装脚本，负责创建 APEX 内部用户、表空间对象和数据字典；apxchpwd.sql用来设置 APEX 内置管理员admin的密码；apex_rest_config.sql用于配置 ORDS 需要的 REST 相关账户；apex_epg_config.sql则是 EPG 路线专用。

images目录也很关键，它存放 APEX 的静态资源文件，比如 JS、CSS、图片。ORDS 和 EPG 都需要告诉中间层这个目录在哪，否则页面会变成“裸奔”状态，样式和交互全部丢失。很多人装完 APEX 后打开页面发现奇丑无比，十有八九是静态文件路径没配对。

2.2 安装前必须检查的三类参数

跑脚本之前，建议花两分钟确认一下数据库环境，省得装到一半被内存和表空间的报错打断。第一，确认SYSAUX表空间有足够的剩余空间。APEX 5.1 默认会把大量元数据放进SYSAUX，建议预留至少 500MB 以上的空间，如果库已经用了很久、SYSAUX 很紧张，先扩容再加安装。

第二，确认临时表空间可用。安装过程会有大量排序和临时对象操作，TEMP表空间太小会直接冒出ORA-01652。第三，确认字符集。数据库字符集建议是AL32UTF8，如果库里已经存了历史数据且字符集是ZHS16GBK，也不是不能装，但要注意应用层出现中文乱码的风险会变大，排查起来相当麻烦。

SELECT tablespace_name, file_name, bytes/1024/1024 AS size_mb FROM dba_data_files WHERE tablespace_name IN ('SYSAUX', 'TEMP');

还有一些细节：安装过程建议用sysdba执行，普通用户权限不够；有 Data Guard 或 RAC 环境的库，尽量在主库安装，备库同步即可。APEX 安装本身不需要停库，但会产生一定的数据库负载，生产环境最好选业务低峰期操作。

2.3 执行 apexins.sql：四个参数每个都不能错

进入安装包解压目录，用 SQL*Plus 以 sysdba 登录数据库，然后执行安装脚本：

cd /opt/apex sqlplus / as sysdba SQL> @apexins.sql SYSAUX SYSAUX TEMP /i/

这行命令里的四个参数很多人不理解，导致自定义表空间时报错。按顺序解释：第一个是 APEX 数据表空间，用来放 APEX 引擎相关的表和索引；第二个是 APEX 文件表空间，承载 APEX 文件对象；第三个是临时表空间；第四个是图片虚拟目录名，默认/i/，意思是通过 URL 访问静态文件时使用/i/这个路径前缀。

如果不想把 APEX 对象放进SYSAUX，可以用业务表空间替代第一个参数，比如：

SQL> @apexins.sql USERS USERS TEMP /i/

执行后脚本会开始创建一系列对象，窗口里会不断滚出PL/SQL procedure successfully completed之类的信息，这是正常现象，不用紧张。整个安装过程视服务器性能而定，一般在十分钟到半小时之间。建议同时开一个 spool 日志：

SQL> spool apex_install.log SQL> @apexins.sql SYSAUX SYSAUX TEMP /i/ SQL> spool off

这样即使中间出了问题，也能直接翻日志定位，不用来回翻终端滚动条。安装中断时，大多数情况下可以直接修复问题后重跑脚本，脚本本身具备一定的可重复执行能力。

2.4 设置管理员密码与后续补全脚本

主安装脚本跑完后，第一件要紧事是设置 APEX 内置管理员密码。否则浏览器访问时默认密码是随机的，或者根本无法登录。执行：

SQL> @apxchpwd.sql

脚本会提示输入新密码，建议设置一个符合复杂度要求的强密码，这个admin账户是整个 APEX 实例的超级管理员，密码泄露等于应用开发后台被人接管，不能图省事用弱口令。

如果走 ORDS 路线，还需要执行另一个脚本：

SQL> @apex_rest_config.sql

这个脚本会要求输入APEX_LISTENER和APEX_REST_PUBLIC_USER两个账户的密码，并完成相关权限配置。如果不执行它，后续 ORDS 初始化时可能连不上 APEX 元数据，页面会报类似APEX_LISTENER无效的错误。

如果只是临时演示，用 EPG 路线，则执行：

SQL> @apex_epg_config.sql

脚本会询问 APEX 安装包的绝对路径，注意这里要填到解压根目录，不是images子目录。回答完之后，EPG 会自动配置静态文件服务。

2.5 验证数据库侧安装结果

数据库端脚本都跑完之后，可以直接查询版本信息确认安装是否成功：

SELECT version_no, release_date FROM apex_release;

正常会返回类似5.1.4的版本号。再查看一下数据库里相关的账户状态：

SELECT username, account_status, default_tablespace FROM dba_users WHERE username LIKE 'APEX%' OR username IN ('APEX_LISTENER', 'APEX_REST_PUBLIC_USER');

正常情况下能看到APEX_050100、APEX_PUBLIC_USER、APEX_LISTENER、APEX_REST_PUBLIC_USER等账户，其中APEX_050100的状态是OPEN，APEX_PUBLIC_USER也应该是解锁状态。如果某些账户处于LOCKED，后面 ORDS 连接时会报错，需要手动解锁：

ALTER USER APEX_PUBLIC_USER ACCOUNT UNLOCK;

至此，数据库端的 APEX 引擎已经就位。接下来的重点是让浏览器能通过 HTTP 访问到这套引擎。

3. ORDS 配置：让浏览器能访问 APEX 应用

3.1 为什么生产环境建议用 ORDS 而不是内置网关

EPG 虽然配置简单，但它有几个天然短板：并发能力一般、不支持常用的 RESTful Service 完整功能、HTTPS 配置不够灵活、对数据库 XML DB 的依赖较重。ORDS 作为一个独立的 Java 应用，把 HTTP 请求完完整整地转成数据库调用，生产环境里性能、安全、运维规范都更符合要求。

ORDS 也支持独立模式和 Tomcat 部署两种运行方式。独立模式适合快速启动、小规模部署，一条java -jar ords.war standalone就能跑起来；Tomcat 部署则适合已有 Java 中间件的环境，启动管理更统一。两种方式原理一致，都是同一个 war 包，只是运行容器不同。

3.2 JDK 与 ORDS 版本选择

ORDS 3.0.x 要求 JDK 1.8，建议直接装最新补丁级别的 JDK 8。下载 ords.war 后，先确认 Java 环境：

java -version

如果机器上已经装了多个 JDK，注意把 JAVA_HOME 指向 JDK 8。版本不匹配的问题很隐蔽，ORDS 启动时可能只抛出一个莫名其妙的UnsupportedClassVersionError，排查起来会绕很大一圈。

3.3 ORDS 初始化配置交互流程

先创建 ORDS 的工作目录，比如/opt/ords，然后把 ords.war 放进去。首次配置执行：

cd /opt/ords java -jar ords.war setup

这个命令会进入交互式问答，问题比较多，但核心信息就几类：数据库连接方式（选基础 JDBC 连接）、数据库主机、端口、服务名、管理员账户密码、是否开启 RESTful Services、APEX 静态文件路径、运行模式、监听端口。

我的经验是，交互式回答时容易因为手误导致配置错误。更推荐使用非交互式参数安装，把关键参数一次性传入：

java -jar ords.war install simple \ --db-hostname 127.0.0.1 \ --db-port 1521 \ --db-servicename orcl \ --admin-user sys \ --admin-password '数据库管理员密码' \ --feature-sdw true \ --feature-rest-enabled-sql true \ --apex-images /opt/apex/images

其中--apex-images必须指向 APEX 解压目录里的images目录，这个参数错了，页面样式就全丢了。--admin-user sys对应的密码要有SYSDBA权限，否则 ORDS 无法创建后续对象。

3.4 独立模式与 Tomcat 部署两种运行方式

ORDS 配置完成后，先用独立模式快速验证：

java -jar ords.war standalone --port 8080

启动日志出现类似Oracle REST Data Services initialized的输出后，打开浏览器访问：

http://服务器IP:8080/ords/apex

如果能出现 APEX 的登录页，说明整个链路已经打通。若环境里已有 Tomcat，也可以把 ords.war 复制到 Tomcat 的webapps目录，启动 Tomcat 后自动部署，访问路径同样是：

http://服务器IP:8080/ords/apex

需要注意 Tomcat 默认端口也是 8080，如果机器上已经有别的应用占用，要在 Tomcat 的conf/server.xml里改端口。独立模式和 Tomcat 方式切换时，ORDS 的配置目录是共享的，不需要重新执行 setup。

3.5 APEX 静态文件路径配置的坑

静态文件路径的问题值得单独拿出来说，因为我在现场见过太多次“装完后页面没有样式”的情况。APEX 5.1 的页面会通过/i/前缀加载静态资源，而 ORDS 需要知道这个/i/对应的真实文件系统路径。配置值就是 APEX 解压目录下的images目录。

配置完成后，可以在浏览器直接访问：

http://服务器IP:8080/i/apex_version.txt

如果能返回版本号，说明静态文件服务正常。返回 404，就去检查 ORDS 配置文件里的apex-images路径，确认目录存在且运行 ORDS 的系统用户有读取权限。这个测试方法很实用，我建议装完后第一时间做。

提示：不要在配置里把--apex-images指到安装包的根目录或者别的层级，必须精确到images目录本身。

4. 安装后的验证、日志与日常维护

4.1 浏览器首次访问和登录检查

ORDS 正常启动后，访问登录页：

http://服务器IP:8080/ords/apex

首次登录使用工作区名称INTERNAL，用户名admin，密码是前面用apxchpwd.sql设置的密码。登录成功后，系统会引导创建普通工作区，之后才能创建应用。如果这一步登录失败，优先检查密码脚本是否执行成功，而不是急着重装。

登录页能打开后，顺便确认一下页面样式是否正常。如果页面光秃秃、JS 报 404，按上一节静态文件路径部分排查。还有一个容易遗漏的点：浏览器地址栏里的访问地址要和 ORDS 配置匹配，不要用 IP 和域名混着访问，某些代理环境下会导致 Cookie 失效。

4.2 安装日志与配置文件位置

APEX 数据库端的安装过程主要靠 SQL*Plus 的 spool 日志保留，这部分没有统一的磁盘日志文件。ORDS 运行后，工作目录下会生成logs文件夹，里面按日期记录请求和异常。当页面报 500、503 时，去logs目录翻日志，通常能直接看到报错的 SQL 或 Java 异常栈。

ORDS 的核心配置文件在启动目录下，主要是defaults.xml和settings.xml。defaults.xml里保存数据库连接、APEX 静态路径、端口等配置。需要改端口或者换库连接时，可以直接编辑它，然后重启 ORDS。注意不要手动把数据库密码以明文形式写进文件，建议用 ORDS 的 wallet 机制保存凭据，避免配置文件泄露导致数据库账号泄露。

4.3 安装产生的数据库账户清单

APEX 5.1 安装后，数据库里会出现一组固定账户，理解每个账户的用途，排错会快很多：

日常运维中，这些账户的密码不要随意修改。尤其APEX_PUBLIC_USER，如果数据库侧改了密码，ORDS 配置文件里没有同步更新，所有 APEX 请求都会报连接错误。修改这类账户密码的正确方式是重新执行相关配置脚本，而不是直接用 ALTER USER。

4.4 升级、备份与卸载注意事项

APEX 5.1 的小版本升级不算复杂。下载新版安装包后，执行同样的apexins.sql脚本，它会检测到已存在的旧版本并自动完成升级。升级前建议做一次数据库备份，尤其在APEX_050100Schema 升级期间，如果中途失败，回滚会比重新安装麻烦得多。

再有就是卸载。APEX 目录下提供了移除脚本，操作前必须备份数据、停掉 ORDS。卸载后所有用 APEX 开发的应用数据都会受影响，生产系统基本不会考虑卸载，但如果测试库需要清环境，可以参考脚本说明执行。我个人的习惯是：直接新建一个数据库实例重装，比在旧库里来回折腾干净得多。

提示：APEX 的应用数据和应用定义都存在数据库里，升级 APEX 引擎不会影响 Application Express 应用数据，但同样建议先导出应用备份。

5. 安装过程常见问题排查实录

5.1 端口冲突：最容易被卡住的点

ORDS 独立模式默认监听 8080，Tomcat 默认也是 8080，Oracle XML DB 的 HTTP 服务有时也占 8080。这三兄弟撞在一起的情况非常常见，典型表现是启动时端口被占用，或者启动成功但访问页面不是 APEX。

先查端口占用：

netstat -an | grep 8080

Linux 下用ss -lntp查得更详细。确认占用进程后，要么停掉旧服务，要么给 ORDS 换端口：

java -jar ords.war standalone --port 8081

如果走 Tomcat，则修改conf/server.xml里的 Connector 端口。端口改完后，访问地址也要跟着改，别忘了。

5.2 打开页面返回 404 或 503

访问http://IP:端口/ords/apex返回 404，通常原因是 ORDS 没有正确映射 APEX 路由。确认访问路径里有没有漏掉/ords层级，APEX 默认挂在/ords上下文下，路径不对就是 404。

返回 503 时，大概率是 ORDS 和数据库之间的连接出了问题。优先看 ORDS 日志，会有ORA-12541、ORA-12514这类网络错误，说明数据库地址、服务名或监听写错了。回到 ORDS 配置重新跑一遍 setup，把db-hostname、db-port、db-servicename核对清楚。

如果是静态资源 404，也就是页面能打开但 CSS/JS 加载失败，检查apex-images路径和/i/虚拟目录的映射是否匹配。直接访问http://IP:端口/i/apex_version.txt是最快的定位方法。

5.3 登录提示错误或页面加载异常

登录页能打开，但输入INTERNAL/admin后提示密码错误，先确认apxchpwd.sql是否执行。还有一种情况是浏览器保存了旧密码，清除浏览器缓存和历史密码后重试。

如果登录后进入页面就退出，或者提示“您的会话已过期”，多半和代理、负载均衡的会话保持机制有关。APEX 依赖数据库会话和 Cookie，中间有代理做转发时，要保证同一客户端的请求落到同一个实例，并且 Cookie 域名配置正确。

页面如果出现大面积乱码，先查数据库字符集和客户端NLS_LANG的设置。AL32UTF8数据库配合SIMPLIFIED CHINESE_CHINA.ZHS16GBK客户端，中文数据偶尔会出现显示异常，建议统一字符集环境再测试。

5.4 常见错误速查表

这套流程我前前后后在多个环境重复过，最大的感受是：APEX 5.1 安装本身不复杂，复杂的是环境里各种隐性问题。数据库版本、Java 版本、端口占用、静态文件路径、字符集，任何一个环节不匹配都会冒出奇奇怪怪的现象。最后给第一次动手安装的朋友一个建议——安装前把本文 1.2 节的版本矩阵和 1.3 节的软件包核对完整，安装中把每一步的输出日志保留好，遇到问题先去查 ORDS 日志而不是盲目重装。按这个节奏走，一套 APEX 5.1 环境从零到登录页，顺利的话半小时内就能搞定。