flvx/vitepress/guide.md

# 使用指南

哆啦A梦是一个基于 go-gost 的现代化转发面板，提供了直观的 Web 界面来管理网络流量转发。

::: tip 需要帮助？
📱 [加入 Telegram 群组](https://t.me/+wdVDni1fdyI0YzE1) | 🐛 [GitHub Issues](https://github.com/bqlpfy/forward-panel/issues) | 🤝 [参与贡献](https://github.com/bqlpfy/forward-panel/pulls)
:::

## 项目介绍

### 核心功能

- 🔄 **TCP/UDP/TLS 端口转发**: 支持多种协议的流量转发
- 👥 **用户管理**: 按账号级别管理流量转发数量和流量限额
- 📊 **流量统计**: 支持双向/单向计费模式，实时监控
- ⚡ **限速控制**: 可创建限速规则进行精细化流量控制
- 🖥️ **节点管理**: 分布式节点部署和监控
- 🚇 **隧道管理**: 灵活的隧道配置和管理
- 🔒 **安全可控**: 内置认证系统，权限分级管理

### 技术架构

- **前端**: Vue.js 2 + Element UI
- **后端**: Spring Boot + MySQL
- **转发引擎**: go-gost
- **部署方式**: Docker Compose

## 第一步：登录系统

安装完成后，打开浏览器访问面板地址：

```
http://your-server-ip:6366
```

使用默认管理员账号登录：
- **用户名**: `admin_user`
- **密码**: `admin_user`

## 第二步：修改默认密码

登录后**务必立即修改默认密码**：

## 第三步：创建节点

节点是运行转发服务的服务器，需要先创建节点才能部署转发服务。

### 添加节点

1. 在左侧菜单点击 **"节点管理"**
2. 点击 **"新增节点"** 按钮
3. 填写节点信息：
   - **节点名称**: 自定义名称（如：香港节点-01）
   - **服务器IP**: 节点服务器的IP地址
   - **入口IP**: 节点服务器的IP地址

4. 点击 **"确定"** 保存节点

### IP地址说明

**服务器IP**：
- 用于创建隧道转发时入口-出口两台服务器之间的通信地址
- 通常是服务器的主要通信IP
- 确保入口和出口节点能够通过此IP互相访问

**入口IP**：
- 用于展示在转发页面，面向用户的访问地址
- 适用于有多个IP的服务器（如多线BGP）

**兜底**：
- 实在理解不到说明你没这个需求，都填节点的公网ip就行


### 节点状态说明

- 🟢 **在线**: 节点正常运行，可以查看CPU、内存等系统信息
- 🔴 **离线**: 节点未连接或agent未安装

## 第四步：安装节点Agent

创建节点后，需要在对应的服务器上安装agent程序。

### 获取安装命令

1. 在节点列表中找到刚创建的节点
2. 点击节点卡片中的 **"复制安装命令"** 按钮
3. 系统会自动复制安装命令到剪贴板

### 执行安装

在目标服务器上执行复制的安装命令：

```bash
# 示例安装命令（实际命令请从面板复制）
curl -L https://your-panel-server:6365/agent/install | bash -s -- --server=your-panel-server:6365 --token=your-node-token
```

### 须知
- 安装或者更新时如果/etc/gost/下存在gost.json和config.json，安装命令会跳过生成，使用当前存在的配置
- gost执行文件会强制更新

### 验证安装

安装完成后，回到面板查看节点状态：
- 节点状态应该变为 🟢 **在线**
- 可以看到CPU使用率、内存使用率等系统信息

## 第五步：创建隧道

隧道定义了流量的入口和出口节点。

### 添加隧道

1. 在左侧菜单点击 **"隧道管理"**
2. 点击 **"新增隧道"** 按钮
3. 配置隧道参数：

**基本信息**：
- **隧道名称**: 自定义名称（如：Web服务隧道）
- **隧道类型**: 
  - **端口转发**: 在单个节点上进行直接端口映射
  - **隧道转发**: 在入口节点和出口节点之间建立隧道连接
- **流量计算**: 
  - 单向计算（仅上传）：仅计算上传流量
  - 双向计算：计算上传和下载的总流量
- **流量倍率**: 计费倍率（默认1.0，设置为2.0表示按实际流量的2倍计费，范围：0.0-100.0）

**入口配置**：
- **入口节点**: 选择流量入口节点
- **起始端口**: 端口范围起始值（默认1）
- **结束端口**: 端口范围结束值（默认65535）
- **监听地址**: 部分专线需要，如果不理解保持默认即可

**出口配置**（仅隧道转发类型需要）：
- **协议类型**: 保持默认即可，如有特殊需求可选择：
  - TLS：数据过墙推荐选择
  - TCP：普通场景
  - MTLS: 多路复用的TLS
- **出口节点**: 选择流量出口节点
- **起始端口**: 出口端口范围起始值（默认1）
- **结束端口**: 出口端口范围结束值（默认65535）

4. 点击 **"创建"** 保存隧道

### 隧道流程图

创建后可以在隧道列表中看到流程图：
```
入口节点 → 出口节点 → 目标服务
```

## 第六步：创建转发

转发规则定义了具体的端口映射关系。

### 添加转发

1. 在左侧菜单点击 **"转发管理"**
2. 点击 **"新增转发"** 按钮
3. 配置转发参数：

**基本信息**：
- **转发名称**: 自定义名称（如：SSH转发）
- **选择隧道**: 选择已创建的隧道

**端口配置**：
- **入口端口**: 
  - **端口**: 手动指定端口号
  - **留空自动分配**: 系统自动分配可用端口
  - 建议：先选择隧道以查看端口范围，留空将自动分配可用端口

**目标配置**：
- **远程地址**: 最终目标服务地址，支持多种格式：
  - IPv4：`192.168.1.100:8080`
  - IPv6：`[2001:db8::1]:8080`
  - 域名：`example.com:8080`

**示例配置**：
```
转发名称: SSH服务转发
选择隧道: Web服务隧道
入口端口: 留空自动分配（或手动指定如 2222）
远程地址: 192.168.1.100:22
```

4. 点击 **"确定"** 保存转发规则



## 第七步：用户管理（可选）

如果需要多用户使用，可以创建普通用户账号并分配资源。

### 创建用户

1. 在左侧菜单点击 **"用户管理"**
2. 点击 **"新增用户"** 按钮
3. 填写用户信息：

**基本信息**：
- **用户名**: 登录用户名（如：15284851274）
- **密码**: 登录密码（系统会自动加密显示）

**资源限制**：
- **流量(GB)**: 总流量限额，如需无限制可设置较大数值（如999999）
- **转发数量**: 可创建的转发数量，如需无限制可设置较大数值（如999999）
- **过期时间**: 账号有效期，可选择具体日期
- **流量重置**: 流量重置周期，默认"每月1号（0点重置）"

**账号状态**：
- **正常**: 用户可正常使用
- **禁用**: 暂停用户使用

**示例配置**：
```
用户名: user001
密码: ********
流量(GB): 100（或999999表示无限制）
转发数量: 10（或999999表示无限制）
过期时间: 2025-12-31
流量重置: 每月1号（0点重置）
状态: 正常
```

4. 点击 **"确定"** 创建用户

### 分配隧道权限

创建用户后，需要为用户分配具体的隧道使用权限：

1. 在用户列表中找到目标用户
2. 点击用户的 **"隧道权限管理"** 按钮
3. 在弹出窗口中配置权限：

**分配新隧道权限**：
- **选择隧道**: 选择要分配给用户的隧道
- **流量限制(GB)**: 该隧道的流量限额
- **转发数量**: 该隧道允许创建的转发数量
- **到期时间**: 该隧道权限的有效期
- **限速规则**: 选择是否应用限速（默认"不限速"）

4. 点击 **"分配权限"** 保存配置

**权限管理**：
- 在"已有隧道权限"列表中可以查看用户的所有隧道权限
- 显示每个隧道的状态、流量统计、转发数量、限速规则、到期时间
- 可以编辑或删除现有权限

### 权限优先级说明

系统采用两级权限管理，优先级如下：

**用户级别权限（优先级最高）**：
- 用户的流量限额和转发数量限制影响该用户的所有转发
- 即使隧道权限设置更大的限额，也不能超过用户级别的总限制
- 例如：用户总流量100GB，即使单个隧道分配200GB，用户实际最多只能使用100GB

**隧道级别权限**：
- 隧道的流量和转发数量限制只影响对应的隧道
- 在用户总限额范围内，进一步细分到具体隧道的使用限制
- 例如：用户总流量100GB，可以分配给隧道A 60GB，隧道B 40GB


## 第八步：限速规则（可选）

如果需要对特定用户或隧道进行限速，需要先创建限速规则。

### 创建限速规则

1. 在左侧菜单点击 **"限速规则"**
2. 点击 **"新增限速"** 按钮
3. 配置限速参数：

**基本配置**：
- **规则名称**: 自定义限速规则名称（如：游戏隧道限速）
- **速度限制**: 设置带宽限制值
  - 单位：Mbps（兆比特每秒）
  - 范围：1-1000000 Mbps
  - 例如：100 表示限制带宽为100Mbps
- **绑定隧道**: 选择要应用此限速规则的隧道

**示例配置**：
```
规则名称: 普通用户限速
速度限制: 100 Mbps
绑定隧道: Web服务隧道
```

4. 点击 **"确定"** 保存限速规则

## 获取帮助

### 社区支持

如果在使用过程中遇到问题或有功能建议，推荐以下方式获取帮助：

1. **💬 Telegram 群组**（推荐）
   - [立即加入](https://t.me/+wdVDni1fdyI0YzE1)
   - 实时讨论，快速回复
   - 与其他用户交流经验

2. **🐛 GitHub Issues**
   - [报告问题](https://github.com/bqlpfy/forward-panel/issues/new)
   - 查看 [已知问题](https://github.com/bqlpfy/forward-panel/issues)
   - 提交功能建议

3. **📖 文档资源**
   - [快速开始指南](/getting-started)
   - [常见问题解答](/faq)
   - [项目架构说明](/project-structure)

### 故障排除

#### 安装相关问题

**问题**: Agent 安装失败
- 检查服务器网络连接
- 确认防火墙设置（开放 6365 端口）
- 使用 `sudo` 权限执行安装命令

**问题**: 节点显示离线
- 检查 Agent 服务状态：`systemctl status gost-agent`
- 查看 Agent 日志：`journalctl -u gost-agent -f`
- 确认面板地址和端口可访问

#### 转发相关问题

**问题**: 转发无法正常工作
- 检查端口是否被占用
- 确认目标地址可达性
- 验证隧道状态是否正常

**问题**: 流量统计异常
- 确认转发规则配置正确
- 检查流量计算方式设置
- 重启相关服务进行重置

#### 权限相关问题

**问题**: 用户无法创建转发
- 检查用户账号状态
- 确认隧道权限分配
- 验证流量和转发数量限制

### 联系开发者

对于紧急问题：

- **GitHub**: [@bqlpfy](https://github.com/bqlpfy)
- **Telegram**: [加入群组](https://t.me/+wdVDni1fdyI0YzE1) 直接联系

## 免责声明

本项目仅供个人学习与研究使用，基于开源项目进行二次开发。使用本项目所带来的任何风险由使用者自行承担。请确保在合法、合规、安全的前提下使用本项目。