跳到主要内容

CountBot 更新指南：源码覆盖、GitHub 命令升级与桌面版更新

引言​

CountBot 更新时，程序文件本身并不重要，真正需要保护的是你的运行数据：

  • 数据库文件（data/countbot.db）：包含所有配置、会话历史
  • 工作空间目录（workspace/）：包含技能、记忆、临时文件

默认情况下，数据库位于运行目录下的 data/countbot.db，工作空间位于 workspace/。如果你修改过工作空间路径，更新前应备份实际生效的目录。

本文会按三种最常见的方式，详细说明 CountBot 的更新流程：

  • 下载源码后覆盖更新
  • 使用 GitHub 命令更新
  • 下载桌面版包进行更新

更新前必须先做的事​

无论采用哪一种更新方式，第一步都应该先停止当前正在运行的 CountBot。

原因很简单：

  • SQLite 在多实例并发写入时容易出现锁库
  • 正在运行时覆盖文件，可能导致更新不完整
  • 配置、日志、临时文件可能还在写入中

常见停止方式如下：

  • 源码运行：在启动终端中按 Ctrl+C
  • 桌面版：先完全退出桌面程序
  • systemd 部署：执行 sudo systemctl stop CountBot

最小备份范围​

如果你只做最小化备份，至少应保留下面两项：

  • workspace/
  • data/countbot.db

如果你希望回滚更稳妥，建议直接完整备份下面这些目录：

  • workspace/
  • data/
  • 可选：你自己额外维护的部署脚本或自定义配置文件

macOS / Linux 备份示例​

mkdir -p backup
cp -a workspace "backup/workspace_$(date +%F_%H%M%S)"
cp data/countbot.db "backup/countbot_$(date +%F_%H%M%S).db"

如果你想完整备份 data/：

mkdir -p backup
cp -a data "backup/data_$(date +%F_%H%M%S)"
cp -a workspace "backup/workspace_$(date +%F_%H%M%S)"

Windows PowerShell 备份示例​

New-Item -ItemType Directory -Force .\backup | Out-Null
Copy-Item .\workspace .\backup\workspace -Recurse -Force
Copy-Item .\data\countbot.db .\backup\countbot.db -Force

如果你的工作空间已经改到其他目录，例如 D:\CountBotWorkspace，那就应该备份那个实际目录，而不是当前目录下的 workspace/。

方式一：下载源码后覆盖更新​

这种方式适合没有用 Git 管理仓库、或者习惯直接下载 ZIP 压缩包更新的用户。

很多用户会习惯把新版本压缩包直接解压到旧目录上方原地覆盖，但这其实不是最稳妥的做法。更推荐的方式是：

  1. 先把新版本解压到一个新目录
  2. 再把旧版本中的数据目录迁移过去
  3. 验证成功后再清理旧目录

这样做的优点是回滚简单，旧版本也不会被立即破坏。

推荐流程​

  1. 停止当前 CountBot。
  2. 备份 workspace/ 和 data/countbot.db。
  3. 从 GitHub 或 Gitee 下载新的 CountBot 源码压缩包。
  4. 解压到一个新的目录，例如 CountBot_new/。
  5. 将旧目录中的 data/ 和 workspace/ 复制到新目录。
  6. 进入新目录，重新安装依赖。
  7. 启动新版本并验证功能。
  8. 验证通过后，再决定是否删除旧版本目录。

示例命令​

cd CountBot_new
pip install -r requirements.txt
python start_app.py

如果你平时是源码桌面模式运行：

python start_desktop.py

这一方式的关键注意点​

  • 不建议直接"全目录无差别覆盖"
  • data/ 和 workspace/ 不应被新版本空目录覆盖掉
  • 如果你有自己的本地修改，最好不要依赖手工覆盖来保留它们
  • 如果更新后前端打不开，可能需要重新构建前端

在需要重新构建前端时，可执行：

cd frontend
npm install
npm run build
cd ..

这一步通常只在前端构建产物缺失、损坏，或者你拿到的是纯源码目录时需要。前提是本机已安装 Node.js 18+。

方式二：使用 GitHub 命令更新​

这种方式适合你最初就是通过 git clone 拉取 CountBot 仓库的场景。相比手工覆盖，它的优势是版本来源清晰，回滚也更容易。

先检查当前仓库状态​

git status
git remote -v

如果工作区是干净的，可以直接执行：

