# MeshRay 配置指南

## 配置文件模板

### config.yaml 完整参数说明

```yaml
# 服务器配置
server:
  port: 9531                    # API 服务端口
  mode: "release"               # gin 模式：debug/release/test
  
# 数据库配置
database:
  type: "sqlite"                # 数据库类型：sqlite
  path: "data/meshray.db"       # SQLite 数据库文件路径
  
# 日志配置
log:
  level: "info"                 # 日志级别：debug/info/warn/error
  format: "json"                # 日志格式：json/console
  output: "logs/meshray.log"    # 日志文件路径
  max_size: 100                 # 单文件最大大小 (MB)
  max_backups: 3                # 保留旧日志文件数
  max_age: 30                   # 日志保留天数
  
# STUN 服务器配置（可选）
stun:
  enabled: true
  servers:
    - "stun.miwifi.com:3478"
    - "stun.stunprotocol.org:3478"
    
# TURN 服务器配置（可选）
turn:
  enabled: false
  server_addr: "turn.example.com:3478"
  username: "meshray_user"
  password: "your_password"
  realm: "meshray"
  
# WireGuard 配置
wireguard:
  interface_name: "wg0"         # WG 网卡名称
  listen_port: 51820            # WG 监听端口
  mtu: 1420                     # WG MTU 值
  
# gRPC 配置（ctr ↔ Core 通信）
grpc:
  port: 50051                   # gRPC 服务端口
  max_message_size: 4194304     # 最大消息大小 (4MB)
  
# 雪花算法配置
snowflake:
  machine_id: 1                 # 机器 ID (0-1023)
  
# 安全配置
security:
  jwt_secret: "your-jwt-secret-key"  # JWT 签名密钥
  jwt_expire: 24h                    # JWT 过期时间
  
# MeshSeed 配置
meshseed:
  default_expiry: 720h          # 默认过期时间 (30 天)
  network_secret_min_len: 32    # NetworkSecret 最小长度
```

---

## Docker Compose 部署配置

### docker-compose.yaml

```yaml
version: '3.8'

services:
  meshray:
    image: zkcoi/meshray:latest
    container_name: meshray
    restart: unless-stopped
    
    # 特权模式（必需：用于创建 WG 网卡）
    privileged: true
    
    # 网络配置
    network_mode: host
    
    # 环境变量
    environment:
      - TZ=Asia/Shanghai
      - MESHRAY_PORT=9531
      - MESHRAY_DB_PATH=/app/data/meshray.db
      
    # 卷挂载
    volumes:
      - ./data:/app/data              # 数据目录
      - ./logs:/app/logs              # 日志目录
      - ./config.yaml:/app/config.yaml  # 配置文件
      
    # 设备映射（WG 网卡必需）
    devices:
      - /dev/net/tun:/dev/net/tun
      
    # 系统参数（IP 转发）
    sysctls:
      - net.ipv4.ip_forward=1
      
    # 能力添加
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
      
    # 健康检查
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9531/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

### 启动命令

```bash
# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f meshray

# 停止服务
docker-compose down

# 重启服务
docker-compose restart
```

---

## 关键参数复用规则

### 1. 跨容器共享数据库

**场景**：多个 MeshRay 实例共享同一数据库（不推荐，仅用于测试）

```yaml
volumes:
  - /shared/data/meshray.db:/app/data/meshray.db
```

**注意**：
- ⚠️ SQLite 不支持多写，可能导致锁竞争
- ✅ 生产环境应使用独立数据库

---

### 2. 外部访问配置

**场景**：允许局域网访问 MeshRay

```yaml
ports:
  - "0.0.0.0:9531:9531"  # 监听所有网卡
  
environment:
  - MESHRAY_CORS_ORIGINS=http://192.168.1.100:9531
```

---

### 3. WireGuard 端口映射

**场景**：Docker 后需要暴露 WG 端口

```yaml
ports:
  - "51820:51820/udp"  # WG 监听端口
  
environment:
  - WIREGUARD_LISTEN_PORT=51820
```

---

### 4. 中继节点特殊配置

**场景**：运行在 Docker 中的 Mesh 中继节点

```yaml
sysctls:
  - net.ipv4.ip_forward=1  # 必需：开启 IP 转发
  
cap_add:
  - NET_ADMIN              # 必需：网络管理权限
  
iptables: true             # 启用 iptables 支持
```

**验证 IP 转发**：
```bash
# 进入容器
docker exec -it meshray sh

