For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/guides/upgrade.md.
  • 简体中文
  • 如何升级 Octop 版本

    升级替换的是 Octop 程序。账号、专家、对话与记忆、技能、通道和模型配置仍留在工作目录。默认目录是 ~/.octop,也可以是 OCTOP_HOME 指向的目录。

    升级前先做一份备份。新版本在重启后生效。重启会暂时中断正在进行的对话。

    页面和 octop update 只安装比当前更新的版本。

    确认当前版本

    打开 管理 → 应用设置 → 应用更新,查看 当前版本。

    也可以在运行 Octop 的机器上执行:

    octop version

    Docker 部署在容器里查看:

    docker exec octop octop version

    在页面中升级

    应用更新 面向具备更新权限的管理员。打开 管理 → 应用设置,选择 应用更新。

    检查更新

    默认打开 只更新稳定版。自动检查只提示稳定版。要安装 alpha、beta、rc 或 dev,先关闭这个开关,再点击 检查更新。

    安装新版本

    出现 发现新版本 后,点击 立即升级。目标是测试版时,页面会再请你确认一次。安装过程会显示下载和安装进度,右侧也可以看到 更新说明。

    重启

    升级完成后重启 Octop。以系统服务运行时,点击 重启服务。大约 1–2 分钟后页面会刷新。以前台 octop run 启动时,停掉旧进程后再执行 octop run,或执行 octop service restart。桌面版会在升级成功后自动重启。

    说明

    从 Git 以可编辑方式安装时,页面会提示改用 git pull。请按下文「升级源码安装」更新。

    版本信息有时来自镜像站,会比 PyPI 官方源略晚。连不上更新服务器时,检查网络后再点 检查更新,或执行 octop update --verbose。

    腾讯云轻量应用服务器和 CVM 上的 Octop 使用同一套页面。你也可以登录实例后执行下面的命令。

    用命令行升级

    安装脚本或托管虚拟环境已经把 octop 放进 PATH 时,在终端执行:

    检查,不安装
    安装稳定版
    跳过确认
    包含测试版
    检查,不安装
    octop update --check

    完整选项见 服务器命令:octop update。

    重新运行安装脚本

    用官方安装脚本安装的实例,再执行一次同一条命令即可原地升级。脚本会复用 ~/.octop 里的环境与数据。

    macOS / Linux
    Windows (PowerShell)
    Windows (cmd)
    macOS / Linux
    curl -fsSL https://download.octop.cloud/octop/scripts/install.sh | bash

    升级 pip 安装

    Octop 装在你自己的 Python 环境里时:

    pip install -U octop

    装过浏览器自动化等可选依赖时,带上同样的 extra,例如 pip install -U "octop[browser]"。

    升级 Docker

    镜像里已经带好 Octop。拉取新镜像并重建容器,继续挂载原来的数据卷。:latest 是精简镜像。容器需要虚拟桌面、OCR 或本地向量时,拉取 :full 或 :<version>-full。启动参数见 Docker 部署。

    如果这台机器还留着分段历史归档(history_v2.sqlite),升级前先停掉旧服务。启动时 Octop 会把这些消息迁回原有历史表,并把归档文件改名为带 .migrated-<timestamp> 后缀的文件。OCTOP_HISTORY_V2_ENABLED 会被忽略。

    docker run
    Docker Compose

    下面以国内镜像为例。当初用的是 GitHub 源时,把镜像名换成 ghcr.io/tencentcloud/octop:latest。-v 必须和现有容器一致。下面的命名卷是 octop-data。当时挂的是宿主机目录时,继续用那个目录。

    docker pull ghcr.nju.edu.cn/tencentcloud/octop:latest
    docker stop octop
    docker rm octop
    docker run -d \
      --name octop \
      -p 8088:8088 \
      -v octop-data:/data/.octop \
      -e HOME=/data \
      ghcr.nju.edu.cn/tencentcloud/octop:latest
    注意

    docker rm 只删除容器。数据在命名卷或宿主机目录里。升级时保留该卷和目录,不要执行 docker volume rm。

    在飞牛OS 上升级

    到 GitHub Releases 下载新版本 .fpk,在应用中心再安装一次。数据目录和配置会保留。Docker 版与本地版的包名、端口见 飞牛OS。

    本地版也可以在页面里点击 立即升级,或在 NAS 上执行 octop update。命令不在 PATH 中时,使用 /usr/local/bin/octop 或 /var/apps/octop-native/bin/octop-cli。升级写入应用中心托管的安装目录。完成后在应用中心重启 Octop。

    升级源码安装

    可编辑安装请在仓库目录里更新。拉取代码、构建页面后再安装到当前环境:

    git pull
    make build-frontend
    pip install -e .

    也可以在 dashboard 目录执行 npm ci && npm run build,效果与 make build-frontend 相同。

    重启并确认

    包更新完成后,重启进程,新版本才会加载。

    系统服务
    前台进程
    系统服务
    octop service restart

    然后执行 octop version,或回到 应用更新 核对 当前版本。

    升级失败时

    • 页面提示无法连接 PyPI:检查本机网络或代理,再点击 检查更新。命令行加上 --verbose 可以看到安装器输出。
    • 页面提示开发版安装:按「源码安装」更新。
    • 各个镜像都失败:更换网络后重试。镜像站上的版本可能暂时落后于 PyPI。