数据库

PostgreSQL 安装与运维

FreeAnima 用 PostgreSQL 存对话归档、语义记忆、自我层及相关数据。相关概念：memory.md、sleep.md。安全与凭证：security.md。

连接配置

在 config.yaml 中设置数据库 URL：

database:
  url: postgresql://user:pass@localhost:5432/anima
  # or use env() (bootstrap cannot resolve vault() — Vault lives in PG):
  # url: env("DATABASE_URL")

生产环境必须设置 database.url。优先 env("DATABASE_URL")，避免在 config.yaml 中写明文密码（冷启动无法解析 Vault）。路径约定： security.md。

可选连接池覆盖（见 packages/habitat/core/db/pg/client.ts / pool-options.ts）：

Env	Default	说明
`FREEANIMA_PG_POOL_MAX`	`10`	连接池上限，对齐部署 `max_connections`
`FREEANIMA_PG_POOL_IDLE_TIMEOUT`	`0`	秒；`0` = 关闭。Bun ≤1.4.0 勿设 `30`（会误杀长查询，见 troubleshooting）
`FREEANIMA_PG_POOL_MAX_LIFETIME`	`600`	秒；周期性换连接，缩小 Bun SQL 预处理语句缓存串台窗口。显式 `0` = 不限制寿命
`FREEANIMA_PG_POOL_HEAL_INTERVAL_MS`	`10000`	毒连接扫描间隔（毫秒）。独立监控连接查 `idle in transaction (aborted)` 后对业务池 `ROLLBACK`。`0` = 关闭

业务池 application_name=freeanima-habitat；监控连接 freeanima-habitat-heal（不经业务池）。

本地安装（Docker，跨平台）

Windows / macOS 上推荐，Linux 也可。镜像含 pgvector：

docker run -d --name anima-pg \
  -e POSTGRES_USER=anima \
  -e POSTGRES_PASSWORD=anima \
  -e POSTGRES_DB=anima \
  -p 5432:5432 \
  pgvector/pgvector:pg18

config.yaml（示例）：

database:
  url: postgresql://anima:anima@127.0.0.1:5432/anima
  # or: url: env("DATABASE_URL")

Windows 贡献者说明（winget、Git Bash、Redis 容器）： windows-dev.md。

本地安装（Debian）

# Install PostgreSQL, create anima db/user (requires sudo)
sudo ./scripts/setup-postgres-debian.sh

# config.yaml (example):
#   url: env("DATABASE_URL")

默认：PostgreSQL 18，仅 localhost，scram-sha-256，专用 anima 库与用户。

扩展（一次性）

全文与向量检索需要 PostgreSQL 扩展。应用用户通常无法 CREATE EXTENSION；请以超级用户执行：

sudo apt install postgresql-18-pgvector   # match psql --version
sudo -u postgres psql -d anima -f core/scripts/ensure-pg-extensions.sql

通过 setup-postgres-debian.sh 全新安装的 Debian 会自动处理扩展。

Schema 迁移

生产环境（推荐）： 配置 PostgreSQL 后，anima service 启动时会自动应用待执行的 schema 迁移。
手动：

DATABASE_URL="postgresql://anima:…@127.0.0.1:5432/anima" \
  just db migrate

安装扩展后执行，或重启 anima service。

`auto_llm_runs` / `auto_llm_messages`（审计）

非对话聊天 LLM（cron agent、记忆维护流水线阶段、对话标题、目标判定、压缩 / handoff 摘要）写入 auto_llm_runs + auto_llm_messages，而不是 conversations / messages。开跑即插入 status=running（finished_at 为空），消息随引擎轮 / 工具轮次追加；结束才 ok / error。栖息地启动（迁移完成后）把残留 running 标为 error（文案：栖息地重启，运行中断）——这是收尸，不是续跑。 output 为最后一条成功助手正文。助手消息 payload.usage 只存供应商用量（prompt / cached / completion tokens）；tokenx 估算仅用于事前上下文窗口，不落库。保留策略（栖息地运行时 / 壳 设置 → 栖息地服务 → 服务配置 auto_llm）：

# habitat_runtime_config fragment (not config.yaml)
auto_llm:
  retention_days: 30
  per_run_kind_keep: 100

在 memory-maintenance 步骤 conversation-cleanup（过期对话清理之后）清理；不删除仍为 running 的行；年龄按 coalesce(finished_at, created_at)。删除 run 时 auto_llm_messages 级联删除。Cron 脚本运行（no_agent）仅用 cron_log。

备份

迁移不能替代备份 — 请定期安排全量备份（如 pg_dump）。
破坏性变更前先备份。
实例集合： PostgreSQL 必需（含 User vault，Agent 根密钥 SSOT）。按需备份 ~/.anima/（FREEANIMA_HOME）中的引导配置 / TLS / 微信等 — 见 security.md。Agent 的 vault/agent-machine.key 是可重建缓存（恢复后从数据维护解锁）。
推荐本机栈：小时级 pg_dump + home tar（短保留）、WAL 归档（archive_mode）、周级 pg_basebackup 做 PITR。逻辑转储以 postgres 超级用户恢复（pg_restore --no-owner --no-acl --no-comments）。
搜索旁表： 可重建索引数据在 search_documents（不在业务 entities / messages）。仅业务逻辑转储可排除它，例如 pg_dump --exclude-table-data=search_documents …，恢复后跑栖息地 FTS rebuild。要保持搜索热的完整转储应包含该表。

集成测试（开发者）

完整集成测试需要 Docker 提供临时 PostgreSQL 实例：

just qa test-integration
just qa test-integration -- --core
just qa test-integration -- tests/integration/memory/foo.test.ts
just test              # unit + integration（串行）

pre-commit / pre-push 不跑 integration；PR CI 全量；功能/修 bug 主动 --core。

故障排查

现象	检查
服务连库失败	`database.url`；PostgreSQL 是否在跑；若用了 `env()` 引用是否可解析；启动错误信息会列出下一步（缺库、鉴权、连接、扩展）
启动/迁移出现 `Idle timeout reached after 30s`	Bun ≤1.4.0 会误杀进行中查询（oven-sh/bun#30646，1.4 仍复现）。确保 `FREEANIMA_PG_POOL_IDLE_TIMEOUT=0`（默认）或临时导出该变量后重启
栖息地「未就绪」超时而进程仍在跑	迁移在 HTTP listen 之前；默认等 15min（`FREEANIMA_HABITAT_READY_TIMEOUT_MS`）。看 `journalctl --user -u anima -f`，勿中途 `stop`
迁移失败	扩展已安装；DB 用户有 DDL 权限；HNSW / 大批量 backfill 可能很慢，勿与上述 idle timeout 混淆
FTS / 关键词召回为空	已执行 `ensure-pg-extensions.sql`（`pg_trgm`）；必要时 jieba/FTS rebuild
Inbox：`Builtin failed` 且 cause 含 `bind message supplies N parameters, but prepared statement … requires M`	Bun SQL 预处理语句缓存串台（oven-sh/bun#30494），不是业务 SQL 写错。Failed query 的 params 个数与 cause 里 statement 对不上；statement 名常是别的查询的 40 字符截断（如 `Pselect "id", "type"…`）。立刻：重启 Habitat 清毒连接。缓解：默认 `FREEANIMA_PG_POOL_MAX_LIFETIME=600` + 毒连接回收（扫 `idle in transaction (aborted)` 后池内 `ROLLBACK`）；勿设 `prepare: false`（jsonb 会绑成 `[object Object]`）。根治：升到含 statement-cache 按 name 字节建键的 Bun 版本后可再观察是否仍复现

更多部署安全事项：security.md。

数据库