---
title: 部署指南
created: 2026-02-25
---

# 部署指南

## 前置条件

- Python 3.10+，已安装 [uv](https://github.com/astral-sh/uv)
- Docker + Docker Compose（含 pgvector 扩展，推荐）或本机 PostgreSQL 15+
- OpenRouter API key

## 步骤

### 1. 启动 pgvector

在 `.scripts/memory/` 目录下创建 `docker-compose.yml`：

```yaml
services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: pgvector
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: memory
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data
      - ./initdb:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d memory"]
      interval: 5s
      timeout: 3s
      retries: 20

volumes:
  pg_data:
```

启动：

```bash
docker compose up -d
# 等待 healthy 后再继续
docker compose ps
```

### 2. 初始化 Schema

```bash
psql postgresql://postgres:postgres@localhost:5432/memory -f schema.sql
```

### 3. 配置环境变量

```bash
cp .env.memory.example .env.memory
# 编辑 .env.memory，填入 VAULT_DIR 和 OPENROUTER_API_KEY
```

必填项：

```ini
VAULT_DIR=/path/to/your/obsidian-vault
PG_DSN=postgresql://postgres:postgres@localhost:5432/memory
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_EMBED_MODEL=openai/text-embedding-3-small
OPENROUTER_EMBED_DIM=1536
```

### 4. 安装依赖

```bash
uv sync
```

### 5. 全量索引

```bash
uv run python ingest_vault.py
```

预期输出：`[DONE] 全量索引完成 primary=N secure=N ...`

### 6. 安装 Git Hook（在 vault 目录执行）

```bash
bash /path/to/vault-memory-pgvector/install-hook.sh
```

验证：`.git/hooks/post-commit` 中出现 `memory async index hook begin`

## 验收检查

| 检查项 | 命令 | 预期 |
|---|---|---|
| DB 连通 | `psql $PG_DSN -c "SELECT 1;"` | 返回 `1` |
| 表存在 | `psql $PG_DSN -c "\dt memory_*"` | 两张表可见 |
| 索引条数 | `psql $PG_DSN -c "SELECT count(*) FROM memory_primary;"` | > 0 |
| 查询链路 | `uv run python query_pgvector.py "测试查询"` | 返回 `<retrieved_context>` 块 |
| Hook 生效 | 提交一个 `.md` 文件后查看 `.memory-sync.log` | 出现 `[UPSERTED]` |

## 回滚

禁用记忆同步（不删数据）：

```bash
# 编辑 vault 的 .git/hooks/post-commit
# 删除 --- memory async index hook begin --- 到 --- memory async index hook end --- 之间的内容
```

清空数据库：

```bash
psql postgresql://postgres:postgres@localhost:5432/memory \
  -c "TRUNCATE memory_primary, memory_secure_audit;"
```