---
url: /getting-started.md
description: mayami 的接法、平台边界和第一份配置
---

# 开始使用

mayami 既做透明代理，也做代理服务器。它接替不再维护的 Go 版 Mayami，项目原名 `sokubaku`，之后曾使用 `mayami-rs`，现行名称是 `mayami`。

## 三种接法和网段

| 接法 | 流量从哪里来 | 适合什么 |
|---|---|---|
| **Segment** | mayami 创建 TAP，容器或虚拟机把 TAP 当作网卡 | 一台虚拟机或一个隔离网络，不碰宿主机现有网卡 |
| **Router** | `capture` 在现有 LAN/WAN 上挂 tc/eBPF | 路由器或旁路由，接管局域网客人和路由器本机的流量 |
| **Host** | TUN 加自动路由，接管本机流量 | 在单台 Linux 主机上使用 |
| **networks** | mayami 或外部运行时管理的网桥 | 给 Docker、Podman、LXC、Incus、libvirt/KVM 客人提供网桥、DHCP、RA、DNS、租户和 flowtable |

```mermaid
flowchart LR
  S[客人或本机流量] --> T{入口}
  T -->|TAP| G[网关与规则]
  T -->|capture| G
  T -->|TUN| G
  T -->|网桥| G
  G --> D[内核直连]
  G --> P[代理出站]
```

`networks` 可以和 Router 组合：网桥上客人的代理流仍由 capture 判定，直连流可交给内核和 flowtable。

## 平台边界

* 完整功能面向 **Linux**：包括 `capture`、eBPF、flowtable、Linux 的 BoringSSL TLS 后端，以及 AnyTLS、Mirage、Imina、naive 等依赖 Linux TLS 的部分。
* macOS 可构建核心和主程序回归测试；非 Linux 上 `capture` 不可用，带 TLS 的部分能力会明确拒绝，而不是悄悄退成明文。
* 只开发用户态时可设置 `AYA_BUILD_SKIP=1`，但这样构建出的程序不能使用 `capture`。

## 第一份配置

`mayami init` 默认写 `mayami.yaml`，也可以选择 `router`、`segment` 或 `network` 模板：

```sh
mayami init router
mayami check -c mayami.yaml
mayami run -c mayami.yaml
```

没有子命令时，mayami 默认执行 `run`：

```sh
mayami -c mayami.yaml
```

配置严格校验，未知字段会报错。模板里的服务器、密钥和网口名仍然是占位值，运行前要逐项填写。

## 下一步

* [安装](/getting-started/install)：Debian、OpenWrt、VyOS，以及容器/虚拟机接法
* [编译](/getting-started/build)：工具链、eBPF、musl、cronet TLS 和打包
* [运行](/getting-started/run)：配置查找、日志、信号、重载和数据目录
* [命令行](/getting-started/cli)：全部子命令与参数
* [迁移](/getting-started/migrating)：从 Go 版 Mayami、旧名称和 sing-box/mihomo 配置迁移