MoFox-Core 维护指南
第一章：安全第一 —— 备份你的重要数据
1.1 为什么要备份？
在进行任何更新或迁移操作之前，备份是至关重要的一步。这就像给你的机器人买了一份保险，即使操作过程中出现意外，我们也能轻松地回到最初的状态，确保你的心血不会白费。
1.2 核心备份内容
我们需要备份以下三个核心部分，它们包含了你对机器人的所有个性化配置和历史数据：
config文件夹：这里存放着机器人的“身份证”（bot_config.toml）、“大脑”（model_config.toml）以及所有插件的功能配置。data文件夹：这里是机器人的“记忆体”，包含了数据库文件（如maibota.db）以及其他插件可能产生的数据。.env文件：这个文件位于项目根目录，包含了最基础的环境变量设置。
1.3 备份方式
手动备份 (图形化操作)
备份过程非常简单，只需复制粘贴即可。
- 定位文件: 打开你的
MoFox-Core项目文件夹。 - 创建备份文件夹: 在
MoFox-Core文件夹之外的其他任何安全位置（例如桌面），创建一个新的文件夹，并将其命名为MoFox-Core_Backup_YYYYMMDD(例如MoFox-Core_Backup_20250923)。 - 复制文件:
- 将
MoFox-Core文件夹内的config文件夹、data文件夹和.env文件，复制到你刚刚创建的备份文件夹中。
- 将
全量备份 (可选，但更安全)
除了备份核心的配置文件和数据外，我们还强烈建议你将整个 MoFox-Core 文件夹完整地复制一份，作为最全面的“镜像备份”。
- 优点: 这是最保险的方式，万一更新出现任何无法解决的严重问题，你甚至不需要进行版本回退，直接将整个备份文件夹恢复即可。
- 操作: 直接将你的
MoFox-Core文件夹复制到安全位置即可。
第二章：更新机器人与环境
警告
在执行本章节的任何操作（如拉取更新、切换分支、版本回退）之前，请务必先完成第一章的备份工作！这是保障你数据安全的最后一道防线。
2.1 更新前准备
在拉取最新代码之前，请确保完成以下准备工作：
确认 Git 已安装:
- 打开你的命令行终端（如
CMD或PowerShell），输入git --version。如果能看到版本号，说明 Git 已正确安装。如果没有，请先 下载并安装 Git。
- 打开你的命令行终端（如
进入项目目录:
- 你必须在
MoFox-Core的项目根目录中执行更新命令。请使用cd命令切换到你的机器人文件夹。 - 例如：
cd D:\MoFox-Core
- 你必须在
**💡 “一键包”用户请注意**:
如果你使用的是整合好的一键启动包，通常不需要手动执行本章的 git 和 uv 命令。你只需直接运行项目内提供的 更新脚本.bat 或类似名称的批处理文件，它会自动帮你完成所有更新步骤。
2.2 拉取最新代码与更新依赖
这是一个标准的更新流程，分为“拉代码”和“装依赖”两步。
第一步：拉取最新代码
在命令行终端中，执行以下命令从 GitHub 上拉取最新的代码：
git pull🌐 网络小贴士: 如果你发现
git pull下载速度极慢或连接失败，可以尝试为 Git 设置国内镜像。
第二步：更新项目依赖
代码更新后，项目所需的程序库（依赖）可能也发生了变化。因此，拉取代码后必须立即更新依赖。
- 激活虚拟环境 (如果尚未激活):shell
.venv\Scripts\activate - 安装/更新依赖:shell
uv pip install -r requirements.txt
2.3 切换分支
MoFox-Core 通常会有不同的开发分支，例如 master (主分支，相对稳定) 和 dev (开发分支，功能最新)。你可以根据自己的需求选择要切换的分支。
查看当前分支:
- 输入以下命令，查看你当前所在的分支。星号
*所在的位置就是当前分支。shellgit branch
- 输入以下命令，查看你当前所在的分支。星号
切换到目标分支:
- 如果你想切换到
dev分支以体验最新功能，请执行：shellgit checkout dev - 如果你想切换回稳定的主分支，请执行：shell
git checkout master
- 如果你想切换到
⚠️ 重要提示: 切换分支后，项目依赖很可能已经发生变化。请务必重新执行 2.2 节中的第二步：更新项目依赖，以确保环境与当前代码分支保持同步。
2.4 版本回退
如果觉得新版不稳定或不喜欢，最简单的解决方法是回退到上一个正常的版本。
查找历史版本号
- 使用
git log命令查看最近的提交记录，找到你想要回退到的版本的 commit hash (版本号)。
- 使用
回退到指定版本
- 警告：这个操作会丢弃你本地的所有未提交的修改，请谨慎操作！
- 执行
git reset --hard 你要回退到的版本号。 - 回退后，同样建议你重新更新一次依赖，以匹配旧版代码的需求。
2.5 启动与验证
所有步骤完成后，像往常一样启动机器人 (uv run python bot.py)，观察日志，确保一切正常。
第三章：数据迁移 —— 保留你的核心数据
3.1 迁移的核心思想
请记住一个核心思想：“程序”和“数据”是分离的。无论你的机器人程序如何更新、切换，甚至更换部署方式，你的核心数据（config、data、.env）都是可以被“继承”的。
3.2 迁移操作指南
迁移的基本步骤永远是三步走：
- 备份旧数据：在源机器人文件夹中，将
config、data和.env文件夹/文件备份出来。 - 部署新程序：获取一个新的、干净的机器人程序（无论是通过
git clone、下载一键包，还是解压zip）。 - 恢复旧数据：将备份好的核心数据文件，覆盖到新程序对应的位置。
3.3 具体应用场景
场景一：版本升级/降级后保留数据
当你在 master 和 dev 分支之间切换，或者使用 git reset 回退到旧版本后，程序文件发生了变化。此时，只需将你最早备份好的 config 和 data 等文件复制回项目目录，覆盖掉新版本的文件，即可让你的配置和数据在新的程序上继续生效。
场景二：创建“复制品”机器人（例如，用于测试）
如果你想创建一个配置和数据与现有机器人完全一样的“克隆体”用于测试：
- 完整复制一份
MoFox-Core项目文件夹。 - 将复制出来的文件夹改个名字，例如
MoFox-Core_Test。 - （可选）根据测试需求，修改
MoFox-Core_Test内的配置文件（例如更换QQ号或端口），避免与正式机器人冲突。 这样你就拥有了一个与原版数据完全一致的测试机器人。
场景三：从“一键包”迁移到手动部署 (或其他一键包)
当你决定不再使用某个一键包，而是想换成官方推荐的 uv 手动部署时，这就是一次“搬家”：
- 从你旧的“一键包”文件夹中，找到
core/bot或者bot目录并备份config和data文件夹,和.env文件。 - 按照部署指南，在一个全新的位置搭建好
uv手动部署环境。 - 将备份好的
config和data文件夹，覆盖到新的手动部署项目根目录中。 - 启动新的机器人，你会发现所有的配置和记忆都回来了！
第四章：故障排除
Q1: 更新后启动失败，或者出现奇怪的错误？
这通常是更新过程中出现了未预料到的问题。别担心，我们有万能的群友们！ 1. 你可以带着启动失败时的错误日志，前往项目的 GitHub Issues 或社区寻求帮助。 2. 如果你在社区中找不到解决方案，可以考虑恢复到之前的备份(如果你之前备份了整个主程序的话)Q2: `git pull` 时提示有冲突 (conflict)？
这通常意味着你不小心修改了项目本身的某些文件。对于大多数用户来说，最简单的解决方法是： 1. **放弃本地修改**: * 执行 `git reset --hard origin/master` (或 `origin/dev`)，放弃你本地的修改，并强制与服务器同步。 > **⚠️ 警告**: 这个命令会**丢弃**你对项目代码的所有本地修改。通常情况下，用户的个性化内容都保存在我们已经备份的 `config` 等文件夹中，所以这个操作是安全的。 2. **重新拉取**: * 放弃修改后，再重新执行 `git pull` 命令。贡献者
minecraft1024a
ikun-11451