Skip to content

迁移 CLI

将配置文件从旧格式升级到当前 v2 格式。

迁移 CLI

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"
    name: "feedback"
    textarea:
      on: true
      rows: 4
      cols: 50

之后：

yaml
annotation_schemes:
  - annotation_type: "text"
    name: "feedback"
    multiline: true
    rows: 4
    cols: 50

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"
    name: "ratings"
    label_requirement: true

之后：

yaml
annotation_schemes:
  - annotation_type: "multirate"
    name: "ratings"
    label_requirement:
      required: true

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 格式。

延伸阅读

有关实现细节，请参阅源代码文档。