arc-frp/NODE_INTEGRATION.md

FRP Manager - Node Integration Setup

This guide explains how to set up the integration between the FRP Manager app and the home server node.

Overview

The integration allows the FRP Manager app (running on your VPS) to:

• Query the home server node for status
• Send updated frpc.toml configurations
• Restart the FRP client remotely
• Monitor node connectivity

Setup Instructions

1. Environment Configuration

App (.env file)

# Copy from .env.example and configure these variables:

# FRP Server Configuration
FRPC_SERVER_ADDR=your-vps-ip-address
FRPC_SERVER_PORT=7000
FRPC_TOKEN=your-secret-token

# Node Integration
NODE_URL=http://your-home-server-ip:3001
NODE_TOKEN=your-node-secret-token
NODE_TIMEOUT=5000

Node (.env file)

# Copy from .env.example and configure these variables:

# Authentication
API_TOKEN=your-node-secret-token

# FRP Configuration
FRPC_CONFIG_PATH=/app/data/frpc.toml
FRPC_CONTAINER_NAME=frpc

2. Security Considerations

Important: Use the same token for NODE_TOKEN in the app and API_TOKEN in the node for authentication.

• Generate a strong, random token (e.g., 32+ character string)
• Keep tokens secure and never commit them to version control
• Use HTTPS in production for encrypted communication

3. Network Setup

Port Configuration

• App: Runs on port 3000 (configurable)
• Node: Runs on port 3001 (configurable)

Firewall Rules

Ensure the node port (3001) is accessible from your VPS:

# On your home server (if using UFW)
sudo ufw allow 3001/tcp

Network Access

• The app needs HTTP/HTTPS access to the node
• Consider using a VPN or port forwarding if the node is behind NAT
• For production, use HTTPS with proper certificates

4. Docker Deployment

Starting the App (VPS)

cd app/
cp .env.example .env
# Edit .env with your configuration
docker-compose up -d

Starting the Node (Home Server)

cd node/
cp .env.example .env
# Edit .env with your configuration
docker-compose up -d

5. API Endpoints

Node Endpoints (Protected by API_TOKEN)

• GET /api/status - Get server status
• GET /api/frpc/status - Get frpc container status
• POST /api/frpc/update-config - Update frpc configuration
• POST /api/frpc/restart - Restart frpc container
• POST /api/frpc/push-and-restart - Update config and restart in one call

App Endpoints (Node Integration)

• GET /api/node/status - Get node status through app
• GET /api/node/connection - Get node connection info
• POST /api/node/push-config - Push current config to node
• POST /api/node/restart-frpc - Restart frpc on node
• POST /api/node/push-and-restart - Push config and restart frpc on node

6. Frontend Features

Dashboard

• Live node status indicator
• Connection monitoring
• Last connection time tracking

Tunnel Manager

• "Push to Node" button for deploying configurations
• Real-time node connectivity status
• Error handling and user feedback

7. Testing the Integration

1. Verify Node Connectivity

# From your VPS, test the node endpoint
curl -H "Authorization: Bearer your-node-secret-token" \
     http://your-home-server-ip:3001/health

2. Test Configuration Push

1. Create/modify tunnels in the app
2. Click "Push to Node" button
3. Verify configuration updated on the node
4. Check that frpc restarted successfully

3. Monitor Logs

# App logs
docker logs frp-manager

# Node logs
docker logs home-server-agent

# FRP client logs
docker logs frpc

8. Troubleshooting

Common Issues

"Node client not configured"

• Check that NODE_URL and NODE_TOKEN are set in app environment
• Verify environment variables are loaded correctly

"Failed to connect to node"

• Verify node is running and accessible
• Check firewall rules
• Ensure correct IP address and port
• Verify token authentication

"frpc container not found"

• Ensure frpc container exists with the correct name
• Check FRPC_CONTAINER_NAME environment variable
• Verify Docker is accessible from the node

Debugging Steps

1. Check Environment Variables

   # In app container
   docker exec frp-manager env | grep NODE_
   
   # In node container
   docker exec home-server-agent env | grep API_TOKEN
   

2. Test Direct API Calls

   # Test node health endpoint (no auth required)
   curl http://your-home-server-ip:3001/health
   
   # Test authenticated endpoint
   curl -H "Authorization: Bearer your-token" \
        http://your-home-server-ip:3001/api/status
   

3. Check Container Status

   # On home server
   docker ps | grep frpc
   docker logs frpc
   

9. Production Considerations

Security

• Use HTTPS with valid certificates
• Implement IP whitelisting if possible
• Regular token rotation
• Monitor authentication logs

Monitoring

• Set up health checks for both app and node
• Monitor node connectivity from app
• Log all configuration changes
• Set up alerts for connection failures

Backup

• Backup frpc configurations
• Backup tunnel database
• Document recovery procedures

Usage Examples

Deploying New Tunnel Configuration

1. Add/Edit Tunnels: Use the web interface to create or modify tunnel configurations
2. Push to Node: Click the "Push to Node" button in the Tunnel Manager
3. Verify: Check the dashboard for node status and tunnel activity

Manual Configuration Management

# Push configuration via API
curl -X POST -H "Authorization: Bearer app-token" \
     http://your-vps:3000/api/node/push-config

# Restart frpc on node
curl -X POST -H "Authorization: Bearer app-token" \
     http://your-vps:3000/api/node/restart-frpc

This integration provides a seamless way to manage FRP configurations across your infrastructure while maintaining security and monitoring capabilities.