博客首页开源平台

Pigsty 自托管 Hindsight：PostgreSQL 原生 AI Agent 长期记忆服务的部署实战

原创2026-10-02 00:50:37485 阅读
文章标签：数据库运维云原生高可用监控

Pigsty 自托管 Hindsight：PostgreSQL 原生 AI Agent 长期记忆服务的部署实战

Hindsight 是面向 AI Agent 的 PostgreSQL 原生长期记忆（long-term memory）服务。本文以 Pigsty 仓库中的 hindsight 应用模板 为主线，讲解如何在 Pigsty 上以外部 PostgreSQL 集群方式自托管 Hindsight：从一条命令拉起全栈，到默认设计取舍、接入真实 LLM、再到中文多语检索的进阶调优。读完本文，你将掌握一套「一个 All-in-One 容器 + 一个 Pigsty 托管数据库 + 两个门户入口」的最小可运行 Hindsight 部署方案，并能根据自己的模型与检索需求完成参数级定制。

Hindsight 与 Pigsty 的集成方式

Hindsight 的官方部署路径默认带有一个嵌入式开发数据库 pg0，但在生产或正式使用场景下，人们通常希望把记忆数据托管在真正被管理的 PostgreSQL 实例中。Pigsty 提供的这套模板正是走 Hindsight 官方 external PostgreSQL 部署路径：用 Pigsty 创建并管理独立的 PostgreSQL 集群，Hindsight 容器通过 postgresql:// 连接串访问它，而不是使用容器内嵌的数据库。

整套栈保持最小化，由三部分组成：

  • 一个 All-in-One Hindsight 容器（官方镜像 ghcr.io/vectorize-io/hindsight:latest），同时提供控制平面 UI 与 REST API；
  • 一个由 Pigsty 管理的 PostgreSQL 数据库 hindsight，承载全部记忆数据与向量索引；
  • 两个 Pigsty 门户入口，分别把域名代理到 UI 与 API 端口。

快速开始：四条命令完成部署

先确保目标节点满足 Pigsty 的安装前提（全新 OS、静态 IP、可执行 root 免密 sudo），然后按以下步骤操作：

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap                  # prepare local repo & ansible
./configure -c app/hindsight # use the hindsight config template
vi pigsty.yml                # IMPORTANT: CHANGE CREDENTIALS / DOMAIN / LLM SETTINGS
./deploy.yml                 # install pigsty & pgsql
./docker.yml                 # install docker & docker-compose
./app.yml                    # install hindsight with docker-compose

四个阶段各司其职：

  • ./bootstrap 准备本地软件源与 Ansible 运行环境；
  • ./configure -c app/hindsight 以 conf/app/hindsight.yml 为配置模板生成 pigsty.yml（.configure -c 指定的是配置文件相对 conf/ 的路径，故写作 app/hindsight）；
  • ./deploy.yml 安装 Pigsty 基础设施与 PostgreSQL 集群；
  • ./docker.yml 在目标节点安装 Docker 与 Docker Compose；
  • ./app.yml 将 app/hindsight/ 目录中的 Compose 资源部署到目标机并拉起 Hindsight。

部署完成后，你有四个访问入口：

入口 地址 说明
UI（门户） http://hs.pigsty Hindsight 控制平面界面，代理到 9999 端口
API（门户） http://hs-api.pigsty Hindsight REST API，代理到 8888 端口
API（直连） http://<your-ip>:8888 不经门户的 API 直连端口
UI（直连） http://<your-ip>:9999 不经门户的 UI 直连端口

其中 hs.pigsty / hs-api.pigsty 两个域名来自 infra_portal 配置，详见下文「门户路由」一节。

模板提供了什么

部署完成后，你实际获得的资产包括：

  • Pigsty 托管的 PostgreSQL 数据库 hindsight，专属服务用户也叫 hindsight；
  • vector 扩展：通过 Pigsty 的 pgvector 扩展默认启用，为记忆检索提供向量索引能力；
  • 官方 All-in-One 镜像 ghcr.io/vectorize-io/hindsight:latest 的 Docker Compose 应用；
  • 持久化模型缓存目录 /data/hindsight：用于存放下载的 embedding / reranker 本地模型，容器重建后模型无需重新下载；
  • 两个 Pigsty 门户：
    • hs.pigsty → Hindsight 控制平面 UI（9999）；
    • hs-api.pigsty → Hindsight REST API（8888）。

