从 v1 迁移
TIP
ChatLuna v2 基于 Cordis 4 重构为独立的应用程序，不能在原有的 Koishi 实例中就地升级 v1 插件。旧版文档见 v1.chatluna.chat。
最稳妥的路线是全新部署一套 v2 实例，使用独立的运行目录、数据库和数据根目录。迁移完配置和资产、完成验证后，再把生产聊天平台切换过来。
迁移前准备
先列出 v1 的资产：
- 平台与账号：接入的平台、机器人账号和身份标识。
- 模型：服务商、模型名、自定义端点和凭据。
- 预设与世界书：YAML 预设、角色卡、世界书和静态资源。
- 规则与行为：场景规则、路由策略、触发词、回复条件和会话归属。
- 扩展：自定义工具、外部插件和必须保留的业务逻辑。
备份与隔离的要求：
- 完全隔离：v2 不能读写 v1 的数据库，两套系统不能共用同一个正在写入的数据目录。
- 完整冷备份：备份 v1 的 Koishi 配置、数据库、媒体资源和凭据。在线数据库用原生导出工具生成一致的备份，并确认备份可以独立读取。
- 可回退：记录 v1 的依赖版本和锁文件，写好回滚步骤。
- 保护凭据：备份中通常有明文 API Key 和聊天记录，设置严格的文件权限，不要提交到公开仓库。
资产对照
| v1 资产 | v2 处理方式 | 重点检查 |
|---|---|---|
| 模型与提供商 | 按 v2 Schema 重新配置 | 提供商插件、端点格式、provider:model 标识、凭据，以及一次真实推理 |
| 聊天平台 | 安装对应的 Satori 适配器，重建连接 | 收消息、发消息、机器人 ID 与平台账号、指令前缀 |
| YAML 预设 | 用 v2 的导入入口导入，检查转换结果 | 变量占位符、include 路径、世界书触发、Few-shot 示例、system 与 context 划分 |
| 人格与状态 | 按 v2 的角色与记忆机制重建 | 记忆作用域、主人确认、自动提取开关、管理权限 |
| Koishi 插件 | 找 v2 移植版，或按新扩展点重写 | 不要因为有指令和会话的兼容层，就假设旧插件都能运行 |
| 历史会话 | 保留为只读副本供参考 | 不能据此伪造 v2 的请求标记、工具调用因果链或计费记录 |
v1 的历史通常只是扁平的消息数组，没有请求参数、工具调用因果链和 Token 消耗，无法无损转换为可重建请求的 v2 会话。强行写入会破坏状态审计。旧会话可以归档为文本，或从中提取提示词，但不要挂载成运行中的会话。
部署 v2 实例
安装步骤见 选择安装方式 与 快速上手。初次启动不要直接连生产平台，先用内置的网页聊天或测试账号调试。
在部署目录运行 chatluna doctor config --dir .（源码工作区用 yarn chatluna doctor config --dir .），确认各项校验通过。注意：
- 通过只代表本地配置格式和路径有效，不代表模型端点或平台网络可用。
- 当前目录、受管实例名和
--dir是不同层级，核对目标目录，避免写错位置。
网络方面，Docker 内部网络、宿主机端口映射、allowRemote 和反向代理 HTTPS 是不同的层级，不要照搬源码仓库中的本地回环默认值。确认 /api 与 /console 都需要认证，未授权或口令错误的请求会被拦截。目前整个实例共用一个访问令牌。
重建模型、平台与规则
模型：按 v2 规范填写密钥、端点和模型，安装对应的提供商插件。保存后发起一次真实对话，确认能收到流式回复、计费统计正常，不要只看模型列表刷新成功。模型标识在不同位置写法不同：
- 运行时和场景规则中用
provider:model。 - API 和数据对象中是独立的
provider与model字段。 - 预设元信息中用
provider/model。
平台：在扩展管理页面安装对应的 Satori 适配器并填写鉴权参数。v2 有 Koishi 风格指令的兼容层，但不代表能运行任意旧插件。配置后分段验证：能收到消息、指令前缀能被识别、回复能正常发出。
场景规则：v2 的场景规则统一管理引擎、模型、预设、会话归属、回复条件和渲染策略。不要从旧配置复制 routingRules、patch 等字段，键名不通用，直接粘贴会解析失败。在控制台中按需求逐条配置，再用「规则预览」确认每个字段的来源和最终值，不要凭直觉猜优先级。
迁移预设、角色与记忆
v2 提供旧版 YAML 预设的导入入口。导入后打开生成的 Markdown 源码、诊断信息和渲染预览，逐项检查：
- Frontmatter：模型名和参数符合 v2 Schema，预览中能正确解析。
- 静态与动态分离：静态人设写在
system，随对话变化的状态和检索资料写在context。可变变量放进system会直接报错，系统不会静默容错。 - 外部引用：
include的相对路径和静态资源都能正常读取。 - 世界书与示例：世界书的触发规则正确，示例对话落在正确的位置。
- 绑定与版本：目标会话或场景已绑定新预设，保存后的 revision 一致，实际渲染出的提示词结构符合预期。
v1 的伪装插件数据、角色卡和旧记忆不会自动转换，需要按新体系重新整理：
- v2 长期记忆默认使用 Markdown 主题后端，自动提取默认关闭。
- 重新规划记忆作用域，不要假定个人记忆只在私聊中可见。
- 主人必须通过真实平台私聊中的绑定码或手动填写用户 ID 确认，系统不会把第一个发言的人当作主人。
- 被管理员显式降级过的账号，重新走主人确认也不会恢复最高权限。确认后在后台核对权限列表。
工具、MCP 与自定义插件
按需启用、逐个验证：
- 逐个接入工具、MCP 和技能，不要把未测试过的工具批量设为
auto。 - 检查工具的参数 Schema 和权限边界，确认审批能拦住敏感操作。
- 技能只是提示词，不会赋予模型额外权限；本地启动的 MCP 进程继承宿主服务的身份，需要防范越权。
自定义插件应拆分到 v2 的标准扩展点：工具、提示词模板、路由、引擎或消息中间件。不要把旧版基于 LangChain 的适配器直接套到新的模型运行时上，也不要为了兼容单个插件去改 Agent 的公共接口，详见 插件开发。重构后确认单元测试能通过。
运行环境方面：代码执行和子代理需要显式配置隔离级别，上下文隔离不等于文件系统隔离，挂载宿主机的 Docker socket 有系统级风险。旧的定时任务需要在 v2 中手动重建，确认执行时间和推送目标，避免上线时补发积压的通知。
验收与切换
切换前逐项确认：
切换步骤：
- 断开 v1：在 v1 中断开生产平台的适配器，确认它已停止收发。不要让 v1 和 v2 同时连接同一个机器人账号。
- 启用 v2：在 v2 中启用对应的适配器，确认平台显示已连接、机器人在线。
- 观察：在生产环境发送测试消息，看运行日志和推理轨迹，确认用户能收到回复。注意消息 API 返回的 HTTP 202 只代表请求已被接受，不代表回复已生成或已送达。
出现严重故障时回退：
- 停止 v2 中的平台适配器，确认它释放了平台连接。
- 用原配置和旧数据库启动 v1，确认机器人恢复响应。
- 不要把 v2 运行期间产生的数据写回 v1 数据库。
- 迁移彻底完成前，不要删除 v1 的备份和旧环境。
遇到问题时参考 排错与诊断。
