跳转至

KMS 模块 API

KMS 模块是 MyApps 平台的**知识管理服务**（obpm-kms），提供企业网盘、知识文档、文件夹、文件分享/收藏/预览、权限管理、全文检索、知识标签、知识 wiki/RAG 等能力。该模块默认运行在 8084 端口，context-path 占位符为 ${myapps.context-path.kms:}（部署时替换为具体上下文路径，缺省为空）。

覆盖进度：39 / 40 控制器（已覆盖 FileController、KmsWikiConceptEntryController、KmsFileWikiController、SearchController、TeamController、FolderController、CategoryController、KmsWikiConceptCategoryController、WatermarkController、DiskController、DiskSyncController、NewDiskController、S3ApiController、S3DiskController、S3CredentialController、FileDownloadController、DocumentTrayController、ApplyAuthorizationController、AuthorizationController、PermissionController、UserSelectboxController、UserController、FileHistoryController、RoleController、MemberController、DepartmentController、ReportController、LogsController、FileTagsController、FileUploadController、UploadController、SecurityController、KeywordCooccurrenceController、KmsAiController、KmsRagController、KmsWikiRagController、KmsCoderRagController、KmsWelcomeController、WeixinServiceController）

KMS 模块共有约 40 个控制器（文件、文件夹、网盘、网盘本地同步、权限、角色、用户、搜索、分类、标签、文档托盘、水印、AI/Wiki/RAG、S3 兼容网关、团队等）。本阶段已文档化 39 个控制器（共 200 个端点：FileController 43 + KmsWikiConceptEntryController 14 + KmsFileWikiController 10 + SearchController 11 + TeamController 9 + FolderController 12 + CategoryController 8 + KmsWikiConceptCategoryController 5 + WatermarkController 4 + DiskController 6 + DiskSyncController 5 + NewDiskController 4 + S3ApiController 7 + S3DiskController 1 + S3CredentialController 3 + FileDownloadController 6 + DocumentTrayController 6 + ApplyAuthorizationController 6 + AuthorizationController 4 + PermissionController 1 + UserSelectboxController 4 + UserController 4 + FileHistoryController 4 + RoleController 1 + MemberController 1 + DepartmentController 1 + ReportController 3 + LogsController 3 + FileTagsController 3 + FileUploadController 2 + UploadController 1 + SecurityController 1 + KeywordCooccurrenceController 1 + KmsAiController 1 + KmsRagController 1 + KmsWikiRagController 1 + KmsCoderRagController 1 + KmsWelcomeController 1 + WeixinServiceController 1）；除 AbstractBaseController 抽象基类外已**全部覆盖完成**。

注：KMS 模块的 REST 基址并非统一的 /api/rest，而是按控制器分布。以 FileController 为例，类级同时声明 ${myapps.context-path.kms:}/api/kms 与 ${myapps.context-path.kms:}/kms 两个前缀，同一端点可经任一前缀访问。详见各控制器文档。

已文档化控制器

