#1 项目需求分析与技术方案设计 (done)

项目需求分析与技术方案设计

1. 项目概述

本软件为一款支持多服务端部署与 AI Agent 智能交互的跨平台聊天系统。用户可通过桌面客户端、移动客户端或 Web 客户端连接至后端服务集群，与真人用户或 AI Agent 进行实时消息通信。系统需要实现高并发、低延迟、可弹性扩展，并内置 AI 对话能力。

2. 需求分析

2.1 功能需求

2.1.1 用户管理

• 注册与登录：支持手机号/邮箱+密码、短信验证码、OAuth2.0（微信、GitHub等）三种方式。
• 用户信息维护：昵称、头像、个性签名、在线状态（在线/忙碌/离线/隐身）。
• 好友管理：添加好友、删除好友、分组、黑名单。
• 群组管理：创建群组、加入/退出群组、群公告、群角色（群主/管理员/普通成员）。

2.1.2 实时消息

• 点对点文本消息：发送、接收、已读回执、撤回（2分钟内）、转发。
• 群聊消息：支持 @ 提及、群公告、消息漫游（历史消息拉取）。
• 多媒体消息：图片（压缩与原图）、语音（≤60秒）、视频（≤30MB）、文件（≤100MB）。
• 消息表情：基础Emoji、自定义图片表情。
• 离线消息：服务端暂存，客户端上线后推送。

2.1.3 AI Agent 集成

• 系统预设多个 AI Agent（如客服助手、闲聊机器人、翻译机器人），用户可主动发起对话。
• Agent 支持多轮对话上下文保持（基于会话 ID）。
• Agent 支持自定义技能（插件），如查天气、查日历、查新闻。
• Agent 回复可以包含富文本（链接、图片、卡片消息）。
• 用户可在设置中启用/禁用特定 Agent。

2.1.4 多服务端架构

• 服务端组件可水平扩展：连接网关、业务服务、消息存储、AI 推理服务各自独立部署。
• 客户端连接时自动分配最优网关节点（基于地理/负载）。
• 支持服务端配置热更新（如限流阈值、Agent 模型切换）。

2.1.5 系统管理

• 后台管理界面：用户管理、群组管理、消息审计、系统监控（QPS、内存、磁盘）。
• 日志记录：操作日志、错误日志、访问日志，支持 Elasticsearch 检索。

2.2 非功能需求

2.2.1 性能

• 单机网关支持 10 万长连接（WebSocket），消息延迟 < 100ms（P99）。
• 消息存储支持百万级用户每日 1 亿条消息，写入吞吐 > 10万 TPS。
• AI Agent 单实例回复延迟 < 2s（不含大模型推理本身，若使用云 API 则依赖外部）。

2.2.2 可扩展性

• 所有服务无状态，通过 Kubernetes 自动伸缩。
• 消息存储使用分片数据库，支持动态增加分片。
• AI Agent 可动态注册新技能，无需重启主服务。

2.2.3 可用性

• 关键服务（网关、消息分发）多副本部署，单副本故障不影响可用性。
• 数据库主从切换 < 30s。
• 服务整体可用性 99.99%（年度停机 < 52分钟）。

2.2.4 安全性

• 传输加密：TLS 1.3，WebSocket 使用 wss。
• 消息内容加密存储（AES-256），服务端不能明文查看（除审计外可解密）。
• 防暴力登录：验证码、限流（每 IP 每分钟 5 次尝试）。
• XSS/CSRF 防护。
• OAuth2.0 授权码模式 + PKCE。

2.3 用例图

3. 技术方案设计

3.1 总体架构

采用微服务架构，核心分为四层：接入层、逻辑层、数据层、AI层。各层组件可独立部署与扩展。

3.2 关键技术选型

3.3 关键技术设计

3.3.1 客户端连接与消息流

采用 WebSocket 作为长连接协议，客户端建立连接后发送认证 token，网关验证后维持会话。消息路由通过服务端内部消息 ID 和 SessionID 结合 Kafka 实现。

消息格式（JSON）：

{
  "msgId": "uuid",
  "from": "userA",
  "to": "userB_or_agent_id",
  "type": "text|image|voice|video|file|system",
  "content": "Hello world",
  "timestamp": 1700000000000,
  "clientMsgId": "客户端去重id",
  "mention": ["userC"] // 仅群聊
}

3.3.2 AI Agent 调度设计

AI Agent 定义为一个微服务，通过注册中心（Consul）注册其支持的技能（skill）。AI 调度服务根据用户消息中的意图（或预设关键词）匹配 AI Agent，将请求转发至对应 Agent 节点。Agent 回复后通过消息服务返回到用户。

Agent 注册数据模型（JSON Schema）：

{
  "agentId": "weather_bot_v1",
  "name": "天气助手",
  "description": "查询全国城市天气",
  "skills": [
    {
      "id": "get_weather",
      "description": "获取指定城市当前天气",
      "params": ["city"]
    }
  ],
  "endpoint": "grpc://agent-cluster:50051",
  "load": 0.3
}

AI调度流程：

1. 用户发送消息 @天气助手 北京天气。
2. 消息服务检测到 @agentId 字段，将消息转发给 AI 调度服务。
3. 调度服务识别意图，查询 Consul 获取可用 weather_bot 节点。
4. 通过 gRPC 将请求转发给选中的 Agent 节点（优先本地 IDC）。
5. Agent 调用外部天气 API（如 和风天气）或本地知识库，生成回复。
6. 回复消息封装为标准消息格式，通过 Kafka 返回给用户。

