MoFox-Core 维护指南
欢迎来到机器人保养手册！🔧 这里会教你如何给机器人做「体检」、「升级大脑」以及「搬家」。别担心，比组装宜家家具简单多了。
第一章：备份你的重要数据
1.1 为什么要备份？
俗话说得好：「不备份的更新，都是在玩俄罗斯轮盘赌」。
备份就像给机器人买保险——万一翻车了，你还能原地复活。花两分钟备份，省下两小时哭泣。
1.2 需要备份的内容
| 文件/文件夹 | 说明 |
|---|---|
config 文件夹 | 机器人的核心配置，包括 bot_config.toml、model_config.toml 及所有插件配置 |
data 文件夹 | 机器人的数据库和记忆数据，如 maibota.db |
.env 文件 | 项目根目录下的环境变量配置 |
1.3 备份方式
方式一：手动备份（懒人版）
- 打开你的
MoFox-Core项目文件夹 - 在项目文件夹之外的安全位置（比如桌面，别放回收站里）创建备份文件夹，命名为
MoFox-Core_Backup_日期（例如MoFox-Core_Backup_20260103） - 把
config文件夹、data文件夹和.env文件复制进去，完事！
方式二：全量备份（强迫症必备）
直接把整个 MoFox-Core 文件夹复制一份。这是「核弹级」备份方案，无论发生什么，你都能满血复活。
第二章：更新机器人 🚀
等等！你备份了吗？
在执行任何更新操作之前，请务必先完成第一章的备份工作！不然出问题别怪我没提醒你
2.1 一键包用户
如果你用的是一键启动包，恭喜你，双击运行 更新脚本.bat 就完事了！下面的内容可以跳过，去喝杯茶吧
2.2 手动更新流程
前置条件：安装 Git
首先检查你有没有安装 Git，打开终端输入：
git --version如果显示版本号（比如 git version 2.43.0），说明已经装好了，跳到下一步。
如果提示「不是内部命令」或「找不到命令」，那就需要先安装 Git：
- 访问 Git 官网：https://git-scm.com/downloads
- 下载 Windows 版本的安装包
- 双击运行，一路点「Next」就行（默认选项就够用）
- 安装完成后，重新打开一个终端窗口，再试试
git --version
小贴士
安装过程中如果看到一堆看不懂的选项，别慌，全部保持默认就对了。Git 的默认设置已经很合理了。
进入项目目录
打开终端，切换到你的机器人文件夹：
cd D:\MoFox-Core开始更新（复制粘贴三连）
# 第一步：从云端拉取最新代码
git pull
# 第二步：激活虚拟环境（让 Python 知道该用哪个环境）
.venv\Scripts\activate
# 第三步：安装/更新依赖包
uv pip install -r requirements.txt龟速下载？
如果 git pull 慢得像蜗牛 ，试试科学上网或者配置国内镜像。
2.3 切换分支
MoFox-Core 有两个主要分支，就像游戏的正式服和测试服：
master：正式服，稳定可靠，适合求稳的朋友dev：测试服，功能最新最潮，但偶尔可能翻车
查看当前分支
git branch切换并更新分支
切换分支后必须拉取最新代码并更新依赖，不然你可能会遇到各种灵异事件 👻
# 想体验新功能？切换到 dev 分支
git checkout dev
git pull
uv pip install -r requirements.txt
# 玩够了想回到稳定版？切换回 master
git checkout master
git pull
uv pip install -r requirements.txt2.4 版本回退（后悔药）
更新完发现新版本有 bug？没关系，我们有「时光机」🕐
# 查看历史版本（找到你想回去的那个时间点）
git log --oneline
# 穿越回指定版本（把「版本号」换成你找到的那串字符）
git reset --hard 版本号
# 别忘了更新依赖
uv pip install -r requirements.txt警告
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 常见迁移场景
场景一：切换分支/版本后保留数据
切换分支或回退版本后，把之前备份的 config 和 data 复制回来就行。就像换了个身体，灵魂还是原来那个~
场景二：克隆一个测试用机器人
想搞一个分身用来做实验？
- 复制整个
MoFox-Core文件夹 - 改名为
MoFox-Core_Test（或者叫「small_white_mouse」也行 ） - 修改配置里的 QQ 号和他们对应的napcat端口，别让两个机器人打架
场景三：从一键包「毕业」到手动部署
想从新手村毕业了？
- 在旧一键包里找到
core/bot或bot目录，把config、data和.env备份出来 - 按照部署指南搭建新的
uv手动部署环境 - 把备份的数据覆盖进去
- 启动！你的机器人会发现自己「觉醒」了，但记忆还在
第四章：故障排除 🔧
遇到问题别慌，这里有药 💊
Q1: 更新后启动失败或报错
症状：更新完启动就炸了，一堆红字。
药方：
- 截图或复制错误日志，去 GitHub Issues 或社区群组求助（群友们很热心的！）
- 实在搞不定？直接恢复之前的全量备份，假装什么都没发生过
Q2: git pull 提示冲突 (conflict)
症状：Git 说你的文件和服务器上的「打架」了。
病因：你手贱改了项目代码文件（下次别这样 ）
药方：
# 放弃你的修改，听服务器的
git reset --hard origin/master
# 或者 git reset --hard origin/dev
# 重新拉取
git pull别担心
这只会丢弃你对代码的修改。config 里的配置不受影响，因为它们被 .gitignore 保护着呢。
Q3: 依赖安装失败
症状：uv pip install 报错或卡住不动。
药方：
- 检查网络，该挂梯子就挂梯子
- 确认虚拟环境激活了（终端前面应该有个
(.venv)） - 清理缓存重来：shell
uv cache clean uv pip install -r requirements.txt
Q4: 切换分支后功能异常
症状：切换分支后机器人行为怪异(或者直接原地爆炸没法启动)。
病因：切换分支后忘记拉取代码和更新依赖了（经典新手错误）
药方：
git pull
uv pip install -r requirements.txtQ5: 提示「git 不是内部命令」
症状：终端说找不到 git。
病因：Git 没装或者装了但没加到环境变量。
药方：回到 2.2 节 按步骤安装 Git，记得装完后重新打开终端窗口。
贡献者
minecraft1024a
ikun-11451