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