上下文管理：每个会话维护一个 Redis 缓存，key 为 session:agentId:userId，value 为最近 10 条对话的 JSON 数组，超时时间 30 分钟。

3.3.3 多服务端扩展与负载均衡

• 网关层使用一致性哈希（基于用户ID hash）将同一用户长期绑定到同一网关节点（减少跨节点消息转发），但当网关故障时需重新分配。
• 消息服务内部无状态，通过 Kafka 分区保证同一用户的消息写入顺序（按 userID hash 到固定 partition）。
• 历史消息存储使用 Cassandra，表设计按 userID 散列到多个节点，分区键为 (userID, bucket)，bucket 按月份或按 ID 哈希取模。

3.3.4 安全性实现

• 传输层：所有客户端与服务端通信使用 TLS 1.3，WebSocket 路径强制 wss。
• 应用层鉴权：每次连接携带 JWT token（RS256签名），网关验证 token 后解析 userID。
• 消息加密：消息内容在服务端入库前使用 AES-256-GCM 加密，密钥由密钥管理服务（KMS）管理，仅在有审计或用户自主导出解密权限时解密。
• 防重放：每个消息携带递增序号或时间戳，服务端检测重复 clientMsgId。

3.4 数据库设计（核心表）

3.4.1 用户表（MySQL）

CREATE TABLE `user` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `username` varchar(64) NOT NULL COMMENT '全局唯一昵称',
  `email` varchar(128) DEFAULT NULL,
  `phone` varchar(20) DEFAULT NULL,
  `password_hash` varchar(256) NOT NULL,
  `avatar_url` varchar(512) DEFAULT NULL,
  `status` tinyint NOT NULL DEFAULT 0 COMMENT '0:离线 1:在线 2:忙碌 3:隐身',
  `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_username` (`username`),
  UNIQUE KEY `uk_email` (`email`),
  KEY `idx_phone` (`phone`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

3.4.2 消息表（Cassandra CQL）

CREATE TABLE chat.user_messages (
    user_id text,          -- 接收方用户ID
    bucket bigint,        -- 时间桶（月度时间戳/1000000）
    msg_id timeuuid,      -- 消息唯一ID（含时间）
    from_user text,
    to_user text,
    msg_type text,
    content blob,         -- 加密后的消息内容
    timestamp bigint,
    client_msg_id text,
    PRIMARY KEY ((user_id, bucket), msg_id)
) WITH CLUSTERING ORDER BY (msg_id DESC);

3.4.3 好友关系（Redis）

SADD friend:userA userB
SADD friend:userA userC
SMEMBERS friend:userA

3.5 部署架构与运维

3.5.1 Kubernetes 部署

所有服务（网关、用户、消息、AI调度、推送）以 Docker 镜像部署在 K8s 集群，使用 HPA 自动伸缩。Cassandra 需部署在 K8s 外的独立集群或使用 Operator 管理（如 K8ssandra）。Redis Cluster 可通过 StatefulSet 部署。Kafka 建议使用 Strimzi 或 Confluent Operator。

资源预估（单节点，支持 10 万并发连接）：

• 网关：2 vCPU, 4GB RAM
• 消息服务：4 vCPU, 8GB RAM
• AI 调度：2 vCPU, 4GB RAM（不含推理）
• 推理节点（若自建）：4 vCPU, 16GB RAM + GPU

3.5.2 监控告警

• Prometheus + Grafana 监控各服务指标（QPS、延迟、连接数、Kafka Lag）。
• 告警规则：连接数 > 80% 上限、消息延迟 > 500ms、AI 回复超时 > 3s。
• 日志通过 Filebeat 采集至 ELK。

4. 备选方案与关键决策记录

5. 实施路线图（8小时工作量细化）

6. 风险与应对

7. 附录：关键接口定义

7.1 WebSocket 消息结构（客户端→服务端）

{
  "cmd": "send_msg",
  "data": {
    "to": "user2_or_group_id",
    "msgType": "text",
    "content": "Hello",
    "clientMsgId": "uuid"
  }
}

7.2 服务端→客户端推送结构

{
  "cmd": "new_msg",
  "data": {
    "msgId": "timeuuid",
    "from": "user1",
    "to": "user2",
    "msgType": "text",
    "content": "Hello",
    "timestamp": 1700000000000
  }
}

7.3 获取历史消息 REST API

• GET /api/v1/messages?userId={target}&beforeMsgId={lastMsgId}&count=50
• 返回消息列表（已解密的明文内容，仅对请求者本人有效）。

本文档覆盖了项目需求分析、架构设计、技术选型、详细流程、数据库设计、部署运维及风险应对，可直接作为后续开发的技术指导。

正文字数太多了删掉了先放一个pdf吧

9.3 合规与安全要求

• 所有监控指标端口（如 /metrics）仅允许内部网络访问（iptables限制）
• Grafana需开启OAuth认证（与LDAP集成）
• 日志中敏感字段（手机号、token）需在logstash中脱敏（使用 ruby { code => 'event.set("message", event.get("message").gsub(/\d{11}/,"******"))' }）
• 告警webhook目标IP须白名单限制

完成日期：2025-03-25
签署人：运维负责人 __________