创建独立用户与账号资源管理

Java MossKB 支持管理员在同一个实例内创建本地普通账号，并复用官方前端的用户管理页面。普通账号各自登录、各自拥有知识库、应用、模型与聊天记录；管理员保留全量管理权限。本页记录该能力的接口、数据结构、前后端实现与验收结果，全部内容已在当前代码中完成。

一、功能范围

能力	状态	说明
管理员创建本地账号	已完成	新增账号固定为普通用户，创建请求无法指定角色
用户分页与搜索	已完成	按用户名或邮箱模糊查询，默认按创建时间倒序
资料编辑	已完成	邮箱、电话、姓名可改，用户名创建后不变
启用 / 禁用	已完成	管理员账号不可禁用，操作会递增会话版本
重置密码	已完成	使用新的带盐口令散列，并递增会话版本
逻辑删除	已完成	保留行并置删除标记，不删除其知识库与应用
资源归属隔离	已完成	列表按归属过滤，详情、修改与嵌套资源逐级校验
公共模型可用不可改	已完成	普通用户可选用公共模型，不能修改管理员模型
分享聊天链接	已完成	按分享访问规则工作，不等同于创建独立管理账号

二、后端接口

用户管理接口集中在 /api/user_manage 下，仅向管理员开放。控制器只做参数绑定，业务规则在服务层：

package nexus.io.mosskb.controller;

import nexus.io.annotation.Get;
import nexus.io.annotation.Post;
import nexus.io.annotation.Put;
import nexus.io.annotation.Delete;
import nexus.io.mosskb.service.UserManagementService;
import nexus.io.tio.http.common.HttpRequest;
import com.alibaba.fastjson2.JSON;
import nexus.io.annotation.RequestPath;
import nexus.io.jfinal.aop.Aop;
import nexus.io.mosskb.service.KbUserService;
import nexus.io.model.result.ResultVo;

@RequestPath("/api/user_manage")
public class ApiUserManage {

  @Post("")
  public ResultVo create(HttpRequest request) {
    return Aop.get(UserManagementService.class).create(JSON.parseObject(request.getBodyString()));
  }

  @Put("/{id}")
  public ResultVo update(Long id, HttpRequest request) {
    return Aop.get(UserManagementService.class).update(id, JSON.parseObject(request.getBodyString()));
  }

  @Get("/{pageNo}/{pageSize}")
  public ResultVo page(Integer pageNo, Integer pageSize, String email_or_username) {
    return Aop.get(KbUserService.class).page(pageNo, pageSize, email_or_username);
  }

  @Put("/{id}/re_password")
  public ResultVo resetPassword(Long id, HttpRequest request) {
    return Aop.get(UserManagementService.class).resetPassword(id, JSON.parseObject(request.getBodyString()));
  }

  @Delete("/{id}")
  public ResultVo delete(Long id) {
    return Aop.get(UserManagementService.class).delete(id);
  }
}

接口	行为
GET /api/valid/user/{size}	管理员创建用户入口检查
GET /api/user_manage/{page}/{size}	用户分页，支持 email_or_username 查询
POST /api/user_manage	创建普通用户
PUT /api/user_manage/{id}	修改资料或 is_active
PUT /api/user_manage/{id}/re_password	提交 password、re_password 重置密码
DELETE /api/user_manage/{id}	逻辑删除普通用户

入口检查同样是管理员专用，它先确认当前账号处于启用且未删除状态，再比对角色：

package nexus.io.mosskb.controller;

import nexus.io.annotation.Get;
import nexus.io.annotation.RequestPath;
import nexus.io.db.activerecord.Db;
import nexus.io.model.result.ResultVo;
import nexus.io.tio.boot.http.TioRequestContext;

@RequestPath("/api/valid")
public class ApiValidController {

  /** Active-account lookup used by the "create user" entry check. */
  private static final String ACTIVE_ROLE = """
      select role
      from moss_kb_user
      where id = ?
        and deleted = 0
        and is_active = true
      """;

  @Get("/user/{size}")
  public ResultVo users(Integer size) {
    Long userId = TioRequestContext.getUserIdLong();
    String role = Db.queryStr(ACTIVE_ROLE, userId);
    if ("ADMIN".equalsIgnoreCase(role)) {
      return ResultVo.ok(true);
    }
    return ResultVo.fail("仅管理员可以创建用户");
  }
}

三、服务层实现

