Remnawave Panel 完整部署教程：基于 Xray-core 的自托管代理管理面板

Remnawave Panel 完整部署教程

项目信息：remnawave/panel · ⭐ 3.7k · v2.7.4 · AGPL-3.0

一款基于 Xray-core 构建的强大代理管理工具，专注于简洁与易用性。采用 NestJS + TypeScript + PostgreSQL 技术栈，支持多节点管理、订阅分发、REST API 等完整功能体系。

一、架构概览

在动手之前，必须理解 Remnawave 的核心设计哲学——Panel 与 Node 完全解耦：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
                    ┌─────────────────────────────┐
用户/管理员 ─────▶  │    Remnawave Panel（管理后台）  │
                    │  NestJS + PostgreSQL + Redis  │
                    │        Port: 3000            │
                    └───────────┬─────────────────┘
                                │ 内部 API 通信
                    ┌───────────▼─────────────────┐
                    │   Remnawave Node（节点实例）   │
                    │     Xray-core 真实引擎        │
                    │   可部署在不同服务器上          │
                    └─────────────────────────────┘
                                │
                    ┌───────────▼─────────────────┐
                    │   最终用户订阅 / 代理流量      │
                    └─────────────────────────────┘

关键原则：

  • Panel 不运行 Xray-core，只负责管理、配置下发、订阅生成
  • Node 才是真正跑代理流量的地方，内含 Xray-core
  • Panel 必须部署在反向代理后面，不可直接暴露到公网
  • Panel 与 Node 可以部署在同一台服务器，也可以异地分离

二、前置要求

2.1 服务器配置

组件 最低配置 推荐配置
CPU 1 核 2 核+
内存 1 GB 2 GB+
硬盘 20 GB 40 GB+
系统 Ubuntu 22.04 / Debian 12 Ubuntu 24.04

2.2 软件依赖

1
2
3
4
5
6
7
# 安装 Docker 和 Docker Compose（以 Ubuntu 为例）
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# 验证安装
docker --version
docker compose version

2.3 需要准备

  • ✅ 一台境外 VPS（Panel 和 Node 可同台或分离）
  • ✅ 一个域名（用于 Panel 管理后台和订阅地址）
  • ✅ 域名已解析到服务器 IP（DNS A 记录）
  • ✅ 服务器放行 80/443 端口

三、部署 Panel 管理后台

3.1 创建项目目录

1
mkdir -p /opt/remnawave && cd /opt/remnawave

3.2 创建 docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
cat > docker-compose.yml << 'EOF'
services:
  remnawave:
    image: remnawave/backend:latest
    container_name: remnawave
    hostname: remnawave
    restart: always
    env_file:
      - .env
    ports:
      - "127.0.0.1:3000:3000"     # Panel API / 前端
      - "127.0.0.1:3001:3001"     # Metrics 监控端口
    depends_on:
      remnawave-db:
        condition: service_healthy
      remnawave-redis:
        condition: service_healthy
    networks:
      - remnawave-network

  remnawave-db:
    image: postgres:17
    container_name: remnawave-db
    hostname: remnawave-db
    restart: always
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - remnawave-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - remnawave-network

  remnawave-redis:
    image: redis:7
    container_name: remnawave-redis
    hostname: remnawave-redis
    restart: always
    volumes:
      - remnawave-redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - remnawave-network

volumes:
  remnawave-db-data:
    driver: local
  remnawave-redis-data:
    driver: local

networks:
  remnawave-network:
    driver: bridge
EOF

3.3 创建 .env 配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
cat > .env << 'EOF'
# ============================
# 应用基础配置
# ============================
APP_PORT=3000
METRICS_PORT=3001
API_INSTANCES=1

# ============================
# JWT 安全密钥（务必替换！）
# ============================
JWT_AUTH_SECRET=替换为随机密钥
JWT_API_TOKENS_SECRET=替换为随机密钥

# ============================
# 数据库配置
# ============================
POSTGRES_USER=remnawave
POSTGRES_PASSWORD=替换为强密码
POSTGRES_DB=remnawave
DATABASE_URL=postgresql://remnawave:替换为强密码@remnawave-db:5432/remnawave

# ============================
# Redis 配置
# ============================
REDIS_HOST=remnawave-redis
REDIS_PORT=6379

# ============================
# 域名配置（务必替换！）
# ============================
# Panel 管理后台访问域名，含协议前缀
FRONT_END_DOMAIN=https://panel.yourdomain.com

