arc-frp/app/README.md

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
• <EFBFBD> Push to Node: Deploy configurations to remote nodes with one click
• 🌐 Live Monitoring: Real-time node connectivity and status tracking
• <EFBFBD>🐳 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:

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.

Quick Start

Using Docker Compose (Recommended)

1. Clone the repository:

git clone <repository-url>
cd frp-manager

2. Create environment configuration:

cp .env.example .env

3. Edit .env with your FRP server details:

FRPC_SERVER_ADDR=your-vps-ip-address
FRPC_SERVER_PORT=7000
FRPC_TOKEN=your-secret-token

4. Start the application:

docker-compose up -d

5. Access the web interface at http://localhost:3000

Manual Installation

1. Install dependencies:

npm install

2. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

3. Start development server:

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

# 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:

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