用户管理服务把每条 SQL 都写成常量，使用 Java 21 的文本块语法（"""）：多行语句保持数据库里能直接执行的排版，参数仍然全部走占位符，不做字符串拼接。

package nexus.io.mosskb.service;

import java.util.Date;

import com.alibaba.fastjson2.JSONObject;

import nexus.io.db.activerecord.Db;
import nexus.io.db.activerecord.Row;
import nexus.io.model.result.ResultVo;
import nexus.io.tio.utils.snowflake.SnowflakeIdUtils;

/** Administrator-managed local accounts; never accept roles or ownership from request bodies. */
public class UserManagementService {

  /** User names are 6-20 characters from a restricted set so they stay safe in URLs and exports. */
  private static final String USERNAME_PATTERN = "[A-Za-z0-9_.@-]{6,20}";

  /** Advisory lock key that serializes account creation across JVM instances. */
  private static final long CREATE_LOCK_KEY = 7335647387278176L;

  private static final String COUNT_BY_USERNAME = """
      select count(*)
      from moss_kb_user
      where username = ?
      """;

  private static final String ACCOUNT_BY_ID = """
      select id, role
      from moss_kb_user
      where id = ?
        and deleted = 0
      """;

  private static final String BUMP_TOKEN_VERSION = """
      update moss_kb_user
      set token_version = token_version + 1
      where id = ?
      """;

  private static final String RESET_PASSWORD = """
      update moss_kb_user
      set password = ?,
          token_version = token_version + 1,
          update_time = now()
      where id = ?
        and deleted = 0
      """;

  private static final String LOGICAL_DELETE = """
      update moss_kb_user
      set deleted = 1,
          is_active = false,
          token_version = token_version + 1,
          update_time = now()
      where id <> 1
        and upper(role) <> 'ADMIN'
        and id = ?
        and deleted = 0
      """;

  private static final String TAKE_CREATE_LOCK = """
      select pg_advisory_xact_lock(%d)
      """.formatted(CREATE_LOCK_KEY);

  public ResultVo create(JSONObject input) {
    String username = input.getString("username");
    String password = input.getString("password");
    if (username == null || !username.matches(USERNAME_PATTERN) || password == null || password.length() < 6
        || password.length() > 20) {
      return ResultVo.fail("用户名需为 6～20 位字母、数字或 _ . @ -，密码需为 6～20 位");
    }
    if (Db.queryLong(COUNT_BY_USERNAME, username) > 0) {
      return ResultVo.fail("用户名已存在");
    }
    Row user = Row.by("id", SnowflakeIdUtils.id()).set("username", username).set("password", UserPassword.hash(password))
        .set("role", "USER").set("is_active", true).set("source", "LOCAL").set("deleted", 0);
    for (String field : new String[] {"email", "phone", "nick_name"}) {
      String value = input.getString(field);
      if (value != null && value.length() > 254) {
        return ResultVo.fail("用户资料过长");
      }
      user.set(field, value == null ? "" : value);
    }
    // Serialize account creation across JVM instances to prevent duplicate names without changing existing records.
    boolean[] duplicate = {false};
    Db.tx(() -> {
      Db.query(TAKE_CREATE_LOCK);
      if (Db.queryLong(COUNT_BY_USERNAME, username) > 0) {
        duplicate[0] = true;
      } else {
        Db.save("moss_kb_user", user);
      }
      return true;
    });
    if (duplicate[0]) {
      return ResultVo.fail("用户名已存在");
    }
    return ResultVo.ok(JSONObject.of("id", user.getLong("id").toString(), "username", username, "role", "USER", "is_active", true));
  }
}

创建流程有三处刻意设计：角色固定写死为 USER，来源固定写死为 LOCAL，用户名与密码先做格式校验。用户名检查做两次，第二次放在事务内的咨询锁（pg_advisory_xact_lock）之后，多实例同时提交同名请求时只有一个能落库。

资料更新与启用状态分开处理：只有出现 is_active 时才校验管理员保护并递增会话版本；资料更新走 Row 参数化更新，并在数据库里刷新 update_time。

  public ResultVo update(Long id, JSONObject input) {
    Row existing = Db.findFirst(ACCOUNT_BY_ID, id);
    if (existing == null) {
      return ResultVo.fail("用户不存在");
    }
    Row update = Row.by("id", id);
    for (String field : new String[] {"email", "phone", "nick_name"}) {
      if (input.containsKey(field)) {
        String value = input.getString(field);
        if (value == null || value.length() > 254) {
          return ResultVo.fail("用户资料无效");
        }
        update.set(field, value);
      }
    }
    boolean activeChanged = input.containsKey("is_active");
    if (activeChanged) {
      if (id == 1L || "ADMIN".equalsIgnoreCase(existing.getStr("role"))) {
        return ResultVo.fail("不能禁用管理员");
      }
      update.set("is_active", input.getBooleanValue("is_active"));
    }
    update.set("update_time", new Date());
    Db.update("moss_kb_user", update);
    if (activeChanged) {
      Db.update(BUMP_TOKEN_VERSION, id);
    }
    return ResultVo.ok();
  }

重置密码要求两次输入一致，并在同一条语句里同时改散列与会话版本；删除语句本身带 id <> 1 and upper(role) <> 'ADMIN' 保护，即使调用方绕过了服务层的角色判断也删不掉管理员：

  public ResultVo resetPassword(Long id, JSONObject input) {
    String password = input.getString("password");
    if (password == null || password.length() < 6 || password.length() > 20 || !password.equals(input.getString("re_password"))) {
      return ResultVo.fail("密码需为 6～20 位，且两次输入一致");
    }
    int updated = Db.update(RESET_PASSWORD, UserPassword.hash(password), id);
    return updated == 1 ? ResultVo.ok() : ResultVo.fail("用户不存在");
  }

  public ResultVo delete(Long id) {
    int updated = Db.update(LOGICAL_DELETE, id);
    return updated == 1 ? ResultVo.ok() : ResultVo.fail("用户不存在或不能删除管理员");
  }

分页查询同样改用文本块，并把条件片段抽成常量复用到计数与列表两条语句上：

package nexus.io.mosskb.service;

import java.util.List;

import com.jfinal.kit.Kv;

import nexus.io.db.activerecord.Db;
import nexus.io.db.activerecord.Row;
import nexus.io.kit.RowUtils;
import nexus.io.mosskb.vo.ResultPage;
import nexus.io.model.result.ResultVo;

public class KbUserService {

  private static final String PAGE_CONDITION = """
      where deleted = 0
        and (username ilike ? or email ilike ?)
      """;

  private static final String COUNT_USERS = """
      select count(*)
      from moss_kb_user
      """ + PAGE_CONDITION;

  private static final String PAGE_USERS = """
      select id, username, email, phone, is_active, role, nick_name, create_time, update_time, source
      from moss_kb_user
      """ + PAGE_CONDITION + """
      order by create_time desc
      limit ? offset ?
      """;

  public ResultVo page(Integer pageNo, Integer pageSize, String search) {
    int currentPage = Math.max(1, pageNo == null ? 1 : pageNo);
    int currentSize = Math.max(1, Math.min(100, pageSize == null ? 20 : pageSize));
    String term = "%" + (search == null ? "" : search) + "%";
    long total = Db.queryLong(COUNT_USERS, term, term);
    List<Row> rows = Db.find(PAGE_USERS, term, term, currentSize, (long) (currentPage - 1) * currentSize);
    return ResultVo.ok(new ResultPage<Kv>(currentPage, currentSize, (int) total, RowUtils.toKv(rows, false)));
  }
}

分页返回的字段不含口令列；页大小被限制在 1～100，页码最小为 1，ilike 的大小写不敏感匹配把通配符全部放进参数而不是语句文本。

四、口令与会话版本

新密码使用 PBKDF2 加独立随机盐存储，格式为 pbkdf2$轮数$盐$派生值；服务会校验轮数范围，防止畸形记录变成算力炸弹。读取时兼容历史账号的旧散列，管理员重置后即改用新格式。

package nexus.io.mosskb.service;

import java.security.MessageDigest;
import java.security.SecureRandom;
import java.util.Base64;
import javax.crypto.SecretKeyFactory;
import javax.crypto.spec.PBEKeySpec;
import nexus.io.tio.utils.crypto.Md5Utils;

public final class UserPassword {
  private UserPassword() { }

  public static String hash(String password) {
    byte[] salt = new byte[16];
    new SecureRandom().nextBytes(salt);
    return "pbkdf2$210000$" + Base64.getEncoder().encodeToString(salt) + "$"
        + Base64.getEncoder().encodeToString(derive(password, salt, 210000));
  }

  public static boolean matches(String password, String stored) {
    if (password == null || stored == null) {
      return false;
    }
    try {
      if (!stored.startsWith("pbkdf2$")) {
        return MessageDigest.isEqual(Md5Utils.md5Hex(password).getBytes(java.nio.charset.StandardCharsets.UTF_8), stored.getBytes(java.nio.charset.StandardCharsets.UTF_8));
      }
      String[] parts = stored.split("\\$");
      int rounds = Integer.parseInt(parts[1]);
      if (parts.length != 4 || rounds < 10000 || rounds > 1000000) {
        return false;
      }
      return MessageDigest.isEqual(derive(password, Base64.getDecoder().decode(parts[2]), rounds), Base64.getDecoder().decode(parts[3]));
    } catch (RuntimeException e) {
      return false;
    }
  }

  private static byte[] derive(String password, byte[] salt, int rounds) {
    PBEKeySpec spec = new PBEKeySpec(password.toCharArray(), salt, rounds, 256);
    try {
      return SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256").generateSecret(spec).getEncoded();
    } catch (java.security.GeneralSecurityException e) {
      throw new IllegalStateException("Password hashing unavailable", e);
    } finally {
      spec.clearPassword();
    }
  }
}

登录时把账号当前的会话版本写进令牌载荷；之后每次请求都在拦截器里比对，账号被禁用、删除或重置密码后旧令牌立即失效：

public ResultVo login(UserLoginReqVo vo) {
  if (vo == null || vo.getUsername() == null || vo.getPassword() == null) {
    return ResultVo.fail("用户名或者密码不正确");
  }
  Row account = Db.findFirst(ACCOUNT_BY_USERNAME, vo.getUsername());
  if (account == null || !UserPassword.matches(vo.getPassword(), account.getStr("password"))) {
    return ResultVo.fail("用户名或者密码不正确");
  }
  Long userId = account.getLong("id");
  String SECRET_KEY = TioAdminEnvUtils.getAdminSecretKey();
  String token = JwtUtils.createToken(SECRET_KEY, java.util.Map.of("userId", userId, "exp", System.currentTimeMillis() / 1000 + 3600, "token_version", account.getLong("token_version")));
  TokenManager.login(userId, token);
  return ResultVo.ok("成功", token);
}

账号状态与令牌版本都在认证拦截器里检查，管理员专属前缀与资源归属也在这里统一裁决：

package nexus.io.mosskb.inteceptor;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

import nexus.io.db.activerecord.Db;
import nexus.io.db.activerecord.Row;
import nexus.io.jfinal.aop.Aop;
import nexus.io.mosskb.service.MossKbAuthService;
import nexus.io.mosskb.service.kb.ApplicationAccess;
import nexus.io.mosskb.service.kb.DatasetAccess;
import nexus.io.mosskb.service.kb.ModelAccess;
import nexus.io.tio.boot.http.TioRequestContext;
import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.http.common.HttpResponse;
import nexus.io.tio.http.common.HttpResponseStatus;
import nexus.io.tio.http.common.RequestLine;
import nexus.io.tio.http.server.intf.HttpRequestInterceptor;
import nexus.io.tio.utils.jwt.JwtUtils;

public class MossKbAuthInterceptor implements HttpRequestInterceptor {

  /** Administrator-only prefixes: account management, mail settings and team management. */
  private static final String[] ADMIN_ONLY_PREFIXES = {"/api/user_manage", "/api/email_setting", "/api/team"};

  private static final Pattern RESOURCE_PATH = Pattern.compile("^/api/(dataset|application|model)/(\\d+)(/.*)?$");

  /** Nested ids that must belong to the same dataset as the path. */
  private static final String[] NESTED_TYPES = {"document", "paragraph", "problem"};

  private static final String ACCOUNT_STATE = """
      select role, is_active, deleted, token_version
      from moss_kb_user
      where id = ?
      """;

  public HttpResponse doBeforeHandler(HttpRequest request, RequestLine requestLine, HttpResponse responseFromCache) {
    String authorization = request.getHeader("authorization");

    MossKbAuthService authService = Aop.get(MossKbAuthService.class);
    Long userId = authService.getIdByToken(authorization);

    if (userId == null) {
      HttpResponse response = TioRequestContext.getResponse();
      response.setStatus(HttpResponseStatus.C401);
      return response;
    }

    Row account = Db.findFirst(ACCOUNT_STATE, userId);
    boolean member = account != null;
    if (member && (!Boolean.TRUE.equals(account.getBoolean("is_active")) || account.getInt("deleted") != 0)) {
      return deny(HttpResponseStatus.C401);
    }
    if (member) {
      String rawToken = authorization.replaceFirst("(?i)^Bearer\\s+", "");
      Object revision = JwtUtils.getPayload(rawToken).get("token_version");
      long tokenVersion = revision == null ? 0 : Long.parseLong(revision.toString());
      if (tokenVersion != account.getLong("token_version")) {
        return deny(HttpResponseStatus.C401);
      }
    }

    String path = requestLine.getPath();
    if (requiresAdministrator(path) && (!member || !"ADMIN".equalsIgnoreCase(account.getStr("role")))) {
      return deny(HttpResponseStatus.C403);
    }
    if (!member && !isPublicPath(path)) {
      return deny(HttpResponseStatus.C403);
    }
    if (member && userId != 1L && !ownsRequestedResource(userId, path)) {
      return deny(HttpResponseStatus.C403);
    }

    TioRequestContext.setUserId(userId);
    return null;
  }
}

资源归属判断把路径拆成「类型 + 资源 ID + 后缀」，并对知识库下的文档、段落、问题再做一次归属校验，避免用别的知识库的子 ID 越过检查：

  /** Checks ownership of /api/{dataset|application|model}/{id} and of nested document, paragraph and problem ids. */
  private boolean ownsRequestedResource(Long userId, String path) {
    Matcher resource = RESOURCE_PATH.matcher(path);
    if (!resource.matches()) {
      return true;
    }
    String type = resource.group(1);
    String suffix = resource.group(3);
    Long id = Long.valueOf(resource.group(2));
    boolean page = !"model".equals(type) && suffix != null && suffix.matches("/\\d+");
    boolean chat = "application".equals(type) && suffix != null && suffix.startsWith("/chat/");
    boolean owns = page || chat || ("dataset".equals(type) ? DatasetAccess.owns(userId, id)
        : "application".equals(type) ? ApplicationAccess.owns(userId, id) : ModelAccess.owns(userId, id));
    if (!owns || !"dataset".equals(type) || suffix == null) {
      return owns;
    }
    return nestedIdsBelongToDataset(id, suffix);
  }

  private boolean nestedIdsBelongToDataset(Long datasetId, String suffix) {
    for (String child : NESTED_TYPES) {
      Matcher childId = Pattern.compile("/" + child + "/(\\d+)(?=/[a-z_]|$)").matcher(suffix);
      if (childId.find() && countChild(child, Long.valueOf(childId.group(1)), datasetId) == 0) {
        return false;
      }
    }
    return true;
  }

  private long countChild(String child, Long childId, Long datasetId) {
    String sql = switch (child) {
      case "document" -> COUNT_DOCUMENT;
      case "paragraph" -> COUNT_PARAGRAPH;
      default -> COUNT_PROBLEM;
    };
    return Db.queryLong(sql, childId, datasetId);
  }

嵌套校验的三条计数语句也用文本块书写：

  private static final String COUNT_DOCUMENT = """
      select count(*)
      from moss_kb_document
      where id = ?
        and dataset_id = ?
      """;

  private static final String COUNT_PARAGRAPH = """
      select count(*)
      from moss_kb_paragraph
      where id = ?
        and dataset_id = ?
      """;

  private static final String COUNT_PROBLEM = """
      select count(*)
      from moss_kb_problem
      where id = ?
        and dataset_id = ?
      """;

五、数据表

用户表以 moss_kb_user 为主表，账号状态、角色、来源与逻辑删除标记都在同一行：

CREATE TABLE "public"."moss_kb_user" (
  "id" BIGINT NOT NULL PRIMARY KEY,
  "email" VARCHAR,
  "phone" VARCHAR NOT NULL,
  "nick_name" VARCHAR NOT NULL,
  "username" VARCHAR NOT NULL,
  "password" VARCHAR NOT NULL,
  "role" VARCHAR NOT NULL,
  "is_active" BOOLEAN NOT NULL,
  "source" VARCHAR NOT NULL,
  "remark" VARCHAR(256),
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX "user_email_index_like" ON "public"."moss_kb_user" USING btree (
  "email" varchar_pattern_ops
);
CREATE INDEX "user_username_index_like" ON "public"."moss_kb_user" USING btree (
  "username" varchar_pattern_ops
);

初始化脚本另外为会话版本补一列，可重复执行：

ALTER TABLE moss_kb_user ADD COLUMN IF NOT EXISTS token_version BIGINT NOT NULL DEFAULT 0;

字段取值约定：role 取 ADMIN / USER，source 取 LOCAL，is_active 控制登录与在用令牌，deleted 为 1 表示逻辑删除。用户名创建后不再变更，删除后的用户名不复用（占用行仍在，唯一性检查照常命中）。

六、前端用户管理页面

前端沿用官方用户管理页面，路由挂在系统设置下，并带管理员角色约束。下面只保留与用户管理相关的分支，其余同级路由已省略：

import { hasPermission } from '@/utils/permission/index'
import Layout from '@/layout/layout-template/SystemLayout.vue'
import { Role, ComplexPermission } from '@/utils/permission/type'

const settingRouter = {
  path: '/setting',
  name: 'setting',
  meta: { icon: 'Setting', title: 'views.system.title', permission: 'SETTING:READ' },
  redirect: () => {
    if (hasPermission(new Role('ADMIN'), 'AND')) {
      return '/user'
    }
    return '/team'
  },
  component: Layout,
  children: [
    {
      path: '/user',
      name: 'user',
      meta: {
        icon: 'User',
        iconActive: 'UserFilled',
        title: 'views.user.title',
        activeMenu: '/setting',
        parentPath: '/setting',
        parentName: 'setting',
        permission: new Role('ADMIN')
      },
      component: () => import('@/views/user-manage/index.vue')
    }
  ]
}

export default settingRouter

接口封装一一对应后端路由，删除与重置密码走同一前缀：

import { Result } from '@/request/Result'
import { get, post, del, put } from '@/request/index'
import type { pageRequest } from '@/api/type/common'
import { type Ref } from 'vue'

const prefix = '/user_manage'

const getUserManage: (
  page: pageRequest,
  email_or_username: string,
  loading?: Ref<boolean>
) => Promise<Result<any>> = (page, email_or_username, loading) => {
  return get(
    `${prefix}/${page.current_page}/${page.page_size}`,
    email_or_username ? { email_or_username } : undefined,
    loading
  )
}

const delUserManage: (user_id: string, loading?: Ref<boolean>) => Promise<Result<boolean>> = (
  user_id,
  loading
) => {
  return del(`${prefix}/${user_id}`, undefined, {}, loading)
}

const postUserManage: (data: any, loading?: Ref<boolean>) => Promise<Result<any>> = (
  data,
  loading
) => {
  return post(`${prefix}`, data, undefined, loading)
}

const putUserManage: (
  user_id: string,
  data: any,
  loading?: Ref<boolean>
) => Promise<Result<any>> = (user_id, data, loading) => {
  return put(`${prefix}/${user_id}`, data, undefined, loading)
}

const putUserManagePassword: (
  user_id: string,
  data: any,
  loading?: Ref<boolean>
) => Promise<Result<any>> = (user_id, data, loading) => {
  return put(`${prefix}/${user_id}/re_password`, data, undefined, loading)
}

export default {
  getUserManage,
  delUserManage,
  postUserManage,
  putUserManage,
  putUserManagePassword
}

列表页负责分页、搜索、启停开关与三个行内操作（编辑、改密、删除）。管理员行的开关与删除按钮在界面上被禁用，与后端保护一致：

<template>
  <LayoutContainer :header="$t('views.user.title')">
    <div class="p-24">
      <div class="flex-between">
        <el-button type="primary" @click="createUser">{{ $t('views.user.createUser') }}</el-button>
        <el-input
          v-model="searchValue"
          @change="searchHandle"
          :placeholder="$t('common.search')"
          prefix-icon="Search"
          class="w-240"
          clearable
        />
      </div>

      <app-table
        class="mt-16"
        :data="tableData"
        :pagination-config="paginationConfig"
        @sizeChange="handleSizeChange"
        @changePage="getList"
        v-loading="loading"
      >
        <el-table-column prop="username" :label="$t('views.user.userForm.form.username.label')" />
        <el-table-column prop="nick_name" :label="$t('views.user.userForm.form.nick_name.label')" />
        <el-table-column
          prop="email"
          :label="$t('views.user.userForm.form.email.label')"
          show-overflow-tooltip
        />
        <el-table-column prop="phone" :label="$t('views.user.userForm.form.phone.label')" />
        <el-table-column :label="$t('common.status.label')" width="80">
          <template #default="{ row }">
            <div @click.stop>
              <el-switch
                :disabled="row.role === 'ADMIN'"
                size="small"
                v-model="row.is_active"
                @change="changeState($event, row)"
              />
            </div>
          </template>
        </el-table-column>
      </app-table>
    </div>
    <UserDialog :title="title" ref="UserDialogRef" @refresh="refresh" />
    <UserPwdDialog ref="UserPwdDialogRef" @refresh="refresh" />
  </LayoutContainer>
</template>
<script setup lang="ts">
import { ref, onMounted, reactive } from 'vue'
import UserDialog from './component/UserDialog.vue'
import UserPwdDialog from './component/UserPwdDialog.vue'
import { MsgSuccess, MsgConfirm, MsgAlert } from '@/utils/message'
import userApi from '@/api/user-manage'
import { datetimeFormat } from '@/utils/time'
import useStore from '@/stores'
import { ValidType, ValidCount } from '@/enums/common'
import { t } from '@/locales'

const { common, user } = useStore()

const UserDialogRef = ref()
const UserPwdDialogRef = ref()
const title = ref('')
const loading = ref(false)
const paginationConfig = reactive({
  current_page: 1,
  page_size: 20,
  total: 0
})
const tableData = ref<any[]>([])

const searchValue = ref('')

function searchHandle() {
  paginationConfig.total = 0
  paginationConfig.current_page = 1
  tableData.value = []
  getList()
}

function changeState(bool: Boolean, row: any) {
  const obj = {
    is_active: bool
  }
  const str = bool ? t('common.status.enableSuccess') : t('common.status.disableSuccess')
  userApi.putUserManage(row.id, obj, loading).then((res) => {
    getList()
    MsgSuccess(str)
  })
}

function createUser() {
  common.asyncGetValid(ValidType.User, ValidCount.User, loading).then(async (res: any) => {
    if (res?.data) {
      title.value = t('views.user.createUser')
      UserDialogRef.value.open()
    } else if (res?.code === 400) {
      MsgConfirm(t('common.tip'), t('views.user.tip.professionalMessage'), {
        cancelButtonText: t('common.confirm'),
        confirmButtonText: t('common.professional')
      })
        .then(() => {
          window.open('https://bytemoss.cn/contact.html', '_blank')
        })
        .catch(() => {})
    }
  })
}

function getList() {
  return userApi.getUserManage(paginationConfig, searchValue.value, loading).then((res) => {
    tableData.value = res.data.records
    paginationConfig.total = res.data.total
  })
}

function refresh() {
  getList()
}

onMounted(() => {
  getList()
})
</script>

创建入口会先调用校验接口：返回成功才打开对话框，返回失败则给出提示。校验类型与数量来自枚举：

export enum ValidType {
  Application = 'application',
  Dataset = 'dataset',
  User = 'user'
}

export enum ValidCount {
  Application = 5,
  Dataset = 50,
  User = 2
}

创建与编辑共用同一个对话框，编辑态下用户名只读，且不显示密码字段：

<template>
  <el-dialog
    :title="title"
    v-model="dialogVisible"
    :close-on-click-modal="false"
    :close-on-press-escape="false"
  >
    <el-form
      ref="userFormRef"
      :model="userForm"
      :rules="rules"
      label-position="top"
      require-asterisk-position="right"
      @submit.prevent
    >
      <el-form-item
        :prop="isEdit ? '' : 'username'"
        :label="$t('views.user.userForm.form.username.label')"
      >
        <el-input
          v-model="userForm.username"
          :placeholder="$t('views.user.userForm.form.username.placeholder')"
          maxlength="20"
          show-word-limit
          :disabled="isEdit"
        >
        </el-input>
      </el-form-item>
      <el-form-item
        :label="$t('views.user.userForm.form.password.label')"
        prop="password"
        v-if="!isEdit"
      >
        <el-input
          type="password"
          v-model="userForm.password"
          :placeholder="$t('views.user.userForm.form.password.placeholder')"
          show-password
        >
        </el-input>
      </el-form-item>
    </el-form>
  </el-dialog>
</template>
<script setup lang="ts">
import { ref, reactive, watch } from 'vue'
import type { FormInstance } from 'element-plus'
import userApi from '@/api/user-manage'
import { MsgSuccess } from '@/utils/message'
import { t } from '@/locales'
const props = defineProps({
  title: String
})

const emit = defineEmits(['refresh'])

const rules = reactive({
  username: [
    {
      required: true,
      message: t('views.user.userForm.form.username.requiredMessage'),
      trigger: 'blur'
    },
    {
      min: 6,
      max: 20,
      message: t('views.user.userForm.form.username.lengthMessage'),
      trigger: 'blur'
    }
  ],
  password: [
    {
      required: true,
      message: t('views.user.userForm.form.password.requiredMessage'),
      trigger: 'blur'
    },
    {
      min: 6,
      max: 20,
      message: t('views.user.userForm.form.password.lengthMessage'),
      trigger: 'blur'
    }
  ]
})

const submit = async (formEl: FormInstance | undefined) => {
  if (!formEl) return
  await formEl.validate((valid, fields) => {
    if (valid) {
      if (isEdit.value) {
        userApi.putUserManage(userForm.value.id, userForm.value, loading).then((res) => {
          emit('refresh')
          MsgSuccess(t('common.editSuccess'))
          dialogVisible.value = false
        })
      } else {
        userApi.postUserManage(userForm.value, loading).then((res) => {
          emit('refresh')
          MsgSuccess(t('common.createSuccess'))
          dialogVisible.value = false
        })
      }
    }
  })
}

defineExpose({ open })
</script>

改密对话框要求两次输入一致，前后端校验规则相同：

<script setup lang="ts">
import { ref, reactive, watch } from 'vue'
import type { FormInstance, FormRules } from 'element-plus'
import type { ResetPasswordRequest } from '@/api/type/user'
import userApi from '@/api/user-manage'
import { MsgSuccess } from '@/utils/message'
import { t } from '@/locales'
const emit = defineEmits(['refresh'])

const userForm = ref<any>({
  password: '',
  re_password: ''
})

const rules = reactive<FormRules<ResetPasswordRequest>>({
  password: [
    {
      required: true,
      message: t('views.user.userForm.form.new_password.requiredMessage'),
      trigger: 'blur'
    },
    {
      min: 6,
      max: 20,
      message: t('views.user.userForm.form.password.lengthMessage'),
      trigger: 'blur'
    }
  ],
  re_password: [
    {
      required: true,
      message: t('views.user.userForm.form.re_password.requiredMessage'),
      trigger: 'blur'
    },
    {
      validator: (rule, value, callback) => {
        if (userFormRef.value.password != userFormRef.value.re_password) {
          callback(new Error(t('views.user.userForm.form.re_password.validatorMessage')))
        } else {
          callback()
        }
      },
      trigger: 'blur'
    }
  ]
})

const submit = async (formEl: FormInstance | undefined) => {
  if (!formEl) return
  await formEl.validate((valid, fields) => {
    if (valid) {
      userApi.putUserManagePassword(userId.value, userForm.value, loading).then((res) => {
        emit('refresh')
        user.profile()
        MsgSuccess(t('views.user.tip.updatePwdSuccess'))
        dialogVisible.value = false
      })
    }
  })
}
</script>

七、界面操作步骤

1. 打开 http://localhost:3000/ui/，使用管理员账号登录。
2. 进入 System → User（中文界面为 系统 → 用户）。
3. 点击 Create User，填写用户名、姓名、邮箱、电话及登录密码并保存。

创建对话框的字段与约束：用户名为 6～20 位且必填，邮箱必填，登录密码为 6～20 位且必填；姓名与电话可选。

4. 为其他人员重复创建。新账号固定为普通用户，创建请求不能指定管理员角色。
5. 需要重置口令时，点击该行右侧的锁形图标，输入两次新密码并保存。改密会立即使该账号已签发的令牌失效。

6. 用户退出管理员登录后用自己的账号登录。普通账号看不到 System 菜单，也没有用户管理入口：

多人同时测试时使用不同浏览器配置文件或不同浏览器，避免共用本地登录状态。

八、独立范围

普通账号分别拥有自己的知识库、应用、私有模型及聊天记录，列表按归属筛选。通过接口直接请求其他账号的知识库或应用也会被拒绝；应用关联知识库时校验归属。嵌套文档、段落、问题 ID 及问题批量操作同时校验所属知识库。公共模型可供普通用户选择使用，但不能由普通用户修改管理员模型。主动分享的聊天链接按分享访问规则工作，不等同于创建独立管理账号。

系统管理员保留管理权限。这是同一实例内的账号与资源权限隔离；如果要求连数据库、管理员、模型密钥和运行进程都完全独立，应分别部署 Java 服务及数据库。

九、验收结果

验收使用管理员界面与两个临时账号完成，实际观测到的行为如下。

创建与落库。 通过界面创建一个普通账号后，列表立即出现该账号，用户总数为 7。数据库中的记录为：

username     | role | is_active | deleted | token_version | source | create_time
doc_demo_01  | USER | t         | 0       | 0             | LOCAL  | 2026-10-03 12:22:06+08
admin        | ADMIN| t         | 0       | 0             | LOCAL  | 2026-10-02 15:49:05+08

新账号口令为 pbkdf2$210000$... 格式，管理员的历史口令行仍保持原有散列，登录兼容未受影响。

改密与会话失效。 对该账号执行一次改密后，token_version 由 0 变为 1，口令散列前缀随之变化（每次都使用新的随机盐）。改密成功后该账号旧令牌立即失效。

角色不能提升。 以普通账号身份调用创建接口并显式传入 role=ADMIN，服务器直接拒绝。

列表隔离。 普通账号查询知识库列表与应用列表，返回均为 total: 0；管理员账号创建的知识库对该账号不可见：

GET /api/dataset/1/20      → 200 {"data":{"records":[],"total":0}}
GET /api/application/1/20  → 200 {"data":{"records":[],"total":0}}

跨账号请求被拒绝。 普通账号直接请求管理员知识库及其文档列表，返回 403：

GET /api/dataset/{管理员知识库ID}                    → 403
GET /api/dataset/{管理员知识库ID}/document/1/20       → 403
GET /api/application/{管理员应用ID}                   → 403

用户管理拒绝。 普通账号请求用户分页、以及尝试创建账号，返回 403：

GET  /api/user_manage/1/20  → 403
POST /api/user_manage       → 403

入口检查。 普通账号调用创建入口检查，返回业务失败码与提示，界面因此不会打开创建对话框：

GET /api/valid/user/100 → {"message":"仅管理员可以创建用户","data":null,"code":400}

禁用后的登录拒绝。 停用临时账号后其登录被拒绝，再次启用后恢复。管理员账号在界面上无法禁用，接口层面也会返回「不能禁用管理员」。

管理员页面验证。 用户列表展示用户名、姓名、邮箱、电话、用户类型、状态、创建时间与操作列；创建对话框与改密对话框均按预期工作。

临时账号验收后停用，正式账号由管理员按实际人员创建。

十、部署与构建

• 执行初始化脚本会应用用户会话相关的 SQL，为用户表增加 token_version 列。
• 后端构建跳过签名，例如 mvn -DskipTests -Dgpg.skip=true package；Java 版本为 21，文本块语法可直接使用。
• 前端为官方用户管理页面，无需额外定制即可对接上述接口。
• Docker 部署按用户要求暂缓，隔离 Python 接口保留；容器环境未就绪时执行会被拒绝。账号管理、知识库检索与远程模型调用不依赖 Docker。

十一、已知取舍

• 编辑用户时前端会提交整个表单对象，其中包含界面上不展示的密码字段；后端只取 email、phone、nick_name 与 is_active，该字段不会写库。后续可收紧为只提交允许变更的字段。
• 用户来源为 LOCAL 时，界面的「用户类型」列显示为系统用户文案，这是官方前端的文案映射，不影响后端归属判断。
• 记录删除采用逻辑删除：行保留、用户名不复用、其知识库与应用仍留在库中，需要清理时应由管理员另行处理。