4169337dd0
Some checks failed
Build All Docker Images / changes (push) Has been cancelled
Build and Push App Docker Image / build (push) Has been cancelled
Build and Push Node Docker Image / build (push) Has been cancelled
Test and Lint / test-app (push) Has been cancelled
Test and Lint / test-node (push) Has been cancelled
Test and Lint / lint-dockerfiles (push) Has been cancelled
Test and Lint / security-scan (push) Has been cancelled
Build All Docker Images / build-app (push) Has been cancelled
Build All Docker Images / build-node (push) Has been cancelled
Build All Docker Images / summary (push) Has been cancelled
270 lines
7 KiB
Markdown
270 lines
7 KiB
Markdown
# FRP Manager
|
||
|
||
A fullstack application for managing FRP (Fast Reverse Proxy) tunnel configurations with a React frontend and Express backend. Now with **Node Integration** for remote management of home server FRP clients.
|
||
|
||
## Features
|
||
|
||
- 🚀 **Web Dashboard**: Modern React-based interface for managing tunnels
|
||
- 🔧 **Tunnel Management**: Create, edit, delete, and toggle tunnel configurations
|
||
- 📊 **Real-time Status**: Monitor tunnel status and FRPC service health
|
||
- 🏠 **Node Integration**: Remote control of home server FRP clients
|
||
- <20> **Push to Node**: Deploy configurations to remote nodes with one click
|
||
- 🌐 **Live Monitoring**: Real-time node connectivity and status tracking
|
||
- <20>🐳 **Docker Support**: Complete Docker Compose setup for easy deployment
|
||
- 📝 **Auto Configuration**: Automatically generates FRPC configuration from active tunnels
|
||
- 🗄️ **SQLite Database**: Persistent storage for tunnel configurations
|
||
- 📋 **Service Logs**: View FRPC service logs directly from the web interface
|
||
|
||
## Tech Stack
|
||
|
||
**Frontend:**
|
||
- React 19
|
||
- TypeScript
|
||
- React Router
|
||
- TanStack Query (React Query)
|
||
- Lucide React Icons
|
||
- React Hot Toast
|
||
|
||
**Backend:**
|
||
- Node.js
|
||
- Express
|
||
- TypeScript
|
||
- SQLite (better-sqlite3)
|
||
- Zod validation
|
||
- Winston logging
|
||
- Axios (for node communication)
|
||
|
||
**Infrastructure:**
|
||
- Docker & Docker Compose
|
||
- FRPC (Fast Reverse Proxy Client)
|
||
|
||
## New: Node Integration
|
||
|
||
The FRP Manager now supports remote management of home server nodes. This allows you to:
|
||
|
||
- **Query Status**: Get real-time status from your home server node
|
||
- **Push Configs**: Send updated frpc.toml configurations remotely
|
||
- **Restart Services**: Restart FRP client on the home server
|
||
- **Monitor Connectivity**: Live status indicators and connection tracking
|
||
|
||
### Setup Node Integration
|
||
|
||
1. **Configure the app** with node connection details in `.env`:
|
||
```bash
|
||
NODE_URL=http://your-home-server:3001
|
||
NODE_TOKEN=your-node-secret-token
|
||
NODE_TIMEOUT=5000
|
||
```
|
||
|
||
2. **Set up the home server node** (see `../node/` directory)
|
||
|
||
3. **Use the web interface** to push configurations with the "Push to Node" button
|
||
|
||
For detailed setup instructions, see [NODE_INTEGRATION.md](../NODE_INTEGRATION.md).
|
||
|
||
## Quick Start
|
||
|
||
### Using Docker Compose (Recommended)
|
||
|
||
1. Clone the repository:
|
||
```bash
|
||
git clone <repository-url>
|
||
cd frp-manager
|
||
```
|
||
|
||
2. Create environment configuration:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
3. Edit `.env` with your FRP server details:
|
||
```bash
|
||
FRPC_SERVER_ADDR=your-vps-ip-address
|
||
FRPC_SERVER_PORT=7000
|
||
FRPC_TOKEN=your-secret-token
|
||
```
|
||
|
||
4. Start the application:
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
5. Access the web interface at `http://localhost:3000`
|
||
|
||
### Manual Installation
|
||
|
||
1. Install dependencies:
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
2. Set up environment variables:
|
||
```bash
|
||
cp .env.example .env
|
||
# Edit .env with your configuration
|
||
```
|
||
|
||
3. Start development server:
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
4. Access the application at `http://localhost:3000`
|
||
|
||
## Configuration
|
||
|
||
### Environment Variables
|
||
|
||
| Variable | Description | Default |
|
||
|----------|-------------|---------|
|
||
| `FRPC_SERVER_ADDR` | FRP server IP address | `your-vps-ip` |
|
||
| `FRPC_SERVER_PORT` | FRP server port | `7000` |
|
||
| `FRPC_TOKEN` | FRP authentication token | - |
|
||
| `NODE_ENV` | Node environment | `development` |
|
||
| `PORT` | Application port | `3000` |
|
||
|
||
### Tunnel Configuration
|
||
|
||
Each tunnel requires:
|
||
- **Name**: Descriptive name (e.g., "Minecraft Server")
|
||
- **Protocol**: TCP or UDP
|
||
- **Local IP**: IP address of the service on your network
|
||
- **Local Port**: Port of the service on your network
|
||
- **Remote Port**: Port to expose on the FRP server
|
||
- **Enabled**: Whether the tunnel is active
|
||
|
||
## Usage
|
||
|
||
### Adding a Tunnel
|
||
|
||
1. Navigate to the "Tunnels" page
|
||
2. Click "Add Tunnel"
|
||
3. Fill in the tunnel details:
|
||
- Name: "Minecraft Server"
|
||
- Protocol: TCP
|
||
- Local IP: 192.168.1.100
|
||
- Local Port: 25565
|
||
- Remote Port: 25565
|
||
- Enabled: ✓
|
||
4. Click "Create"
|
||
|
||
### Managing Tunnels
|
||
|
||
- **Edit**: Click the edit button to modify tunnel settings
|
||
- **Toggle**: Use the power button to enable/disable tunnels
|
||
- **Delete**: Remove tunnels you no longer need
|
||
- **Status**: View real-time tunnel status on the dashboard
|
||
|
||
### Service Management
|
||
|
||
Use the "Server Status" page to:
|
||
- Start/Stop/Restart the FRPC service
|
||
- Regenerate FRPC configuration
|
||
- View service logs
|
||
- Monitor system health
|
||
|
||
## API Endpoints
|
||
|
||
### Tunnels
|
||
- `GET /api/tunnels` - Get all tunnels
|
||
- `POST /api/tunnels` - Create new tunnel
|
||
- `GET /api/tunnels/:id` - Get tunnel by ID
|
||
- `PUT /api/tunnels/:id` - Update tunnel
|
||
- `DELETE /api/tunnels/:id` - Delete tunnel
|
||
- `GET /api/tunnels/:id/status` - Get tunnel status
|
||
|
||
### FRPC Service
|
||
- `GET /api/frpc/status` - Get service status
|
||
- `POST /api/frpc/start` - Start service
|
||
- `POST /api/frpc/stop` - Stop service
|
||
- `POST /api/frpc/restart` - Restart service
|
||
- `POST /api/frpc/regenerate` - Regenerate configuration
|
||
- `GET /api/frpc/logs` - Get service logs
|
||
|
||
## Development
|
||
|
||
### Project Structure
|
||
|
||
```
|
||
app/
|
||
├── src/
|
||
│ ├── client/ # React frontend
|
||
│ │ ├── api/ # API client
|
||
│ │ ├── components/ # React components
|
||
│ │ ├── pages/ # Page components
|
||
│ │ └── App.tsx # Main App component
|
||
│ └── server/ # Express backend
|
||
│ ├── database.ts # Database layer
|
||
│ ├── frpc-manager.ts # FRPC management
|
||
│ ├── logger.ts # Logging utilities
|
||
│ ├── main.ts # Server entry point
|
||
│ ├── routes.ts # API routes
|
||
│ └── types.ts # TypeScript types
|
||
├── public/ # Static assets
|
||
├── data/ # Database and config files
|
||
├── logs/ # Application logs
|
||
└── docker-compose.yml # Docker configuration
|
||
```
|
||
|
||
### Scripts
|
||
|
||
```bash
|
||
# Development
|
||
npm run dev # Start development server
|
||
|
||
# Production
|
||
npm run build # Build application
|
||
npm start # Start production server
|
||
|
||
# Docker
|
||
docker-compose up # Start all services
|
||
docker-compose down # Stop all services
|
||
```
|
||
|
||
### Contributing
|
||
|
||
1. Fork the repository
|
||
2. Create a feature branch
|
||
3. Make your changes
|
||
4. Test thoroughly
|
||
5. Submit a pull request
|
||
|
||
## Troubleshooting
|
||
|
||
### Common Issues
|
||
|
||
**FRPC service won't start:**
|
||
- Check if the server address and port are correct
|
||
- Verify the authentication token
|
||
- Ensure the FRPC container has the updated configuration
|
||
|
||
**Tunnels show as inactive:**
|
||
- Verify the local service is running
|
||
- Check firewall settings
|
||
- Ensure the local IP and port are correct
|
||
|
||
**Database errors:**
|
||
- Check if the `data` directory exists and is writable
|
||
- Verify SQLite permissions
|
||
|
||
### Logs
|
||
|
||
Application logs are stored in the `logs` directory:
|
||
- `combined.log`: All application logs
|
||
- `error.log`: Error logs only
|
||
|
||
FRPC logs can be viewed through the web interface or directly:
|
||
```bash
|
||
docker logs frpc
|
||
```
|
||
|
||
## License
|
||
|
||
MIT License - see LICENSE file for details.
|
||
|
||
## Support
|
||
|
||
For issues and questions:
|
||
1. Check the troubleshooting section
|
||
2. Review the logs for error messages
|
||
3. Open an issue on the repository
|