默认设计选择：先求「能跑起来」

模板默认采用一组保守但稳妥的组合：

  • 外部 PostgreSQL：由 Pigsty 管理，而非 Hindsight 内嵌的 pg0；
  • pgvector：负责向量检索（vector search）；
  • native：PostgreSQL 原生全文检索（text search）；
  • HINDSIGHT_API_LLM_PROVIDER=none：不连接任何外部模型服务。

最后一项值得特别说明。none provider 的意图是让整栈在没有任何外部模型依赖的情况下立即可启动——你不必先搭好 Ollama 或申请 OpenAI Key 就能把 UI 和 API 跑起来。代价是：事实抽取（fact extraction）、记忆整合（consolidation）与 reflect 等依赖 LLM 的能力会保持受限，直到你为它接入一个真实的 LLM provider。

这一点在 app/hindsight/.env 中体现得很直白：

# Default to `none` so the stack boots without any external model provider.
# Switch to ollama/openai/groq/... to enable fact extraction, consolidation and reflect.
HINDSIGHT_API_LLM_PROVIDER=none
HINDSIGHT_API_LLM_MODEL=gpt-5-mini
HINDSIGHT_API_LLM_API_KEY=
#HINDSIGHT_API_LLM_BASE_URL=https://api.openai.com/v1

配置模板的源码级拆解

应用组定义：conf/app/hindsight.yml

conf/app/hindsight.yml 是整个部署的核心配置。它定义了四个节点角色组，全部落在同一台主机 10.10.10.10 上：

hindsight 应用组通过 apps 声明应用自身的运行参数：

hindsight:
  hosts: { 10.10.10.10: {} }
  vars:
    app: hindsight   # specify app name to be installed (in the apps)
    apps:
      hindsight:
        file:
          - { path: /data/hindsight ,state: directory ,mode: 0755 }
        conf:
          HINDSIGHT_VERSION: latest
          HINDSIGHT_API_PUBLISH_PORT: 8888
          HINDSIGHT_UI_PUBLISH_PORT: 9999
          HINDSIGHT_MODEL_CACHE: /data/hindsight
          HINDSIGHT_DB_HOST: 10.10.10.10
          HINDSIGHT_DB_PORT: 5432
          HINDSIGHT_DB_NAME: hindsight
          HINDSIGHT_DB_USER: hindsight
          HINDSIGHT_DB_PASSWORD: DBUser.Hindsight
          HINDSIGHT_DB_SCHEMA: public
          HINDSIGHT_API_VECTOR_EXTENSION: pgvector
          HINDSIGHT_API_TEXT_SEARCH_EXTENSION: native
          HINDSIGHT_API_LLM_PROVIDER: none
          HINDSIGHT_API_LLM_MODEL: gpt-5-mini
          HINDSIGHT_API_LLM_API_KEY: ''
  • file 声明需要预创建的目录 /data/hindsight（权限 0755），这正是模型缓存卷的主机侧目录；
  • conf 中所有键会被 app.yml 逐一写入目标机 /opt/hindsight/.env。

pg-meta 集群组定义了记忆数据库的规格：单节点主库 pg-meta，启用 pgvector 扩展；创建服务用户 hindsight（允许 pgbouncer、pool_mode: session、角色 dbrole_readwrite）；创建数据库 hindsight（owner 为 hindsight，扩展 vector）。同时专门为 Docker 桥接网段放行访问：

pg_hba_rules:
  - { user: hindsight ,db: all ,addr: 172.17.0.0/16 ,auth: pwd ,title: 'allow hindsight access from local docker network' }

这行 HBA 规则是整条链路能连通的关键：Hindsight 容器默认经 172.17.0.0/16 的 Docker 网络访问宿主机 5432 端口，必须显式允许该网段。

模板还顺带配置了每日自动备份：

pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am

即每天凌晨 1 点对集群执行一次全量备份（Pigsty 的 pg-backup 脚本，参考 files/postgres/pg-backup）。

infra 与 etcd 组提供门户反代与高可用协调所需的依赖组件。infra_portal 是门户路由的定义位置：

infra_portal:
  home: { domain: i.pigsty }
  hindsight:
    domain: hs.pigsty
    endpoint: "10.10.10.10:9999"
    websocket: false
    certbot: hs.pigsty
  hindsight-api:
    domain: hs-api.pigsty
    endpoint: "10.10.10.10:8888"
    websocket: false
    certbot: hs-api.pigsty

即 Nginx 门户把 hs.pigsty 代理到 10.10.10.10:9999（UI），把 hs-api.pigsty 代理到 10.10.10.10:8888（API），并可为两个域名签发 Let's Encrypt 证书。全局变量中还定义了 docker_enabled: true、node_repo_modules: node,infra,pgsql、pg_version: 18 等基础设施参数；模板顶部注释给出了替换域名的快捷方式：

sed -ie 's/hs.pigsty/hs.yourdomain.com/g; s/hs-api.pigsty/hs-api.yourdomain.com/g' pigsty.yml

安装流程：app.yml 如何工作

应用安装由根目录的 app.yml Playbook 驱动，它按固定顺序完成四件事：

  1. 拷贝资源：把 app/<appname>/ 目录（默认 src，可用 app_def.src 覆盖）复制到目标机 /opt/<appname>/（默认 dest，可用 app_def.dest 覆盖）；
  2. 准备目录：按 app.file 列表创建目录/文件；
  3. 写入环境变量：按 app.conf 以 lineinfile 方式更新 /opt/<appname>/.env，密钥落盘时文件权限设为 0600，并在日志中隐藏取值（no_log: true）；
  4. 启动应用：在 /opt/<appname> 目录下执行 make {{ app_args }}（Hindsight 的 app_args 为空，即执行默认的 make up）。

因此，部署后的实际运行时配置位于目标机的 /opt/hindsight/.env，这也是后续修改 LLM 或检索参数时的第一修改点——原文档也明确提示：编辑 /opt/hindsight/.env，或在 pigsty.yml 的 app.conf 中覆盖相同键后重新执行 ./app.yml。

Compose 编排：docker-compose.yml

app/hindsight/docker-compose.yml 是整个应用的最小编排定义：单一服务 hindsight，使用官方 All-in-One 镜像 ghcr.io/vectorize-io/hindsight:${HINDSIGHT_VERSION:-latest}。其中两个细节值得注意：

extra_hosts:
  - host.docker.internal:host-gateway

这行把 host.docker.internal 映射到宿主机网关，使容器内能直接访问宿主机上运行的 Ollama（http://host.docker.internal:11434/v1），也解释了 README 中 Ollama 配置为什么使用该主机名。

ports:
  - '${HINDSIGHT_API_PUBLISH_PORT:-8888}:${HINDSIGHT_API_PORT:-8888}'
  - '${HINDSIGHT_UI_PUBLISH_PORT:-9999}:9999'
volumes:
  - '${HINDSIGHT_MODEL_CACHE:-/data/hindsight}:/home/hindsight/.cache'

端口与模型缓存目录全部通过环境变量可覆盖，默认值与模板一致。

启用真实 LLM

默认 none provider 只能让栈「活着」，要启用记忆抽取与 reflect，需要把 HINDSIGHT_API_LLM_PROVIDER 切换为真实 provider。修改位置是目标机 /opt/hindsight/.env，或在 pigsty.yml 的 app.conf 中覆盖同名键后重跑 ./app.yml。

使用同机 Ollama

如果宿主机已运行 Ollama，用 host.docker.internal 访问即可（Compose 已自动映射该主机名）：

HINDSIGHT_API_LLM_PROVIDER=ollama
HINDSIGHT_API_LLM_BASE_URL=http://host.docker.internal:11434/v1
HINDSIGHT_API_LLM_MODEL=qwen3:8b

