---
url: /configuration.md
description: mayami 配置的结构、值语法和术语
---

# 配置总览

mayami 的配置是一份严格校验的 YAML。它有 17 个顶层键；下面是最小完整骨架。

```yaml check
log: info
mode: rule
unified_delay: false
gateway: {}
cache_file: {}
inbounds: {}
outbounds: {}
rule_sets: {}
http_clients: {}
providers: {}
route: {}
dns:
  servers:
    default: {type: udp, address: 127.0.0.1:53}
  final: default
musubi: {}
networks: {}
ntp: {enabled: false}
```

## 顶层键

| 键 | 类型 | 默认 | 页面 |
|---|---|---|---|
| `log` | 字符串或映射 | `info`、带时间戳、标准输出 | [log](/configuration/log) |
| `mode` | 字符串 | `rule` | [mode](/configuration/mode) |
| `unified_delay` | 布尔值 | `false` | 本页 |
| `gateway` | 映射 | 空映射；总内存为系统内存的 1/4 | [gateway](/configuration/gateway) |
| `api` | 映射或省略 | 不启用 | [api](/configuration/api) |
| `cache_file` | 映射 | 启用，路径 `cache.db` | [cache_file](/configuration/cache-file) |
| `inbounds` | 名字到入站的映射 | 空 | [inbound](/configuration/inbound/) |
| `outbounds` | 名字到出站的映射 | 空 | [出站总览](/configuration/outbound/) |
| `rule_sets` | 名字到规则集的映射 | 空 | [route/rule-set](/configuration/route/rule-set) |
| `http_clients` | 名字到下载客户端的映射 | 空 | [http_clients](/configuration/http-client) |
| `providers` | 名字到 provider 的映射 | 空 | [providers](/configuration/provider) |
| `route` | 映射 | 空；`final` 取第一个出站 | [路由总览](/configuration/route/) |
| `dns` | 映射 | DNS crate 的默认值 | [DNS 总览](/configuration/dns/) |
| `musubi` | 名字到 mesh 的映射 | 空 | [musubi](/configuration/musubi) |
| `networks` | 名字到网段的映射 | 空 | [网段总览](/configuration/networks/) |
| `docker` | 空映射或省略 | 不启用 IPAM socket | [docker](/configuration/docker) |
| `ntp` | 映射 | 启用，trust host，三个公共服务器，30 分钟 | [ntp](/configuration/ntp) |

`unified_delay` 打开时，延迟测试只在已经建立的连接上再发一次 HEAD，把握手时间排除在结果之外；它不改变选择算法。

## 严格解析

* 每个结构都拒绝未知字段。
* 同一映射里的重复键会报错。
* 带 `type` 的对象必须把 `type` 写在第一项；放在后面会被拒绝。
* 出错格式是 `文件:行:列: 错误`，随后打印出错行和 `^` 标记。
* 不提供旧拼写兼容层。字段改名、协议被移除或值类型不对时，`check` 直接失败。

### 编辑器补全与校验

发布站把生成的 JSON Schema 放在 `/schema/mayami.json`。VS Code 配合
[YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
扩展（`yaml-language-server`）时，在配置文件第一行写：

```yaml
# yaml-language-server: $schema=https://你的文档站.example/schema/mayami.json
```

也可以把本地构建出的 `site/content/public/schema/mayami.json` 写成 `file://`
路径，或在工作区设置里把 `yaml.schemas` 映射到 `mayami.yaml`。Schema 是
draft 2020-12，字段与 serde 结构一起更新；构建时 `pnpm build:schema`
会在有 `MAYAMI_BIN` 或默认 `../target/debug/mayami` 时刷新它。

## 值语法

### 时长

时长是一个非负整数加一个单位：

| 单位 | 含义 |
|---|---|
| `s` | 秒 |
| `m` | 分 |
| `h` | 小时 |
| `d` | 天 |

例如 `30s`、`5m`、`1h`、`7d`。裸数字、负数和 `1h30m` 这类复合写法都会被拒绝。

### 大小

大小可写成字节整数，或使用 `KiB`、`MiB`、`GiB`：

```text
4096
128KiB
64MiB
1GiB
```

`KB`、`MB` 等十进制单位不被接受。

### 端点

出站和 NTP 的端点写作 `host`、`host:port`、裸 IPv6 地址或 `[IPv6]:port`。省略端口时，出站默认 `443`，NTP 默认 `123`。监听地址要求 `SocketAddr` 语义，端口必须写出。

### 路径

相对路径以数据目录为基准：有 `-D` 时是 `-D`，否则是配置文件所在目录。绝对路径保持绝对。各页会说明默认路径。

### 名字

入站、出站、规则集、provider、HTTP 客户端等以映射键命名。空名字、重复名字和缺失的映射键不会被自动补成 `<type>-<index>`。名字在同类对象中唯一；入站和出站可以同名。

### 规则顺序和 final

映射和数组保持 YAML 中的顺序。`route.rules` 先匹配先得；`route.final` 没写时取第一个出站，一个出站都没有时使用内建 `DIRECT`。

## 术语

| 术语 | 含义 |
|---|---|
| **直连** | 规则决定不经过代理，把流交回内核或本机网络栈 |
| **代理** | 流交给某个 outbound，由该协议连接目标 |
| **放手 / release** | `capture` 判为直连后，把首包交回内核，由 nftables/NAT 和内核转发继续 |
| **接管 / capture** | mayami 在网口或网桥上挂 tc/eBPF/TUN/TAP，读取并决定流 |
| **Segment** | mayami 自建 TAP，一台虚拟机或一个隔离段把它当网卡 |
| **Router** | mayami 接管现有 LAN/WAN，典型是路由器或旁路由 |
| **Host** | mayami 建 TUN 并在本机路由表中接管自己的流量 |
| **网段** | `networks:` 管理的网桥、地址、DHCP、RA、DNS 和成员集合 |
| **租户** | 一组可重叠网段的隔离域；各有 VRF、路由表、conntrack zone 和标记 |
| **成员** | 插进网段的整口、veth、tap 或 trunk 子口 |

## 相关

* [开始使用](/getting-started/)
* [命令行](/getting-started/cli)
* [入站总览](/configuration/inbound/)