文件 中文名 基址 端点数
file.md FileController（文件域） ${myapps.context-path.kms:}/api/kms、${myapps.context-path.kms:}/kms 43
wiki-concept-entry.md KmsWikiConceptEntryController（Wiki 概念词条） ${myapps.context-path.kms:}/api/kms/wiki/concept/entries、${myapps.context-path.kms:}/kms/wiki/concept/entries 14
file-wiki.md KmsFileWikiController（文件 Wiki） ${myapps.context-path.kms:}/api/kms/wiki、${myapps.context-path.kms:}/kms/wiki 10
search.md SearchController（搜索/榜单） ${myapps.context-path.kms:}/api/kms、${myapps.context-path.kms:}/kms 11
team.md TeamController（团队域） ${myapps.context-path.kms:}/api/kms 9
folder.md FolderController（文件夹/目录域） ${myapps.context-path.kms:}/api/kms 12
category.md CategoryController（分类/标签域） ${myapps.context-path.kms:}/api/kms、${myapps.context-path.kms:}/kms 8
wiki-concept-category.md KmsWikiConceptCategoryController（Wiki 概念分类） ${myapps.context-path.kms:}/api/kms/wiki/concept/categories、${myapps.context-path.kms:}/kms/wiki/concept/categories 5
watermark.md WatermarkController（水印域） ${myapps.context-path.kms:}/api/kms 4
disk.md DiskController（网盘域） ${myapps.context-path.kms:}/api/kms 6
disk-sync.md DiskSyncController（企业网盘本地目录同步） ${myapps.context-path.kms:}/api/kms 5
new-disk.md NewDiskController（新网盘域） ${myapps.context-path.kms:}/api/kms 4
s3-api.md S3ApiController（S3 兼容数据面） ${myapps.kms.s3.path-prefix:/s3}、/kms${myapps.kms.s3.path-prefix:/s3} 7
s3-disk.md S3DiskController（S3 客户端网盘集合） ${myapps.context-path.kms:}/api/kms/s3 1
s3-credential.md S3CredentialController（S3 凭证域） ${myapps.context-path.kms:}/api/kms/s3-credentials 3
file-download.md FileDownloadController（文件下载域） ${myapps.context-path.kms:}/api 6
document-tray.md DocumentTrayController（文档托盘域） ${myapps.context-path.kms:}/api/portal/dynaform/document 6
apply-authorization.md ApplyAuthorizationController（申请授权域） ${myapps.context-path.kms:}/api/kms 6
authorization.md AuthorizationController（授权域） ${myapps.context-path.kms:}/api/kms 4
permission.md PermissionController（权限域） ${myapps.context-path.kms:}/api/kms 1
user-selectbox.md UserSelectboxController（用户选择框域） ${myapps.context-path.kms:}/api/kms/users/selectbox 4
user.md UserController（用户域） ${myapps.context-path.kms:}/api/kms 4
file-history.md FileHistoryController（文件历史域） ${myapps.context-path.kms:}/api/file-history 4
role.md RoleController（角色配置域） ${myapps.context-path.kms:}/api/core/sysconfig 1
member.md MemberController（团队成员域） ${myapps.context-path.kms:}/api/kms 1
department.md DepartmentController（部门域） ${myapps.context-path.kms:}/api/kms 1
report.md ReportController（报表域） ${myapps.context-path.kms:}/api/kms 3
logs.md LogsController（日志域） ${myapps.context-path.kms:}/api/kms 3
file-tags.md FileTagsController（文件标签域） ${myapps.context-path.kms:}/api/file-tags 3
file-upload.md FileUploadController（文件上传域） ${myapps.context-path.kms:}/api 2
upload.md UploadController（通用上传域） ${myapps.context-path.kms:}/api 1
security.md SecurityController（安全域） ${myapps.context-path.kms:}/api 1
keyword-cooccurrence.md KeywordCooccurrenceController（关键词共现图域） ${myapps.context-path.kms:}/api/keywords 1
kms-ai.md KmsAiController（KMS AI 域） ${myapps.context-path.kms:}/api/ai 1
kms-rag.md KmsRagController（KMS RAG 检索域） ${myapps.context-path.kms:}/api/kms/rag 1
kms-wiki-rag.md KmsWikiRagController（Wiki RAG 域） ${myapps.context-path.kms:}/api/kms/wiki/rag、${myapps.context-path.kms:}/kms/wiki/rag 1
kms-coder-rag.md KmsCoderRagController（Coder RAG 域） ${myapps.context-path.kms:}/api/kms/coder/rag 1
kms-welcome.md KmsWelcomeController（欢迎页/健康检查域） ${myapps.context-path.kms:} 1
weixin-service.md WeixinServiceController（微信服务域） ${myapps.context-path.kms:}/weixin/jsapi 1

待补控制器（仅余抽象基类）

KMS 模块控制器已**全部覆盖完成**（除下述抽象基类）：

  • 公共基类：AbstractBaseController（抽象基类，不单独成文；其内部类 Resource 与全局异常处理器在 file.md「公共说明」、本页「错误码补充」与「鉴权说明」段已有完整描述）

