xuqinmin12/XuqmGroup-Server

派生 0

XuqmGroup 8fe4ae99cc feat: finalize backend deployment and api docs

2026-04-24 10:42:11 +08:00

12 KiB

原始文件 Blame 文件历史

XuqmGroup-Server 后端文档

当前推荐阅读入口：/docs/server/README.md
仓库内联调文档：docs/API_ACCESS.md
该文档保留为仓库内说明，线上地址、初始化账号与最新联调接口请以最新文档为准。

Spring Boot 3.4.4 · Java 21 · Maven 多模块

模块结构

XuqmGroup-Server/
├── pom.xml                  # 父 POM，统一依赖版本
├── common/                  # 公共库（ApiResponse、JWT、异常处理）
├── tenant-service/          # 租户服务      :8081
├── im-service/              # IM 服务       :8082
├── push-service/            # 推送服务      :8083
└── update-service/          # 版本管理服务  :8084

技术栈

组件	版本
Spring Boot	3.4.4
Java	21
Spring Security 6	JWT 无状态认证
Spring Data JPA	Hibernate 6，ddl-auto: update
MySQL	8.x
Redis	7.x（验证码、子账号会话）
JJWT	0.12.6，HMAC-SHA256
Spring Mail	邮件验证码
Spring WebSocket + STOMP	IM 实时通信

快速启动

# 前置：MySQL 8 + Redis 7 本地运行
cd XuqmGroup-Server

# 启动所有服务（各模块独立启动）
cd tenant-service && mvn spring-boot:run &
cd im-service     && mvn spring-boot:run &
cd push-service   && mvn spring-boot:run &
cd update-service && mvn spring-boot:run &

首次启动会自动建表（ddl-auto: update）。
运营平台默认管理员：admin / Admin@123456（可通过 ops.admin.* 配置覆盖）。

tenant-service（租户服务）`:8081`

数据库表

表名	说明
`t_tenant`	租户主账号 & 子账号
`t_app`	应用
`t_feature_service`	功能服务（IM/推送/版本管理）
`t_email_verification`	邮箱验证码
`t_ops_admin`	运营平台管理员

接口列表

认证（无需 Token）

方法	路径	说明
GET	`/api/auth/captcha`	获取图形验证码
POST	`/api/auth/send-email-code?email=&purpose=`	发送邮箱验证码（purpose: REGISTER / FORGOT_PASSWORD / SUB_ACCOUNT）
POST	`/api/auth/register`	注册主账号
POST	`/api/auth/login`	登录，返回 JWT
POST	`/api/auth/forgot-password?email=`	发送重置密码邮件
POST	`/api/auth/reset-password?email=&code=&newPassword=`	重置密码

注册请求体

{
  "username": "demo",
  "password": "Demo@123456",
  "email": "demo@example.com",
  "nickname": "Demo",
  "emailCode": "AB3K"
}

登录请求体

{
  "account": "demo",
  "password": "Demo@123456",
  "captchaKey": "uuid-from-captcha-api",
  "captchaCode": "XK2P"
}

登录响应

{
  "code": 200, "status": "0",
  "data": { "token": "eyJ..." },
  "message": "success"
}

应用管理（需 Token）

方法	路径	说明
GET	`/api/apps`	查询当前租户的应用列表
GET	`/api/apps/{id}`	查询应用详情
POST	`/api/apps`	创建应用
PUT	`/api/apps/{id}`	更新应用信息
DELETE	`/api/apps/{id}`	删除应用

创建应用请求体

{
  "name": "我的App",
  "packageName": "com.example.myapp",
  "description": "描述",
  "iconUrl": "https://cdn.example.com/icon.png"
}

应用对象（响应）

{
  "id": "uuid",
  "tenantId": "uuid",
  "name": "我的App",
  "packageName": "com.example.myapp",
  "appKey": "ak_xxxxxxxx",
  "appSecret": "as_xxxxxxxx",
  "createdAt": "2026-04-21T00:00:00"
}

功能服务（需 Token）

方法	路径	说明
GET	`/api/apps/{appId}/services`	获取应用下所有功能服务
POST	`/api/apps/{appId}/services/toggle?platform=&serviceType=&enable=`	开启/关闭功能服务
POST	`/api/apps/{appId}/services/{id}/regenerate-key`	重新生成 secretKey

platform 枚举：ANDROID / IOS / HARMONY
serviceType 枚举：IM / PUSH / UPDATE

子账号（需 Token）

