跳到主要内容

面向企业 DBA 的 SkillFlaw 数据库指南

SkillFlaw 数据库存储了支撑 SkillFlaw 运行所必需的数据，包括启动、流程执行、用户交互以及管理操作。 数据库同时支撑前端（可视化编辑器）与后端（API）能力，因此其可用性对 SkillFlaw 的稳定性与功能完整性至关重要。 关于数据库 schema 详情，请参阅 内存管理选项。

本指南面向企业数据库管理员（DBA）与生产环境运维人员，解释如何为 SkillFlaw 配置 PostgreSQL，包括高可用（HA）与 Active-Active 形态，以及监控、维护与安全方面的最佳实践。

使用 PostgreSQL 配置 SkillFlaw​

PostgreSQL 是 SkillFlaw 官方支持的应用数据库，也是推荐的生产选择，原因在于它具备较好的可扩展性、性能与稳定性。

以下步骤说明如何为单实例或多实例部署配置 PostgreSQL。 更多背景请参阅 配置外部 PostgreSQL 数据库。

  1. 准备 PostgreSQL：

    1. 部署 PostgreSQL 实例（建议版本 12 及以上），可运行在本地服务器、Kubernetes 或托管云服务上。
    2. 为 SkillFlaw 创建数据库。
    3. 为 SkillFlaw 创建具备最小必要权限的 PostgreSQL 用户，用于管理并写入数据库，例如在 SkillFlaw 所用表上具备 CREATE、SELECT、INSERT、UPDATE、DELETE 权限。

  2. 获取连接串，格式为 postgresql://user:password@host:port/dbname，例如 postgresql://skillflaw:securepassword@postgres:5432/skillflaw。

    如果你使用高可用部署，应使用虚拟 IP 或代理主机名，而不是直接数据库主机。 详见下文 PostgreSQL 高可用。

  3. 通过 .env 文件或部署平台的环境变量管理能力配置 SkillFlaw。

    1. 在 SkillFlaw 部署目录中创建 .env 文件：


      _10
      touch .env

    2. 把连接串写入 .env：


      _10
      SKILLFLAW_DATABASE_URL="postgresql://skillflaw:securepassword@postgres:5432/skillflaw"

      更多变量说明请参阅 环境变量。

  4. 使用 PostgreSQL 连接启动 SkillFlaw：


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

  5. 可选：执行迁移。

    SkillFlaw 使用迁移机制维护数据库 schema。 当 SkillFlaw 首次连接到 PostgreSQL 时，会自动运行迁移并创建所需表结构。

    直接手改 schema 可能会与 SkillFlaw 内建的 schema 管理冲突。 如果你需要更新 schema，可以使用 SkillFlaw CLI 手动执行迁移：

    1. 先运行 skillflaw migration 预览变更。

    2. 审核变更，确认迁移是安全的。

    3. 运行 skillflaw migration --fix 正式执行迁移。

      这是一个可能删除数据的破坏性操作。 更多说明请参阅 skillflaw migration。

  6. 为了验证配置，可以在可视化编辑器或 API 中随便创建一个流程，然后检查数据库中是否已记录相应表与活动。 流程内容本身不重要，重点是确认数据确实落到了 PostgreSQL 中。

    例如可执行：


    _10
    SELECT * FROM pg_stat_activity WHERE datname = 'skillflaw';

PostgreSQL 高可用​

为了进一步提升性能、可靠性与可扩展性，建议在生产环境中采用高可用（HA）或 Active-Active HA PostgreSQL 架构。 当多个 SkillFlaw 实例依赖同一个数据库时，这一点尤其重要，因为它可以降低停机风险，并在数据库节点故障时维持服务连续性。

  1. 配置流复制：

    1. 配置一个主库负责写入。

    2. 配置一个或多个副本用于读取与故障切换。

      根据你的延迟与一致性要求，在同步复制与异步复制之间做选择。

  2. 通过以下任一方案实现自动故障切换：

    • 使用 HA 编排器、分布式配置存储与流量路由器，例如 Patroni、etcd 或 Consul，以及 HAProxy。
    • 单独使用 Pgpool-II，或配合其他支持服务增强 HA 能力。
    • 使用具备内建自动故障切换的托管服务，例如 AWS RDS 或 Google Cloud SQL。

  3. 将 PostgreSQL 连接串更新为指向 HA 入口。 如果你采用多实例 SkillFlaw 部署，请确保所有实例连接到同一个 HA PostgreSQL。

    连接串形式取决于你的 HA 方案：

    • 使用一个总是指向当前主库的虚拟 IP 或 DNS 名，例如 postgresql://skillflaw:securepassword@db-proxy:5432/skillflaw?sslmode=require。
    • 使用托管服务提供的官方 endpoint，例如 skillflaw.cluster-xyz.us-east-1.rds.amazonaws.com。

  4. 可选：为读密集型场景增加读负载均衡：

    1. 使用如 PgBouncer 之类的连接池，把读请求分发给多个副本。
    2. 让 SkillFlaw 仍通过一个统一连接串连接到主 PostgreSQL 或代理入口。

在完成 HA 或 Active-Active HA 之后，请持续监控故障切换事件，并确认副本是否保持同步。 如果设置了 SKILLFLAW_DATABASE_CONNECTION_RETRY=True，SkillFlaw 会借助 SQLAlchemy 在数据库恢复后尝试重新连接，从而减轻故障切换造成的中断。

虽然 PostgreSQL 对并发连接支持较好，但你仍需要监控高负载下的锁竞争、死锁以及性能退化情况。

数据库故障的影响​

如果 PostgreSQL 不可用，以下 SkillFlaw 功能会失败：

  • 流程读取：无法从数据库加载新流程或已有流程。
  • 流程保存：无法保存新流程，也无法更新已有流程。
  • 用户认证：登录与用户管理功能失效。
  • 项目集合访问：无法访问或共享社区 / 自定义项目集合。
  • 配置读取：无法读取应用设置。
  • 配置更新：无法保存设置变更。
  • 执行日志访问：无法获取历史执行日志。
  • 日志写入：新的执行日志或系统日志无法落库。
  • 多用户协作：用户之间无法共享流程或项目。
  • API 流程加载：涉及加载新流程（未命中缓存）的 API 请求会失败。

那些已经加载到内存中的流程，有时仍可继续运行，只要依赖缓存配置即可。 但一切需要数据库访问的操作都会失败，直到数据库恢复。 例如，一个缓存中的流程可能还能执行，但无法再把日志或消息历史写入数据库。

为了尽量降低数据库故障的概率与影响，建议采用 HA 配置，并定期做备份。 例如，可以通过 pg_dump 做逻辑备份，或者启用 WAL 持续归档，以支持时间点恢复。 同时应定期演练恢复流程，确保团队在灾备场景中知道如何真正执行恢复。

数据库监控​

请持续监控 PostgreSQL，以保障性能与可靠性：

  • 可使用 pgAdmin、Prometheus + PostgreSQL exporter，或云平台自带的 PostgreSQL 监控工具。
  • 跟踪 CPU、内存与磁盘 I/O 等性能指标。
  • 监控副本健康状态、可用性、延迟与同步情况。 例如，可使用 pg_stat_activity 监控连接数与竞争情况。
  • 针对高延迟、故障切换与复制问题设置告警。
  • 启用 PostgreSQL 日志（如 log_connections、log_statements）以追踪访问与变更。

另请参阅​