> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/zhong-wen-fan-ti/cherry-studio/installation/v1-to-v2-migration.md).

# V1 升級到 V2

{% hint style="danger" %}
遷移係單向嘅：V1 資料可以入到 V2，V2 新資料唔會同步返去 V1。升級前請同時保留 V1 完整備份同完全退出應用之後複製嘅整個 V1 資料目錄。
{% endhint %}

{% hint style="warning" %}
保留資料嘅正確路徑係：**V1.9.13 → V2.0.2（直接完成資料遷移）**。唔再需要先安裝 V2.0.0。
{% endhint %}

## 根據而家情況選擇

| 而家情況             | 操作                                   |
| ---------------- | ------------------------------------ |
| 仲喺 V1，需要保留資料     | 將 V1 更新到 1.9.13，按本頁步驟直接安裝 V2.0.2。    |
| 已經喺度用緊 V2        | 正常升級 V2.0.2，繼續使用而家嘅 V2 資料；唔好撳【重新遷移】。 |
| 之前遷移 V1 失敗或者漏咗資料 | 完整備份而家嘅 V2 之後，先至可以用【重新遷移】由 V1 重新開始。  |
| 唔需要 V1 資料        | 可以揀【忽略並使用默認值】，由默認設定開始；V1 資料唔會遷入。     |

## 升級前確認

* V1 唔低於 1.9.12，建議先更新到最終版 1.9.13 並至少啟動一次。
* 首次遷移可以直接用 V2.0.2。
* 自訂資料目錄或者外置磁碟可以正常讀寫。
* 對話、Agent、知識庫導入同文件處理任務都已經完成。

{% hint style="warning" %}
遷移嚮導會讀取而家嘅 V1 資料目錄，唔會讀 V1 備份 ZIP。備份係用嚟意外恢復，唔可以代替原始資料目錄參與遷移。
{% endhint %}

## 操作步驟

{% stepper %}
{% step %}

### 更新並備份 V1

將 V1 更新到 1.9.13。喺數據備份頁面關閉【精簡備份】，建立完整備份，並將備份保存在應用數據目錄之外。
{% endstep %}

{% step %}

### 複製整個 V1 資料目錄

喺 V1 嘅數據設定中確認目錄位置，完全退出 Cherry Studio 之後複製成個目錄。唔好淨係複製數據庫文件。
{% endstep %}

{% step %}

### 檢查自訂目錄

如果用移動硬碟、網絡卷或者其他自訂位置，確認路徑已經掛載同可讀寫。路徑唔可訪問時，唔好改用默認目錄繼續遷移。
{% endstep %}

{% step %}

### 首次啟動 V2.0.2

從 [V2 官方下載](https://cherryai.com.cn/download) 攞返啱系統同晶片嘅 V2.0.2 安裝包，亦可以用 [GitCode 發佈頁](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) 或者 [GitHub 發佈頁](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)。完全退出 V1 之後安裝並啟動。
{% endstep %}

{% step %}

### 完成【數據遷移嚮導】

核對嚮導顯示嘅數據位置，再揀【開始遷移】。遷移期間唔好關閉應用、搬動數據目錄或者斷開外置磁碟。
{% endstep %}

{% step %}

### 查看結果並重啟

遷移完成之後先展開警告信息，再揀【重啟應用】。
{% endstep %}
{% endstepper %}

## 升級後檢查

* 檢查常用模型服務、API Key 同默認模型。
* 檢查助手分組、提示詞、Agent 權限同知識庫綁定。
* 打開常用會話、知識庫同文件；只重建顯示失敗嘅知識來源。
* 喺【設定】→【網絡搜尋】重新確認關鍵詞搜尋同網址讀取服務。
* 檢查側欄收藏同自訂 CSS。
* 喺【設定】→【數據】建立新嘅 V2 完整備份。

更多入口變化見 [【功能差異】](/docs/zhong-wen-fan-ti/cherry-studio/installation/v1-v2-feature-differences.md)。

## 只係遷移失敗先用【重新遷移】

如果之前 V1 遷移失敗或者漏咗資料，V2.0.2 可以喺【設定】→【數據】揀【重新遷移】。呢個操作會重啟應用，並從保留嘅 V1 資料重新執行遷移。

{% hint style="danger" %}
【重新遷移】會永久刪除而家嘅 V2 資料，唔會將 V1 同 V2 資料合併。除非之前 V1 遷移失敗或者漏咗資料，否則一定唔好撳。操作前必須建立而家 V2 嘅完整備份；需要保留嘅 V2 新內容亦應該另外匯出。
{% endhint %}

## 遷移失敗時

| 選項         | 咩時候用              | 注意事項                                             |
| ---------- | ----------------- | ------------------------------------------------ |
| 【重試】       | 修復目錄、磁碟或者臨時數據問題之後 | 優先選擇，唔會退出遷移流程。                                   |
| 【儲存問題資訊】   | 重試都失敗，需要求助        | 文件只會儲存在本地，可能包含路徑、內容或者憑據，只提供畀 Cherry Studio 支援團隊。 |
| 【忽略並使用默認值】 | 明確放棄匯入 V1 數據      | 清除今次已寫入嘅部分 V2 數據並由默認設定開始；之後唔會再自動提示遷移。            |
| 【繼續使用 V1】  | 暫時無法遷移，需要恢復工作     | 重新安裝 V1 並繼續使用原本 V1 數據目錄。                         |

{% hint style="danger" %}
遷移失敗或者誤揀【忽略並使用默認值】時，唔好自己刪除數據庫，亦唔好反覆覆蓋安裝。保留 V1 原數據同備份並聯絡 Cherry Studio 支援團隊。
{% endhint %}

## 常見問題

<details>

<summary>淨係得 V1 備份 ZIP，可以直接遷移嗎？</summary>

唔可以。先喺兼容嘅 V1 入面恢復並確認數據正常，再保留完整數據目錄，然後啟動 V2 遷移。

</details>

<details>

<summary>知識庫都要重建索引嗎？</summary>

唔需要。有效索引會遷移；只處理顯示失敗、缺少嵌入模型或者無法讀取嘅來源。

</details>

## 參考資料

* [Cherry Studio V2 官方下載](https://cherryai.com.cn/download)
* [Cherry Studio V1 官方下載](https://cherryai.com.cn/download/v1)
* V2.0.2 發佈頁：[GitCode](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) · [GitHub](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)
* [官方遷移設計說明](https://github.com/CherryHQ/cherry-studio/blob/main/src/main/data/migration/v2/README.md#version-compatibility-gate)
* [問題反饋同功能建議](/docs/zhong-wen-fan-ti/question-contact/suggestions.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cherryai.com.cn/docs/zhong-wen-fan-ti/cherry-studio/installation/v1-to-v2-migration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.