mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-12 03:00:50 +08:00
docs(pg): slim migration guide to shell one-liners
Migrator: only refuse import when SQLite and PG both have rows for a table (PG seed rows ok when SQLite empty). Add unit test for conflict helper. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
parent
1caf96e694
commit
0dc0c4663f
3 changed files with 73 additions and 189 deletions
|
|
@ -1,204 +1,61 @@
|
|||
# Assistant 库：SQLite → PostgreSQL 迁移指南
|
||||
# Assistant 库：SQLite → PostgreSQL
|
||||
|
||||
本文说明如何将 **助手主持久化**（会话、`chat_message`、设置、租户等）从默认 **SQLite** 迁到 **PostgreSQL**，以及割接前后的操作顺序与排障要点。实现上仍通过同一套 `SqliteStore` API；仅底层连接与 SQL 方言不同。
|
||||
|
||||
更完整的环境变量说明见 [`ENVIRONMENT_VARIABLES.md`](./ENVIRONMENT_VARIABLES.md) 中的「存储与迁移」一节；本文侧重 **操作步骤与脚本**。
|
||||
环境变量与字段说明见 [`ENVIRONMENT_VARIABLES.md`](./ENVIRONMENT_VARIABLES.md)。下文只列 **仓库根** 下各场景 **一条命令**（壳脚本；底层 migrator 由壳调用，不必手抄）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 何时需要读本文
|
||||
|
||||
- 生产或预发要把 **assistant 主库** 从 `data/ai_ops.sqlite`（或自定义 SQLite 路径）迁到 **PostgreSQL**。
|
||||
- 需要 **一次性导入历史数据**，再切换 `AIA_ASSISTANT_DB_BACKEND=postgresql` 上线。
|
||||
- 排查「PG 上表空 / 导入失败 / 网关连错库」等问题。
|
||||
|
||||
若只做 **新部署、无历史 SQLite 数据**：在空库上建 schema 后，直接配置 PG 与 `postgresql` 后端即可，**不必**跑数据导入脚本。
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心概念
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| 后端选择 | `AIA_ASSISTANT_DB_BACKEND`：`sqlite`（默认）或 `postgresql`（别名 `pg` / `postgres` 等）。 |
|
||||
| PG 连接串 | `AIA_ASSISTANT_DATABASE_URL`（或 `OPS_ASSISTANT_DATABASE_URL` / `AIA_ASSISTANT_PG_DSN` 等别名）。SQLAlchemy 使用时会规范为 `postgresql+psycopg://…`。 |
|
||||
| Schema 来源 | 推荐 **`alembic upgrade head`**（`alembic.ini` 的 `script_location = assistant_migrations`）。等价方式：在目标库执行 `svc/persistence/ddl/postgresql_bootstrap.sql`（与迁移首版语义一致，二选一即可，勿混用导致重复建表报错）。 |
|
||||
| 数据导入 | `runtime/operations/scripts/migrate_assistant_sqlite_to_postgresql.py`：**只拷数据**，不建表；要求目标 PG **已存在 schema**。默认要求 PG 中待拷贝表 **为空**（可用 `--allow-non-empty` 跳过检查，自担重复/FK 风险）。 |
|
||||
| 网关 | 进程内通过 `get_assistant_store()` 单例连库；**切换 URL 或后端后需重启网关**（必要时 `reset` 相关进程环境）。 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐总体顺序（ checklist ）
|
||||
|
||||
1. **在 PostgreSQL 上创建数据库**（例如 `oclaw`），为应用用户授予 `CREATE` / `USAGE` on schema `public` 及后续表所需权限。
|
||||
2. 在**目标库**上完成 **schema**：`alembic upgrade head`（仓库根执行，且已配置指向该库的 `DATABASE_URL` / 环境变量），或执行 `postgresql_bootstrap.sql`。
|
||||
3. **不要**在未建表的空库上直接启动依赖全表的生产网关（会报错或产生不一致状态）。应完成第 2 步后再启动，或先保持 `sqlite` 仅跑导入机。
|
||||
4. 使用下文 **割接脚本** 或 **直接调用 migrator**：先做 **`--dry-run`**，确认行数与表列表无误后再实导。
|
||||
5. 将运行环境改为 **`AIA_ASSISTANT_DB_BACKEND=postgresql`** 并设置 **`AIA_ASSISTANT_DATABASE_URL`**（与导入时**同一**目标库）。
|
||||
6. **重启**网关及所有使用 `get_assistant_store()` 的 worker，使新配置生效。
|
||||
7. 验证管理台会话列表、发一条测试消息、必要时跑 `AIA_TEST_PG_URL` 相关测试（见下文）。
|
||||
|
||||
---
|
||||
|
||||
## 4. Schema：Alembic（推荐）
|
||||
|
||||
仓库根：
|
||||
**在目标 PostgreSQL 上建空表（schema，二选一）**
|
||||
|
||||
```bash
|
||||
# 已设置 AIA_ASSISTANT_DATABASE_URL 指向目标 PG，且已安装依赖（含 alembic、psycopg）
|
||||
cd /path/to/oclaw
|
||||
export PYTHONPATH=.
|
||||
alembic upgrade head
|
||||
cd /path/to/oclaw && export PYTHONPATH=. && alembic upgrade head
|
||||
```
|
||||
|
||||
首版迁移 `assistant_migrations/versions/001_assistant_pg_initial.py` 会读取 `svc/persistence/ddl/postgresql_bootstrap.sql` 并逐条执行（仅当方言为 `postgresql` 时）。
|
||||
|
||||
**说明**：`downgrade()` 未实现；回滚依赖 **数据库备份 / 文件备份**，而非 Alembic 反向迁移。
|
||||
（若不用 Alembic：用 `psql` 等对目标库执行一次 `svc/persistence/ddl/postgresql_bootstrap.sql`，**勿**又对同一库再跑一遍 Alembic。）
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据导入：`migrate_assistant_sqlite_to_postgresql.py`
|
||||
|
||||
路径：`runtime/operations/scripts/migrate_assistant_sqlite_to_postgresql.py`。
|
||||
|
||||
**行为摘要**
|
||||
|
||||
- 从 SQLite 读表顺序（按 `PRAGMA foreign_key_list` 拓扑），仅插入 **SQLite 与 PG `public` 中同名的共有列**。
|
||||
- 默认若任一待拷贝表在 PG 中 **已有行** 则 **退出**（避免重复）；`--allow-non-empty` 可关闭该检查。
|
||||
- `--dry-run`：只统计源表行数，**不写 PG**。
|
||||
|
||||
**常用参数**
|
||||
|
||||
| 参数 | 含义 |
|
||||
|------|------|
|
||||
| `--sqlite PATH` | 源 SQLite 文件路径。 |
|
||||
| `--sqlite-from-db-path` | 使用 `db_path()`（受 `AIA_ASSISTANT_DB_PATH` 等影响）作为源库。 |
|
||||
| `--load-system-env` | 合并 `_local/system.env`（与网关 `load_system_env` 思路一致，便于设备上只维护一份 env）。 |
|
||||
| `--pg-url URL` | 目标 PG；不设则从环境变量读取（见脚本 `--help`）。 |
|
||||
| `--dry-run` | 预演。 |
|
||||
| `--allow-non-empty` | 允许目标表非空（慎用）。 |
|
||||
| `--batch N` | 批量插入行数，默认 500。 |
|
||||
|
||||
**示例（本机预演）**
|
||||
|
||||
```bash
|
||||
cd /path/to/oclaw
|
||||
export PYTHONPATH=.
|
||||
export AIA_ASSISTANT_DATABASE_URL='postgresql+psycopg://USER:PASS@127.0.0.1:5432/oclaw'
|
||||
python runtime/operations/scripts/migrate_assistant_sqlite_to_postgresql.py \
|
||||
--load-system-env --sqlite-from-db-path --dry-run
|
||||
# 确认无报错后去掉 --dry-run 再执行
|
||||
```
|
||||
|
||||
**显式路径示例**
|
||||
|
||||
```bash
|
||||
python runtime/operations/scripts/migrate_assistant_sqlite_to_postgresql.py \
|
||||
--sqlite data/ai_ops.sqlite \
|
||||
--pg-url 'postgresql+psycopg://postgres:pass@127.0.0.1:5432/oclaw'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 割接包装脚本（备份 + dry-run + 导入）
|
||||
|
||||
在跑正式导入前，**强烈建议**备份 SQLite 文件。脚本会把副本放到 `data/pg_cutover_backups/`（可改参数或环境变量）。
|
||||
|
||||
### 6.1 Windows（PowerShell）
|
||||
|
||||
`runtime/operations/scripts/cutover_sqlite_to_postgresql.ps1`
|
||||
|
||||
典型用法：
|
||||
**Windows：备份 SQLite → 预演 → 导入 PG**（`_local\system.env` 里已配好 `AIA_ASSISTANT_DATABASE_URL` 等）
|
||||
|
||||
```powershell
|
||||
cd D:\path\to\oclaw
|
||||
# 若 URL 写在 _local\system.env 中：
|
||||
.\runtime\operations\scripts\cutover_sqlite_to_postgresql.ps1 -LoadSystemEnv
|
||||
# 或显式传入：
|
||||
.\runtime\operations\scripts\cutover_sqlite_to_postgresql.ps1 -PgUrl "postgresql+psycopg://..."
|
||||
cd D:\path\to\oclaw; .\runtime\operations\scripts\cutover_sqlite_to_postgresql.ps1 -LoadSystemEnv
|
||||
```
|
||||
|
||||
常用开关：`-SqlitePath`、`-BackupDir`、`-SkipDryRun`、`-DryRunOnly`、`-NoBackup`（不推荐生产）、`-LoadSystemEnv`。
|
||||
---
|
||||
|
||||
### 6.2 Linux / bash
|
||||
**Linux / macOS：同上**
|
||||
|
||||
`runtime/operations/scripts/cutover_sqlite_to_postgresql.sh`
|
||||
|
||||
- 环境变量：`SQLITE_PATH`、`BACKUP_DIR`、`NO_BACKUP`、`SKIP_DRY_RUN`、`DRY_RUN_ONLY` 等（见脚本头部注释）。
|
||||
- 默认会 `--load-system-env` 并解析 SQLite 路径。
|
||||
|
||||
仅 **导入**（不复制备份逻辑时也可用轻量包装）：
|
||||
|
||||
`runtime/operations/scripts/assistant_import_sqlite_to_postgresql.sh`（内部调用 migrator 的 `--load-system-env --sqlite-from-db-path`）。
|
||||
```bash
|
||||
cd /path/to/oclaw && chmod +x runtime/operations/scripts/cutover_sqlite_to_postgresql.sh && ./runtime/operations/scripts/cutover_sqlite_to_postgresql.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 切换运行时与网关
|
||||
**Linux / macOS：只要导入、不要割接备份流程**
|
||||
|
||||
导入完成后：
|
||||
```bash
|
||||
cd /path/to/oclaw && chmod +x runtime/operations/scripts/assistant_import_sqlite_to_postgresql.sh && ./runtime/operations/scripts/assistant_import_sqlite_to_postgresql.sh --dry-run
|
||||
```
|
||||
|
||||
1. 设置 **`AIA_ASSISTANT_DB_BACKEND=postgresql`**。
|
||||
2. 设置 **`AIA_ASSISTANT_DATABASE_URL`**（与导入目标一致）。
|
||||
3. 重启 **网关**、**wiki worker**、**渠道 worker** 等所有持有 DB 连接的进程。
|
||||
|
||||
**注意**：`get_assistant_store()` 在进程内会按 `(backend, 连接键)` 缓存；连接键对 PostgreSQL 使用 **URL 的哈希**（避免在内存键中携带明文口令）。改环境后必须重启进程，否则会连旧库。
|
||||
确认后去掉 `--dry-run` 再执行同一条。
|
||||
|
||||
---
|
||||
|
||||
## 8. 验证与自动化测试
|
||||
**导入完成后切到 PG 跑网关**
|
||||
|
||||
- 管理台：会话列表、打开历史会话、发送一条新消息，确认读写正常。
|
||||
- 单测：设置环境变量 **`AIA_TEST_PG_URL`** 后，部分用例会对真实 PG 跑冒烟（例如 `tests/test_database_backend.py`）。详见 [`ENVIRONMENT_VARIABLES.md`](./ENVIRONMENT_VARIABLES.md) 中 `AIA_TEST_PG_URL` 说明。
|
||||
设置 `AIA_ASSISTANT_DB_BACKEND=postgresql` 与 `AIA_ASSISTANT_DATABASE_URL`（与导入目标一致），**重启**网关及所有连库的 worker。
|
||||
|
||||
---
|
||||
|
||||
## 9. 备份与回滚
|
||||
**仅清空 PG 里会话数据（危险，确认库名）**
|
||||
|
||||
- **割接脚本** 默认将 SQLite 复制到 `data/pg_cutover_backups/<原名>_pre_pg_<时间戳>.sqlite`。
|
||||
- 若导入后需回退到 SQLite：恢复该备份文件为 `data/ai_ops.sqlite`（或你的 `AIA_ASSISTANT_DB_PATH`），将 `AIA_ASSISTANT_DB_BACKEND` 改回 `sqlite` 或未设置，重启服务。
|
||||
- PostgreSQL 侧回滚：依赖实例级备份（快照 / `pg_dump`），不在应用脚本内自动完成。
|
||||
```powershell
|
||||
# Windows：见脚本说明
|
||||
.\runtime\operations\scripts\clear_postgres_chat_sessions.ps1
|
||||
```
|
||||
|
||||
---
|
||||
```bash
|
||||
# 或仓库根（须设 AIA_CONFIRM_CHAT_SESSION_WIPE=1，见脚本）
|
||||
export PYTHONPATH=. && python runtime/operations/scripts/clear_all_chat_sessions.py --yes --postgresql
|
||||
```
|
||||
|
||||
## 10. 仅清空 PG 中的对话数据（可选）
|
||||
|
||||
若要在 **PostgreSQL** 上删除所有会话及相关行（危险操作），使用：
|
||||
|
||||
- `runtime/operations/scripts/clear_postgres_chat_sessions.ps1`（加载 `_local/system.env`、强制 PG、设置确认变量后调用 Python），或
|
||||
- `python runtime/operations/scripts/clear_all_chat_sessions.py --yes --postgresql`
|
||||
且必须同时设置 **`AIA_CONFIRM_CHAT_SESSION_WIPE=1`**。
|
||||
|
||||
详见脚本内说明；**勿**在未确认库名时针对生产执行。
|
||||
|
||||
---
|
||||
|
||||
## 11. 常见问题（排障）
|
||||
|
||||
| 现象 | 可能原因 | 处理 |
|
||||
|------|----------|------|
|
||||
| 导入报「表非空」 | PG 已有数据 | 换新库或 `--allow-non-empty`（谨慎） |
|
||||
| 网关仍像连 SQLite | 环境未生效 / 未重启 | 检查进程环境、`assistant_store` 单例 |
|
||||
| `invalid_credentials` / 连接失败 | URL 或网络或权限 | 用 `psql` 或 `psycopg` 单独测连 |
|
||||
| 部分表未拷贝 | PG 无同名表 | 先 `alembic upgrade head`；查看 migrator 打印的 `skip (not in PG public schema)` |
|
||||
| 仍为 SQLite 但已填 PG URL | 后端未切到 `postgresql` | 首次解析 URL 会 `UserWarning`；确认 `AIA_ASSISTANT_DB_BACKEND` 与重启 |
|
||||
| 连接 PG 长时间无响应 | 网络/防火墙 | 可调 `AIA_ASSISTANT_PG_CONNECT_TIMEOUT`（默认 10s，见 `ENVIRONMENT_VARIABLES.md`） |
|
||||
|
||||
---
|
||||
|
||||
## 12. 相关文件索引
|
||||
|
||||
| 路径 | 用途 |
|
||||
|------|------|
|
||||
| `alembic.ini` | Alembic 配置，`script_location = assistant_migrations` |
|
||||
| `assistant_migrations/` | PG schema 版本链 |
|
||||
| `svc/persistence/ddl/postgresql_bootstrap.sql` | 初始 DDL（与首版迁移同源） |
|
||||
| `svc/persistence/pg_adapter.py` | psycopg 连接（含 `connect_timeout`） |
|
||||
| `svc/persistence/assistant_store.py` | `get_assistant_store()` 工厂 |
|
||||
| `runtime/operations/scripts/migrate_assistant_sqlite_to_postgresql.py` | 数据导入 |
|
||||
| `runtime/operations/scripts/cutover_sqlite_to_postgresql.ps1` / `.sh` | 备份 + 预演 + 导入 |
|
||||
| `runtime/operations/scripts/clear_all_chat_sessions.py` | 清空会话（需确认 env） |
|
||||
| `docs/ENVIRONMENT_VARIABLES.md` | 环境变量权威列表 |
|
||||
|
||||
---
|
||||
|
||||
**维护建议**：若变更割接流程或新增迁移步骤，请同步更新本文与 `ENVIRONMENT_VARIABLES.md` 中的摘要，避免文档分叉。
|
||||
排障与超时等见 `ENVIRONMENT_VARIABLES.md`。
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue