fiora 内置命令行工具详解:8 个服务端管理脚本的用法与源码级原理
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)
- 通过
inquirer弹出确认框,确认"Confirm to delete all messages?"后才继续; - 连接 MongoDB,执行
Message.deleteMany({})删除全部聊天消息,再执行History.deleteMany({})删除全部历史记录(History模型用于记录每个用户在每个会话中的最后已读消息 id,见 history.ts); - 再次弹出确认框,询问是否一并删除消息文件("Confirm to delete all message files(Except OSS files)?");
- 若确认,脚本会扫描
packages/server/public/目录下文件名以ImageMessage_或FileMessage_开头的文件并逐个删除。
说明:该命令删除的是全部历史消息(对应 Message 集合),并非按会话或按时间筛选;消息图片与文件只有在"存储在服务器本地"时才会被删除,如果配置了阿里云 OSS 等对象存储(对应 server.ts 中的 aliyunOSS 配置项),则 OSS 中的文件不会受影响。
2. deleteTodayRegisteredUsers —— 删除当天注册的所有新用户
用法
fiora deleteTodayRegisteredUsers
执行流程(源码见 packages/bin/scripts/deleteTodayRegisteredUsers.ts)
- 连接 MongoDB;
- 以服务器本地时间为准构造当天零点时间,查询
createTime >= 当天00:00:00的所有用户,打印"今天新注册用户数"; - 若数量为 0 直接返回;否则弹出确认框;
- 确认后,对每个用户依次调用
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 均可用。
执行流程
- 连接 MongoDB,按参数查找用户并打印其
_id与username; - 弹出确认框"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)
脚本依次对以下五项进行检查,全部通过则环境基本就绪:
- Node 版本:通过
node --version输出当前 Node 版本(仓库根目录 package.json 要求node >= 14); - MongoDB 连接:调用
initMongoDB(),成功则打印MongoDB is OK; - Redis 连接:调用
initRedis()并等待connect事件,成功则打印Redis is OK(Redis 默认连接localhost:6379,可用环境变量RedisHost/RedisPort覆盖); - 服务端口占用:使用
detect-port检测server.port(默认 9200)是否被占用,空闲打印Port [9200] is OK,否则打印红色Port [9200] was occupied; - 首页文件检查:读取
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。
执行流程:
- 连接 MongoDB;
- 查询所有
avatar字段匹配正则/fioraavatar/的用户(即默认只扫描包含fioraavatar字样的错误头像); - 若存在错误头像,逐条打印
_id、username、avatar,并弹出确认框"Confirm to fix?"; - 确认后,对每个用户执行
avatar = avatar.replace(searchValue, replaceValue)并保存; - 若没有匹配用户,则打印
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)保持一致的逻辑:
- 校验
username与password均非空; - 连接 MongoDB,查询用户名是否已存在,存在则打印
The username already exists; - 查找默认群组(
Group.findOne({ isDefault: true })),若不存在则打印Default group does not exist; - 使用
bcryptjs生成盐(SALT_ROUNDS = 10,见 utils/const.ts)并计算密码哈希,创建用户记录,其中头像调用getRandomAvatar()随机分配; - 若触发 Mongoose 校验错误(如用户名含不支持字符或超长),打印
Username contains unsupported characters or the length exceeds the limit(用户名命名规则NAME_REGEXP见 const.ts); - 将新用户加入默认群组:若默认群组暂无创建者则设为新用户,并把新用户 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等),请确保脚本运行环境的配置与服务端一致,避免误操作到错误的数据库。
相关资源
- CLI 入口实现:index.ts
- 脚本动态加载器:packages/bin/index.ts
- 全部脚本源码:packages/bin/scripts
- 数据模型:用户 user.ts、群组 group.ts、消息 message.ts、好友 friend.ts、历史记录 history.ts
- 服务端配置:packages/config/server.ts
- 入门指南:Getting-Start.md