Initial commit
This commit is contained in:
+437
@@ -0,0 +1,437 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user