Skip to content

遷移 CLI

將配置檔案從舊格式升級到當前 v2 格式。

Potato 包含一個遷移工具，幫助將配置檔案從舊格式升級到當前 v2 格式。該工具自動檢測並應用必要的更改，同時保留你的現有設定。

用法

bash
# Basic migration (prints migrated config to stdout)
potato migrate config.yaml --to-v2
 
# Save to a new file
potato migrate config.yaml --to-v2 --output new_config.yaml
 
# Modify the original file in place
potato migrate config.yaml --to-v2 --in-place
 
# Preview changes without applying them
potato migrate config.yaml --to-v2 --dry-run

命令選項

選項簡寫描述
--to-v2必需。 遷移到 v2 格式
--output FILE-o將遷移後的配置寫入指定檔案
--in-place-i直接修改原始配置檔案
--dry-run顯示將要進行的更改但不應用
--quiet-q抑制資訊性輸出

注意： --in-place 和 --output 不能同時使用。

遷移規則

遷移工具應用以下轉換：

1. Textarea 到 Multiline

將舊的 textarea 格式轉換為文本模式的新 multiline 格式。

之前：

yaml
annotation_schemes:
  - annotation_type: "text"

之後：

yaml
annotation_schemes:
  - annotation_type: "text"

2. 舊版使用者配置

檢測舊的 user_config 格式並建議新增顯式的 login 配置。

之前：

yaml
user_config:
  allow_all_users: true

之後：

yaml
user_config:
  allow_all_users: true
login:
  type: open

3. 標籤要求格式

將布林值 label_requirement 轉換為字典格式。

之前：

yaml
annotation_schemes:
  - annotation_type: "multirate"

之後：

yaml
annotation_schemes:
  - annotation_type: "multirate"

4. 輸出格式建議

在使用舊版輸出格式時提供建議。如果 output_annotation_format 設定為 csv 或 tsv，建議使用 json 以支援更豐富的標註資料（片段、後設資料）。

示例

預覽更改（模擬執行）

bash
$ potato migrate old_config.yaml --to-v2 --dry-run
 
Migration changes:
 
[textarea_to_multiline] Convert textarea.on to multiline format:
  - Converted textarea.on to multiline in schema 'feedback'
 
[legacy_user_config] Migrate legacy user_config to login format:
  - Added login.type: open (from allow_all_users: true)
 
Dry run - no changes written.

遷移並儲存到新檔案

bash
$ potato migrate old_config.yaml --to-v2 --output migrated_config.yaml
 
Migration changes:
...
 
Wrote migrated config to migrated_config.yaml

靜默模式

bash
# Just output the migrated YAML, no status messages
$ potato migrate old_config.yaml --to-v2 --quiet > new_config.yaml

何時使用遷移

考慮在以下情況使用遷移工具：

  • 從 Potato 舊版本升級時
  • 啟動伺服器時看到棄用警告
  • 配置選項未按預期工作
  • 希望確保配置遵循當前最佳實踐

故障排除

"Configuration file is empty"

YAML 檔案無法解析或為空。請檢查：

  • 檔案存在且可讀
  • YAML 語法有效
  • 檔案包含配置內容

"Invalid YAML in configuration file"

YAML 中存在語法錯誤。常見問題：

  • 縮排不正確
  • 鍵後缺少冒號
  • 未引用的特殊字元

無需遷移

如果看到 "No migrations needed - config is already up to date"，說明你的配置已經使用當前 v2 格式。

延伸閱讀

有關實現細節，請參閱原始碼文件。