# Virgil Security 接入到聊天系统设计方案（服务器） ## 1. 服务器设计目标 服务端的目标不是参与解密，而是提供 **业务承载层**： - 业务身份认证 - 设备管理 - Virgil JWT 签发 - 单聊/群聊会话管理 - 密文消息接入与路由 - 离线同步 - 文件上传/下载票据 - 群成员关系与群密钥版本索引 - 风控与设备吊销 --- ## 2. 服务器总体架构 ```mermaid flowchart LR subgraph Backend["业务服务端"] B1["API Gateway"] B2["Auth Service"] B3["Virgil JWT Service"] B4["Conversation Service"] B5["Message Router / Sync"] B6["Group Service"] B7["Push Service"] B8["File Ticket Service"] B9["Risk / Device Service"] B10["Metadata DB"] end subgraph Virgil["Virgil Cloud"] V1["Cards / Public Key Directory"] V2["Restore Related Services"] end subgraph OSS["Object Storage / CDN"] O1["Encrypted File Objects"] end B1 --> B2 B1 --> B3 B1 --> B4 B1 --> B5 B1 --> B6 B1 --> B8 B1 --> B9 B2 --> B10 B3 --> B10 B4 --> B10 B5 --> B10 B6 --> B10 B8 --> O1 B9 --> B10 B3 --> V1 B3 --> V2 ``` --- ## 3. 服务器职责边界 ## 3.1 服务端应该负责什么 - 用户登录与 token - 设备注册与吊销 - Virgil JWT 签发 - 会话与群组元数据 - 密文消息存储 - 消息序列号与游标 - 离线消息投递 - 已读/已送达状态 - 文件票据 - 群成员变更事件 - 风控控制 ## 3.2 服务端不应该负责什么 - 私钥保存 - 文本明文解析 - 文件明文解析 - 群密钥管理的明文操作 - 替客户端做消息加解密 --- ## 4. 推荐服务拆分 ```text api-gateway auth-service virgil-jwt-service conversation-service message-service group-service sync-service push-service file-ticket-service risk-device-service ``` ### 各服务说明 #### api-gateway - 统一入口 - 鉴权 - 请求限流 - trace 注入 #### auth-service - 登录 - refresh - logout #### virgil-jwt-service - 生成 Virgil JWT - user/device 到 virgil identity 的映射 - 风控前置校验 #### conversation-service - 单聊会话 - 会话设置 - 会话列表 #### message-service - 接收密文 envelope - 分配 message_id / seq - 存储与 fanout #### group-service - 创建群 - 加人/踢人/退群 - 群资料 - 维护 group_key_version #### sync-service - bootstrap - 增量消息 - 群事件同步 #### push-service - message.new - message.recall - group.member_changed - device.revoked #### file-ticket-service - 上传票据 - 下载票据 - 文件元信息 #### risk-device-service - 设备状态 - 完整性校验 - 风险拦截 --- ## 5. 服务端数据模型 ## 5.1 用户与设备 ```mermaid erDiagram USER ||--o{ DEVICE : owns USER { string user_id string status int64 created_at } DEVICE { string device_id string user_id string platform string device_model string app_version string virgil_identity string status int64 last_seen_at } ``` ## 5.2 会话与消息 ```mermaid erDiagram CONVERSATION ||--o{ MESSAGE : contains CONVERSATION { string conversation_id string type string peer_key string group_id int64 created_at } MESSAGE { string message_id string conversation_id string chat_type string sender_user_id string sender_device_id string receiver_user_id string group_id int64 group_key_version string content_type int envelope_version string cipher_suite bytes ciphertext bytes signature int64 seq int64 server_timestamp } ``` ## 5.3 群与群事件 ```mermaid erDiagram GROUP ||--o{ GROUP_MEMBER : has GROUP ||--o{ GROUP_KEY_EVENT : emits GROUP { string group_id string conversation_id string owner_user_id string name int64 group_key_version string status } GROUP_MEMBER { string group_id string user_id string role string status int64 join_version int64 leave_version } GROUP_KEY_EVENT { string event_id string group_id int64 group_key_version string event_type string operator_user_id int64 created_at } ``` --- ## 6. 服务端接口设计 ## 6.1 认证与设备 ### 登录 ```http POST /api/v1/auth/login ``` ### 刷新 token ```http POST /api/v1/auth/refresh ``` ### 登出 ```http POST /api/v1/auth/logout ``` ### 注册设备 ```http POST /api/v1/devices/register ``` ### 查询设备列表 ```http GET /api/v1/devices ``` ### 吊销设备 ```http POST /api/v1/devices/{device_id}:revoke ``` --- ## 6.2 Virgil JWT ### 获取 Virgil JWT ```http POST /api/v1/security/virgil-jwt ``` 请求： ```json { "device_id": "ios_a1" } ``` 响应： ```json { "virgil_jwt": "virgil_jwt_xxx", "expires_in": 3600, "virgil_identity": "u_1001:ios_a1" } ``` --- ## 6.3 会话 ### 创建/获取单聊 ```http POST /api/v1/conversations/single ``` ### 会话列表 ```http GET /api/v1/conversations ``` ### 会话详情 ```http GET /api/v1/conversations/{conversation_id} ``` ### 会话设置 ```http POST /api/v1/conversations/{conversation_id}/settings ``` --- ## 6.4 消息 ### 发送消息 ```http POST /api/v1/messages ``` ### 批量发送 ```http POST /api/v1/messages:batchSend ``` ### 拉取指定消息 ```http GET /api/v1/messages/{message_id} ``` ### 撤回消息 ```http POST /api/v1/messages/{message_id}:recall ``` ### 仅自己删除 ```http POST /api/v1/messages/{message_id}:deleteForMe ``` --- ## 6.5 群组 ### 创建群 ```http POST /api/v1/groups ``` ### 群详情 ```http GET /api/v1/groups/{group_id} ``` ### 群上下文 ```http GET /api/v1/groups/{group_id}/context ``` ### 群成员列表 ```http GET /api/v1/groups/{group_id}/members ``` ### 加人 ```http POST /api/v1/groups/{group_id}/members:add ``` ### 移除成员 ```http POST /api/v1/groups/{group_id}/members:remove ``` ### 退群 ```http POST /api/v1/groups/{group_id}:leave ``` ### 解散群 ```http POST /api/v1/groups/{group_id}:dismiss ``` ### 修改群资料 ```http POST /api/v1/groups/{group_id}/profile ``` --- ## 6.6 文件 ### 申请上传票据 ```http POST /api/v1/files/upload-ticket ``` ### 上传完成 ```http POST /api/v1/files/{file_id}:complete ``` ### 获取下载票据 ```http POST /api/v1/files/{file_id}/download-ticket ``` ### 获取文件元信息 ```http GET /api/v1/files/{file_id} ``` --- ## 6.7 同步 ### 冷启动 bootstrap ```http GET /api/v1/sync/bootstrap ``` ### 增量消息同步 ```http GET /api/v1/sync/messages ``` ### 群事件同步 ```http GET /api/v1/sync/group-events ``` --- ## 6.8 回执与状态 ### 已送达/已读 ```http POST /api/v1/messages/ack ``` ### 批量已读 ```http POST /api/v1/conversations/{conversation_id}:markRead ``` ### 输入中 ```http POST /api/v1/conversations/{conversation_id}/typing ``` --- ## 6.9 风控与安全 ### 预检查 ```http POST /api/v1/security/precheck ``` ### 设备完整性上报 ```http POST /api/v1/security/integrity-report ``` --- ## 7. 服务端核心流程 ## 7.1 签发 Virgil JWT ```mermaid sequenceDiagram participant C as 客户端 participant J as Virgil JWT Service participant A as Auth Service participant R as Risk / Device Service C->>J: /security/virgil-jwt J->>A: 校验 access_token A-->>J: 用户有效 J->>R: 校验 device_id / 风险状态 R-->>J: 允许或拒绝 J-->>C: 返回 virgil_jwt ``` ## 7.2 消息接收与路由 ```mermaid sequenceDiagram participant C as 客户端 participant M as Message Service participant S as Sync Service participant P as Push Service participant DB as Metadata DB C->>M: POST /messages M->>DB: 存储 envelope M->>DB: 分配 message_id / seq M->>S: 写离线同步流 M->>P: 触发新消息推送 M-->>C: 返回 accepted ``` ## 7.3 群成员变更 ```mermaid sequenceDiagram participant A as 管理员客户端 participant G as Group Service participant DB as Metadata DB participant S as Sync Service participant P as Push Service A->>G: /groups/{id}/members:add G->>DB: 更新群成员 G->>DB: group_key_version + 1 G->>S: 写入 group event G->>P: 推送 group.member_changed G-->>A: 返回最新 group_key_version ``` --- ## 8. 服务端幂等与校验 ## 8.1 幂等设计 ### 发消息幂等键 推荐： ```text sender_user_id + sender_device_id + client_message_id ``` ### 创建群幂等 推荐使用： ```http Idempotency-Key: ``` ## 8.2 消息接口校验项 - 当前用户是会话参与者 - `sender_device_id` 属于当前用户 - 单聊的 `receiver_user_id` 与会话匹配 - 群聊的 `group_id` 与会话匹配 - 当前用户是群成员 - `group_key_version` 合法 - `ciphertext` 长度不超过限制 ## 8.3 Virgil JWT 接口校验项 - 业务 token 有效 - `device_id` 属于当前用户 - 设备状态为 active - 未被吊销 - 风控未阻断 --- ## 9. WebSocket / 推送事件建议 ### WebSocket 事件 - `message.new` - `message.recall` - `message.ack` - `group.member_changed` - `group.profile_changed` - `device.revoked` - `security.force_logout` ### 推送原则 推送中不要放消息明文，建议只放： - 会话 ID - 发送方昵称 - 占位提示 --- ## 10. 服务端风险点 - 若服务端误记录明文日志，会破坏 E2EE 边界 - 若文件下载链接长期有效，文件密文泄露面会扩大 - 若群成员变更后未提升 `group_key_version`，客户端可能使用旧上下文 - 若被吊销设备仍可获取 Virgil JWT，会造成安全失控 - 若推送带明文，会绕过加密链路 --- ## 11. 推荐实施路径 ## 阶段 1：单聊 MVP 实现： - 登录 - Virgil JWT - 单聊消息发送 - 增量同步 - 已读回执 ## 阶段 2：群聊 实现： - 创建群 - 群成员管理 - group_key_version - 群事件同步 ## 阶段 3：文件与恢复 实现： - 文件票据 - 加密文件上传下载 - 新设备恢复 - 风控增强 --- ## 12. 服务器总结 服务器在 Virgil Security 接入中的核心定位是： - 不参与消息解密 - 不保存私钥 - 只处理密文、元数据和业务控制逻辑 具体来说，服务器负责： - 身份认证 - 设备管理 - Virgil JWT 签发 - 密文消息接入、存储、路由 - 会话与群成员关系 - 文件票据 - 同步与推送 - 风控和设备吊销 这样才能既保留现有聊天系统的业务能力，又维持端到端加密的安全边界。