安装

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

Debian

sudo apt install ./mayami_<版本>_arm64.deb

OpenWrt

apk add --no-scripts --no-network --allow-untrusted /tmp/mayami.apk

VyOS

sudo dpkg -i mayami_*_arm64.deb mayami-vyos_*_all.deb

不要让两个实例接管同一流量

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/

安装与升级

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：

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

接替 Go 版 Mayami

Go 版留下的配置可能让 dpkg 询问保留哪一份。先停旧服务并移开旧配置，或者预先写好新配置并使用 --force-confold。详见 迁移。

OpenWrt

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

先检查前提

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+。

安装但不启用

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

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 配置

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 端口。

正式启用

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

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

24.10 手工安装

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

VyOS

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

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

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

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

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 管理：

configure
set service mayami capture
commit
save

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

sudo systemctl reload mayami

容器与虚拟机

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

页面历史

最后编辑于 大约 15 小时前

查看完整历史

4e7e0a6-site: Documents the manual

d5a0b7c-site: Scaffolds the documentation site