鉴权说明

（据源码）KMS 模块通过 Servlet 过滤器 KmsSecurityFilter（在 cn.myapps.kms.conf.KmsMvcConfig 中以 FilterRegistrationBean 注册，URL 模式 /*；当 context-path 为 / 时为 /kms/*）统一控制访问。鉴权流程如下：

  1. 系统间调用放行：若前置过滤器已将请求标记为 pass=true（如携带合法系统 systemToken 的 Feign 调用），直接放行。
  2. S3 兼容网关分流：匹配 KmsS3DataPlanePath 的 S3 数据面请求（使用 AWS SigV4 或 Bearer 鉴权）不经本过滤器的 Cookie/JWT 校验，直接放行。
  3. 豁免 URI（isExcludeURI）：以下路径免 accessToken 直通——
  4. 健康检查：^.*actuator/health$
  5. 登录：含 /login.、或 ^<contextPath>/runtime/login.*
  6. 管理控制台：^<contextPath>/admin、^<contextPath>/domain.*
  7. 托盘服务：含 /tray/service
  8. 鉴权时效：含 /authtime
  9. 金格 Office：含 service/OfficeServer
  10. 外部分享预览：匹配 .*outsideshare/.*/preview，或 query 参数 id+code 校验通过且 duration 未过期的分享预览
  11. 静态资源后缀：.jpg/.gif/.png/.ico/.js/.css/.map/.woff/.html/.properties
  12. /kms/uploads 路径：在豁免分支与已登录分支内均交由 FileDownloadServlet 处理文件下载
  13. 移动端 App 模式：当请求带 query 参数 mode=app（手机 App「嗨办公」场景）时，过滤器以 query 参数 userId 调用 Security.generateToken(userId) 生成 accessToken 并下发 Cookie，跳过常规 token 校验。
  14. 常规请求：调用 Security.getUserIdFromToken(request) 解析 accessToken；解析异常返回 HTTP 401（无响应体）。成功解析后，若令牌距过期不足 Security.REFRESH_TIME（1 小时）则刷新 Cookie；取不到用户 id 时返回 HTTP 401（无响应体）。

accessToken 传递方式（据 cn.myapps.common.util.Security.getUserIdFromToken），按以下顺序查找：

  1. query 参数 accessToken
  2. query 参数 access_token（移动端兼容）
  3. 请求头 accessToken
  4. Cookie accessToken
  5. 请求头 Authorization: Bearer <token>

执行用户：控制器内 getUser()（继承自 AbstractBaseController）调用 Security.getUserIdFromToken(request) 还原当前用户 id，再经 Feign（UserAPI.getUserById）装载 KmsUser。KMS 不使用 userCode 参数（与 runtime /rest/ 集成 API 不同）。

