跳到主要内容

配置外部 PostgreSQL 数据库

SkillFlaw 要求使用 PostgreSQL 作为应用数据库。

本指南将带你完成在本地或托管部署环境中为 SkillFlaw 配置 PostgreSQL。

在这种配置下，SkillFlaw 的所有结构化应用数据——包括流程、消息历史和日志——都会由 PostgreSQL 统一管理。 由于 PostgreSQL 在并发用户支持、数据完整性与可扩展性方面更强，因此它更适合生产环境。将 PostgreSQL 作为数据库后，SkillFlaw 能更有效地支撑多用户与更大规模的负载。

前置条件​

将 SkillFlaw 连接到本地 PostgreSQL 数据库​

  1. 如果 SkillFlaw 当前正在运行，请先按 Ctrl+C 停止它。

  2. 找到 PostgreSQL 数据库的连接串，格式为 postgresql://user:password@host:port/dbname。

    连接串中的 hostname 取决于你如何运行 PostgreSQL：

    • 如果 PostgreSQL 直接运行在当前机器上，请使用 localhost。
    • 如果 PostgreSQL 运行在托管平台或内部网络中，请使用平台提供的服务主机名或 DNS 名称。
    • 如果你使用的是云托管 PostgreSQL，服务提供方通常会直接给出包含用户名与密码的连接串。

  3. 编辑或创建 SkillFlaw .env 文件：


    _10
    touch .env

    你也可以把 SkillFlaw 仓库中的 .env.example 作为模板。

  4. 在 .env 中，把 SKILLFLAW_DATABASE_URL 设置为你的 PostgreSQL 连接串：


    _10
    SKILLFLAW_DATABASE_URL="postgresql://user:password@localhost:5432/dbname"

    SkillFlaw 使用 SQLAlchemy 配合 psycopg 驱动，以便把 SSL 参数直接传递给 PostgreSQL 连接。

    PostgreSQL 驱动兼容性

    SkillFlaw 需要使用 psycopg2-binary 或 psycopg[binary] 作为 PostgreSQL 驱动。由于时区处理要求更严格，asyncpg 与 SkillFlaw 当前数据库 schema 不兼容。

    支持以下 SSL 模式：

    • sslmode=require：要求使用 SSL 连接，但不校验服务端证书。安全性相对最低，但对多数场景已足够。


      _10
      SKILLFLAW_DATABASE_URL="postgresql://user:password@localhost:5432/dbname?sslmode=require"

    • sslmode=verify-ca：要求 SSL，并校验证书是否由指定 CA 签发。此时需要把证书路径加入连接串：


      _10
      SKILLFLAW_DATABASE_URL="postgresql://user@localhost:5432/dbname?sslmode=verify-ca&sslcert=/path/to/client.crt&sslkey=/path/to/client.key&sslrootcert=/path/to/ca.crt"

    • sslmode=verify-full：要求 SSL、校验证书，并校验请求主机名与证书主机名是否一致。下面示例里的 db.example.com 必须与服务端证书 CN 匹配。这是最安全的模式。


      _10
      SKILLFLAW_DATABASE_URL="postgresql://user@db.example.com:5432/dbname?sslmode=verify-full&sslcert=/path/to/client.crt&sslkey=/path/to/client.key&sslrootcert=/path/to/ca.crt"

      不要把 SkillFlaw 环境变量 SKILLFLAW_SSL_CERT_FILE 和 SKILLFLAW_SSL_KEY_FILE 用于 PostgreSQL 证书：这两个变量是给 SkillFlaw 服务器启用 HTTPS 用的，不是用来连接 PostgreSQL 的。

      更多 PostgreSQL SSL 证书管理说明，请参阅 PostgreSQL 官方文档。

  5. 保存修改后，使用 .env 文件启动 SkillFlaw：


    _10
    uv run skillflaw run --env-file .env

    如果你还需要连接池与超时等可选配置，请参阅 配置外部 memory。

  6. 在 SkillFlaw 中运行任意流程，制造一些数据库流量。

  7. 检查 PostgreSQL 数据库中的表与活动，确认在你运行流程之后已创建新表并产生新数据。

多个 SkillFlaw 实例共用同一个 PostgreSQL 数据库​

你可以让多个 SkillFlaw 实例通过同一个 SKILLFLAW_DATABASE_URL 指向同一个 PostgreSQL 数据库。

例如，如果你在不同端口上运行两个 SkillFlaw 进程，它们都可以复用相同的数据库连接串：


_10
SKILLFLAW_DATABASE_URL="postgresql://user:password@db.example.com:5432/skillflaw"

每个实例仍然应使用自己独立的运行端口，并在必要时使用各自独立的 SKILLFLAW_CONFIG_DIR 来存放本地文件与日志。

启动后，你可以通过查询 PostgreSQL 元数据（如 pg_stat_activity）来确认两个实例都已成功连接。

另请参阅​