Docker 中连接宿主机 PostgreSQL 的配置与扩展安装问题总结

摘要：本文总结了在 Docker 容器中连接宿主机 PostgreSQL 数据库时遇到的常见问题，包括使用 host.docker.internal 无法连接、数据库不存在、权限不足以及扩展缺失等问题，并提供了完整的解决方案和配置方法。

1. 连接宿主机 PostgreSQL 的常见方式

1.1 使用 host.docker.internal

      推荐方式，适用于大多数现代 Docker 环境（Linux、Docker Desktop for Mac/Windows）。但需注意：Linux 默认不支持该方式，需手动启用。

docker run --add-host=host.docker.internal:host-gateway -e DATABASE_URL=postgresql://username:password@host.docker.internal:5432/dbname?sslmode=disable bitmagnet

1.2 使用局域网 IP

      获取宿主机局域网 IP（如 192.168.x.x），并在容器中使用该 IP 连接 PostgreSQL。

DATABASE_URL=postgresql://username:password@192.168.1.100:5432/dbname

1.3 使用 --network host 模式

      容器直接使用宿主机网络，可以使用 localhost 连接 PostgreSQL。

docker run --network host -d bitmagnet

2. 常见错误及解决方案

2.1 TLS 错误

      PostgreSQL 拒绝 SSL/TLS 连接，需在连接字符串中禁用 SSL。

postgresql://postgres@host.docker.internal:5432/bitmagnet?sslmode=disable

2.2 数据库不存在

      确保数据库已创建。

sudo -u postgres createdb bitmagnet

2.3 权限不足

      使用具有超级权限的用户（如 postgres）连接数据库。

CREATE USER your_user WITH SUPERUSER;

3. 扩展安装问题

3.1 pg_trgm 扩展缺失

      PostgreSQL 缺少扩展文件，需安装 postgresql-contrib 包。

sudo apt install -y postgresql-contrib

3.2 btree_gin 扩展缺失

      手动编译并安装 btree_gin 扩展到自定义 PostgreSQL 路径。

cd /root/postgresql-16.1/contrib/btree_gin
make clean
make
make install

4. 配置文件建议

4.1 pg_hba.conf

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             0.0.0.0/0            trust
# IPv6 local connections:
host    all             all             ::/0                 trust
# Allow replication connections from localhost, by a user with the
# replication privilege.
local   replication     all                                     trust
host    replication     all             127.0.0.1/32            trust
host    replication     all             ::1/128                 trust
host    bitmagnet  postgres    0.0.0.0/0    trust

5. 总结

• 使用 host.docker.internal 或局域网 IP 连接宿主机 PostgreSQL。
• 确保数据库存在且用户有权限。
• 安装必要的扩展（如 pg_trgm、btree_gin）。
• 修改 pg_hba.conf 文件以允许远程连接。