FileController 鉴权：本控制器路径 /api/kms/**、/kms/** 均不在上述豁免名单内，所有端点均需 accessToken。详见 file.md「公共说明」。

完整鉴权机制与错误码说明见：顶层 index.md。

错误码补充

KMS 模块未引入模块专属业务错误码。错误码由 AbstractBaseController 的全局异常处理器统一映射（成功 errcode=0），与顶层 index.md「错误码表」一致：

errcode HTTP 含义
0 200 成功（success("ok", data)）
400 400 请求参数有误（InvalidRequestException，如文件不存在、重复收藏、含文件夹的标签批量操作等）
403 403 权限不足（ForbiddenException，如缺少 CODE_SHARE/CODE_FAVORITE 等授权码；UnauthorizedException 也映射为 403）
404 404 资源未找到（ResourceNotFoundException）
500 500 服务器错误（其他 Exception；个别端点如 FileController.deleteFileCategory 在 catch 内显式返回 errcode=500）

注意：KMS 的 Resource 为 AbstractBaseController 内部类，其构造器对 data 执行 ESAPI.encode(data) 做 XSS 编码，故响应 data 中的 HTML 特殊字符会被转义（与顶层统一 Resource 结构一致，字段同为 errcode/errmsg/data/errors）。

覆盖说明

本阶段覆盖 obpm-kms 工作树下的 FileController（文件域，43 个端点，KMS 模块端点最多的控制器）、KmsWikiConceptEntryController（Wiki 概念词条，14 个端点）、KmsFileWikiController（文件 Wiki，10 个端点）、SearchController（搜索/榜单，11 个端点）、TeamController（团队域，9 个端点）、FolderController（文件夹/目录域，12 个端点，含企业网盘相对路径 resolve-or-create）、CategoryController（分类/标签域，8 个端点）、KmsWikiConceptCategoryController（Wiki 概念分类，5 个端点）、WatermarkController（水印域，4 个端点）、DiskController（网盘域，6 个端点）、DiskSyncController（企业网盘本地目录同步，5 个端点）、NewDiskController（新网盘域，4 个端点）、S3ApiController（S3 兼容数据面，7 个端点，path-style，SigV4 / Bearer 鉴权，XML 响应）、S3DiskController（S3 客户端网盘集合，1 个端点）、S3CredentialController（S3 凭证域，3 个端点）、FileDownloadController（文件下载域，6 个端点，含二进制流下载与外部分享校验/下载）、DocumentTrayController（文档托盘域，6 个端点，Word 字段编辑状态/水印下载与打印，多经 Feign 回调 runtime）、ApplyAuthorizationController（申请授权域，6 个端点）、AuthorizationController（授权域，4 个端点）、PermissionController（权限域，1 个端点，按位掩码返回操作权限）、UserSelectboxController（用户选择框域，4 个端点，通讯录/部门树/关键字搜索用户）、UserController（用户域，4 个端点，当前登录用户/按Id查询/角色设置/按部门+名称查询）、FileHistoryController（文件历史域，4 个端点，基于 kms_file.version 的版本列表/取版本/最大版本号/还原）、RoleController（角色配置域，1 个端点，后台管理控制台 HTML 页面，返回 ModelAndView 而非 JSON Resource）、MemberController（团队成员域，1 个端点，按团队Id查询成员）、DepartmentController（部门域，1 个端点，按当前用户域查询部门列表）、ReportController（报表域，3 个端点，1 个查询返回 JSON Resource + 2 个导出 Excel 为二进制流响应）、LogsController（日志域，3 个端点，操作日志/KM 访问日志/全用户上传数量统计）、FileTagsController（文件标签域，3 个端点，按 fileChecksum 增删查自动标签）、FileUploadController（文件上传域，2 个端点，文件上传 / 文件夹结构上传，KMS 版与 runtime 上传控制器区分）、UploadController（通用上传域，1 个端点，上传至 /uploads/avatar/）、SecurityController（安全域，1 个端点，用户注销并清除 SSO/Cookie）、KeywordCooccurrenceController（关键词共现图域，1 个端点，返回力导向图节点/边结构）、KmsAiController（KMS AI 域，1 个端点，按 fileId + 网盘向量检索相似文件）、KmsRagController（KMS RAG 检索域，1 个端点，按 message + disk_id 网盘向量库检索 top-k 片段，供 obpm-ai Feign 调用，响应非 Resource）、KmsWikiRagController（Wiki RAG 域，1 个端点，对 wiki 向量索引检索，content 截前 300 字，响应非 Resource）、KmsCoderRagController（Coder RAG 域，1 个端点，对 coder cookbook 向量索引检索，供 obpm-ai Feign 调用，响应非 Resource）、KmsWelcomeController（欢迎页/健康检查域，1 个端点，返回 {status, service} Map，响应非 Resource）、WeixinServiceController（微信服务域，1 个端点，方法级 @RequestMapping 不限 HTTP 方法，返回 {status, message, data} Map，响应非 Resource）。本批后 KMS 模块**全部覆盖完成**（除 AbstractBaseController 抽象基类不单独成文）。