方法	路径	说明
GET	`/api/sub-accounts`	查询子账号列表
POST	`/api/sub-accounts/send-verify-code?email=`	发送邮箱验证码（24h 内有效一次）
POST	`/api/sub-accounts/verify-email?email=&code=`	验证邮箱（通过后 24h 内可创建）
POST	`/api/sub-accounts`	创建子账号（需先验证邮箱）
DELETE	`/api/sub-accounts/{id}`	禁用子账号
GET	`/api/sub-accounts/generate-password`	生成随机密码

创建子账号请求体

{
  "username": "sub_user",
  "password": "Sub@123456",
  "email": "sub@example.com",
  "nickname": "子账号"
}

运营平台（需 OPS Token）

方法	路径	说明
POST	`/api/auth/ops/login`	运营平台登录
GET	`/api/ops/tenants?keyword=&page=&size=`	分页查询租户
POST	`/api/ops/tenants/{id}/toggle-status`	启用/禁用租户
GET	`/api/ops/statistics`	获取统计数据

运营登录请求体

{ "username": "admin", "password": "Admin@123456" }

统计响应

{
  "data": {
    "totalTenants": 128,
    "todayNew": 5,
    "activeApps": 42,
    "onlineUsers": 0
  }
}

im-service（IM 服务）`:8082`

数据库表

表名	说明
`im_account`	IM 用户账号（仅存 userId，不含昵称/头像）
`im_group`	群组（memberIds、adminIds 为逗号分隔字符串）
`im_message`	消息记录
`im_keyword_filter`	关键词过滤规则
`im_webhook_config`	Webhook 配置

IM 账号登录

POST /api/im/auth/login
  ?appId=ak_xxx
  &userId=user_001
  &nickname=张三      (可选，仅首次注册时存入外部系统)
  &avatar=https://...  (可选)

响应：{ "data": { "token": "eyJ..." } }

HTTP 消息接口

方法	路径	说明
POST	`/api/im/messages/send?appId=`	发送消息
POST	`/api/im/messages/{id}/revoke?appId=`	撤回消息
GET	`/api/im/messages/history/{toId}?appId=&page=&size=`	查询历史消息

发送消息请求体

{
  "toId": "user_002",
  "chatType": "SINGLE",
  "msgType": "TEXT",
  "content": "Hello!",
  "mentionedUserIds": ""
}

消息类型（MsgType）

值	说明
TEXT	文本（支持表情 Unicode / 自定义表情 ID）
IMAGE	图片（content 为 URL）
VIDEO	视频
AUDIO	语音
FILE	文件
CUSTOM	自定义（content 为 JSON 字符串）
LOCATION	位置（content 为 `{"lat":x,"lng":y,"address":"..."}`)
NOTIFY	系统通知
RICH_TEXT	图文混排
CALL_AUDIO	音频通话信令
CALL_VIDEO	视频通话信令
FORWARD	转发（content 为原消息 JSON）
REVOKED	已撤回（系统占位，不可主动发送）

WebSocket 实时通信

连接

ws://localhost:8082/ws/im?token=<im_jwt>

支持 STOMP 协议（可直接使用原生 WebSocket 发 JSON frame）。

发送消息（客户端 → 服务端）

{
  "destination": "/app/chat.send",
  "payload": {
    "appId": "ak_xxx",
    "toId": "user_002",
    "chatType": "SINGLE",
    "msgType": "TEXT",
    "content": "Hello!"
  }
}

接收消息（服务端 → 客户端）

单聊推送至：/user/{userId}/queue/messages
群聊推送至：/topic/group/{groupId}

Frame 格式：

{
  "type": "MESSAGE",
  "payload": {
    "id": "uuid",
    "fromId": "user_001",
    "toId": "user_002",
    "chatType": "SINGLE",
    "msgType": "TEXT",
    "content": "Hello!",
    "revoked": false,
    "createdAt": "2026-04-21T10:00:00"
  }
}

撤回消息（客户端 → 服务端）

{
  "destination": "/app/chat.revoke",
  "payload": { "appId": "ak_xxx", "messageId": "msg-uuid" }
}

撤回推送（服务端 → 客户端）

{
  "type": "REVOKE",
  "payload": { "msgId": "msg-uuid", "operatorId": "user_001" }
}

关键词过滤

在 im_keyword_filter 表中配置，支持 REPLACE（替换为 *）和 BLOCK（拒绝发送）两种动作，pattern 为正则表达式。

Webhook

在 im_webhook_config 表中为 App 配置 URL，消息发送后异步 HTTP POST 通知，超时 3000ms，格式：

{
  "event": "message",
  "appId": "ak_xxx",
  "message": { ...消息对象... }
}

push-service（推送服务）`:8083`

数据库表

表名	说明
`push_device_token`	设备推送 token（appId + userId + vendor 唯一）

支持厂商