git fetch --all --tags
git pull origin main
pip install -r requirements.txt
python start_app.py

如果你的默认分支不是 main，请替换成实际分支名。

如果本地做过修改，先暂存再更新​

git stash push -u -m "before-countbot-upgrade"
git fetch --all --tags
git pull --rebase origin main
pip install -r requirements.txt

如果你还需要恢复自己的修改：

git stash pop

如果出现冲突，就先处理冲突，再继续启动程序。

升级到指定版本标签​

如果你不想跟随主分支最新提交，而是固定升级到某个已发布版本标签，可以执行：

git fetch --tags
git checkout v0.6.0
pip install -r requirements.txt

如果你不希望进入 detached HEAD，也可以先新建分支后再切换到目标标签。

Git 更新方式的注意点​

  • 更新前依然要先备份 workspace/ 和 data/countbot.db
  • 如果本地改动较多，直接 git pull 很容易产生冲突
  • 如果依赖版本发生变化，pip install -r requirements.txt 不要跳过
  • 如果前端页面异常，可以补一次 frontend 构建

方式三：下载桌面版更新​

如果你使用的是 CountBot 桌面预编译版（如 .exe 安装包），升级逻辑和源码版没有本质区别。

::: warning 桌面预编译版限制 桌面预编译版不支持通过环境变量修改监听地址，无法开启远程访问模式。

如需远程访问，请改用源码版本。 :::

CountBot 的桌面版并不是另一套单独维护的后端，而是仍然使用同一套数据库、同一套工作空间和同一套后端逻辑，只是换成了桌面窗口来承载前端界面。因此，桌面版升级最核心的事情仍然是：

  • 保留 data/
  • 保留 workspace/
  • 替换程序本体

推荐流程​

  1. 完全退出旧版桌面程序。
  2. 备份旧版本目录里的 data/ 和 workspace/。
  3. 从 Releases 页面下载新的桌面版安装包或压缩包。
  4. 将新版本解压到新的目录。
  5. 把旧版本中的 data/ 和 workspace/ 复制到新目录。
  6. 启动新版本并检查历史数据是否仍然存在。

为什么不推荐原地覆盖​

原地覆盖的问题在于，一旦新版本有问题，旧版文件也已经被你覆盖掉了，回滚会很麻烦。

更稳妥的做法始终是：

  • 旧目录保留
  • 新目录单独部署
  • 数据目录迁移
  • 验证通过后再清理旧版本

桌面版常见问题​

  • Windows 缺少 WebView2 时，桌面窗口可能无法打开
  • Linux 可能需要安装 libwebkit2gtk
  • 如果你并不是使用打包版，而是通过 python start_desktop.py 运行，那本质上仍属于源码更新范畴

更新完成后的检查清单​

升级完成后，不要只看"程序能不能启动"，还应做一次最基本的业务验证。

建议至少检查下面这些内容：

  • 页面是否能正常打开
  • 历史会话是否仍然存在
  • 设置项是否被保留
  • 工作空间中的技能、记忆、临时文件是否仍可访问
  • 发送一条测试消息，确认模型调用正常
  • 如果你启用了渠道机器人或定时任务，最好额外做一次连通性验证

如果你做的是大版本升级，建议再查看目标版本的发布说明，确认是否有配置结构变化、渠道配置变化或前端构建要求变化。

常用入口如下：

  • GitHub Releases: https://github.com/countbot-ai/CountBot/releases
  • Gitee Releases: https://gitee.com/countbot-ai/CountBot/releases

升级失败后如何回滚​

如果升级后出现异常，不建议继续在当前目录里反复覆盖文件。更稳妥的回滚方式是：

  1. 停止当前新版本实例。
  2. 恢复备份的 data/countbot.db。
  3. 恢复备份的 workspace/。
  4. 切回旧版本目录，或切回旧 Git 提交。
  5. 重新启动并验证功能。

只要数据库和工作空间备份完整，大部分升级问题都可以在较短时间内恢复。

总结​

对于 CountBot 来说，更新的正确顺序几乎总是一样的：

  1. 先停服务
  2. 先备份 workspace/
  3. 先备份 data/countbot.db
  4. 再替换程序文件
  5. 最后启动并验证

真正容易出问题的，从来不是"代码没更新成功"，而是"升级时把自己的运行数据一起覆盖掉了"。

所以无论你使用源码版、Git 版本，还是桌面打包版，都建议把"保状态目录、换程序文件"作为固定更新原则。