# 部署架构、中间件选型与缓存策略

文档编号：pcbjia-OPS-ARCH-V1.0
目标：支撑社区与商城的实时消息、论坛检索、AI 知识库与附件存储；先单机跑通，后期平滑扩容，不改业务表结构。

> 适用范围说明：本站当前部署在万小智 SaaS 平台，以下为对外交付与自建时的参考架构，平台侧实际可用能力受版本限制（详见附件K 第四节）。

---

## 一、架构分层

```
用户（PC / H5）
  → Nginx（SSL、静态资源、限流、防盗链）
  → 前端静态资源
  → 应用服务（HTTP / WebSocket / 异步 Worker）
  → Redis（缓存、会话、限流、队列、锁）
  → PostgreSQL / MySQL（业务主库）
  → 向量库（精华知识库语义检索）
  → 对象存储（附件）
  → 定时任务
```

## 二、中间件选型

| 组件 | 建议选型 | 用途 |
| --- | --- | --- |
| 反向代理 | Nginx 1.24+ | SSL、静态资源、限流、防盗链、gzip |
| 业务库 | PostgreSQL 14+ / MySQL 8.0 | 主数据与事务 |
| 缓存与队列 | Redis 7.x | 热点缓存、在线会话、限流、分布式锁、队列 |
| 向量库 | Qdrant（轻量）或 Milvus | 精华内容语义检索 |
| 对象存储 | S3 兼容（MinIO 自建或云 OSS） | 附件、图片、压缩包 |
| 异步任务 | Redis Queue / Asynq | AI 预回答、向量同步、导出、统计 |
| 搜索（后期） | Meilisearch | 全文检索，前期用库内检索 + 缓存 |
| 监控 | Prometheus + Grafana | QPS、时延、错误率、慢查询、AI 调用 |
| 日志 | Loki 或 ELK | 业务、WS、AI、审计日志 |
| 病毒扫描 | ClamAV | 上传压缩包查杀 |

起步方案：单体后端 + 单实例数据库 + 单 Redis + Qdrant 单节点 + 对象存储单桶。

## 三、缓存设计

### 3.1 Key 规范

```
user:info:{uid}
user:credit:{uid}
chat:room:{roomId}:online
chat:thread:{tid}:hot
forum:section:{sid}:list
forum:post:{pid}
forum:post:{pid}:reply:list
search:global:{hash}
ws:session:{uid}
rate:limit:{scene}:{uid}
lock:{domain}:{id}
```

### 3.2 TTL

| 数据 | TTL | 失效方式 |
| --- | --- | --- |
| 用户信息、帖子与线程详情 | 300s | 更新时主动删除 |
| 版块列表、信息流 | 120s | 定时与写操作失效 |
| 在线用户集合 | 心跳续期 | 下线自动清理 |
| 搜索结果 | 60s | 自然过期 |
| 限流计数 | 与窗口一致 | 自然过期 |

### 3.3 队列任务

1. `ai_pre_answer` 发帖预回答
2. `essence_vector_sync` 精华变更同步向量
3. `export_task` 导出 PDF 与 Markdown
4. `statistic_daily` 每日统计
5. `clean_orphan_attachment` 孤立附件清理
6. `ai_usage_stat` AI 调用汇总

### 3.4 必须加锁的场景

悬赏采纳、帖子与线程双向绑定、精华标记与向量同步、批量后台操作。

## 四、数据库优化

1. InnoDB / PostgreSQL 默认引擎，字符集 utf8mb4，支持表情符号。
2. 慢查询阈值 200ms，纳入监控。
3. 分表时机：`chat_message` 超过 5000 万后按 `thread_id` 哈希分表；日志表按月分区。
4. 事务边界：悬赏采纳、双向绑定必须在单事务内完成。
5. 备份：每日全量 + 增量日志，保留 7 天。

## 五、向量库

- Collection：`essence_knowledge`，维度按所选 embedding 模型（如 1024）
- 字段：`source_type`、`source_id`、`tags`、`content`、`is_valid`
- 写入时机：仅精华标记时写入；取消精华置 `is_valid=0` 不删向量
- 检索：向量化 → 相似度 topN → 过滤 `is_valid=1`
- 隔离：私信、普通聊天、未精华内容永不进入向量库

## 六、对象存储

1. 分桶：图片桶与文件桶分离。
2. 命名：`{md5}_{timestamp}.ext`，先查 md5 复用。
3. 私有桶 + 签名 URL，有效期 1–2 小时。
4. 水印：异步生成带水印版本，原图仅管理员可见。
5. 校验：后缀白名单、MIME 校验、病毒扫描。

## 七、WebSocket 实时方案

1. 连接携带 token 鉴权。
2. 心跳 30s，60s 无心跳判定下线。
3. 消息先落库再推送。
4. 进入线程加载最近 50 条，向上滚动分页。
5. 只推送当前在线且已加入该线程的用户。
6. 断线自动重连，重连后拉取增量消息。

## 八、缓存异常处理

- 雪崩：过期时间加随机偏移
- 击穿：热点数据加互斥锁
- 穿透：参数校验 + 空值短缓存
- 降级开关：关闭 AI、WS 降级轮询、关闭导出任务

## 九、容量规划（起步预估）

| 组件 | 起步 | 说明 |
| --- | --- | --- |
| 业务库 | 4C8G / 200G | 千万级消息、百万级帖子 |
| Redis | 4G | 后期扩到 8–16G |
| 向量库 | 单节点 4C8G | 初期数万条精华 |
| 对象存储 | 200G | 按上传量扩容 |

## 十、安全加固

1. Nginx 禁止访问 `.env`、`.sql` 与源码目录，限制请求体大小。
2. 除登录注册与公开文档外全部鉴权。
3. 密码哈希存储，管理员 IP 白名单可选。
4. CORS 仅允许前端域名。
5. 限流：新用户消息 1 条/5s、发帖 1 次/60s；普通用户消息 1 条/2s、发帖 1 次/10s；专家与版主白名单。
6. 附件 ZIP 只解析清单，病毒扫描前置。
7. AI 输出服务端追加免责文本。
8. 敏感内容关键词过滤 + AI 预检。

## 十一、发布流程

1. 提交触发单元测试
2. 构建前端静态资源与后端产物
3. 镜像打包
4. 测试环境部署与人工验收
5. 生产发布前自动备份数据库
6. 灰度批次放量，按指标红线决定是否继续