这是最省事的本地化方案：模型推理不出本机，记忆数据不出本机。

使用 OpenAI 兼容 API

HINDSIGHT_API_LLM_PROVIDER=openai
HINDSIGHT_API_LLM_BASE_URL=https://api.openai.com/v1
HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxx
HINDSIGHT_API_LLM_MODEL=gpt-5-mini

由于 OpenAI 兼容协议已成为事实标准，HINDSIGHT_API_LLM_BASE_URL 也可以指向任何兼容网关（如本地代理、国产模型服务的 OpenAI 兼容端点）。

中文 / 多语检索的进阶路径

默认的 pgvector + native 组合是「最稳妥的首次部署」：向量检索由 pgvector 提供，全文检索使用 PostgreSQL 内置的 native 实现。但如果你的语料以中文为主、对多语言 BM25 与分词质量有更高要求，模板预留了一条后续调优路径：使用 Pigsty 的 vchord 与 vchord_bm25 扩展。

在 PostgreSQL 中安装这两个扩展后（Pigsty 扩展体系已包含 vchord，参见 conf/app/hindsight.yml 中注释掉的配置项），将 .env 中的两项同时切换：

HINDSIGHT_API_VECTOR_EXTENSION=vchord
HINDSIGHT_API_TEXT_SEARCH_EXTENSION=vchord

.env 中还有一组面向本地模型的选项，适合内网或离线场景：

# Persist downloaded local reranker / embedding models across container restarts
#HINDSIGHT_API_EMBEDDINGS_PROVIDER=local
#HINDSIGHT_API_RERANKER_PROVIDER=local

配合 /data/hindsight 缓存卷，本地 embedding 与 reranker 模型下载一次即可跨容器重建持久复用。

管理命令与日常运维

Hindsight 应用目录自带 Makefile，部署到 /opt/hindsight 后即可直接使用：

命令 作用
make up 后台启动 Compose 应用（docker compose up -d），是 app.yml 内部调用的启动入口
make log 跟随容器日志（docker compose logs -f）
make info 查看容器状态（docker compose ps）
make down 停止并移除容器（docker compose down）
make pull 拉取最新镜像（docker compose pull）
make clean 移除容器（docker compose rm），并提示：如有需要请到 PostgreSQL 中清理 hindsight 数据库
make save / make tarball 把镜像导出为 gzip 压缩的 tgz（默认存 /tmp/docker/hindsight.tgz），便于离线内网分发
make load 从本地 tgz 加载镜像（docker load），离线部署时与 save 配对使用

make view 会在启动前打印关键环境变量摘要，方便快速核对配置是否生效：

view:
	cat .env | grep -E '^(HINDSIGHT_(API_PUBLISH_PORT|UI_PUBLISH_PORT|DB_NAME|DB_USER|API_LLM_PROVIDER|API_LLM_MODEL|API_VECTOR_EXTENSION|API_TEXT_SEARCH_EXTENSION))='

运维层面，记忆数据库 hindsight 与 Pigsty 托管的其他 PostgreSQL 集群享受同等待遇：每日凌晨 1 点的全量备份（见上文 pg_crontab）、Patroni 高可用、监控面板与告警规则（参考 files/grafana/pgsql/ 系列面板）均可直接复用。

参数速查表

以下环境变量决定了 Hindsight 部署的行为，全部可在 pigsty.yml 的 app.conf 或目标机 /opt/hindsight/.env 中调整：

