fiora 内置命令行工具详解:8 个服务端管理脚本的用法与源码级原理

原创2026-09-28 09:53:561,952 阅读
文章标签:即时通讯后端前端移动开发跨平台Monorepo社交

fiora 内置命令行工具详解:8 个服务端管理脚本的用法与源码级原理

fiora 是一个基于 node.js、MongoDB、socket.io 与 react 构建的开源聊天应用。为了方便服务器运维与管理,fiora 在仓库中内置了一套命令行工具,覆盖"删除消息、删除用户、注册账号、诊断环境、修复数据、修改群名"等常见操作。本文以官方脚本文档为主体,结合 CLI 入口 与 脚本实现 源码,逐一讲解每个子命令的完整用法、参数要求、执行前置条件与底层实现逻辑,帮助读者安全、精准地管理 fiora 服务端数据。

注意! 这些脚本大多会直接修改数据库(删除消息、删除用户等),推荐(但非必需)在执行前提前备份数据库并停止服务端,避免产生不可恢复的数据损失。

一、工具概览:fiora 命令从何而来

命令入口与调用链

在仓库根目录的 package.json 中声明了 "bin": "index.ts",配合 yarn install 后的 yarn link,便可以在项目环境中直接执行 fiora 命令。根目录的 index.ts 使用 commander 定义子命令,实际并不直接操作数据库,而是通过 npx ts-node --transpile-only packages/bin/index.ts <command> ... 转调到 packages/bin 包。

packages/bin 包内的 index.ts 则是一个极简的动态加载器:它读取 process.argv[2] 作为脚本名,动态 import 对应的 scripts/${script}.ts 文件并调用其默认导出(run 函数)。如果脚本不存在,会打印红色提示 [xxx] 脚本不存在。

也就是说,一条 fiora getUserId alice 命令的真实执行链路为:

fiora (commander 入口)
  → npx ts-node --transpile-only packages/bin/index.ts getUserId alice
    → 动态加载 packages/bin/scripts/getUserId.ts
      → 初始化 MongoDB 连接 → 执行查询 → 打印结果

统一前置条件:连接 MongoDB

绝大多数脚本的第一步都是调用 initMongoDB()(见 packages/database/mongoose/initMongoDB.ts)。该函数使用 mongoose.connect(config.database, ...) 连接数据库,连接地址默认值为 mongodb://localhost:27017/fiora,可通过环境变量 Database 覆盖(见 packages/config/server.ts)。如果连接失败,脚本会打印错误日志并直接 process.exit(0) 退出。因此,执行任何脚本前,请确保 MongoDB 服务可用,且服务端配置指向正确的数据库实例。

二、删除类脚本:清理消息与用户数据

1. deleteMessages —— 清空全部历史消息

用法

fiora deleteMessages

执行流程(源码见 packages/bin/scripts/deleteMessages.ts)

  1. 通过 inquirer 弹出确认框,确认"Confirm to delete all messages?"后才继续;
  2. 连接 MongoDB,执行 Message.deleteMany({}) 删除全部聊天消息,再执行 History.deleteMany({}) 删除全部历史记录(History 模型用于记录每个用户在每个会话中的最后已读消息 id,见 history.ts);
  3. 再次弹出确认框,询问是否一并删除消息文件("Confirm to delete all message files(Except OSS files)?");
  4. 若确认,脚本会扫描 packages/server/public/ 目录下文件名以 ImageMessage_ 或 FileMessage_ 开头的文件并逐个删除。

说明:该命令删除的是全部历史消息(对应 Message 集合),并非按会话或按时间筛选;消息图片与文件只有在"存储在服务器本地"时才会被删除,如果配置了阿里云 OSS 等对象存储(对应 server.ts 中的 aliyunOSS 配置项),则 OSS 中的文件不会受影响。

2. deleteTodayRegisteredUsers —— 删除当天注册的所有新用户

用法

fiora deleteTodayRegisteredUsers

执行流程(源码见 packages/bin/scripts/deleteTodayRegisteredUsers.ts)

  1. 连接 MongoDB;
  2. 以服务器本地时间为准构造当天零点时间,查询 createTime >= 当天00:00:00 的所有用户,打印"今天新注册用户数";
  3. 若数量为 0 直接返回;否则弹出确认框;
  4. 确认后,对每个用户依次调用 deleteUser(userId, false)(false 表示跳过二次确认),逐个删除其相关数据。

