From 168bf4662c717bf6337c59bf14a3e251592f86b9 Mon Sep 17 00:00:00 2001 From: XuqmGroup Date: Fri, 8 May 2026 18:32:00 +0800 Subject: [PATCH] =?UTF-8?q?docs(deploy):=20=E6=B7=BB=E5=8A=A0=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=96=87=E6=A1=A3=E5=92=8C=E5=AE=89=E5=85=A8=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 XuqmGroup 部署文档，包含部署方案、架构建议和部署步骤 - 添加安全设计规范，涵盖密码安全、AppSecret验证和服务端API认证 - 补充平台REST API规范，定义Server-to-Server调用接口和错误码 - 创建Java IM服务端SDK计划文档，规划Maven包发布和接口实现 --- .nvmrc | 2 +- Dockerfile | 6 +- Jenkinsfile | 4 +- docs-site/docs/server/api.md | 457 +++++----- docs-site/docs/server/go-sdk.md | 61 +- docs-site/docs/server/java-sdk.md | 87 +- docs-site/docs/server/python-sdk.md | 38 +- docs-site/docs/server/websocket.md | 6 +- tenant-platform/package.json | 1 + tenant-platform/src/api/app.ts | 98 ++- tenant-platform/src/api/update.ts | 2 +- .../src/views/im/ImManagementView.vue | 2 +- .../src/views/im/ImWebhookView.vue | 3 +- .../src/views/push/PushConfigView.vue | 782 ++++++++++-------- .../views/update/VersionManagementView.vue | 294 ++++++- yarn.lock | 5 + 16 files changed, 1144 insertions(+), 704 deletions(-) diff --git a/.nvmrc b/.nvmrc index 2bd5a0a..db49bb1 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -22 +22.22.2 diff --git a/Dockerfile b/Dockerfile index 07ac4e1..34c70e8 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,3 +1,4 @@ +# syntax=docker/dockerfile:1.7 FROM node:22-alpine AS build WORKDIR /workspace @@ -7,7 +8,10 @@ COPY tenant-platform ./tenant-platform COPY ops-platform ./ops-platform COPY docs-site ./docs-site -RUN yarn install --frozen-lockfile +ENV YARN_CACHE_FOLDER=/var/cache/yarn + +RUN --mount=type=cache,target=/var/cache/yarn,sharing=locked \ + yarn install --frozen-lockfile ARG TENANT_APP_BASE=/ ARG OPS_APP_BASE=/ops/ diff --git a/Jenkinsfile b/Jenkinsfile index bc844c5..7bffa6d 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -15,6 +15,7 @@ pipeline { PROD_USER = 'ubuntu' COMPOSE_FILE = '/opt/xuqm/deploy/compose.production.yaml' IMAGE_NAME = 'web' + DOCKER_BUILDKIT = '1' } stages { @@ -29,7 +30,8 @@ pipeline { def fullImage = "${ACR_REGISTRY}/${ACR_NAMESPACE}/${IMAGE_NAME}:${params.IMAGE_TAG}" bat """ docker login ${ACR_REGISTRY} -u ${ACR_USERNAME} -p %ACR_PASS% - docker build -t ${fullImage} . + docker pull ${fullImage} || exit 0 + docker build --build-arg BUILDKIT_INLINE_CACHE=1 --cache-from ${fullImage} -t ${fullImage} . docker push ${fullImage} docker rmi ${fullImage} """ diff --git a/docs-site/docs/server/api.md b/docs-site/docs/server/api.md index a5e6b0a..cd1ae5c 100644 --- a/docs-site/docs/server/api.md +++ b/docs-site/docs/server/api.md @@ -1,249 +1,280 @@ # Server API 参考 +XuqmGroup 的服务端能力分成三类： + +- `IM 服务`：账号、消息、群组、好友、会话、黑名单、管理端、回调 +- `Push 服务`：设备注册、离线推送、诊断、管理端 +- `Update 服务`：应用版本、RN Bundle、应用商店提审、发布配置、操作日志 + **Base URL**：`https://dev.xuqinmin.com` -所有 API 通过 Nginx 反代，无需区分内部端口。 +所有接口都通过 Nginx 反代，无需关心内部端口。 + +--- ## 认证 -除 `/api/im/auth/login` 外，所有 IM 接口需在请求头携带 JWT Token： +### IM 服务 -``` -Authorization: Bearer -``` +- `POST /api/im/auth/login` 之前的所有请求，客户端和服务端均需携带 `Authorization: Bearer ` +- `im_jwt` 通过 `POST /api/im/auth/login` 颁发 +- 登录请求需要 `X-App-Timestamp`、`X-App-Nonce`、`X-App-Signature` -Token 由 `/api/im/auth/login` 接口签发。当前 IM 登录不做过期功能，只校验 `userId + UserSig` 是否匹配。 +### Push / Update / Tenant 相关服务 + +- 业务侧调用通常使用 `appKey` +- 管理端接口需要租户或运营平台的 JWT +- 内部接口统一使用 `X-Internal-Token` --- -## IM 服务（/api/im/） +## IM 服务 -### 登录 · 获取 Token +### 账号与登录 -``` -POST /api/im/auth/login -``` - -**Query 参数** - -| 参数 | 必填 | 说明 | +| 方法 | 路径 | 说明 | |------|------|------| -| `appId` | 是 | 应用 ID | -| `userId` | 是 | 用户 ID | +| `POST` | `/api/im/auth/login` | IM 登录，返回 JWT Token | +| `GET` | `/api/im/accounts/{userId}` | 获取账号资料 | +| `PUT` | `/api/im/accounts/{userId}` | 更新账号资料 | +| `GET` | `/api/im/accounts/search` | 搜索账号 | +| `POST` | `/api/im/accounts/import` | 导入单个账号 | +| `POST` | `/api/im/accounts/import/batch` | 批量导入账号 | +| `DELETE` | `/api/im/accounts/{userId}` | 删除账号 | +| `GET` | `/api/im/accounts/{userId}/exists` | 检查账号是否存在 | -**请求头** +### 消息 -| 头 | 必填 | 说明 | -|----|------|------| -| `X-App-Timestamp` | 是 | 当前时间戳（毫秒） | -| `X-App-Nonce` | 是 | 随机字符串 | -| `X-App-Signature` | 是 | HmacSHA256 签名 | +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/im/messages/send` | 发送消息 | +| `POST` | `/api/im/messages/{id}/revoke` | 撤回消息 | +| `PUT` | `/api/im/messages/{id}` | 编辑消息 | +| `GET` | `/api/im/messages/history/{toId}` | 单聊历史 | +| `GET` | `/api/im/messages/group-history/{groupId}` | 群聊历史 | +| `GET` | `/api/im/messages/search` | 按关键字搜索消息 | +| `GET` | `/api/im/messages/offline/count` | 离线消息数 | +| `POST` | `/api/im/messages/offline` | 同步离线消息 | -**签名 Payload**（已简化，不再包含 nickname/avatar）： -``` -{appId}\n{userId}\n{timestamp}\n{nonce} -``` +### 会话 -**响应** +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/im/conversations` | 会话列表 | +| `PUT` | `/api/im/conversations/{targetId}/pinned` | 置顶会话 | +| `PUT` | `/api/im/conversations/{targetId}/muted` | 免打扰 | +| `PUT` | `/api/im/conversations/{targetId}/read` | 标记已读 | +| `PUT` | `/api/im/conversations/{targetId}/draft` | 设置草稿 | +| `PUT` | `/api/im/conversations/{targetId}/hidden` | 隐藏会话 | +| `PUT` | `/api/im/conversations/{targetId}/group` | 设置会话分组 | +| `GET` | `/api/im/conversation-groups` | 会话分组列表 | +| `GET` | `/api/im/conversation-groups/{groupName}` | 指定分组内容 | +| `DELETE` | `/api/im/conversations/{targetId}` | 删除会话 | -```json -{ "token": "eyJ..." } -``` +### 好友与黑名单 -> 重复登录会覆盖当前会话；SDK 侧不做生命周期检测或旧登录兼容。 +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/im/friends` | 好友列表 | +| `POST` | `/api/im/friends` | 添加好友 | +| `POST` | `/api/im/friends/batch` | 批量添加好友 | +| `DELETE` | `/api/im/friends/{friendId}` | 删除好友 | +| `DELETE` | `/api/im/friends` | 删除全部好友 | +| `POST` | `/api/im/friends/batch/remove` | 批量删除好友 | +| `PUT` | `/api/im/friends/{friendId}/group` | 设置好友分组 | +| `GET` | `/api/im/friends/groups` | 好友分组列表 | +| `GET` | `/api/im/friends/groups/{groupName}` | 指定分组好友 | +| `POST` | `/api/im/friends/check` | 校验好友关系 | +| `GET` | `/api/im/blacklist` | 黑名单列表 | +| `POST` | `/api/im/blacklist` | 添加黑名单 | +| `DELETE` | `/api/im/blacklist` | 删除黑名单 | +| `GET` | `/api/im/blacklist/check` | 校验黑名单关系 | + +### 群组 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/im/groups` | 群列表 | +| `POST` | `/api/im/groups` | 创建群组 | +| `GET` | `/api/im/groups/public` | 公开群列表 | +| `GET` | `/api/im/groups/search` | 搜索群 | +| `GET` | `/api/im/groups/{groupId}` | 群详情 | +| `GET` | `/api/im/groups/{groupId}/members` | 群成员 | +| `GET` | `/api/im/groups/{groupId}/members/search` | 搜索群成员 | +| `PUT` | `/api/im/groups/{groupId}` | 更新群信息 | +| `POST` | `/api/im/groups/{groupId}/members` | 添加群成员 | +| `POST` | `/api/im/groups/{groupId}/members/batch` | 批量添加群成员 | +| `DELETE` | `/api/im/groups/{groupId}/members/{targetUserId}` | 删除群成员 | +| `POST` | `/api/im/groups/{groupId}/members/batch/remove` | 批量删除群成员 | +| `POST` | `/api/im/groups/{groupId}/roles` | 设置群角色 | +| `POST` | `/api/im/groups/{groupId}/owner` | 转让群主 | +| `PUT` | `/api/im/groups/{groupId}/attributes` | 更新群属性 | +| `POST` | `/api/im/groups/{groupId}/attributes/delete` | 删除群属性 | +| `POST` | `/api/im/groups/{groupId}/mute` | 群成员禁言 | +| `DELETE` | `/api/im/groups/{groupId}` | 解散群 | +| `POST` | `/api/im/groups/{groupId}/join-requests` | 发送加群申请 | +| `GET` | `/api/im/groups/{groupId}/join-requests` | 查询加群申请 | +| `POST` | `/api/im/groups/{groupId}/join-requests/{requestId}/accept` | 接受加群申请 | +| `POST` | `/api/im/groups/{groupId}/join-requests/{requestId}/reject` | 拒绝加群申请 | +| `POST` | `/api/im/groups/{groupId}/join-requests/batch/accept` | 批量接受加群申请 | +| `POST` | `/api/im/groups/{groupId}/join-requests/batch/reject` | 批量拒绝加群申请 | + +### 管理端 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/im/admin/users/state` | 查询用户在线状态 | +| `POST` | `/api/im/admin/users/kick` | 踢下线用户 | +| `POST` | `/api/im/admin/messages/batch-send` | 批量发消息 | +| `POST` | `/api/im/admin/messages/read` | 管理端标记已读 | +| `POST` | `/api/im/admin/messages/import` | 导入消息 | +| `GET` | `/api/im/admin/groups/{groupId}/owner` | 查询群主 | +| `PUT` | `/api/im/admin/groups/{groupId}/owner` | 管理端转让群主 | +| `PUT` | `/api/im/admin/groups/{groupId}/attributes` | 管理端更新群属性 | +| `POST` | `/api/im/admin/groups/{groupId}/attributes/delete` | 管理端删除群属性 | +| `GET` | `/api/im/admin/groups/{groupId}/read-receipts` | 群已读统计 | +| `GET` | `/api/im/admin/webhooks` | Webhook 列表 | +| `POST` | `/api/im/admin/webhooks` | 创建 Webhook | +| `PUT` | `/api/im/admin/webhooks/{id}` | 更新 Webhook | +| `DELETE` | `/api/im/admin/webhooks/{id}` | 删除 Webhook | +| `GET` | `/api/im/admin/webhook-deliveries` | Webhook 投递记录 | +| `GET` | `/api/im/admin/webhook-alerts` | Webhook 告警 | +| `POST` | `/api/im/admin/webhook-alerts/{id}/acknowledge` | 告警确认 | +| `GET` | `/api/im/admin/webhooks/{id}/health` | Webhook 健康状态 | +| `GET` | `/api/im/admin/keyword-filters` | 敏感词列表 | +| `POST` | `/api/im/admin/keyword-filters` | 新增敏感词 | +| `PUT` | `/api/im/admin/keyword-filters/{id}` | 更新敏感词 | +| `DELETE` | `/api/im/admin/keyword-filters/{id}` | 删除敏感词 | +| `GET` | `/api/im/admin/global-mute` | 全局禁言状态 | +| `PUT` | `/api/im/admin/global-mute` | 更新全局禁言 | +| `GET` | `/api/im/admin/operation-logs` | IM 操作日志 | + +### 内部接口 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/im/internal/presence/resolve-token` | 解析 IM Token | +| `GET` | `/api/im/internal/presence/users/{userId}` | 查询用户在线状态 | --- -### 发送消息 +## Push 服务 -``` -POST /api/im/messages/send -Authorization: Bearer -Content-Type: application/json -``` +### 公开接口 -**请求体** +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/push/register` | 设备注册推送 token | +| `DELETE` | `/api/push/unregister` | 设备取消注册 | +| `POST` | `/api/push/send` | 发送推送 | +| `POST` | `/api/push/receive-push` | 推送回执/接收 | + +### 管理端 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/push/admin/user-status` | 查询用户推送状态 | +| `GET` | `/api/push/admin/device-logs` | 设备日志 | +| `POST` | `/api/push/admin/test-offline` | 离线推送测试 | + +### 内部接口 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/push/internal/notify` | 内部通知转发 | +| `GET` | `/api/push/internal/diagnostics/search` | 按 token 查询诊断 | +| `GET` | `/api/push/internal/device-logs` | 内部设备日志 | +| `POST` | `/api/push/internal/test-offline` | 内部离线测试 | + +--- + +## Update 服务 + +### 应用版本 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/v1/updates/app/check` | 检查应用更新 | +| `POST` | `/api/v1/updates/app/upload` | 上传应用版本 | +| `GET|POST` | `/api/v1/updates/app/inspect` | 检查上传内容 | +| `POST` | `/api/v1/updates/app/{id}/publish` | 发布应用版本 | +| `POST` | `/api/v1/updates/app/{id}/unpublish` | 取消发布 | +| `POST` | `/api/v1/updates/app/{id}/gray` | 灰度发布 | +| `GET` | `/api/v1/updates/app/list` | 版本列表 | + +### RN Bundle + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/v1/rn/update/check` | 检查 RN 更新 | +| `POST` | `/api/v1/rn/upload` | 上传 RN Bundle | +| `GET|POST` | `/api/v1/rn/inspect` | 检查 RN 上传内容 | +| `GET` | `/api/v1/rn/list` | RN 列表 | +| `POST` | `/api/v1/rn/{id}/publish` | 发布 RN Bundle | +| `POST` | `/api/v1/rn/{id}/unpublish` | 取消发布 RN Bundle | +| `POST` | `/api/v1/rn/{id}/gray` | RN 灰度 | + +### 应用商店提审 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/v1/updates/publish/config` | 获取发布配置 | +| `PUT` | `/api/v1/updates/publish/config` | 更新发布配置 | +| `GET` | `/api/v1/updates/gray/members` | 灰度成员列表 | +| `POST` | `/api/v1/updates/gray/members/sync` | 同步灰度成员 | +| `POST` | `/api/v1/updates/gray/members/import` | 导入灰度成员 | +| `GET` | `/api/v1/updates/store/configs` | 获取应用市场配置 | +| `PUT` | `/api/v1/updates/store/configs/{storeType}` | 更新应用市场配置 | +| `DELETE` | `/api/v1/updates/store/configs/{storeType}` | 删除应用市场配置 | +| `GET` | `/api/v1/updates/store/credentials` | 获取市场凭据摘要 | +| `POST` | `/api/v1/updates/store/app/{versionId}/submit` | 预提交应用市场 | +| `POST` | `/api/v1/updates/store/app/{versionId}/execute-submit` | 执行提审 | +| `POST` | `/api/v1/updates/store/app/{versionId}/review` | 回写审核结果 | + +### 运营日志与文件 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/v1/updates/ops/logs` | 更新操作日志 | +| `GET` | `/api/v1/updates/files/apk/{filename}` | APK 文件访问 | +| `GET` | `/api/v1/rn/files/{appKey}/{platform}/{moduleId}` | RN Bundle 文件访问 | +| `POST` | `/api/v1/updates/unified/upload` | 统一发布包上传 | + +--- + +## 数据模型约定 + +### 应用标识 + +- 所有业务侧判断应用身份使用 `appKey` +- `appId` 仅保留在第三方厂商账号字段里，不作为应用身份 + +### 常见响应 ```json { - "toId": "user_002", - "chatType": "SINGLE", - "msgType": "TEXT", - "content": "Hello!" + "code": 200, + "status": "0", + "data": { }, + "message": "success" } ``` -`chatType`：`SINGLE` | `GROUP` +### 错误码 -`msgType`：`TEXT` | `IMAGE` | `VIDEO` | `AUDIO` | `FILE` | `CUSTOM` | `LOCATION` | `NOTIFY` | `RICH_TEXT` | `CALL_AUDIO` | `CALL_VIDEO` | `FORWARD` - -**响应**：`ImMessage` 对象 - ---- - -### 撤回消息 - -``` -PUT /api/im/messages/{messageId}/revoke -Authorization: Bearer -``` - -**响应**：更新后的 `ImMessage`（`status: "REVOKED"`，`msgType: "REVOKED"`） - ---- - -### 消息历史（单聊） - -``` -GET /api/im/messages/history?appId=&userId=&toId=&page=0&size=50 -Authorization: Bearer -``` - -**响应**：分页 `ImMessage` 列表 - ---- - -### 创建群组 - -``` -POST /api/im/groups -Authorization: Bearer -Content-Type: application/json -``` - -```json -{ - "appId": "ak_demo_chat", - "name": "开发群", - "memberIds": ["user_001", "user_002"] -} -``` - -**响应**：`ImGroup` 对象 - ---- - -### 获取群列表 - -``` -GET /api/im/groups?appId=ak_demo_chat -Authorization: Bearer -``` - ---- - -### 添加群成员 - -``` -POST /api/im/groups/{groupId}/members -Authorization: Bearer -Content-Type: application/json - -{ "userId": "user_003" } -``` - ---- - -### 移除群成员 - -``` -DELETE /api/im/groups/{groupId}/members/{targetUserId} -Authorization: Bearer -``` - ---- - -### 会话扩展 - -``` -PUT /api/im/conversations/{targetId}/hidden?appId=&chatType=SINGLE&hidden=true -PUT /api/im/conversations/{targetId}/group?appId=&chatType=SINGLE&groupName=重要客户 -GET /api/im/conversation-groups?appId= -GET /api/im/conversation-groups/{groupName}?appId= -``` - -### 好友扩展 - -``` -DELETE /api/im/friends?appId= -PUT /api/im/friends/{friendId}/group?appId=&groupName=同事 -GET /api/im/friends/groups?appId= -GET /api/im/friends/groups/{groupName}?appId= -``` - -### 黑名单校验 - -``` -GET /api/im/blacklist/check?appId=&targetUserId=user_002 -``` - -### 群扩展 - -``` -POST /api/im/groups/{groupId}/owner -PUT /api/im/groups/{groupId}/attributes -POST /api/im/groups/{groupId}/attributes/delete -``` - -管理端补充： - -``` -POST /api/im/admin/groups/{groupId}/owner?appId= -PUT /api/im/admin/groups/{groupId}/attributes?appId= -POST /api/im/admin/groups/{groupId}/attributes/delete?appId= -POST /api/im/admin/groups/{groupId}/read-receipts?appId= -``` - ---- - -## 数据模型 - -### ImMessage - -```json -{ - "id": "uuid", - "appId": "ak_demo_chat", - "fromUserId": "user_001", - "toId": "user_002", - "chatType": "SINGLE", - "msgType": "TEXT", - "content": "Hello!", - "status": "SENT", - "mentionedUserIds": [], - "createdAt": "2026-04-24T10:00:00" -} -``` - -### ImGroup - -```json -{ - "id": "group_uuid", - "appId": "ak_demo_chat", - "name": "开发群", - "creatorId": "user_001", - "memberIds": ["user_001", "user_002"], - "adminIds": ["user_001"], - "extAttributes": "{\"department\":\"sales\"}", - "createdAt": "2026-04-24T10:00:00" -} -``` - ---- - -## 错误码 - -| HTTP 状态 | code | 说明 | +| HTTP 状态 | code | 含义 | |-----------|------|------| -| 400 | 400 | 请求参数错误 | -| 401 | 401 | Token 无效或签名验证失败 | -| 403 | 403 | 无权限操作（如撤回他人消息）| -| 404 | 404 | 资源不存在 | -| 500 | 500 | 服务器内部错误 | +| `400` | `400` | 参数错误 | +| `401` | `401` | 鉴权失败 | +| `403` | `403` | 无权限 | +| `404` | `404` | 资源不存在 | +| `500` | `500` | 服务端内部错误 | -错误响应格式： +--- -```json -{ "code": 403, "message": "只能撤回自己发送的消息" } -``` +## 集成建议 + +- 服务端业务代码统一使用 Java / Go / Python Server SDK 调用上述 REST 接口 +- 客户端统一使用 `appKey` 作为应用上下文 +- 实时刷新场景建议使用 IM SDK 订阅服务端事件 +- 更新、Push、IM 的后台能力可以独立接入，也可以组合使用 diff --git a/docs-site/docs/server/go-sdk.md b/docs-site/docs/server/go-sdk.md index 492fd82..cecdf13 100644 --- a/docs-site/docs/server/go-sdk.md +++ b/docs-site/docs/server/go-sdk.md @@ -1,13 +1,18 @@ # Go Server SDK -XuqmGroup 服务端 Go SDK，提供 IM 消息发送、群管理、Push 推送等能力。 +XuqmGroup 服务端 Go SDK，按照腾讯云服务端 API 的分类方式封装了： + +- IM 账号、消息、群组、好友、会话、黑名单 +- 管理端 Webhook、统计、操作日志 +- Push 注册与推送 +- Update 版本管理、RN Bundle、应用商店提审 --- ## 安装 ```bash -go get xuqinmin.com/xuqinmin12/XuqmGroup-ServerSDK-Go +go get github.com/xuqmgroup/xuqmgroup-server-sdk-go ``` --- @@ -15,19 +20,40 @@ go get xuqinmin.com/xuqinmin12/XuqmGroup-ServerSDK-Go ## 初始化 ```go -import xuqmsdk "xuqinmin.com/xuqinmin12/XuqmGroup-ServerSDK-Go" +import xuqmsdk "github.com/xuqmgroup/xuqmgroup-server-sdk-go" -client := xuqmsdk.NewClient(xuqmsdk.Config{ +client, err := xuqmsdk.NewClient(xuqmsdk.ClientConfig{ BaseURL: "https://dev.xuqinmin.com", - AppID: "your_app_id", + AppKey: "your_app_key", AppSecret: "your_app_secret", }) +if err != nil { + log.Fatal(err) +} ``` > 服务端 SDK 需要 `appSecret` 用于 HMAC 签名，`appSecret` 绝不下发到客户端。 --- +## 能力分类 + +| 分类 | 主要方法 | +|------|----------| +| 登录 | `Login` | +| 账号 | `ImportAccount`, `ImportAccounts`, `DeleteAccount`, `GetProfile`, `UpdateProfile`, `SearchAccounts`, `CheckAccount` | +| 消息 | `SendMessage`, `RevokeMessage`, `EditMessage`, `FetchHistory`, `FetchGroupHistory`, `SearchMessages` | +| 会话 | `ListConversations`, `SetConversationPinned`, `SetConversationMuted`, `MarkRead`, `SetDraft`, `SetConversationHidden`, `SetConversationGroup`, `DeleteConversation` | +| 好友 | `ListFriends`, `AddFriend`, `AddFriends`, `RemoveFriend`, `RemoveFriends`, `RemoveAllFriends`, `SetFriendGroup`, `ListFriendGroups`, `ListFriendsByGroup`, `CheckFriends` | +| 黑名单 | `ListBlacklist`, `AddBlacklist`, `RemoveBlacklist`, `CheckBlacklist` | +| 群组 | `ListGroups`, `ListPublicGroups`, `SearchGroups`, `GetGroup`, `ListGroupMembers`, `SearchGroupMembers`, `CreateGroup`, `UpdateGroup`, `AddGroupMember`, `AddGroupMembers`, `RemoveGroupMember`, `RemoveGroupMembers`, `SetGroupRole`, `TransferGroupOwner`, `LeaveGroup`, `UpdateGroupAttributes`, `RemoveGroupAttributes`, `MuteGroupMember`, `DismissGroup`, `SendGroupJoinRequest`, `ListGroupJoinRequests`, `AcceptGroupJoinRequest`, `RejectGroupJoinRequest`, `AcceptGroupJoinRequests`, `RejectGroupJoinRequests` | +| 管理端 | `QueryUserState`, `KickUsers`, `BatchSendMessage`, `AdminSetMsgRead`, `ImportMessages`, `AdminTransferGroupOwner`, `AdminUpdateGroupAttributes`, `AdminRemoveGroupAttributes`, `AdminGroupReadReceipts` | +| Webhook | `ListWebhooks`, `CreateWebhook`, `UpdateWebhook`, `DeleteWebhook`, `VerifyCallbackSignature`, `ParseCallbackEnvelope` | +| Push | `RegisterPushToken`, `SendPush` | +| Update | `CheckAppUpdate`, `UploadAppVersion`, `PublishAppVersion`, `UnpublishAppVersion`, `GrayAppVersion`, `ListAppVersions`, `CheckRnUpdate`, `UploadRnBundle`, `PublishRnBundle`, `UnpublishRnBundle`, `ListRnBundles` | + +--- + ## 发送消息 ```go @@ -65,22 +91,15 @@ err := client.RevokeMessage("message_id") ## 群管理 ```go -// 创建群组 -group, err := client.CreateGroup(xuqmsdk.CreateGroupRequest{ - Name: "项目讨论", - MemberIDs: []string{"user_001", "user_002"}, -}) +group, err := client.CreateGroup("项目讨论", []string{"user_001", "user_002"}, "NORMAL") +if err != nil { + log.Fatal(err) +} -// 添加群成员 err = client.AddGroupMember("group_xxx", "user_003") - -// 移除群成员 err = client.RemoveGroupMember("group_xxx", "user_003") -// 获取群列表 groups, err := client.ListGroups() - -// 获取群成员 members, err := client.ListGroupMembers("group_xxx") ``` @@ -89,12 +108,7 @@ members, err := client.ListGroupMembers("group_xxx") ## Push 推送 ```go -err := client.SendPush(xuqmsdk.SendPushRequest{ - UserID: "user_001", - Title: "新消息", - Body: "你有一条未读消息", - Payload: map[string]string{"chatId": "user_002"}, -}) +err := client.SendPush("user_001", "新消息", "你有一条未读消息", `{"chatId":"user_002"}`) ``` --- @@ -106,11 +120,10 @@ SDK 返回的错误实现了标准 `error` 接口。业务方可根据错误类 ```go msg, err := client.SendMessage(req) if err != nil { - // 可断言为 *xuqmsdk.APIError 获取 HTTP 状态码和详细错误信息 if apiErr, ok := err.(*xuqmsdk.APIError); ok { log.Printf("API 错误: status=%d, code=%d, message=%s", apiErr.Status, apiErr.Code, apiErr.Message) } } ``` -[→ Server API 文档 →](/server/api) +[→ Server API 文档](/server/api) diff --git a/docs-site/docs/server/java-sdk.md b/docs-site/docs/server/java-sdk.md index ec6e447..1cc1c26 100644 --- a/docs-site/docs/server/java-sdk.md +++ b/docs-site/docs/server/java-sdk.md @@ -1,6 +1,13 @@ # Java Server SDK -XuqmGroup 服务端 Java SDK，提供 IM 消息发送、群管理、Push 推送等能力。 +XuqmGroup 服务端 Java SDK，按腾讯云服务端 API 的思路封装了以下能力： + +- IM 账号与登录 +- 消息发送、编辑、撤回、历史查询 +- 好友、黑名单、会话、群组 +- Webhook、管理端操作、统计 +- Push 注册与发送 +- Update 版本检查、上传、发布、灰度、应用商店提审 --- @@ -10,14 +17,14 @@ Maven 在 `pom.xml` 中添加： ```xml - nexus-xuqm - https://nexus.xuqinmin.com/repository/android/ + xuqm-nexus + https://nexus.xuqinmin.com/repository/maven-public/ com.xuqm - xuqm-server-sdk - 0.1.0 + im-sdk + 0.1.0-SNAPSHOT ``` @@ -25,11 +32,11 @@ Gradle： ```kotlin repositories { - maven { url = uri("https://nexus.xuqinmin.com/repository/android/") } + maven { url = uri("https://nexus.xuqinmin.com/repository/maven-public/") } } dependencies { - implementation("com.xuqm:xuqm-server-sdk:0.1.0") + implementation("com.xuqm:im-sdk:0.1.0-SNAPSHOT") } ``` @@ -38,14 +45,13 @@ dependencies { ## 初始化 ```java -import com.xuqm.sdk.server.XuqmServerClient; -import com.xuqm.sdk.server.XuqmServerConfig; +import com.xuqm.im.sdk.XuqmImServerSdk; -XuqmServerClient client = new XuqmServerClient(XuqmServerConfig.builder() +XuqmImServerSdk client = XuqmImServerSdk.builder() .baseUrl("https://dev.xuqinmin.com") - .appId("your_app_id") + .appKey("your_app_key") .appSecret("your_app_secret") - .build()); + .build(); ``` > 服务端 SDK 需要 `appSecret` 用于 HMAC 签名，`appSecret` 绝不下发到客户端。 @@ -55,15 +61,18 @@ XuqmServerClient client = new XuqmServerClient(XuqmServerConfig.builder() ## 发送消息 ```java -import com.xuqm.sdk.server.model.SendMessageRequest; -import com.xuqm.sdk.server.model.ImMessage; +import com.xuqm.im.sdk.XuqmImServerSdk.ImMessage; +import com.xuqm.im.sdk.XuqmImServerSdk.SendMessageRequest; -ImMessage msg = client.sendMessage(SendMessageRequest.builder() - .toId("user_002") - .chatType("SINGLE") - .msgType("TEXT") - .content("Hello from Java SDK!") - .build()); +ImMessage msg = client.sendMessage(new SendMessageRequest( + "user_002", + "SINGLE", + "TEXT", + "Hello from Java SDK!", + null, + null, + null +)); System.out.println("消息已发送: " + msg.getId()); ``` @@ -87,28 +96,32 @@ client.revokeMessage("message_id"); --- -## 群管理 +## 能力分类 + +| 分类 | 主要方法 | +|------|----------| +| IM 账号 | `login`, `importAccount`, `importAccounts`, `deleteAccount`, `getProfile`, `updateProfile`, `searchAccounts` | +| 消息 | `sendMessage`, `revokeMessage`, `editMessage`, `fetchHistory`, `fetchGroupHistory`, `searchMessages` | +| 会话 | `listConversations`, `setConversationPinned`, `setConversationMuted`, `markRead`, `setDraft`, `setConversationHidden`, `setConversationGroup`, `deleteConversation` | +| 好友 | `listFriends`, `addFriend`, `addFriends`, `removeFriend`, `removeFriends`, `removeAllFriends`, `setFriendGroup`, `listFriendGroups`, `listFriendsByGroup`, `checkFriends` | +| 黑名单 | `listBlacklist`, `addBlacklist`, `removeBlacklist`, `checkBlacklist` | +| 群组 | `listGroups`, `createGroup`, `updateGroup`, `addGroupMember`, `addGroupMembers`, `removeGroupMember`, `removeGroupMembers`, `setGroupRole`, `transferGroupOwner`, `leaveGroup`, `updateGroupAttributes`, `removeGroupAttributes`, `muteGroupMember`, `dismissGroup`, `sendGroupJoinRequest`, `listGroupJoinRequests`, `acceptGroupJoinRequest`, `rejectGroupJoinRequest`, `acceptGroupJoinRequests`, `rejectGroupJoinRequests` | +| 管理端 | `queryUserState`, `kickUsers`, `batchSendMessage`, `adminSetMsgRead`, `importMessages`, `adminTransferGroupOwner`, `adminUpdateGroupAttributes`, `adminRemoveGroupAttributes`, `adminGroupReadReceipts` | +| Webhook | `listWebhooks`, `createWebhook`, `updateWebhook`, `deleteWebhook`, `verifyCallbackSignature`, `parseCallbackEnvelope`, 各类 `parse*CallbackPayload` | +| Push | `registerPushToken`, `sendPush` | +| Update | `checkAppUpdate`, `uploadAppVersion`, `publishAppVersion`, `unpublishAppVersion`, `grayAppVersion`, `listAppVersions`, `checkRnUpdate`, `uploadRnBundle`, `publishRnBundle`, `unpublishRnBundle`, `listRnBundles` | + +## 群管理示例 ```java -import com.xuqm.sdk.server.model.*; +import com.xuqm.im.sdk.XuqmImServerSdk.GroupView; -// 创建群组 -ImGroup group = client.createGroup(CreateGroupRequest.builder() - .name("项目讨论") - .memberIds(List.of("user_001", "user_002")) - .build()); +GroupView group = client.createGroup("项目讨论", List.of("user_001", "user_002"), "NORMAL"); -// 添加群成员 client.addGroupMember("group_xxx", "user_003"); - -// 移除群成员 client.removeGroupMember("group_xxx", "user_003"); -// 获取群列表 -List groups = client.listGroups(); - -// 获取群成员 -List members = client.listGroupMembers("group_xxx"); +List groups = client.listGroups(); ``` --- @@ -131,11 +144,11 @@ client.sendPush(SendPushRequest.builder() ## 错误处理 ```java -import com.xuqm.sdk.server.exception.XuqmApiException; +import com.xuqm.im.sdk.XuqmImServerSdk.ImSdkException; try { ImMessage msg = client.sendMessage(request); -} catch (XuqmApiException e) { +} catch (ImSdkException e) { System.err.printf("API 错误: status=%d, code=%d, message=%s%n", e.getHttpStatus(), e.getCode(), e.getMessage()); } diff --git a/docs-site/docs/server/python-sdk.md b/docs-site/docs/server/python-sdk.md index fb3cd06..7b811e5 100644 --- a/docs-site/docs/server/python-sdk.md +++ b/docs-site/docs/server/python-sdk.md @@ -1,13 +1,18 @@ # Python Server SDK -XuqmGroup 服务端 Python SDK，提供 IM 消息发送、群管理、Push 推送等能力。 +XuqmGroup 服务端 Python SDK，按照腾讯云服务端 API 的分类方式封装了： + +- IM 账号、消息、群组、好友、会话、黑名单 +- 管理端 Webhook、统计、操作日志 +- Push 注册与推送 +- Update 版本管理、RN Bundle、应用商店提审 --- ## 安装 ```bash -pip install xuqm-im-server-sdk +pip install xuqmgroup-server-sdk-python ``` --- @@ -19,7 +24,7 @@ from xuqm_im_server_sdk import XuqmImServerSdk sdk = XuqmImServerSdk( base_url="https://dev.xuqinmin.com", - app_id="your_app_id", + app_key="your_app_key", app_secret="your_app_secret", ) ``` @@ -28,6 +33,24 @@ sdk = XuqmImServerSdk( --- +## 能力分类 + +| 分类 | 主要方法 | +|------|----------| +| 登录 | `login` | +| 账号 | `import_account`, `import_accounts`, `delete_account`, `get_profile`, `update_profile`, `search_accounts`, `check_account` | +| 消息 | `send_message`, `revoke_message`, `edit_message`, `fetch_history`, `fetch_group_history`, `search_messages` | +| 会话 | `list_conversations`, `set_conversation_pinned`, `set_conversation_muted`, `mark_read`, `set_draft`, `set_conversation_hidden`, `set_conversation_group`, `delete_conversation` | +| 好友 | `list_friends`, `add_friend`, `add_friends`, `remove_friend`, `remove_friends`, `remove_all_friends`, `set_friend_group`, `list_friend_groups`, `list_friends_by_group`, `check_friends` | +| 黑名单 | `list_blacklist`, `add_blacklist`, `remove_blacklist`, `check_blacklist` | +| 群组 | `list_groups`, `list_public_groups`, `search_groups`, `get_group`, `list_group_members`, `search_group_members`, `create_group`, `update_group`, `add_group_member`, `add_group_members`, `remove_group_member`, `remove_group_members`, `set_group_role`, `transfer_group_owner`, `leave_group`, `update_group_attributes`, `remove_group_attributes`, `mute_group_member`, `dismiss_group`, `send_group_join_request`, `list_group_join_requests`, `accept_group_join_request`, `reject_group_join_request`, `accept_group_join_requests`, `reject_group_join_requests` | +| 管理端 | `query_user_state`, `kick_users`, `batch_send_message`, `admin_set_msg_read`, `import_messages`, `admin_transfer_group_owner`, `admin_update_group_attributes`, `admin_remove_group_attributes`, `admin_group_read_receipts` | +| Webhook | `list_webhooks`, `create_webhook`, `update_webhook`, `delete_webhook`, `verify_callback_signature`, `parse_callback_envelope` | +| Push | `register_push_token`, `send_push` | +| Update | `check_app_update`, `upload_app_version`, `publish_app_version`, `unpublish_app_version`, `gray_app_version`, `list_app_versions`, `check_rn_update`, `upload_rn_bundle`, `publish_rn_bundle`, `unpublish_rn_bundle`, `list_rn_bundles` | + +--- + ## 发送消息 ```python @@ -62,22 +85,15 @@ sdk.revoke_message("message_id") ## 群管理 ```python -# 创建群组 group = sdk.create_group( name="项目讨论", member_ids=["user_001", "user_002"], ) -# 添加群成员 sdk.add_group_member("group_xxx", "user_003") - -# 移除群成员 sdk.remove_group_member("group_xxx", "user_003") -# 获取群列表 groups = sdk.list_groups() - -# 获取群成员 members = sdk.list_group_members("group_xxx") ``` @@ -109,4 +125,4 @@ except XuqmAPIError as e: print(f"API 错误: status={e.status}, code={e.code}, message={e.message}") ``` -[→ Server API 文档 →](/server/api) +[→ Server API 文档](/server/api) diff --git a/docs-site/docs/server/websocket.md b/docs-site/docs/server/websocket.md index 3b3c3cb..570e910 100644 --- a/docs-site/docs/server/websocket.md +++ b/docs-site/docs/server/websocket.md @@ -93,7 +93,7 @@ SEND destination:/app/chat.send content-type:application/json -{"appId":"ak_demo_chat","messageId":"...","toId":"user_002","chatType":"SINGLE","msgType":"TEXT","content":"Hello"} +{"appKey":"ak_demo_chat","messageId":"...","toId":"user_002","chatType":"SINGLE","msgType":"TEXT","content":"Hello"} \x00 ``` @@ -104,7 +104,7 @@ SEND destination:/app/chat.revoke content-type:application/json -{"appId":"ak_demo_chat","messageId":"..."} +{"appKey":"ak_demo_chat","messageId":"..."} \x00 ``` @@ -115,7 +115,7 @@ SEND destination:/app/chat.sync content-type:application/json -{"appId":"ak_demo_chat"} +{"appKey":"ak_demo_chat"} \x00 ``` diff --git a/tenant-platform/package.json b/tenant-platform/package.json index 3f91c84..e4bb115 100644 --- a/tenant-platform/package.json +++ b/tenant-platform/package.json @@ -10,6 +10,7 @@ }, "dependencies": { "axios": "^1.7.9", + "@xuqm/vue3-sdk": "0.2.0", "element-plus": "^2.9.1", "@element-plus/icons-vue": "^2.3.1", "pinia": "^3.0.1", diff --git a/tenant-platform/src/api/app.ts b/tenant-platform/src/api/app.ts index faa4e11..eaddb47 100644 --- a/tenant-platform/src/api/app.ts +++ b/tenant-platform/src/api/app.ts @@ -61,53 +61,87 @@ export interface UpdateServiceConfig { defaultMarketUrl?: string } -export interface PushVendorConfig { +export type PushVendorKey = 'huawei' | 'xiaomi' | 'oppo' | 'vivo' | 'honor' | 'harmony' | 'apns' +export type PushImportance = 'MIN' | 'LOW' | 'DEFAULT' | 'HIGH' | 'MAX' +export type PushPriority = 'LOW' | 'DEFAULT' | 'HIGH' +export type PushInterruptionLevel = '' | 'passive' | 'active' | 'time-sensitive' | 'critical' + +export interface XiaomiPushVendorConfig { appId?: string appKey?: string appSecret?: string +} + +export interface HuaweiPushVendorConfig { + appId?: string + appSecret?: string +} + +export interface OppoPushVendorConfig { + appId?: string + appKey?: string masterSecret?: string +} + +export interface VivoPushVendorConfig { + appId?: string + appKey?: string + appSecret?: string +} + +export interface HonorPushVendorConfig { + appId?: string clientId?: string clientSecret?: string +} + +export interface HarmonyPushVendorConfig { + appId?: string + appSecret?: string +} + +export interface ApnsPushVendorConfig { teamId?: string keyId?: string bundleId?: string - keyPath?: string + privateKey?: string sandbox?: boolean - serviceAccountJson?: string +} + +export interface PushVendorsConfig { + huawei?: HuaweiPushVendorConfig + xiaomi?: XiaomiPushVendorConfig + oppo?: OppoPushVendorConfig + vivo?: VivoPushVendorConfig + honor?: HonorPushVendorConfig + harmony?: HarmonyPushVendorConfig + apns?: ApnsPushVendorConfig +} + +export interface PushProfileConfig { + profileKey: string + vendor: PushVendorKey + routeType: string + enabled: boolean channelId?: string category?: string - receiptId?: string + importance?: PushImportance + priority?: PushPriority + threadIdentifier?: string + interruptionLevel?: PushInterruptionLevel + badge?: boolean + sound?: boolean + vibration?: boolean + notifyType?: number + version?: number + remark?: string } export interface PushServiceConfig { - huawei?: PushVendorConfig - xiaomi?: PushVendorConfig - oppo?: PushVendorConfig - vivo?: PushVendorConfig - honor?: PushVendorConfig - harmony?: PushVendorConfig - apns?: PushVendorConfig - fcm?: PushVendorConfig - channels?: PushNotificationChannelConfig[] - routing?: Record -} - -export interface PushNotificationChannelConfig { - key: string - channelId: string - version: number - name: string - description?: string - importance: 'MIN' | 'LOW' | 'DEFAULT' | 'HIGH' | 'MAX' - sound: boolean - vibration: boolean - badge: boolean -} - -export interface PushNotificationRouteConfig { - channel: string - category: string - priority: 'LOW' | 'DEFAULT' | 'HIGH' + schemaVersion?: number + updatedAt?: string + vendors?: PushVendorsConfig + profiles?: PushProfileConfig[] } export const appApi = { diff --git a/tenant-platform/src/api/update.ts b/tenant-platform/src/api/update.ts index 1a3414c..717d934 100644 --- a/tenant-platform/src/api/update.ts +++ b/tenant-platform/src/api/update.ts @@ -80,7 +80,7 @@ updateClient.interceptors.response.use( ) export type StoreType = 'HUAWEI' | 'MI' | 'OPPO' | 'VIVO' | 'HONOR' | 'APP_STORE' | 'GOOGLE_PLAY' | 'HARMONY_APP' | 'REVIEW_WEBHOOK' -export type StoreReviewState = 'PENDING' | 'UNDER_REVIEW' | 'APPROVED' | 'REJECTED' +export type StoreReviewState = 'PENDING' | 'SUBMITTING' | 'UNDER_REVIEW' | 'APPROVED' | 'REJECTED' export type PublishMode = 'MANUAL' | 'NOW' | 'SCHEDULED' | 'AUTO_REVIEW' export type GrayMode = 'PERCENT' | 'MEMBERS' export type GraySelectionSource = 'LOCAL' | 'CALLBACK' diff --git a/tenant-platform/src/views/im/ImManagementView.vue b/tenant-platform/src/views/im/ImManagementView.vue index b8baf32..3f01a0d 100644 --- a/tenant-platform/src/views/im/ImManagementView.vue +++ b/tenant-platform/src/views/im/ImManagementView.vue @@ -698,7 +698,7 @@ /> POST 到你配置的回调地址，`Content-Type: application/json`。 - `X-App-Id`、`X-App-Timestamp`、`X-App-Nonce`、`X-App-Signature`。 + `X-App-Key`、`X-App-Timestamp`、`X-App-Nonce`、`X-App-Signature`。 统一 envelope：`callbackId`、`callbackType`、`callbackEvent`、`requestTime`、`payload`、`appKey`。 `HMAC-SHA256(appSecret, appKey + '\\n' + timestamp + '\\n' + nonce + '\\n' + sha256(body))`。 回调发送失败只记录日志，不会中断消息发送、撤回等主流程。 diff --git a/tenant-platform/src/views/im/ImWebhookView.vue b/tenant-platform/src/views/im/ImWebhookView.vue index aebf924..f488653 100644 --- a/tenant-platform/src/views/im/ImWebhookView.vue +++ b/tenant-platform/src/views/im/ImWebhookView.vue @@ -29,7 +29,7 @@ /> 服务端以 `POST` 方式推送到你配置的回调地址。 - `X-App-Id`、`X-App-Timestamp`、`X-App-Nonce`、`X-App-Signature`。 + `X-App-Key`、`X-App-Timestamp`、`X-App-Nonce`、`X-App-Signature`。 `HMAC-SHA256(appSecret, appKey + '\\n' + timestamp + '\\n' + nonce + '\\n' + sha256(body))`。 接收方建议按 `callbackId` 去重。 @@ -244,4 +244,3 @@ onMounted(async () => { await Promise.all([loadApp(), loadWebhooks()]) }) - diff --git a/tenant-platform/src/views/push/PushConfigView.vue b/tenant-platform/src/views/push/PushConfigView.vue index 78e2617..a7a3e40 100644 --- a/tenant-platform/src/views/push/PushConfigView.vue +++ b/tenant-platform/src/views/push/PushConfigView.vue @@ -24,131 +24,171 @@ - - - 通知通道 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 新增通道 - - 业务分类路由 - - - - - - - - - - - - - - - - - 厂商凭据 + +
{{ vendor.hint }}
- +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
刷新 @@ -161,18 +201,37 @@ diff --git a/yarn.lock b/yarn.lock index a0ca3a8..0eb3849 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1172,6 +1172,11 @@ dependencies: vue "^3.5.13" +"@xuqm/vue3-sdk@0.2.0": + version "0.2.0" + resolved "https://nexus.xuqinmin.com/repository/npm-hosted/@xuqm/vue3-sdk/-/vue3-sdk-0.2.0.tgz#f527250cb1b3b944920133d694866432709559bc" + integrity sha512-JlvaAVkxXpgawVCR1fGDVaeDJeOsk3XKoKLOFpPw3zAokkWL3cvGhXt2RWHiZ89Fwj5+VRFzSeJNx3DesmPDmw== + abbrev@^2.0.0: version "2.0.0" resolved "https://registry.npmjs.org/abbrev/-/abbrev-2.0.0.tgz"