fix: harden assistant SQLite/PostgreSQL dual-backend (singleton, timeouts, warnings)

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/ASSISTANT_PG_MIGRATION.md

@@ -141,7 +141,7 @@ cd D:\path\to\oclaw
 2. 设置 **`AIA_ASSISTANT_DATABASE_URL`**（与导入目标一致）。
 3. 重启 **网关**、**wiki worker**、**渠道 worker** 等所有持有 DB 连接的进程。
 
-**注意**：`get_assistant_store()` 在进程内会按 `(backend, 连接键)` 缓存；改环境后必须重启进程，否则会连旧库。
+**注意**：`get_assistant_store()` 在进程内会按 `(backend, 连接键)` 缓存；连接键对 PostgreSQL 使用 **URL 的哈希**（避免在内存键中携带明文口令）。改环境后必须重启进程，否则会连旧库。
 
 ---
 
@@ -180,7 +180,8 @@ cd D:\path\to\oclaw
 | 网关仍像连 SQLite | 环境未生效 / 未重启 | 检查进程环境、`assistant_store` 单例 |
 | `invalid_credentials` / 连接失败 | URL 或网络或权限 | 用 `psql` 或 `psycopg` 单独测连 |
 | 部分表未拷贝 | PG 无同名表 | 先 `alembic upgrade head`；查看 migrator 打印的 `skip (not in PG public schema)` |
-| Windows 上 Alembic 编码问题 | 控制台代码页 | 使用 UTF-8 终端或重定向日志到文件 |
+| 仍为 SQLite 但已填 PG URL | 后端未切到 `postgresql` | 首次解析 URL 会 `UserWarning`；确认 `AIA_ASSISTANT_DB_BACKEND` 与重启 |
+| 连接 PG 长时间无响应 | 网络/防火墙 | 可调 `AIA_ASSISTANT_PG_CONNECT_TIMEOUT`（默认 10s，见 `ENVIRONMENT_VARIABLES.md`） |
 
 ---
 
@@ -191,7 +192,7 @@ cd D:\path\to\oclaw
 | `alembic.ini` | Alembic 配置，`script_location = assistant_migrations` |
 | `assistant_migrations/` | PG schema 版本链 |
 | `svc/persistence/ddl/postgresql_bootstrap.sql` | 初始 DDL（与首版迁移同源） |
-| `svc/config/database.py` | 后端与 DSN 解析 |
+| `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` | 备份 + 预演 + 导入 |

docs/ENVIRONMENT_VARIABLES.md

@@ -636,6 +636,7 @@
   - 默认：未设置（按 `sqlite` 处理）
   - 取值：`sqlite`（默认）或 `postgresql`（大小写不敏感，亦接受 `pg` / `postgres` 等别名）
   - 作用：主 assistant 持久化后端；设为 `postgresql` 时必须配置 `AIA_ASSISTANT_DATABASE_URL`（或 `OPS_*` / `*_PG_DSN` 别名）
+  - 说明：仍为 `sqlite` 时若设置了 PostgreSQL URL 环境变量，会在首次解析 SQLAlchemy URL 时发出**一次性** `UserWarning`（提示 URL 被忽略），避免误配割接后仍连 SQLite
   - 生效：`oclaw/svc/config/database.py`, `oclaw/svc/persistence/assistant_store.py`
 
 - `AIA_ASSISTANT_DATABASE_URL` / `OPS_ASSISTANT_DATABASE_URL`（及 `AIA_ASSISTANT_PG_DSN` 等别名）
@@ -643,6 +644,11 @@
   - 作用：PostgreSQL 连接串（`postgresql://…` 或 `postgresql+psycopg://…`）
   - 生效：`oclaw/svc/config/database.py`, Alembic `assistant_migrations/env.py`
 
+- `AIA_ASSISTANT_PG_CONNECT_TIMEOUT`
+  - 默认：`10`（秒）
+  - 作用：原始 `psycopg` 连接（`SqliteStore._connect` 每条业务连接）的 `connect_timeout` 上限，避免错误主机/防火墙时长时间挂死；范围钳制为 `1..120`
+  - 生效：`oclaw/svc/persistence/pg_adapter.py`
+
 - `AIA_TEST_PG_URL`
   - 默认：空
   - 作用：仅测试用；设置后部分 pytest 会对真实 PostgreSQL 跑冒烟（如 `tests/test_database_backend.py`）