HUAWEI / XIAOMI / OPPO / VIVO / HONOR / APNS（iOS）/ FCM

接口

方法	路径	说明
POST	`/api/push/register`	注册设备 token
POST	`/api/push/send`	向指定用户推送通知

注册 token

POST /api/push/register
  ?appId=ak_xxx
  &userId=user_001
  &vendor=HUAWEI
  &token=device_push_token

发送推送

POST /api/push/send
  ?appId=ak_xxx
  &userId=user_001
  &title=新消息
  &body=张三: Hello!
  &payload={"type":"IM","msgId":"uuid"}

环境变量配置

push:
  huawei:
    app-id: ${HUAWEI_APP_ID}
    app-secret: ${HUAWEI_APP_SECRET}
  xiaomi:
    app-secret: ${XIAOMI_APP_SECRET}
  apns:
    key-id: ${APNS_KEY_ID}
    team-id: ${APNS_TEAM_ID}
    key-path: ${APNS_KEY_PATH}      # .p8 文件路径
    bundle-id: ${APNS_BUNDLE_ID}
    production: false               # true = 生产环境

update-service（版本管理服务）`:8084`

数据库表

表名	说明
`app_version`	原生 App 版本（Android APK / iOS 跳转链接）
`rn_bundle`	RN Bundle 版本

App 版本管理

方法	路径	说明
GET	`/api/v1/updates/app/check`	检查更新
POST	`/api/v1/updates/app/upload`	上传版本（APK 文件 multipart）
POST	`/api/v1/updates/app/{id}/publish`	发布版本
GET	`/api/v1/updates/app/list`	版本列表

检查更新

GET /api/v1/updates/app/check
  ?appId=ak_xxx
  &platform=ANDROID
  &currentVersionCode=10

响应（有更新）：

{
  "data": {
    "needsUpdate": true,
    "versionName": "1.1.0",
    "versionCode": 11,
    "downloadUrl": "http://update.xuqm.com/files/apk/xxx.apk",
    "changeLog": "修复若干问题",
    "forceUpdate": false,
    "appStoreUrl": "",
    "marketUrl": ""
  }
}

platform 枚举：ANDROID / IOS / HARMONY

上传 APK（multipart/form-data）

POST /api/v1/updates/app/upload
  appId=ak_xxx
  platform=ANDROID
  versionName=1.1.0
  versionCode=11
  changeLog=更新内容
  forceUpdate=false
  apkFile=<binary>

RN Bundle 管理

方法	路径	说明
GET	`/api/v1/rn/update/check`	检查 RN Bundle 更新
POST	`/api/v1/rn/upload`	上传 Bundle 文件
POST	`/api/v1/rn/{id}/publish`	发布 Bundle

检查 RN 更新

GET /api/v1/rn/update/check
  ?appId=ak_xxx
  &moduleId=main
  &platform=android
  &currentVersion=1.0.0

响应（有更新）：

{
  "data": {
    "needsUpdate": true,
    "latestVersion": "1.1.0",
    "downloadUrl": "http://...",
    "md5": "abc123...",
    "minCommonVersion": "1.0.0",
    "note": "热更新说明"
  }
}

上传 Bundle（multipart/form-data）

POST /api/v1/rn/upload
  appId=ak_xxx
  moduleId=main
  platform=ANDROID
  version=1.1.0
  minCommonVersion=1.0.0
  note=修复闪退
  bundle=<binary .bundle 文件>

服务端自动计算 MD5，存储至 {upload-dir}/rn/{appId}/{platform}/{moduleId}/。

环境变量配置

update:
  upload-dir: ${UPDATE_UPLOAD_DIR:/tmp/xuqm-update}
  base-url: ${UPDATE_BASE_URL:http://localhost:8084}

12 KiB 原始文件 Blame 文件历史 Unescape Escape

XuqmGroup-Server 后端文档

模块结构

技术栈

快速启动

tenant-service（租户服务）:8081

数据库表

接口列表

认证（无需 Token）

应用管理（需 Token）

功能服务（需 Token）

子账号（需 Token）

运营平台（需 OPS Token）

im-service（IM 服务）:8082

数据库表

IM 账号登录

HTTP 消息接口

WebSocket 实时通信

关键词过滤

Webhook

push-service（推送服务）:8083

数据库表

支持厂商

接口

环境变量配置

update-service（版本管理服务）:8084

数据库表

App 版本管理

RN Bundle 管理

环境变量配置

12 KiB

原始文件 Blame 文件历史

tenant-service（租户服务）`:8081`

im-service（IM 服务）`:8082`

push-service（推送服务）`:8083`

update-service（版本管理服务）`:8084`