由于复用了 deleteUser 的完整逻辑,该命令不仅删除用户记录本身,还会同步清理该用户的历史消息、群组关系与好友关系(详见下文)。

3. deleteUser —— 删除指定用户及其关联数据

用法

fiora deleteUser [userId]

参数说明:<a href="https://link.gitcode.com/i/34f9fe2abc3b580cfaba1392b0344fa7" target="_blank">userId] 既可以是 MongoDB 的 ObjectId,也可以是用户名。源码([deleteUser.ts)通过 mongoose.isValidObjectId(userIdOrName) 判断参数是 ObjectId 还是 username,再分别按 { _id: userIdOrName } 或 { username: userIdOrName } 查询。例如 fiora deleteUser 64b3f8... 或 fiora deleteUser alice 均可用。

执行流程

  1. 连接 MongoDB,按参数查找用户并打印其 _id 与 username;
  2. 弹出确认框"Confirm to delete user?",确认后执行以下五步清理:
    • 删除该用户的历史消息:先查出 from: user._id 的全部消息,再删除这些消息 id 关联的 History 记录;
    • 删除该用户发送的消息:Message.deleteMany({ from: user._id });
    • 退出已加入的群组:找出 members 包含该用户的群组,把该用户从 members 中移除;若该用户恰好是群主(creator),则同时将 creator 置为 null;
    • 删除好友关系:分别删除 from: user._id 与 to: user._id 的 Friend 记录(fiora 的好友关系是单向的,见 friend.ts,因此需要双向清理);
    • 删除用户本身:User.deleteMany({ _id: user._id })。

如果用户不存在,会打印 User [xxx] does not exist;参数缺失时打印 Wrong command, [userIdOrName] is missing.;执行中出错会被 try/catch 捕获并打印失败原因。

三、诊断类脚本:doctor 定位启动失败

doctor —— 检查服务端配置与运行状态

用法

fiora doctor

执行流程(源码见 packages/bin/scripts/doctor.ts)

脚本依次对以下五项进行检查,全部通过则环境基本就绪:

  1. Node 版本:通过 node --version 输出当前 Node 版本(仓库根目录 package.json 要求 node >= 14);
  2. MongoDB 连接:调用 initMongoDB(),成功则打印 MongoDB is OK;
  3. Redis 连接:调用 initRedis() 并等待 connect 事件,成功则打印 Redis is OK(Redis 默认连接 localhost:6379,可用环境变量 RedisHost/RedisPort 覆盖);
  4. 服务端口占用:使用 detect-port 检测 server.port(默认 9200)是否被占用,空闲打印 Port [9200] is OK,否则打印红色 Port [9200] was occupied;
  5. 首页文件检查:读取 packages/server/public/index.html,若不存在则提示 Homepage not exists;若内容仍包含"默认首页"占位文本,则提示需要先通过 yarn build:web 构建 Web 客户端;正常则打印 Homepage is OK。

适用场景:当 fiora 服务端启动失败时,doctor 可以快速定位是"依赖服务未就绪"(MongoDB/Redis)、"端口被占用"还是"前端产物未构建"。

四、数据修复类脚本:fixUsersAvatar

fixUsersAvatar —— 修复用户错误的头像路径

用法

fiora fixUsersAvatar [searchValue] [replaceValue]

参数说明(源码见 packages/bin/scripts/fixUsersAvatar.ts)

  • searchValue:需要被替换的旧路径片段,默认值为 fioraavatar;
  • replaceValue:替换后的新路径片段,默认值为 fiora/avatar。

执行流程:

  1. 连接 MongoDB;
  2. 查询所有 avatar 字段匹配正则 /fioraavatar/ 的用户(即默认只扫描包含 fioraavatar 字样的错误头像);
  3. 若存在错误头像,逐条打印 _id、username、avatar,并弹出确认框"Confirm to fix?";
  4. 确认后,对每个用户执行 avatar = avatar.replace(searchValue, replaceValue) 并保存;
  5. 若没有匹配用户,则打印 OK! All user's avatar is corrent。

文档原文强调:请根据你的实际情况修改脚本判断逻辑。默认的匹配关键字 fioraavatar 与替换值 fiora/avatar 仅是示例,当你遇到其他错误路径格式时,需要自行调整源码中的正则与默认参数。

作为对比,正常的新用户头像由 getRandomAvatar.ts 生成,格式为 ${publicPath}avatar/${number}.jpg(如 /avatar/3.jpg),其中 publicPath 默认 /,可通过环境变量 PublicPath 覆盖,头像图片共有 15 张可选(AvatarCount = 15)。

五、用户与群组管理脚本

1. getUserId —— 通过用户名查询 userId

用法

fiora getUserId [username]

源码见 packages/bin/scripts/getUserId.ts:连接 MongoDB 后按 username 精确查询用户,存在则打印 The userId of [username] is: <_id>,不存在则打印 User [username] does not exist。

该命令常用于"先查询 userId,再执行 fiora deleteUser"的管理场景,也是把 userId 配置为管理员(server.ts 中的 administrator 配置项)时的辅助工具。

2. register —— 命令行注册新用户

用法

fiora register [username] [password]

源码见 packages/bin/scripts/register.ts,完整流程与 Web 端注册接口(见 packages/server/src/routes/user.ts)保持一致的逻辑:

  1. 校验 username 与 password 均非空;
  2. 连接 MongoDB,查询用户名是否已存在,存在则打印 The username already exists;
  3. 查找默认群组(Group.findOne({ isDefault: true })),若不存在则打印 Default group does not exist;
  4. 使用 bcryptjs 生成盐(SALT_ROUNDS = 10,见 utils/const.ts)并计算密码哈希,创建用户记录,其中头像调用 getRandomAvatar() 随机分配;
  5. 若触发 Mongoose 校验错误(如用户名含不支持字符或超长),打印 Username contains unsupported characters or the length exceeds the limit(用户名命名规则 NAME_REGEXP 见 const.ts);
  6. 将新用户加入默认群组:若默认群组暂无创建者则设为新用户,并把新用户 id 追加进 members。

典型应用场景:当服务端配置了 disableRegister: true 禁用注册时(Web 端会提示"注册功能已被禁用, 请联系管理员开通账号",见 user.ts),管理员可以通过该命令行脚本绕过限制,为指定用户开通账号。

3. updateDefaultGroupName —— 修改默认群组名称

用法

fiora updateDefaultGroupName [newName]

源码见 packages/bin/scripts/updateDefaultGroupName.ts:连接 MongoDB 后查找 isDefault: true 的默认群组(不存在则打印 Default group does not exist),将其 name 字段更新为 newName 并保存,成功打印 Update default group name success!,失败则打印失败原因。

说明:默认群组是 fiora 中所有新注册用户自动加入的群组(参考上文 register 脚本及 register 接口),因此修改其名称会影响后续所有新用户默认加入的群组展示名。注意群组名同样受 NAME_REGEXP 命名规则约束(见 group.ts),不合法的新名称会导致保存失败。

六、命令速查表与安全使用建议

8 个命令一览

命令 参数 核心作用 关键副作用
fiora deleteMessages 无 删除全部历史消息 同步清理 History 记录;确认后可删除本地消息文件
fiora deleteTodayRegisteredUsers 无 删除当天新注册用户 级联清理消息、群组、好友关系
fiora deleteUser [userId] userId 或用户名 删除指定用户 级联删除其消息、历史、群组关系、好友关系
fiora doctor 无 检查 Node/MongoDB/Redis/端口/首页 只读诊断,不修改数据
fiora fixUsersAvatar [searchValue] [replaceValue] 均可选 修复错误头像路径 按正则批量改写 avatar 字段
fiora getUserId [username] 必填 查询用户 id 只读
fiora register [username] [password] 均必填 命令行注册新用户 写入新用户并加入默认群组
fiora updateDefaultGroupName [newName] 必填 修改默认群组名 改写默认群组 name 字段

使用建议

  • 执行前备份:除 doctor、getUserId 外,其余脚本都会直接改写 MongoDB 数据,且多为不可逆操作(如删除消息、删除用户)。建议执行前使用 mongodump 备份,并停止服务端进程,避免运行中的服务向数据库写入新数据。
  • 注意交互式确认:deleteMessages、deleteTodayRegisteredUsers、deleteUser、fixUsersAvatar 均内置 inquirer 确认环节,在无人值守的自动化脚本中执行时需注意交互问题。
  • 参数校验与命名规则:用户名、群名均受 NAME_REGEXP 约束,注册或改名失败时优先检查参数是否合法。
  • 与配置的联动:脚本连接 MongoDB 与 Redis 的地址均来自 packages/config/server.ts(环境变量 Database、RedisHost、RedisPort 等),请确保脚本运行环境的配置与服务端一致,避免误操作到错误的数据库。

相关资源

登录后查看全文
fiora