Meshray-Manager/docs/配置指南.md

MeshRay 配置指南

配置文件模板

config.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

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

启动命令

# 启动服务
docker-compose up -d

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

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

---

关键参数复用规则

1. 跨容器共享数据库

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

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

注意：

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

---

2. 外部访问配置

场景：允许局域网访问 MeshRay

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

---

3. WireGuard 端口映射

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

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

---

4. 中继节点特殊配置

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

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

验证 IP 转发：

# 进入容器
docker exec -it meshray sh

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

---

ExternalService 配置示例

STUN 服务器

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

TURN 服务器（长期凭证）

{
  "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 服务器（短期凭证）

{
  "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 反向代理）

{
  "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 阿里云

{
  "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

{
  "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

配置：

# 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 中继功能
• 多客户端连接

配置：

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 直连

配置：

# config.yaml
stun:
  enabled: false
  
turn:
  enabled: false

策略设置：

• 只启用 Direct-UDP 层
• 禁用所有 Relay 层

---

故障排查

检查配置文件有效性

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

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

查看当前配置

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

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

重置配置

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

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

---

最后更新：v2.1.0