# 数据库设计
**本文档引用的文件**
- [backend/app/database.py](file://backend/app/database.py)
- [backend/app/models/user.py](file://backend/app/models/user.py)
- [backend/app/models/query.py](file://backend/app/models/query.py)
- [backend/app/models/citation_record.py](file://backend/app/models/citation_record.py)
- [backend/app/models/query_task.py](file://backend/app/models/query_task.py)
- [backend/app/models/subscription.py](file://backend/app/models/subscription.py)
- [backend/app/models/__init__.py](file://backend/app/models/__init__.py)
- [backend/alembic/env.py](file://backend/alembic/env.py)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/app/config.py](file://backend/app/config.py)
- [docker-compose.yml](file://docker-compose.yml)
- [backend/app/services/query.py](file://backend/app/services/query.py)
- [backend/app/services/citation.py](file://backend/app/services/citation.py)
- [backend/app/schemas/citation.py](file://backend/app/schemas/citation.py)
- [backend/app/api/citations.py](file://backend/app/api/citations.py)
- [backend/app/api/reports.py](file://backend/app/api/reports.py)
## 更新摘要
**变更内容**
- 新增数据库迁移版本，添加confidence和match_type字段到citation_records表
- 更新CitationRecord模型以支持新的字段定义
- 增强报告功能，支持匹配置信度和匹配类型的统计分析
- 更新CSV导出功能，包含新的字段输出
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件为 GEOF 智能检索与引用监测平台的数据库设计文档，聚焦于基于 PostgreSQL 的关系型数据库架构，涵盖：
- 表结构设计与实体关系映射（ER）
- 索引策略与查询优化
- SQLAlchemy ORM 模型实现（模型定义、关系配置、查询封装）
- 数据库迁移管理、版本控制与部署策略
- 数据完整性约束、事务处理与并发控制
- 性能优化、查询分析与缓存策略
- 备份、恢复与维护最佳实践
## 项目结构
后端采用 FastAPI + SQLAlchemy Async + Alembic 迁移的典型分层架构：
- 配置层：读取环境变量，提供数据库连接字符串
- 数据库引擎与会话：异步连接池与会话工厂
- ORM 模型层：用户、查询、引用记录、任务、订阅
- 迁移层：Alembic 初始化迁移脚本
- 服务层：业务查询封装，统一事务边界
- 容器编排：Docker Compose 启动 Postgres 与 Redis
```mermaid
graph TB
subgraph "应用层"
SvcQ["服务: 查询
backend/app/services/query.py"]
SvcC["服务: 引用
backend/app/services/citation.py"]
API["API: 引用
backend/app/api/citations.py"]
Reports["API: 报告
backend/app/api/reports.py"]
end
subgraph "ORM 层"
MUser["模型: 用户
backend/app/models/user.py"]
MQuery["模型: 查询
backend/app/models/query.py"]
MCit["模型: 引用记录
backend/app/models/citation_record.py"]
MTask["模型: 查询任务
backend/app/models/query_task.py"]
MSub["模型: 订阅
backend/app/models/subscription.py"]
end
subgraph "基础设施"
DB["PostgreSQL 数据库"]
RD["Redis 缓存"]
end
Cfg["配置: DATABASE_URL
backend/app/config.py"]
Eng["引擎与会话
backend/app/database.py"]
Alembic["迁移: Alembic
backend/alembic/*"]
Cfg --> Eng
Eng --> DB
SvcQ --> Eng
SvcC --> Eng
API --> SvcC
Reports --> SvcC
MUser --> Eng
MQuery --> Eng
MCit --> Eng
MTask --> Eng
MSub --> Eng
Alembic --> DB
SvcQ --> RD
SvcC --> RD
```
图表来源
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-44](file://backend/app/models/citation_record.py#L1-L44)
- [backend/app/models/query_task.py:1-39](file://backend/app/models/query_task.py#L1-L39)
- [backend/app/models/subscription.py:1-37](file://backend/app/models/subscription.py#L1-L37)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
章节来源
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
## 核心组件
- 数据库引擎与会话
- 使用异步引擎与会话工厂，开启自动提交、自动刷新、自动回滚等参数，确保事务一致性与资源释放。
- 提供依赖注入式 get_db 生成器，保证每个请求生命周期内复用同一会话。
- ORM 模型
- 所有模型继承自统一的 Base，表名与字段类型均在模型中显式声明。
- 关系通过 relationship 显式配置，支持级联删除与孤儿对象清理。
- 迁移与版本控制
- Alembic 环境集成 SQLAlchemy Base 元数据，支持离线/在线迁移。
- 初始迁移脚本定义了用户、查询、引用记录、查询任务、订阅五张表及必要索引。
- 新增迁移版本支持confidence和match_type字段，增强报告功能。
- 服务层封装
- 查询与引用统计、导出等业务逻辑封装在服务层，统一执行 SQL 并返回结果。
- 对外暴露清晰的查询接口，内部进行权限校验与计数限制。
章节来源
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/__init__.py:1-14](file://backend/app/models/__init__.py#L1-L14)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:1-128](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L1-L128)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:1-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L1-L37)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/services/citation.py:1-429](file://backend/app/services/citation.py#L1-L429)
## 架构总览
下图展示数据库层与应用层的交互关系，以及迁移与容器编排对数据库的影响。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "FastAPI 应用"
participant SvcC as "引用服务"
participant Reports as "报告服务"
participant DB as "PostgreSQL"
participant Alembic as "迁移工具"
Client->>API : 请求 /citations 或 /reports
API->>SvcC : 调用引用服务
SvcC->>DB : 执行查询/统计/插入
API->>Reports : 调用报告服务
Reports->>DB : 执行导出查询
DB-->>Reports : 返回统计数据
DB-->>SvcC : 返回引用记录
Reports-->>API : 返回CSV内容
SvcC-->>API : 返回查询列表/详情
API-->>Client : 响应数据
Note over Alembic,DB : 首次启动或升级时执行迁移
```
图表来源
- [backend/app/services/citation.py:1-429](file://backend/app/services/citation.py#L1-L429)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
## 详细组件分析
### 实体关系映射（ER）
- 用户（users）：主键 id，唯一邮箱，计划与配额字段，活跃状态，时间戳。
- 查询（queries）：外键 user_id，关键词、目标品牌、别名列表、平台列表、频率、状态、下次查询时间，时间戳。
- 引用记录（citation_records）：外键 query_id，平台、是否引用、引用位置、引用文本、竞争品牌列表、原始响应、匹配置信度、匹配类型、查询时间。
- 查询任务（query_tasks）：外键 query_id，平台、状态、错误信息、调度/开始/完成时间。
- 订阅（subscriptions）：外键 user_id，计划、状态、起止日期、金额、支付方式与流水号，时间戳。
**更新** 新增confidence和match_type字段到引用记录表，支持增强的报告功能。
```mermaid
erDiagram
USERS {
uuid id PK
string email UK
string password_hash
string name
string plan
integer max_queries
boolean is_active
timestamptz created_at
timestamptz updated_at
}
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
timestamptz last_queried_at
timestamptz next_query_at
timestamptz created_at
timestamptz updated_at
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
string platform
boolean cited
integer citation_position
text citation_text
jsonb competitor_brands
text raw_response
float confidence
string match_type
timestamptz queried_at
}
QUERY_TASKS {
uuid id PK
uuid query_id FK
string platform
string status
text error_message
timestamptz scheduled_at
timestamptz started_at
timestamptz completed_at
}
SUBSCRIPTIONS {
uuid id PK
uuid user_id FK
string plan
string status
date start_date
date end_date
numeric amount
string payment_method
string payment_id
timestamptz created_at
}
USERS ||--o{ QUERIES : "拥有"
QUERIES ||--o{ CITATION_RECORDS : "产生"
QUERIES ||--o{ QUERY_TASKS : "触发"
USERS ||--o{ SUBSCRIPTIONS : "订阅"
```
图表来源
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-44](file://backend/app/models/citation_record.py#L1-L44)
- [backend/app/models/query_task.py:1-39](file://backend/app/models/query_task.py#L1-L39)
- [backend/app/models/subscription.py:1-37](file://backend/app/models/subscription.py#L1-L37)
章节来源
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-44](file://backend/app/models/citation_record.py#L1-L44)
- [backend/app/models/query_task.py:1-39](file://backend/app/models/query_task.py#L1-L39)
- [backend/app/models/subscription.py:1-37](file://backend/app/models/subscription.py#L1-L37)
### 索引策略
- 查询表（queries）
- idx_queries_user_id：按用户过滤
- idx_queries_status：按状态过滤
- idx_queries_next_query_at：按下次查询时间调度
- 引用记录表（citation_records）
- idx_citation_records_query_id：按查询聚合
- idx_citation_records_queried_at：按时间排序/范围
- idx_citation_records_platform：按平台统计
- **新增** idx_citation_records_confidence：按匹配置信度过滤（建议）
- **新增** idx_citation_records_match_type：按匹配类型过滤（建议）
**更新** 新增针对confidence和match_type字段的索引建议，支持更精细的查询过滤。
这些索引覆盖了常见查询路径与统计场景，有助于提升分页、过滤、排序与聚合的性能。
章节来源
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:57-94](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L57-L94)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:21-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L21-L37)
- [backend/app/models/query.py:50-54](file://backend/app/models/query.py#L50-L54)
- [backend/app/models/citation_record.py:37-44](file://backend/app/models/citation_record.py#L37-L44)
- [backend/app/models/query_task.py:36-38](file://backend/app/models/query_task.py#L36-L38)
### SQLAlchemy ORM 模型实现
- 字段类型与默认值
- UUID 主键与外键，JSONB 存储数组/字典，布尔、整数、文本、数值、时间戳等。
- 默认值通过 server_default/onupdate 设置，减少应用层重复逻辑。
- **新增** confidence字段（Float类型，nullable=True）用于存储匹配的可信度评分。
- **新增** match_type字段（String类型，长度20，nullable=True）用于标识匹配类型。
- 关系配置
- 用户与查询、订阅为一对多；查询与引用记录、任务为一对多。
- 级联删除与孤儿对象清理（delete-orphan），避免悬挂数据。
- 查询封装
- 服务层使用 select + func + join 封装复杂查询，统一处理分页与计数。
- 权限校验：仅允许访问当前用户的资源，防止越权。
**更新** CitationRecord模型新增confidence和match_type字段定义，支持增强的报告功能。
```mermaid
classDiagram
class User {
+id : uuid
+email : string
+password_hash : string
+name : string
+plan : string
+max_queries : int
+is_active : bool
+created_at : datetime
+updated_at : datetime
+queries
+subscriptions
}
class Query {
+id : uuid
+user_id : uuid
+keyword : string
+target_brand : string
+brand_aliases : list
+platforms : list
+frequency : string
+status : string
+last_queried_at : datetime
+next_query_at : datetime
+created_at : datetime
+updated_at : datetime
+user
+citation_records
+query_tasks
}
class CitationRecord {
+id : uuid
+query_id : uuid
+platform : string
+cited : bool
+citation_position : int
+citation_text : text
+competitor_brands : list
+raw_response : text
+confidence : float
+match_type : string
+queried_at : datetime
+query
}
class QueryTask {
+id : uuid
+query_id : uuid
+platform : string
+status : string
+error_message : text
+scheduled_at : datetime
+started_at : datetime
+completed_at : datetime
+query
}
class Subscription {
+id : uuid
+user_id : uuid
+plan : string
+status : string
+start_date : date
+end_date : date
+amount : float
+payment_method : string
+payment_id : string
+created_at : datetime
+user
}
User "1" <-- "many" Query : "拥有"
Query "1" <-- "many" CitationRecord : "产生"
Query "1" <-- "many" QueryTask : "触发"
User "1" <-- "many" Subscription : "订阅"
```
图表来源
- [backend/app/models/user.py:11-41](file://backend/app/models/user.py#L11-L41)
- [backend/app/models/query.py:11-48](file://backend/app/models/query.py#L11-L48)
- [backend/app/models/citation_record.py:11-44](file://backend/app/models/citation_record.py#L11-L44)
- [backend/app/models/query_task.py:11-34](file://backend/app/models/query_task.py#L11-L34)
- [backend/app/models/subscription.py:11-36](file://backend/app/models/subscription.py#L11-L36)
章节来源
- [backend/app/models/user.py:1-41](file://backend/app/models/user.py#L1-L41)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-44](file://backend/app/models/citation_record.py#L1-L44)
- [backend/app/models/query_task.py:1-39](file://backend/app/models/query_task.py#L1-L39)
- [backend/app/models/subscription.py:1-37](file://backend/app/models/subscription.py#L1-L37)
### 数据库迁移管理、版本控制与部署策略
- 迁移入口
- Alembic 环境加载 Base 元数据，支持离线/在线迁移。
- 在线迁移通过异步引擎连接数据库，避免阻塞。
- 迁移版本
- **初始版本** (488d0bd5ab01)：创建 users、queries、citation_records、query_tasks、subscriptions 表，并建立必要索引。
- **新增版本** (b2c4d6e8fa10)：向 citation_records 表添加 confidence 和 match_type 字段，支持增强的报告功能。
- 外键约束与级联删除策略明确，确保数据一致性。
- 部署策略
- Docker Compose 启动 PostgreSQL 与 Redis，应用容器依赖数据库健康检查。
- 生产环境建议将数据库与缓存分离，使用独立卷持久化数据。
**更新** 新增b2c4d6e8fa10迁移版本，支持confidence和match_type字段的添加。
```mermaid
flowchart TD
Start(["开始"]) --> CheckEnv["检查 DATABASE_URL"]
CheckEnv --> LoadBase["加载 Base 元数据"]
LoadBase --> Mode{"运行模式"}
Mode --> |离线| Offline["配置 URL 与元数据"]
Mode --> |在线| Online["创建异步引擎并连接"]
Offline --> RunMigs["执行迁移"]
Online --> RunMigs
RunMigs --> Version{"检查版本"}
Version --> |488d0bd5ab01| InitMigration["初始迁移"]
Version --> |b2c4d6e8fa10| AddFields["添加新字段"]
InitMigration --> Done(["完成"])
AddFields --> Done
```
图表来源
- [backend/alembic/env.py:33-88](file://backend/alembic/env.py#L33-L88)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:21-128](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L21-L128)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:21-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L21-L37)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
章节来源
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:1-128](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L1-L128)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:1-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L1-L37)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
### 数据完整性约束、事务处理与并发控制
- 完整性约束
- 唯一约束：用户邮箱唯一
- 外键约束：查询、任务、订阅均对用户做级联删除
- JSONB 字段默认值：空数组/字典，避免 NULL 导致的条件判断复杂化
- **新增** confidence字段允许NULL值，match_type字段限制长度为20字符
- 事务处理
- 服务层方法在单个事务内执行插入/更新/删除，提交后刷新对象状态
- 会话工厂设置 expire_on_commit=False，减少后续查询的额外开销
- 并发控制
- 异步连接池与会话隔离，避免阻塞
- 服务层在执行前进行权限校验与配额检查，降低并发冲突概率
**更新** 新增对confidence和match_type字段的完整性约束说明。
章节来源
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py:36-111](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py#L36-L111)
- [backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py:21-37](file://backend/alembic/versions/b2c4d6e8fa10_add_confidence_match_type_to_citation_records.py#L21-L37)
- [backend/app/services/query.py:45-81](file://backend/app/services/query.py#L45-L81)
- [backend/app/database.py:12-18](file://backend/app/database.py#L12-L18)
### 查询流程与优化要点
- 查询列表与计数
- 分页查询与计数分离，避免重复扫描全表
- 使用索引覆盖 user_id 与 created_at 排序
- **新增** 支持按confidence和match_type过滤查询
- 引用统计
- 使用 JOIN 查询限定到用户所属的查询
- 按平台分组统计，利用索引加速 queried_at 与 platform
- **新增** 支持按匹配置信度和匹配类型进行统计分析
- 导出 CSV
- 以查询为维度导出，先验证所有权再执行导出
- **新增** 输出confidence和match_type字段到CSV文件
**更新** 增强查询流程，支持新的字段过滤和统计功能。
```mermaid
sequenceDiagram
participant API as "API"
participant Svc as "服务"
participant DB as "数据库"
API->>Svc : get_citations(user_id, query_id?, platform?, dates?, confidence?, match_type?)
Svc->>DB : SELECT ... FROM citation_records JOIN queries WHERE ...
DB-->>Svc : 记录集
Svc->>DB : COUNT ... FROM citation_records JOIN queries WHERE ...
DB-->>Svc : 总数
Svc-->>API : 结果与总数
```
图表来源
- [backend/app/services/citation.py:30-79](file://backend/app/services/citation.py#L30-L79)
章节来源
- [backend/app/services/query.py:12-32](file://backend/app/services/query.py#L12-L32)
- [backend/app/services/citation.py:30-79](file://backend/app/services/citation.py#L30-L79)
### 报告功能增强
- **匹配置信度分析**
- confidence字段用于存储匹配的可信度评分（0.0-1.0）
- 支持按置信度区间进行统计分析
- 在CSV导出中显示详细的置信度信息
- **匹配类型分类**
- match_type字段标识匹配类型：exact（精确匹配）、alias（别名匹配）、fuzzy（模糊匹配）
- 支持按匹配类型进行分组统计
- 在报告中提供中文显示（精确匹配、别名匹配、模糊匹配）
- **增强的统计指标**
- 支持按置信度和匹配类型的组合进行交叉分析
- 提供更精细的引用质量评估
**新增** 报告功能章节，详细介绍新增的confidence和match_type字段的应用。
章节来源
- [backend/app/services/citation.py:298-308](file://backend/app/services/citation.py#L298-L308)
- [backend/app/services/citation.py:342-429](file://backend/app/services/citation.py#L342-L429)
- [backend/app/schemas/citation.py:7-18](file://backend/app/schemas/citation.py#L7-L18)
## 依赖分析
- 模块耦合
- 模型层仅依赖 Base 与 SQLAlchemy 类型，低耦合
- 服务层依赖模型与会话，职责清晰
- Alembic 依赖 Base 与配置，迁移脚本与模型同步演进
- **新增** API层依赖服务层，提供RESTful接口
- 外部依赖
- PostgreSQL 异步驱动（asyncpg）
- Redis（用于缓存，如需要）
**更新** 新增API层依赖关系，支持新的报告功能接口。
```mermaid
graph LR
Cfg["配置
config.py"] --> DB["数据库引擎
database.py"]
DB --> Models["ORM 模型
models/*"]
Models --> Services["服务层
services/*"]
Services --> API["API层
api/*"]
Alembic["迁移
alembic/*"] --> DB
Docker["编排
docker-compose.yml"] --> DB
```
图表来源
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/__init__.py:1-14](file://backend/app/models/__init__.py#L1-L14)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
章节来源
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/database.py:1-29](file://backend/app/database.py#L1-L29)
- [backend/app/models/__init__.py:1-14](file://backend/app/models/__init__.py#L1-L14)
- [backend/alembic/env.py:1-89](file://backend/alembic/env.py#L1-L89)
- [docker-compose.yml:1-71](file://docker-compose.yml#L1-L71)
## 性能考虑
- 索引优化
- 为高频过滤字段建立单列索引（user_id/status/next_query_at/platform/queried_at/confidence/match_type）
- 对 JSONB 字段可考虑 GIN 索引（如需复杂查询），当前迁移脚本未启用
- **新增** 建议为confidence和match_type字段建立单独索引，支持高效过滤
- 查询优化
- 分页与计数分离，避免重复扫描
- 使用 JOIN 限定用户范围，减少全表扫描
- 时间范围查询使用索引覆盖
- **新增** 支持按confidence范围和match_type进行高效过滤
- 缓存策略
- 引用统计与趋势数据可缓存至 Redis，设置合理过期时间
- 导出 CSV 可缓存热点查询结果，降低数据库压力
- **新增** 报告统计数据可缓存，提高频繁访问的响应速度
- 连接与并发
- 使用异步连接池，避免阻塞
- 控制并发度，避免大量写入导致锁争用
**更新** 新增针对confidence和match_type字段的性能优化建议。
## 故障排查指南
- 迁移失败
- 检查 DATABASE_URL 是否正确，Alembic 配置与环境变量一致
- 确认数据库已初始化且用户具备权限
- **新增** 检查新字段的默认值和约束条件
- 查询异常
- 核对服务层权限校验逻辑，确认 user_id 与查询归属一致
- 检查索引是否存在，必要时重建索引
- **新增** 验证confidence和match_type字段的数据类型和取值范围
- 导出失败
- 确认查询所有权校验通过
- 检查 CSV 写入逻辑与字符编码
- **新增** 验证新字段在导出过程中的处理逻辑
**更新** 新增针对新字段的故障排查指导。
章节来源
- [backend/alembic/env.py:33-88](file://backend/alembic/env.py#L33-L88)
- [backend/app/services/citation.py:14-22](file://backend/app/services/citation.py#L14-L22)
## 结论
本数据库设计围绕用户、查询、引用记录、任务与订阅五大实体展开，采用 PostgreSQL + SQLAlchemy Async + Alembic 的成熟技术栈，具备良好的扩展性与可维护性。通过合理的索引策略、事务边界与服务层封装，能够满足日常查询、统计与导出需求。
**更新** 新增的confidence和match_type字段显著增强了报告功能，提供了更精细的引用质量分析能力。建议在生产环境中进一步引入缓存与监控，持续优化查询路径与索引覆盖。
## 附录
- 部署与运维
- 使用 Docker Compose 启动数据库与应用，确保数据库健康检查通过后再启动应用
- 生产环境建议使用独立数据库实例与只读副本，配合连接池与慢查询日志
- **新增** 升级时确保迁移脚本按顺序执行，从初始版本到最新版本
- 备份与恢复
- 使用 pg_dump/pg_restore 进行逻辑备份与恢复
- 对关键表定期增量备份，结合 WAL 归档实现点-in-time 恢复
- **新增** 新字段变更需要纳入备份策略，确保数据完整性
- 监控与告警
- 监控连接数、查询延迟、索引命中率与慢查询
- 对迁移脚本变更进行版本化管理与回滚演练
- **新增** 监控新字段的使用情况和性能影响
**更新** 新增针对新字段的部署和运维指导。