docs(platform): Add database documentation system and restructure deployment docs
Completed: - Add 6 core database documents (docs/01-平台基础层/07-数据库/) Architecture overview, migration history, environment comparison, tech debt tracking, seed data management, PostgreSQL extensions - Restructure deployment docs: archive 20 legacy files to _archive-2025/ - Create unified daily operations manual (01-日常更新操作手册.md) - Add pending deployment change tracker (03-待部署变更清单.md) - Update database development standard to v3.0 (three iron rules) - Fix Prisma schema type drift: align @db.* annotations with actual DB IIT: UUID/Timestamptz(6), SSA: Timestamp(6)/VarChar(20/50/100) - Add migration: 20260227_align_schema_with_db_types (idempotent ALTER) - Add Cursor Rule for auto-reminding deployment change documentation - Update system status guide v6.4 with deployment and DB doc references - Add architecture consultation docs (Prisma guide, SAE deployment guide) Technical details: - Manual migration due to shadow DB limitation (TD-001 in tech debt) - Deployment docs reduced from 20+ scattered files to 3 core documents - Cursor Rule triggers on schema.prisma, package.json, Dockerfile changes Made-with: Cursor
This commit is contained in:
147
docs/01-平台基础层/07-数据库/05-PostgreSQL扩展与特性.md
Normal file
147
docs/01-平台基础层/07-数据库/05-PostgreSQL扩展与特性.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# PostgreSQL 扩展与特性
|
||||
|
||||
> 版本: v1.0
|
||||
> 更新日期: 2026-02-27
|
||||
> 维护说明: 新增扩展或变更配置时更新此文档
|
||||
|
||||
---
|
||||
|
||||
## 1. 扩展总览
|
||||
|
||||
| 扩展 | 版本 | 用途 | 安装方式 | 依赖模块 |
|
||||
|------|------|------|---------|---------|
|
||||
| **pgvector** (vector) | 0.8.1 | 向量存储与相似度检索 | Docker 镜像内置 | EKB, IIT, SSA |
|
||||
| **pg_bigm** | 1.2 | 中文/日文双字节全文检索 | Docker 镜像内置 | EKB |
|
||||
| **plpgsql** | 1.0 | PostgreSQL 过程语言 | 系统内置 | 全局 |
|
||||
|
||||
---
|
||||
|
||||
## 2. pgvector — 向量搜索
|
||||
|
||||
### 2.1 基本信息
|
||||
|
||||
- **Docker 镜像**: `pgvector/pgvector:pg15`（本地开发基础镜像）
|
||||
- **用途**: 存储文本 embedding 向量，支持语义相似度检索
|
||||
- **算法**: 支持 L2 距离、内积、余弦相似度
|
||||
|
||||
### 2.2 使用表
|
||||
|
||||
| Schema | 表 | 列 | 维度 | 模型 | 用途 |
|
||||
|--------|-----|-----|------|------|------|
|
||||
| `ekb_schema` | `ekb_chunk` | `embedding` | 1024 | 通义千问 Embedding | 企业知识库 RAG 检索 |
|
||||
| `iit_schema` | `conversation_history` | `embedding` | 1536 | OpenAI ada-002 | IIT 对话历史语义搜索 |
|
||||
| `ssa_schema` | `ssa_tools_library` | `embedding` | 1024 | 通义千问 Embedding | SSA 工具语义匹配 |
|
||||
|
||||
### 2.3 Prisma 中的声明方式
|
||||
|
||||
pgvector 在 Prisma 中通过 `Unsupported` 类型声明：
|
||||
|
||||
```prisma
|
||||
embedding Unsupported("vector(1024)")?
|
||||
```
|
||||
|
||||
> ⚠️ 已知限制：Prisma diff 引擎无法正确比较 `Unsupported` 类型，每次 diff 会产生假变更。详见 `03-技术债务追踪.md` TD-004。
|
||||
|
||||
### 2.4 索引建议
|
||||
|
||||
对于高频检索的向量列，建议创建 HNSW 索引：
|
||||
|
||||
```sql
|
||||
CREATE INDEX idx_ekb_chunk_embedding ON ekb_schema.ekb_chunk
|
||||
USING hnsw (embedding vector_cosine_ops)
|
||||
WITH (m = 16, ef_construction = 64);
|
||||
```
|
||||
|
||||
当前状态：暂未创建向量索引，数据量较小时顺序扫描即可满足性能要求。
|
||||
|
||||
---
|
||||
|
||||
## 3. pg_bigm — 中文全文检索
|
||||
|
||||
### 3.1 基本信息
|
||||
|
||||
- **用途**: 基于双字节 gram 的模糊搜索，特别适合中文、日文
|
||||
- **优势**: 无需分词器，开箱即用，支持 LIKE '%关键词%' 加速
|
||||
|
||||
### 3.2 使用场景
|
||||
|
||||
| Schema | 表 | 列 | 用途 |
|
||||
|--------|-----|-----|------|
|
||||
| `ekb_schema` | `ekb_chunk` | `content` | 知识库文本块的关键词搜索 |
|
||||
|
||||
### 3.3 索引创建示例
|
||||
|
||||
```sql
|
||||
CREATE INDEX idx_ekb_chunk_content_bigm ON ekb_schema.ekb_chunk
|
||||
USING gin (content gin_bigm_ops);
|
||||
```
|
||||
|
||||
> 详细安装指南见 `docs/02-通用能力层/03-RAG引擎/06-pg_bigm安装指南.md`
|
||||
|
||||
---
|
||||
|
||||
## 4. pg-boss — PostgreSQL 原生任务队列
|
||||
|
||||
### 4.1 基本信息
|
||||
|
||||
- **类型**: Node.js 库（非 PostgreSQL 扩展），利用 PostgreSQL 实现任务队列
|
||||
- **表位置**: `platform_schema` 下的 5 张表（job, job_common, queue, schedule, subscription）
|
||||
- **用途**: 异步任务处理，替代 Redis + BullMQ
|
||||
|
||||
### 4.2 核心特性
|
||||
|
||||
| 特性 | 说明 |
|
||||
|------|------|
|
||||
| 延迟任务 | 支持定时执行 |
|
||||
| 重试机制 | 失败自动重试，支持配置重试次数和退避策略 |
|
||||
| 优先级 | 支持任务优先级 |
|
||||
| 死信队列 | 超过重试次数的任务进入死信队列 |
|
||||
| 定时调度 | 通过 schedule 表支持 cron 表达式 |
|
||||
|
||||
### 4.3 使用模块
|
||||
|
||||
| 模块 | 用途 |
|
||||
|------|------|
|
||||
| ASL | 文献筛选批处理、全文提取分发 |
|
||||
| PKB | 文档批处理任务 |
|
||||
| IIT | 定时质控任务（cron） |
|
||||
|
||||
> 详细运维指南见 `docs/07-运维文档/01-PgBoss队列监控与维护.md`
|
||||
> 架构设计见 `docs/02-通用能力层/Postgres-Only异步任务处理指南.md`
|
||||
|
||||
---
|
||||
|
||||
## 5. Docker 镜像配置
|
||||
|
||||
### 5.1 本地开发 (docker-compose.yml)
|
||||
|
||||
```yaml
|
||||
services:
|
||||
postgres:
|
||||
image: pgvector/pgvector:pg15 # 内含 pgvector 扩展
|
||||
container_name: ai-clinical-postgres
|
||||
environment:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: postgres123
|
||||
POSTGRES_DB: ai_clinical_research
|
||||
ports:
|
||||
- "5432:5432"
|
||||
volumes:
|
||||
- pgdata:/var/lib/postgresql/data
|
||||
```
|
||||
|
||||
> pg_bigm 需在 Docker 构建时额外安装，见项目根目录的 Docker 配置。
|
||||
|
||||
### 5.2 阿里云 RDS
|
||||
|
||||
- **实例类型**: RDS PostgreSQL 15 基础版
|
||||
- **扩展管理**: 通过 RDS 控制台 → 插件管理启用
|
||||
- **已启用**: pgvector, pg_bigm
|
||||
|
||||
---
|
||||
|
||||
## 6. 更新日志
|
||||
|
||||
| 日期 | 操作人 | 变更 |
|
||||
|------|--------|------|
|
||||
| 2026-02-27 | AI 助手 | 初始化文档，记录 3 个扩展 + pg-boss 特性 |
|
||||
Reference in New Issue
Block a user