变量 默认值 说明
HINDSIGHT_VERSION latest 镜像版本标签
HINDSIGHT_API_PUBLISH_PORT 8888 API 宿主端口
HINDSIGHT_UI_PUBLISH_PORT 9999 UI 宿主端口
HINDSIGHT_MODEL_CACHE /data/hindsight 模型缓存卷（容器内 /home/hindsight/.cache）
HINDSIGHT_DB_HOST 10.10.10.10 PostgreSQL 主机
HINDSIGHT_DB_PORT 5432 PostgreSQL 端口
HINDSIGHT_DB_NAME / HINDSIGHT_DB_USER / HINDSIGHT_DB_PASSWORD hindsight / hindsight / DBUser.Hindsight 数据库名、用户、密码（必须与 pg_users 一致）
HINDSIGHT_DB_SCHEMA public 使用的数据库 schema
HINDSIGHT_API_VECTOR_EXTENSION pgvector 向量扩展，可切换 vchord
HINDSIGHT_API_TEXT_SEARCH_EXTENSION native 全文检索扩展，可切换 vchord
HINDSIGHT_API_LLM_PROVIDER none LLM provider：none / ollama / openai 等
HINDSIGHT_API_LLM_MODEL gpt-5-mini 默认模型名（none 下不生效）
HINDSIGHT_API_LLM_BASE_URL 空 兼容端点，Ollama 用 http://host.docker.internal:11434/v1
HINDSIGHT_API_LLM_API_KEY 空 API Key
HINDSIGHT_API_LOG_LEVEL info 日志级别

数据库连接串由 .env 中的片段拼接而成：HINDSIGHT_API_DATABASE_URL 与 HINDSIGHT_API_MIGRATION_DATABASE_URL 都取 postgresql://${HINDSIGHT_DB_USER}:${HINDSIGHT_DB_PASSWORD}@${HINDSIGHT_DB_HOST}:${HINDSIGHT_DB_PORT}/${HINDSIGHT_DB_NAME} 的形式，schema 由 HINDSIGHT_API_DATABASE_SCHEMA 指定。

小结

这套模板的价值在于把「AI Agent 长期记忆」这一前沿能力，落到了 Pigsty 一贯的托管底座上：记忆数据不是散落在容器内嵌库里的孤儿，而是受 Patroni 高可用、每日全量备份、监控告警覆盖的正规 PostgreSQL 集群；向量检索与全文检索由可切换的扩展体系支撑；LLM 接入从 none 起步、按需演进到 Ollama 或任意 OpenAI 兼容端点。对于希望「像管理数据库一样管理 AI 记忆」的团队，这是一条低摩擦、可审计、可演进的实践路径。

登录后查看全文
数据库运维云原生高可用监控
版权声明：本文由 AtomGit 博客平台 AIGC 生成并经审核发布，遵循 CC 4.0 BY-SA 版权协议，转载请注明出处。
pigsty

相关推荐

Cognee 实战指南：用自托管知识图谱为 AI Agent 构建持久长期记忆
Cognee 是当前仓库（cognee）所承载的开源 AI 记忆平台，核心目标是为 AI Agent 提供跨会话的持久长期记忆：以任意格式摄取数据，构建可自托管的知识图谱，让每个 Agent 都能在完整上下文中回忆、连接与行动。本文以仓库根目录 [README.md](https://gitcode
人工智能 2236
nanobot 自托管 AI Agent 部署指南：从本地网关到生产级服务
nanobot 是一个基于 Python 的轻量级、开源、可自托管的个人 AI Agent 框架。本文以官方指南 self-hosted-ai-agent.md 为主线，完整讲解如何在自有机器或服务器上把 nanobot 运行成一个长期在线的网关进程：它将统一承载 WebUI 浏览器工作台、聊天应用
人工智能 1430
AI Agent如何拥有长期记忆？Agentic Design Patterns记忆管理（Memory Management）指南
> 在 **Agentic Design Patterns** 这本 424 页的实战指南中，**记忆管理（Memory Management）**是第 8 章的核心主题。它回答了所有 AI Agent 构建者最关心的问题：**如何让你的 AI Agent 拥有长期记忆**，跨会话记住用户偏好、任务
文档 335
上一篇：XPipe 10.1 增量更新解读：文件下载区重设计、连接管理 API 扩展与平台兼容性修复下一篇：stitch-skills 实战：基于 shadcn/ui 组件库的品牌化主题定制完全指南

热门文章

Awesome 清单宣言解读：遵循 awesome 社区标准打造高质量精选资源列表的完整指南 HOT
文档 2674
Awesome 列表贡献指南：从首次提交到 Pull Request 合并的完整实战流程
文档 2520
从零创建并提交一个 Awesome 精选列表：完整流程、硬性门槛与规范实战指南
文档 1966