# 订阅地址域名（用户订阅链接的前缀）
SUB_PUBLIC_DOMAIN=https://panel.yourdomain.com/api/sub
EOF

生成安全密钥（必须执行，替换上方默认值）：

1
2
3
4
5
# 生成 JWT_AUTH_SECRET
openssl rand -hex 64

# 生成 JWT_API_TOKENS_SECRET
openssl rand -hex 64

将两条命令的输出分别填入 .env 对应字段。

⚠️ 安全警告：.env 文件包含数据库密码和 JWT 密钥，请设置严格权限：

1
chmod 600 /opt/remnawave/.env

3.4 配置反向代理（以 Nginx 为例）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# 安装 Nginx 和 certbot
apt install -y nginx certbot python3-certbot-nginx

# 申请 SSL 证书
certbot --nginx -d panel.yourdomain.com

# 创建 Nginx 配置
cat > /etc/nginx/sites-available/remnawave << 'EOF'
server {
    listen 80;
    server_name panel.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name panel.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/panel.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.yourdomain.com/privkey.pem;

    # 安全头
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "DENY" always;
    add_header X-XSS-Protection "1; mode=block" always;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

ln -s /etc/nginx/sites-available/remnawave /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

3.5 启动 Panel

1
2
3
4
5
6
cd /opt/remnawave
docker compose up -d

# 查看启动状态
docker compose ps
docker compose logs -f remnawave

启动成功后，浏览器访问 https://panel.yourdomain.com 即可看到管理界面。

🎉 首次访问：Panel 会引导你创建管理员账户，按提示操作即可。

四、部署节点（Node）

节点是实际运行 Xray-core、承载代理流量的服务。

4.1 在 Panel 中创建节点配置

  1. 登录管理后台，进入 节点管理（Nodes）→ 管理
  2. 点击 + 按钮，填写节点信息：
    • 节点名称：随意命名，如 “香港 01”
    • 节点地址：节点服务器的 IP 或域名
    • API 端口：默认 2222（节点与 Panel 通信用，不对公网暴露）
  3. 保存后，点击 “复制 docker-compose.yml” 按钮

Panel 会自动生成包含认证 Token 的节点配置文件。

4.2 在节点服务器上部署

1
2
3
4
5
6
7
8
9
10
11
# 创建节点目录
mkdir -p /opt/remnanode && cd /opt/remnanode

# 将 Panel 生成的 docker-compose.yml 内容粘贴到此处
vim docker-compose.yml

# 启动节点
docker compose up -d

# 验证连接状态
docker compose logs -f

节点启动后，回到 Panel 的节点列表，状态应显示为在线（Online）。

4.3 典型节点 docker-compose.yml（参考格式）

Panel 自动生成的文件内容类似如下（实际 Token 由 Panel 注入）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
services:
  remnawave-node:
    image: remnawave/node:latest
    container_name: remnawave-node
    restart: always
    environment:
      - APP_PORT=2222
      - REMNAWAVE_PANEL_URL=https://panel.yourdomain.com
      - REMNAWAVE_NODE_TOKEN=<Panel自动生成的Token>
    ports:
      - "0.0.0.0:2222:2222"   # Panel 与 Node 内部通信
      - "0.0.0.0:443:443"     # 用户代理流量
      - "0.0.0.0:80:80"
    volumes:
      - remnanode-data:/opt/remnawave-node/data

volumes:
  remnanode-data:
    driver: local

五、创建入站协议（Inbound）

节点上线后，需要在 Panel 配置入站流量协议。

5.1 常用协议配置

进入 配置（Config）→ 入站（Inbounds）→ 添加：

VLESS + REALITY（推荐，抗封锁能力最强）：

参数 值
协议 VLESS
传输方式 TCP
安全性 Reality
目标域名 www.apple.com（或其他 TLS 网站）
端口 443

Trojan + TLS：

参数 值
协议 Trojan
传输方式 TCP
安全性 TLS
证书 填写你的域名证书路径

5.2 创建用户

进入 用户管理（Users）→ 添加，配置：

  • 用户名
  • 流量配额（0 = 不限）
  • 到期时间
  • 关联节点（选择已上线的节点）

六、获取订阅链接

用户创建完成后，Panel 会自动生成订阅链接，格式如下：

1
https://panel.yourdomain.com/api/sub/<用户Token>

将此链接填入客户端即可一键导入所有配置节点。

6.1 推荐客户端

平台 推荐客户端 下载地址
iOS Shadowrocket / Sing-box App Store
Android NekoBox / Hiddify GitHub Releases
Windows v2rayN / Hiddify GitHub Releases
macOS ClashX / Mihomo Party GitHub Releases
Linux sing-box GitHub Releases

七、常用运维命令

7.1 Panel 管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
cd /opt/remnawave

# 查看运行状态
docker compose ps

# 查看实时日志
docker compose logs -f remnawave

# 更新 Panel（拉取最新镜像）
docker compose pull
docker compose up -d

# 停止服务
docker compose down

# 停止并清数据（慎用！）
docker compose down -v

7.2 修改配置文件后重启

1
2
# 环境变量变更必须重建容器
docker compose down && docker compose up -d

7.3 数据备份

1
2
3
4
5
6
# 备份 PostgreSQL 数据
docker exec remnawave-db pg_dump -U remnawave remnawave > backup_$(date +%F).sql

# 备份整个数据卷
docker run --rm -v remnawave_remnawave-db-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/db-backup-$(date +%F).tar.gz /data

八、故障排查

8.1 Panel 无法访问

1
2
3
4
5
6
7
8
# 检查容器是否正常运行
docker compose ps

# 查看 Panel 日志
docker compose logs remnawave | tail -50

# 检查端口监听
ss -tlnp | grep 3000

8.2 节点离线

1
2
3
4
5
6
7
8
9
# 在节点服务器检查日志
docker compose logs remnawave-node | tail -50

# 验证 Panel 与节点连通性（从节点服务器执行）
curl -v https://panel.yourdomain.com/health

# 检查防火墙
ufw status
# 确保节点的 2222 端口对 Panel 服务器 IP 开放

8.3 数据库连接失败

1
2
3
4
5
# 检查 PostgreSQL 健康状态
docker exec remnawave-db pg_isready -U remnawave -d remnawave

# 检查 DATABASE_URL 格式是否与密码一致
grep DATABASE_URL /opt/remnawave/.env

九、进阶配置

9.1 Cloudflare Tunnel（替代反向代理）

如果你的服务器被封锁或无法配置 HTTPS，可以使用 Cloudflare Tunnel 作为替代方案：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 安装 cloudflared
wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
dpkg -i cloudflared-linux-amd64.deb

# 登录 Cloudflare
cloudflared tunnel login

# 创建隧道
cloudflared tunnel create remnawave

# 配置隧道指向本地 Panel
cat > ~/.cloudflared/config.yml << 'CONF'
tunnel: <你的隧道ID>
credentials-file: /root/.cloudflared/<你的隧道ID>.json

ingress:
  - hostname: panel.yourdomain.com
    service: http://localhost:3000
  - service: http_status:404
CONF

# 启动并设置自启
cloudflared service install

9.2 启用 Metrics 监控

Panel 的 3001 端口暴露 Prometheus 格式的监控指标，可以接入 Grafana 进行可视化：

1
2
3
4
5
6
# 在 Nginx 配置中添加 metrics 路径（仅限内网访问）
location /metrics {
    allow 127.0.0.1;
    deny all;
    proxy_pass http://127.0.0.1:3001;
}

9.3 API 二次开发

Remnawave 提供了完整的 REST API，适合自动化运维：

1
2
3
4
# 在 Panel 设置中生成 API Token
# 示例：查询用户列表
curl -H "Authorization: Bearer <你的API Token>" \
  https://panel.yourdomain.com/api/v1/users

官方还有社区维护的 Python SDK，可用于批量自动化管理。

十、总结

Remnawave Panel 对比同类工具（Marzban、3X-UI）的核心优势：

特性 Remnawave Marzban 3X-UI
架构 Panel + Node 分离 一体式 一体式
多节点管理 ✅ 原生支持 ✅ ⚠️ 有限
REST API ✅ 完整文档 ⚠️ ❌
技术栈 NestJS + TS Python Go
活跃度 高（96+ 版本） 高 中
授权协议 AGPL-3.0 AGPL-3.0 MIT

适合场景：

  • 🏢 需要管理多台节点服务器的团队
  • 👨‍💻 希望通过 API 进行自动化运营的开发者
  • 🔒 对安全性要求高（Panel/Node 分离架构）
  • 📈 需要监控和统计功能的运营场景

部署成本参考：

  • Panel 服务器：国内/海外 VPS，2GB 内存起，年付 ~¥300
  • Node 节点：境外流量服务器，1GB 内存起，年付 ~¥150/台
  • 域名：~¥50/年

📌 官方资源

⚠️ 合规提醒：请务必在当地法律法规允许的范围内使用，自建服务仅限个人合规用途。