# 安装、升级与数据迁移

> 选择正确的 Vetta 构建、完成升级，并安全迁移项目、会话和本地配置。

Canonical page: /getting-started/installation-and-updates



<Takeaways>
  <li>
    先确认下载包对应当前操作系统和处理器架构
  </li>

  <li>
    升级前保留项目导出或版本控制基线
  </li>

  <li>
    不要把会话正文、凭证和项目文件混成一份备份
  </li>
</Takeaways>

## 选择安装来源 [#选择安装来源]

普通用户应从[下载页](https://openvetta.com/download)获取与当前操作系统和架构匹配的安装包。仓库当前面向 Windows、macOS 和 Linux；下载页没有列出的平台或架构没有可替代的安装包。

源码开发者从仓库运行桌面端时需要 Bun 1.3+ 和 Node.js 20+，并使用 `apps/desktop` 下的开发命令。开发环境默认使用独立数据目录，避免覆盖已安装版本的数据。

## 开源版与商业版 [#开源版与商业版]

桌面端的构建模式在打包时确定，不是安装后的运行时开关：

| 模式               | 登录与云服务           | 能力来源       | 共同能力                   |
| ---------------- | ---------------- | ---------- | ---------------------- |
| 开源版 / serv-less  | 不包含账户、订阅和远程模型目录  | GitHub 能力源 | 本地会话、BYOK、插件、主题、IM、知识库 |
| 商业版 / Vetta Serv | 可包含登录、组织、订阅和官方目录 | 官方服务端能力源   | 本地会话、BYOK、插件、主题、IM、知识库 |

不要把一个模式的服务端地址、Marketplace 配置或更新配置复制到另一个模式。构建模式和环境变量属于发布者配置；终端用户只需要按下载来源使用对应安装包。

## 升级前检查 [#升级前检查]

<Checklist title="升级前保留这些证据">
  <li>
    项目目录已有 Git 提交、压缩归档或其它可恢复副本。
  </li>

  <li>
    没有仍在运行的任务、批量任务或知识库后台加工。
  </li>

  <li>
    重要会话已经等待写入完成，未处于持续重试或等待权限状态。
  </li>

  <li>
    如果使用 IM、Webhook 或自动化，已经记录当前开关、渠道和任务状态。
  </li>

  <li>
    凭证由系统或 Vetta 配置存储保护，不把 

    `models.json`

    、Token 或 Cookie 复制到备份说明中。
  </li>
</Checklist>

安装新版本通常会保留本地配置和数据目录。升级后若出现模型、插件或运行时异常，先在设置中重新验证对应能力，再查看[配置与数据路径](/reference/configuration-paths/)和[故障排查](/troubleshooting/)；不要先删除整个 `~/.vetta` 目录。

## 迁移哪些内容 [#迁移哪些内容]

| 内容            | 迁移建议               | 注意事项                |
| ------------- | ------------------ | ------------------- |
| 项目文件          | 使用 Git、项目导出或文件系统备份 | 这是任务真实产物的首要副本       |
| 项目级 `.vetta/` | 与项目一起迁移            | 保留目录结构，确认其中没有凭证     |
| 普通会话          | 迁移对应会话目录及元数据       | 不要让两个进程同时写同一会话      |
| 模型、MCP 和其它设置  | 优先通过设置页重新配置        | 手工迁移前脱敏，并核对版本兼容性    |
| 凭证与 OAuth 状态  | 不复制到公开或跨设备文档       | 按目标设备重新登录或重新授权      |
| 知识库原始资料       | 备份原始文件             | 整理结果可重新生成，不等同于原始资料  |
| IM 绑定状态       | 按渠道重新绑定更安全         | QR 绑定和第三方会话有自己的生命周期 |

全局路径、项目路径和会话目录见[配置与数据路径](/reference/configuration-paths/)。路径是当前实现事实，不应被当成跨版本稳定协议；自动化集成请优先使用 SDK、RPC 或公开 CLI。

## 升级后的验收 [#升级后的验收]

1. 启动 Vetta，确认能打开一个已知项目。
2. 显式选择一个模型，发送最小测试消息。
3. 打开一个历史会话，确认消息和产物可读取。
4. 如果使用插件、MCP、知识库或自动化，逐项执行一次只读或测试操作。
5. 确认更新后的版本、权限和数据边界符合预期，再恢复无人值守任务。

<Callout title="不要用删除数据解决升级问题" type="warn">
  删除整个用户数据目录会同时影响会话、配置、知识库、插件和渠道状态。先导出诊断信息、保留目录副本并确认具体故障对象，再执行定向清理。
</Callout>