Ubuntu 上 pgAdmin 插件安装教程

一 概念澄清

• pgAdmin 的“插件”主要有两类：
  1. 客户端插件：增强 pgAdmin 4 的功能（如新面板、工具、主题等），安装到 pgAdmin 的插件目录，通过界面启用。
  2. 服务器端扩展：增强 PostgreSQL 数据库的功能（如 oracle_fdw、postgis 等），需要在数据库里执行 CREATE EXTENSION，不属于 pgAdmin 本体。

二 客户端插件安装步骤

• 确认 pgAdmin 安装方式（决定插件目录）
  • APT 系统安装：插件目录通常为 /usr/lib/pgadmin4/plugins
  • pip/venv 用户安装：插件目录通常为 ~/.local/share/pgadmin/pgadmin4/plugins
• 安装步骤
  1. 获取插件包（.zip 或 .tar.gz），解压到临时目录
     unzip plugin.zip -d /tmp/pgadmin_plugins
  2. 复制到插件目录（注意权限）
     • 系统安装：sudo cp -r /tmp/pgadmin_plugins/plugin_name /usr/lib/pgadmin4/plugins/
     • 用户安装：cp -r /tmp/pgadmin_plugins/plugin_name ~/.local/share/pgadmin/pgadmin4/plugins/
  3. 重启 pgAdmin（桌面快捷方式或系统服务）
  4. 启用插件：打开 pgAdmin → 顶部菜单 Tools → Plugin Manager → 勾选并 Apply
• 注意
  • 插件必须与当前 pgAdmin 4 版本兼容（查看插件文档的“Supported Versions”）。
  • 仅从可信来源下载，避免安全风险；系统目录复制需 sudo。

三 服务器端扩展安装示例 oracle_fdw（PostgreSQL 侧）

• 适用场景：让 PostgreSQL 通过 oracle_fdw 访问 Oracle 数据库（这是数据库扩展，不是在 pgAdmin 里安装）。
• 步骤
  1. 安装编译依赖与 Oracle Instant Client
     sudo apt-get install build-essential postgresql-server-dev-12

     下载并解压 Oracle Instant Client（Basic 与 SDK，版本需一致），例如 21.8

     sudo unzip -d /usr/lib/postgresql/12 instantclient-basic-linux.x64-21.8.0.0.0dbru.zip
     sudo unzip -d /usr/lib/postgresql/12 instantclient-sdk-linux.x64-21.8.0.0.0dbru.zip
  2. 配置环境变量（示例）
     echo ‘export ORACLE_HOME=/usr/lib/postgresql/12/instantclient_21_8’ >> ~/.bashrc
     echo ‘export PG_HOME=/usr/lib/postgresql/12’ >> ~/.bashrc
     echo ‘export LD_LIBRARY_PATH=$PG_HOME/lib:$ORACLE_HOME:$LD_LIBRARY_PATH’ >> ~/.bashrc
     echo ‘export PATH=$PG_HOME/bin:$PATH’ >> ~/.bashrc
     source ~/.bashrc
  3. 编译安装 oracle_fdw
     unzip -d /usr/lib/postgresql/12 oracle_fdw-ORACLE_FDW_2_4_0.zip
     cd /usr/lib/postgresql/12/oracle_fdw-ORACLE_FDW_2_4_0
     make && sudo make install
  4. 在数据库中创建扩展（可在 pgAdmin 的查询工具执行）
     CREATE EXTENSION oracle_fdw;
  5. 若报动态库无法加载（如 libclntsh.so.21.1 找不到），注册库路径并刷新
     echo ‘/usr/lib/postgresql/12/instantclient_21_8’ | sudo tee /etc/ld.so.conf.d/oracle-x86_64.conf
     sudo ldconfig
• 提示
  • 扩展版本需与 PostgreSQL 主版本匹配（如 server-dev-12 对应 PG 12）。
  • 连接 Oracle 时，注意 listener.ora 与 tnsnames.ora 配置及网络可达性。

四 常见问题与排查

• 插件不显示或不可用
  • 检查插件目录是否正确（系统：/usr/lib/pgadmin4/plugins；用户：~/.local/share/pgadmin/pgadmin4/plugins）。
  • 确认插件与当前 pgAdmin 4 版本兼容；重启 pgAdmin 后再到 Tools → Plugin Manager 启用。
• 服务器端扩展创建失败
  • 缺少头文件或开发库：安装对应版本的 postgresql-server-dev-N 与编译工具（build-essential）。
  • 动态库未找到：将 Oracle Instant Client 路径加入 /etc/ld.so.conf.d/ 并执行 sudo ldconfig。
• 权限问题
  • 复制到系统插件目录需要 sudo；用户目录无需 sudo。