帮助中心产品文档与操作指南

PostgreSQL安装与第一个业务数据库

发布时间：2026-11-05

本篇在一台新的 Ubuntu 24.04 LTS 服务器上安装 PostgreSQL 16，创建独立业务账号和数据库，再验证中文数据写入、退出后重新读取。使用系统软件源中的软件包，应用与数据库先部署在同一台服务器，不开放公网5432端口。已有 PostgreSQL 集群的服务器，应先核对现有版本、端口和数据目录，不按新装流程重复创建。

安装软件包，查看真正运行的数据库实例

使用能执行sudo的系统账户，先确认系统版本和软件源候选包：

cat /etc/os-release
sudo apt update
apt-cache policy postgresql-16 postgresql-client-16
sudo apt install postgresql-16 postgresql-client-16
pg_lsclusters

正常的新安装通常显示 16 main，状态为 online，端口为5432。以实际输出为准；若存在其他集群，不要把其他版本的数据目录复制过来覆盖。确认本篇这套实例：

sudo systemctl status postgresql@16-main --no-pager
sudo -u postgres psql -X -p 5432 -d postgres -c "SELECT version();"

postgresql.service 可能是管理多个实例的汇总服务，因此仅看到它 active (exited) 还不够。这里需要实际集群在线，而且SQL查询能够返回版本。若你的集群名或端口不同，后面的命令也要对应修改。

创建业务账号和独立数据库

Ubuntu的本机管理可以使用系统用户postgres，通过socket进入数据库。该账户用于管理，不填写到网站的日常连接配置。

sudo -u postgres psql -X -p 5432 -d postgres

进入psql后先创建角色。下面的示例名称需要确认尚未使用；如果角色已经存在，就停止核对用途，不继续改它的密码：

\set ON_ERROR_STOP on
CREATE ROLE baole_app LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION;

收到CREATE ROLE成功结果后，再设置密码和创建数据库。数据库已经存在时同样停止，不删除重建：

\password baole_app
CREATE DATABASE baole_site OWNER baole_app ENCODING 'UTF8' TEMPLATE template0;
\du baole_app
\l baole_site
\q

\password 会提示两次输入密码，避免把明文密码写进SQL历史。baole_app 和 baole_site 是示例名称，可以统一换成项目专用名称。该账号是这一个业务库的所有者，适合初始化和迁移；多角色项目可在上线时再拆分权限更小的运行账号。

使用业务账号连接，再写入一条中文数据

以下命令在Linux终端运行，明确指定 127.0.0.1 使用TCP密码认证：

psql -X -h 127.0.0.1 -p 5432 -U baole_app -d baole_site -W

输入刚设置的数据库密码，执行：

SELECT current_user, current_database(), inet_server_addr(), inet_server_port();
BEGIN;
CREATE TABLE public.baole_connection_check (
    id integer PRIMARY KEY,
    note text NOT NULL
);
INSERT INTO public.baole_connection_check VALUES (1, '宝乐云数据库连接测试');
COMMIT;
SELECT id, note FROM public.baole_connection_check;

第一条应显示业务账号、目标库、127.0.0.1和实际端口；最后一条应返回中文测试内容。建表和写入放在同一事务内，任何一步报错都先执行 ROLLBACK;。若测试表已经存在，停止操作，改用独立的新表名后重新执行整段事务，避免向原有表插入数据。

输入 \q 退出，再执行同一条连接命令重新登录，读取刚才的记录：

SELECT id, note FROM public.baole_connection_check WHERE id = 1;

重新连接后仍能读取，说明不是只打开了一个空的客户端窗口。确认该表仅有本次示例数据后，可用 DROP TABLE public.baole_connection_check; 清理测试表；应用使用的库和账号继续保留。

把连接信息填写到程序里

配置项 本篇示例
数据库类型 PostgreSQL，使用程序对应的PostgreSQL驱动。
主机和端口 127.0.0.1:5432；按实际实例端口填写。
数据库与用户 baole_site / baole_app。
密码 刚通过\password设置的独立密码，保存在程序的受控配置中。

用同一组配置运行程序的数据库检查或初始化，再验证程序实际读写。应用运行在容器或另一台服务器时，127.0.0.1的含义会改变，需要另外设计连接路径；不要仅为连通就把数据库监听地址和访问范围全部放开。

常见报错怎样处理

现象 检查位置
Peer authentication failed 通常走了本机socket身份匹配。业务密码连接明确使用-h 127.0.0.1，不把认证规则改成trust。
password authentication failed 核对账号、目标实例和密码。必要时由postgres管理员在正确实例中用\password baole_app重设。
Connection refused 检查pg_lsclusters、实际监听端口和对应实例日志；不是先改数据库密码。
permission denied for schema public 检查当前账号及数据库所有者，确认连接的是刚创建的目标库；不要直接给所有用户授予全局权限。

实例没有启动时，可查看 sudo journalctl -u postgresql@16-main -n 80 --no-pager；涉及配置的真实路径可由管理连接执行 SHOW config_file; 和 SHOW hba_file; 获取。正式写入业务数据前，继续配置 PostgreSQL备份与恢复验证。