Label Studio 连接外部 PostgreSQL 数据库的配置指南

在使用 Label Studio 时，许多用户会选择将其与外部 PostgreSQL 数据库集成，而不是使用内置的数据库服务。本文将详细介绍如何正确配置 Label Studio 以连接外部 PostgreSQL 数据库，并解决常见的连接问题。

数据库架构准备

在连接外部 PostgreSQL 数据库时，首先需要确保目标架构（schema）已存在。Label Studio 默认会尝试在名为 "labelstudio" 的架构中创建其所需的表结构。如果该架构不存在，会导致连接失败。

可以通过以下 SQL 命令检查架构是否存在：

SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'labelstudio';

如果架构不存在，需要手动创建：

CREATE SCHEMA labelstudio;

数据库用户权限配置

确保连接数据库的用户拥有足够的权限：

1. 创建专用数据库用户（如非使用现有用户）
2. 授予该用户对 labelstudio 架构的所有权限
3. 确保用户有权限连接数据库

Helm 配置详解

在 Kubernetes 环境中使用 Helm 部署 Label Studio 时，values.yaml 文件需要特别配置：

global:
  pgConfig:
    host: "数据库主机地址"
    port: 5432
    dbName: "数据库名称"
    userName: "用户名"
    password:
      secretName: "labelstudio-db"  # 存储密码的Secret名称
      secretKey: "POSTGRES_PASSWORD"  # Secret中的键名
app:
  extraEnvironmentVars:
    POSTGRES_SCHEMA: "labelstudio"
    PGOPTIONS: "-c search_path=labelstudio"  # 强制使用指定架构
postgresql:
  enabled: false  # 禁用内置PostgreSQL

关键配置说明：

• postgresql.enabled: false 禁用内置数据库
• POSTGRES_SCHEMA 指定 Label Studio 使用的架构名称
• PGOPTIONS 确保所有查询默认使用指定架构

连接测试与验证

在部署前，建议先测试数据库连接是否正常：

1. 使用 pg_isready 命令测试基本连接性
2. 使用 psql 命令行工具验证凭据是否正确
3. 检查 PostgreSQL 的配置文件（pg_hba.conf 和 postgresql.conf）确保允许外部连接

常见问题解决

1. 架构不存在错误：确保指定架构已创建，并检查大小写是否匹配
2. 权限不足：验证用户对架构和表的权限
3. 连接失败：检查网络连通性、安全设置和认证配置
4. 迁移失败：确保数据库用户有创建表的权限

最佳实践建议

1. 为 Label Studio 创建专用数据库和用户，不要使用高权限账户
2. 定期备份数据库，特别是执行升级前
3. 在生产环境中考虑使用连接池
4. 监控数据库性能，Label Studio 的标注数据可能增长迅速

通过以上配置和注意事项，可以确保 Label Studio 顺利连接并使用外部 PostgreSQL 数据库，为标注工作提供稳定可靠的数据存储支持。