数据库

PostgreSQL 安装与运维

FreeAnima uses PostgreSQL for conversation archives, semantic memory, self layer, and related data. Related concepts: memory.md, sleep.md. Security and credentials: 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")

Production must set database.url. Prefer env("DATABASE_URL") over plaintext passwords in config.yaml (Vault is unavailable at cold start). Path conventions: security.md.

Optional pool overrides（见 src/host/core/db/pg/client.ts）:

Env	Default	Notes
`FREEANIMA_PG_POOL_MAX`	`10`	连接池上限，对齐部署 `max_connections`
`FREEANIMA_PG_POOL_IDLE_TIMEOUT`	`0`	秒；`0` = 关闭。Bun ≤1.3.14 勿设 `30`（会误杀长查询，见 troubleshooting）
`FREEANIMA_PG_POOL_MAX_LIFETIME`	`0`	秒；`0` = 不限制连接寿命

本地安装（Debian）

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

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

默认：PostgreSQL 17、仅 localhost、scram-sha-256、专用 anima 数据库与用户。

扩展（一次性）

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

sudo apt install postgresql-17-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`（审计）

Background LLM without user turns (cron agent, sleep pipeline stages) writes to auto_llm_runs instead of creating conversations. Retention (Habitat runtime / Shell Settings → Habitat 服务 → 服务配置 auto_llm):

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

在 sleep-cycle 步骤 conversation-cleanup（过期对话清理之后）中清除。Cron 脚本运行（no_agent）仅使用 cron_log。

备份

迁移不能替代备份 — 请定期安排全量备份（如 pg_dump）。
破坏性变更前先备份。
备份策略应包含 ~/.anima/（可用 FREEANIMA_HOME 覆盖）——见 security.md。
Recommended local stack: hourly pg_dump + home tar (short retention), WAL archive (archive_mode), weekly pg_basebackup for PITR. Restore logical dumps as postgres superuser (pg_restore --no-owner --no-acl --no-comments).

集成测试（开发者）

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

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

pre-commit 的 just qa test-changed 不会运行集成测试。

故障排查

Symptom	Check
Service fails on DB connect	`database.url`; PostgreSQL running; `env()` refs resolvable if used; startup error message lists next steps (missing DB, auth, connection, extensions)
`Idle timeout reached after 30s` on startup/migrate	Bun ≤1.3.14 会误杀进行中查询（oven-sh/bun#30646）。确保 `FREEANIMA_PG_POOL_IDLE_TIMEOUT=0`（默认）或临时导出该变量后重启
Habitat 「未就绪」超时而进程仍在跑	迁移在 HTTP listen 之前；默认等 15min（`FREEANIMA_HABITAT_READY_TIMEOUT_MS`）。看 `journalctl --user -u anima -f`，勿中途 `stop`
Migration fails	Extensions installed; DB user has DDL privileges；HNSW / 大批量 backfill 可能很慢，勿与上述 idle timeout 混淆
FTS / keyword recall empty	`ensure-pg-extensions.sql` applied (`pg_trgm`); jieba/FTS rebuild if needed

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

数据库