> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 如何升级 Octop 版本

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

升级前先做一份[备份](/guide/guides/backup-restore.md)。新版本在重启后生效。重启会暂时中断正在进行的对话。

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

## 确认当前版本

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

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

```bash
octop version
```

Docker 部署在容器里查看：

```bash
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 时，在终端执行：


```bash 检查，不安装
octop update --check
```
```bash 安装稳定版
octop update
```
```bash 跳过确认
octop update --yes
```
```bash 包含测试版
octop update --allow-prerelease --yes
```


完整选项见 [服务器命令：octop update](/cli/server-commands.md#octop-update)。

## 重新运行安装脚本

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


```bash macOS / Linux
curl -fsSL https://download.octop.cloud/octop/scripts/install.sh | bash
```
```powershell Windows (PowerShell)
irm https://download.octop.cloud/octop/scripts/install.ps1 | iex
```
```bat Windows (cmd)
curl -fsSL https://download.octop.cloud/octop/scripts/install.bat -o install.bat
install.bat
```


## 升级 pip 安装

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

```bash
pip install -U octop
```

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

## 升级 Docker

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

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


**docker run**

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

在 Compose 文件所在目录执行。国内镜像配置会拉取 `ghcr.nju.edu.cn/tencentcloud/octop:latest`，并继续挂载宿主机的 `~/.octop`（或 `OCTOP_DATA`）。
```bash
docker compose -f docker-compose.cn.yml pull
docker compose -f docker-compose.cn.yml up -d
```
文件在仓库的 `docker/` 目录时，把 `-f` 换成 `docker/docker-compose.cn.yml`。
使用源码构建的 `docker-compose.yml` 时，在仓库根目录重建并启动：
```bash
docker compose -f docker/docker-compose.yml up -d --build
```



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


## 在飞牛OS 上升级

到 [GitHub Releases](https://github.com/TencentCloud/Octop/releases) 下载新版本 `.fpk`，在应用中心再安装一次。数据目录和配置会保留。Docker 版与本地版的包名、端口见 [飞牛OS](/guide/fnos.md)。

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

## 升级源码安装

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

```bash
git pull
make build-frontend
pip install -e .
```

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

## 重启并确认

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


```bash 系统服务
octop service restart
```
```bash 前台进程
octop run
```


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

## 升级失败时

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