---
url: /getting-started/migrating.md
description: 从 Go 版 Mayami、旧名称、sing-box 和 mihomo 迁移
---

# 迁移

mayami 是 Go 版 Mayami 的接替实现，但迁移不是原地升级，也没有自动配置转换器。先停掉会与新版争用同一接口、端口、BPF 状态或 DNS 的旧实例，再准备配置和回退方案。

## 从 Go 版 Mayami 切换

现行包使用 `/usr/bin/mayami`、`/etc/mayami`、`/var/lib/mayami`、`mayami.service` 和 `mayami` 用户，与 Go 版位置相同，因此两者不能并存。

* Debian 上，Go 版留下的 `/etc/mayami/mayami.yaml` 可能让 dpkg 询问保留哪一份；先移开旧配置，或使用已写好的新配置与 `--force-confold`。
* OpenWrt 的 apk 会覆盖程序，却可能保留旧 `/etc/init.d/mayami`；先停用旧服务并把程序、启动脚本和配置移开。
* 配置结构需要按 mayami 的 serde 结构重写，不能只改扩展名。
* 协议认证材料不能因为字段相似就假定兼容；先做互通测试。

## 从旧名称迁移

`mayami-rs` 和更早的 `sokubaku` 不会自动迁移：

| 项目 | 旧位置或名称 | 现位置或名称 |
|---|---|---|
| 配置 | `/etc/mayami-rs`、`~/.config/mayami-rs` | `/etc/mayami`、`~/.config/mayami` |
| 数据 | `/var/lib/mayami-rs` | `/var/lib/mayami` |
| systemd | `mayami-rs.service` | `mayami.service` |
| OpenWrt | `/etc/init.d/mayami-rs` | `/etc/init.d/mayami` |
| VyOS | `service mayami-rs` | `service mayami` |
| 配置环境变量 | `MAYAMI_RS_CONFIG` | `MAYAMI_CONFIG` |
| 数据环境变量 | `MAYAMI_RS_DATA` | `MAYAMI_DATA` |
| 控制 API 密钥 | `MAYAMI_RS_SECRET` | `MAYAMI_SECRET` |

`cache.db` 的内部格式和认证格式没有因改名变化，但旧服务停止前不要复制运行中的状态。BPF pin、cgroup 和 nftables 表名变了，不能做跨名称的无缝热升级。

## 从 sing-box 或 mihomo 配置迁移

mayami 采用与 sing-box 相似的规则、DNS 和代理字段，也读取 mihomo 的 provider、组和规则集概念，但配置仍会严格校验，未知字段直接报错。

当前支持的入站：

`tap`、`tun`、`capture`、`dns`、`shadowsocks`、`socks`、`http`、`mixed`、`anytls`、`kasumi`、`kyoukai`、`mirage`、`imina`、`naive`、`direct`。

当前支持的出站：

`direct`、`naive`、`shadowsocks`、`socks`、`http`、`anytls`、`kasumi`、`kyoukai`、`mirage`、`imina`、`selector`、`fallback`、`urltest`、`loadbalance`、`chain`。

不要把上层实现的完整配置直接投喂给 mayami。先按上面的类型缩小范围，再逐步运行：

```sh
mayami check -c migrated.yaml
```

错误会指出文件、行、列和未知字段。规则集和 provider 也可以先离线编译或匹配，见 [命令行](/getting-started/cli#rset)。

## 切换检查

1. 为旧配置和数据做可恢复备份。
2. 在独立路径准备新配置，并显式使用 `-c`、`-D` 做 `check`。
3. 确认网口、监听地址、DNS、证书、规则集缓存和代理服务器参数。
4. 停止旧服务，确认进程和网络接管都已退出。
5. 启动新服务，限定在可回退的维护窗口内验证。