438 lines
8.0 KiB
Markdown
438 lines
8.0 KiB
Markdown
# 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*
|