---
url: /getting-started/install.md
description: 在 Debian、OpenWrt、VyOS 安装，并接入容器或虚拟机
---

# 安装

安装包只负责把程序和配套文件放到目标位置。带 `capture` 的运行、DNS 接管和真实转发仍需单独验收；在路由器上第一次接管流量时，应保留 SSH 和回退路径。

::: code-group

```sh [Debian]
sudo apt install ./mayami_<版本>_arm64.deb
```

```sh [OpenWrt]
apk add --no-scripts --no-network --allow-untrusted /tmp/mayami.apk
```

```sh [VyOS]
sudo dpkg -i mayami_*_arm64.deb mayami-vyos_*_all.deb
```

:::

::: warning 不要让两个实例接管同一流量
Go 版 Mayami、旧名称 `mayami-rs`/`sokubaku` 与现行 `mayami` 不自动迁移。切换前停掉旧服务，确认进程退出，并避免两套实例争用同一网口、端口、BPF 状态或 nftables 表。
:::

## Debian

Debian/Ubuntu 包提供 amd64 与 arm64，内含静态 musl 程序。

### 装了什么

| 内容 | 位置 |
|---|---|
| 程序 | `/usr/bin/mayami` |
| 配置 | `/etc/mayami/mayami.yaml`，`root:mayami`，0640 |
| 数据目录 | `/var/lib/mayami`，0700，属于 `mayami` |
| systemd | `mayami.service`、`mayami@.service` |
| 用户 | `mayami`，由 `systemd-sysusers` 创建 |
| sysctl | `/usr/lib/sysctl.d/60-mayami.conf` |
| 补全 | bash、fish、zsh |
| 示例 | `/usr/share/doc/mayami/examples/` |

### 安装与升级

```sh
sudo apt install ./mayami_<版本>_arm64.deb
sudo vi /etc/mayami/mayami.yaml
sudo mayami -c /etc/mayami/mayami.yaml -D /var/lib/mayami check
sudo systemctl enable --now mayami
```

`apt remove` 保留配置和数据；`apt purge` 删除数据目录。升级时被修改过的配置不会被覆盖。

### capture 需要 root

普通代理只以 `mayami` 用户运行。`capture` 要加载 eBPF、挂 tc/XDP、写 nftables 和 BPF pin，因此需要 root：

```sh
sudo mkdir -p /etc/systemd/system/mayami.service.d
sudo cp /usr/share/doc/mayami/capture.conf \
  /etc/systemd/system/mayami.service.d/
sudo systemctl daemon-reload
sudo systemctl restart mayami
```

::: warning 接替 Go 版 Mayami
Go 版留下的配置可能让 dpkg 询问保留哪一份。先停旧服务并移开旧配置，或者预先写好新配置并使用 `--force-confold`。详见 [迁移](/getting-started/migrating)。
:::

## OpenWrt

OpenWrt 25.12+ 使用 APK；24.10 及更早的 opkg 不能安装这里的 APKv3 包。

### 先检查前提

```sh
cat /etc/apk/arch
df -h /overlay
apk info -e kmod-sched-core kmod-sched-bpf kmod-tun
```

APK 架构必须与 `/etc/apk/arch` 的完整值一致。`capture` 还需要 fw4/nftables、cgroup v2、`/sys/fs/bpf`，以及对应的内核 BPF、clsact、TUN 和 BTF 配置。`fail: open` 另需 Linux 6.6+。

### 安装但不启用

包不会创建活动配置、开机链接或启动服务。只安装已有的、可信的本地包：

```sh
sha256sum /tmp/mayami.apk
apk add --simulate --no-scripts --no-network \
  --allow-untrusted /tmp/mayami.apk
apk add --no-scripts --no-network \
  --allow-untrusted /tmp/mayami.apk
```

模拟事务如果会改动其他 WORLD 包，应停止。首次安装后确认服务未启用、未运行是预期状态。

### 准备 pending 配置

```sh
umask 077
mkdir -p /etc/mayami
cp /usr/share/mayami/examples/router.yaml \
  /etc/mayami/config.yaml.pending
chmod 600 /etc/mayami/config.yaml.pending
vi /etc/mayami/config.yaml.pending
mayami -c /etc/mayami/config.yaml.pending check
```

`check` 通过只表示配置能构建，不代表 capture、eBPF、fw4、DNS 和真实转发已经验收。正式启用前再把它放到 `/etc/mayami/config.yaml`，并按路由器现有 DNS 架构安排 53 端口。

### 正式启用

```sh
/etc/init.d/mayami start
/etc/init.d/mayami enable
logread -e mayami
```

OpenWrt init 会等待逻辑 `wan` 接口最多 15 秒，并在需要时挂载 bpffs、设置 ping socket 权限。停止服务时先摘除 capture 状态，程序退完后网络才恢复。

::: info 24.10 手工安装
旧 opkg 系统不能安装上面的 APK。只能手工复制静态程序、`packaging/openwrt/mayami.init` 和示例，并继续遵守“只安装不启用”的边界。
:::

## VyOS

VyOS 需要两个同一次构建出的包：

| 包 | 内容 |
|---|---|
| `mayami` | 程序、systemd 单元、用户和 sysctl |
| `mayami-vyos` | `service mayami` 模板、commit 脚本和 `/config` 持久安装器 |

```sh
sudo dpkg -i mayami_*_arm64.deb mayami-vyos_*_all.deb
sudo mayami-vyos install \
  mayami_*_arm64.deb mayami-vyos_*_all.deb
```

第二个命令把包存入 `/config/mayami/packages`，使系统镜像升级后能装回来。然后准备配置：

```sh
sudo mkdir -p /config/mayami
sudo mayami -c /config/mayami/mayami.yaml init
sudo vi /config/mayami/mayami.yaml
sudo mayami -c /config/mayami/mayami.yaml \
  -D /config/mayami/data check
```

交给 VyOS 管理：

```sh
configure
set service mayami capture
commit
save
```

只有使用 `capture` 或网段时才需要 `capture` 节点；它让服务以 root 和所需能力运行。只改 YAML 后，VyOS 配置没变，因此使用：

```sh
sudo systemctl reload mayami
```

## 容器与虚拟机

运行时接入、Docker/Podman/LXC/Incus/libvirt 的具体命令和 `external` 边界见 [手册：容器与虚拟机运行时](/manual/runtimes)。