# 检查 IP 转发
cat /proc/sys/net/ipv4/ip_forward
# 输出应为：1
```

---

## ExternalService 配置示例

### STUN 服务器

```json
{
  "category": "networking",
  "serviceType": "stun_server",
  "name": "公共 STUN",
  "config": {
    "servers": [
      "stun.miwifi.com:3478",
      "stun.stunprotocol.org:3478",
      "stun.l.google.com:19302"
    ]
  }
}
```

### TURN 服务器（长期凭证）

```json
{
  "category": "networking",
  "serviceType": "turn_server",
  "name": "Coturn 服务器",
  "config": {
    "server_addr": "turn.example.com:3478",
    "realm": "meshray",
    "auth_type": "long_term",
    "long_term": {
      "username": "meshray_user",
      "password": "secure_password_123"
    }
  }
}
```

### TURN 服务器（短期凭证）

```json
{
  "category": "networking",
  "serviceType": "turn_server",
  "name": "Coturn 动态凭证",
  "config": {
    "server_addr": "turn.example.com:3478",
    "realm": "meshray",
    "auth_type": "short_term",
    "short_term": {
      "username": "meshray_user",
      "auth_secret": "super_secret_key_for_hmac",
      "expires_in": 86400
    }
  }
}
```

### WS 隧道（Nginx 反向代理）

```json
{
  "category": "networking",
  "serviceType": "ws_tunnel",
  "name": "Nginx WS 代理",
  "config": {
    "server_type": "nginx",
    "endpoint_type": "wss",
    "endpoint": "wss://relay.example.com/ws-tunnel",
    "use_coturn_stun": false
  }
}
```

### DDNS 阿里云

```json
{
  "category": "dns",
  "serviceType": "ddns_aliyun",
  "name": "阿里云 DDNS",
  "config": {
    "access_key_id": "LTAI5t...",
    "access_key_secret": "...",
    "region_id": "cn-hangzhou",
    "domain": "home.example.com",
    "txt_record_name": "_meshray"
  }
}
```

### Webhook

```json
{
  "category": "automation",
  "serviceType": "webhook",
  "name": "企业微信机器人",
  "config": {
    "url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json"
    },
    "body_template": "{\"msgtype\":\"text\",\"text\":{\"content\":\"{{.Message}}\"}}"
  }
}
```

---

## 常见场景配置案例

### 场景 1：家庭 NAS 部署

**需求**：
- 部署在家庭 NAS（群晖/威联通）
- 通过公网 IPv6 访问
- 自动更新 IPv6 地址到 DDNS

**配置**：
```yaml
# docker-compose.yaml
services:
  meshray:
    image: zkcoi/meshray:latest
    network_mode: host  # 使用宿主机网络，获取 IPv6
    
    environment:
      - IPV6_ENABLED=true
      
    volumes:
      - ./data:/app/data
```

**ExternalService**：
1. 添加 DDNS 服务（IPv6 自动更新）
2. 添加 STUN 服务（辅助穿透）

---

### 场景 2：云服务器中转

**需求**：
- 云服务器作为中转节点
- 开启 Mesh 中继功能
- 多客户端连接

**配置**：
```yaml
services:
  meshray:
    privileged: true
    network_mode: host
    
    sysctls:
      - net.ipv4.ip_forward=1  # 必需：IP 转发
      
    cap_add:
      - NET_ADMIN              # 必需：WG 网卡管理
```

**ExternalService**：
1. 添加 TURN 服务器（云服务商提供）
2. 配置为中继节点（AllowedIPs = 0.0.0.0/0）

---

### 场景 3：纯内网部署

**需求**：
- 完全离线运行
- 不使用 STUN/TURN
- 仅 Direct-UDP 直连

**配置**：
```yaml
# config.yaml
stun:
  enabled: false
  
turn:
  enabled: false
```

**策略设置**：
- 只启用 Direct-UDP 层
- 禁用所有 Relay 层

---

## 故障排查

### 检查配置文件有效性

```bash
# 验证 YAML 语法
python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"

# 检查 JSON 配置
jq '.' config.json
```

### 查看当前配置

```bash
# API 查询
curl http://localhost:9531/api/config

# 查看环境变量
docker exec meshray env | grep MESHRAY
```

### 重置配置

```bash
# 删除配置文件
rm config.yaml data/meshray.db

# 重新初始化
docker-compose up -d
```

---

*最后更新：v2.1.0*