{"id":27639488,"url":"https://github.com/missuo/snell-panel","last_synced_at":"2025-10-25T16:44:38.811Z","repository":{"id":285755083,"uuid":"853480410","full_name":"missuo/snell-panel","owner":"missuo","description":"Snell Panel for Surge","archived":false,"fork":false,"pushed_at":"2025-04-14T15:57:46.000Z","size":538,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-23T22:17:00.734Z","etag":null,"topics":["snell","snell-server","surge"],"latest_commit_sha":null,"homepage":"http://snell-panel.owo.nz/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/missuo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-06T18:35:59.000Z","updated_at":"2025-04-14T15:57:49.000Z","dependencies_parsed_at":"2025-04-02T14:39:12.124Z","dependency_job_id":null,"html_url":"https://github.com/missuo/snell-panel","commit_stats":null,"previous_names":["missuo/snell-panel"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/missuo%2Fsnell-panel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/missuo%2Fsnell-panel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/missuo%2Fsnell-panel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/missuo%2Fsnell-panel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/missuo","download_url":"https://codeload.github.com/missuo/snell-panel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250522297,"owners_count":21444512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["snell","snell-server","surge"],"created_at":"2025-04-23T22:17:04.526Z","updated_at":"2025-10-25T16:44:38.800Z","avatar_url":"https://github.com/missuo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Snell Panel for Surge\n\n## Overview\n\nSnell Panel is a comprehensive management system for Snell proxy nodes that provides unified node management and automatic subscription link generation. The system consists of a backend API server and multiple frontend interfaces (Web UI and iOS App) for seamless node administration.\n\n**Key Components:**\n- **Backend Server**: RESTful API server that manages nodes and generates subscription links\n- **Web UI**: Browser-based management interface accessible at [snell-panel.owo.nz](http://snell-panel.owo.nz)\n- **iOS App**: Native mobile application available through TestFlight for enhanced mobile experience\n\n## Features\n\n### Node Management\n- **Multi-node Support**: Unified management of multiple Snell proxy nodes\n- **Node Operations**: Add, delete, and modify node configurations\n- **Node Renaming**: Customize node names for better organization\n- **Relay Nodes**: Support for adding sub-nodes (relay/transit nodes) for advanced routing\n- **Real-time Monitoring**: Track node status and performance\n\n### Subscription Management\n- **Automatic Generation**: Generate subscription links compatible with Surge and other proxy clients\n- **Dynamic Updates**: Subscription links automatically reflect node changes\n- **Multiple Formats**: Support for various subscription formats\n\n### API \u0026 Integration\n- **RESTful API**: Complete API endpoints for programmatic node management\n- **Cross-platform**: API serves both Web UI and iOS App with consistent functionality\n- **Secure Access**: Token-based authentication for API security\n\n### User Interface\n- **Web UI**: Feature-rich browser interface for desktop management\n- **iOS App**: Native mobile app with optimized touch interface\n- **Responsive Design**: Consistent experience across all devices\n\n## How to Use\n\n### Method 1: Direct Binary Execution\n\n1. **Configure environment variables**\n\n   Create a `.env` file or set environment variables:\n\n   ```bash\n   export API_TOKEN=your_token_here\n   export DATABASE_URL=your_database_url_here  # e.g., postgres://user:pass@host:port/dbname\n   export PORT=8080  # Optional, defaults to 8080\n   ```\n\n2. **Start the Snell Panel server**\n\n   ```bash\n   ./snell-panel\n   ```\n\n### Method 2: Using Docker Compose (Recommended)\n\n1. **Configure the compose.yaml file**\n\n   Edit the `compose.yaml` file and update the environment variables:\n\n   ```yaml\n   environment:\n     - API_TOKEN=your_token_here\n     - DATABASE_URL=your_database_url_here\n   ```\n\n2. **Start the service**\n\n   ```bash\n   docker-compose up -d\n   ```\n\n   The service will be available on port 9997.\n\n### Method 3: Using Docker\n\n1. **Build the Docker image**\n\n   ```bash\n   docker build -t snell-panel .\n   ```\n\n2. **Run the container**\n\n   ```bash\n   docker run -d \\\n     --name snell-panel \\\n     -p 8080:8080 \\\n     -e API_TOKEN=your_token_here \\\n     -e DATABASE_URL=your_database_url_here \\\n     snell-panel\n   ```\n\n### Method 4: Vercel Serverless Deployment\n\n1. **Set up Supabase Database**\n\n   - Go to [supabase.com](https://supabase.com) and create a new project\n   - Navigate to Settings \u003e Database and copy the connection string\n   - The connection string format should be: `postgresql://postgres:[YOUR-PASSWORD]@[YOUR-HOST]:[YOUR-PORT]/postgres`\n\n   **Detailed Steps:**\n   - Create a Supabase account and new project\n   - Go to Project Settings → Database\n   - Under \"Connection string\", select \"URI\" \n   - Copy the connection string (it will look like `postgresql://postgres:[YOUR-PASSWORD]@db.xxxxx.supabase.co:5432/postgres`)\n   - Replace `[YOUR-PASSWORD]` with your actual database password\n\n2. **Deploy to Vercel**\n\n   Click the button below to deploy directly to Vercel:\n\n   [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/missuo/snell-panel)\n\n   Or manually deploy:\n\n   ```bash\n   # Clone the repository\n   git clone https://github.com/missuo/snell-panel.git\n   cd snell-panel\n\n   # Install Vercel CLI\n   npm i -g vercel\n\n   # Deploy to Vercel\n   vercel --prod\n   ```\n\n3. **Configure Environment Variables in Vercel**\n\n   In your Vercel dashboard, go to your project settings and add the following environment variables:\n\n   ```\n   API_TOKEN=your_token_here\n   DATABASE_URL=your_supabase_database_url\n   ```\n\n   Example Supabase DATABASE_URL:\n   ```\n   postgresql://postgres:your_password@db.abcdefghijklmnop.supabase.co:5432/postgres\n   ```\n\n4. **Access your deployment**\n\n   Your Snell Panel will be available at `https://your-project-name.vercel.app`\n\n   **Advantages of Vercel Deployment:**\n   - Serverless architecture with automatic scaling\n   - Global edge network for faster response times\n   - Automatic HTTPS and custom domain support\n   - Zero server maintenance required\n   - Free tier available for personal projects\n\n## Install Snell Server\n\nUse the following command to **install** Snell Server:\n\n```bash\nbash \u003c(curl -Ls https://ssa.sx/sn) install your_panel_url your_token custom_node_name\n```\n\nUse the following command to **uninstall** Snell Server:\n\n```bash\nbash \u003c(curl -Ls https://ssa.sx/sn) uninstall your_panel_url your_token custom_node_name\n```\n\n`custom_node_name` is optional. If your node name contains spaces, please use quotes. For example:\n\n```bash\nbash \u003c(curl -Ls https://ssa.sx/sn) install your_panel_url your_token \"My Node Name\"\n```\n\nUse the following command to **update** Snell Server:\n```bash\nbash \u003c(curl -Ls https://ssa.sx/sn) update\n```\n\n## Access the Web UI\n\nAccess the management Web UI using the following link:\n\n[https://snell-panel.owo.nz](https://snell-panel.owo.nz)\n\n**Web UI Features:**\n- **Dashboard**: Overview of all managed nodes and their status\n- **Node Management**: Add, delete, and configure Snell proxy nodes\n- **Node Customization**: Rename nodes for better organization and identification\n- **Relay Configuration**: Set up sub-nodes (relay/transit nodes) for advanced routing scenarios\n- **Subscription Links**: Generate and copy subscription URLs for various proxy clients\n- **Real-time Updates**: Live status monitoring and configuration changes\n\nYou can get the subscription link from the Web UI.\n\n### Alternative: iOS App\n\nYou can also use the iOS App instead of the WebUI for a better mobile experience. Since the app is not yet available on the App Store, you must use TestFlight to install it:\n\n**TestFlight Beta Download:**\n[https://testflight.apple.com/join/wKvw64P6](https://testflight.apple.com/join/wKvw64P6)\n\n**iOS App Features:**\n- **Native Interface**: Optimized touch interface for iOS devices\n- **Full Functionality**: Complete node management capabilities matching the Web UI\n- **Node Operations**: Add, delete, rename, and configure nodes on-the-go\n- **Relay Management**: Configure sub-nodes and routing policies\n- **Subscription Sharing**: Easy copy and share subscription links\n- **Offline Access**: View node configurations even when offline\n\n**Installation Notes:** \n- The TestFlight beta may have limited slots available\n- You need to install [TestFlight](https://apps.apple.com/app/testflight/id899247664) first on your iOS device\n- The iOS app provides the same functionality as the web interface with native mobile optimization\n\n## API Documentation\n\nSnell Panel provides a comprehensive RESTful API for programmatic node management and integration.\n\n**Base URL:** `https://your-panel-domain.com`\n\n**Authentication:** All API requests require a `token` query parameter:\n```\nGET /entries?token=your_api_token_here\n```\n\n### Endpoints\n\n#### 1. Welcome Message\n```\nGET /\n```\nReturns a welcome message with basic API information.\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"Welcome to Snell Panel. Please use the API to manage the entries.\\n https://github.com/missuo/snell-panel\"\n}\n```\n\n#### 2. Create Node Entry\n```\nPOST /entry?token=your_token\n```\n\n**Request Body:**\n```json\n{\n  \"ip\": \"example.com\",\n  \"port\": 443,\n  \"psk\": \"your_psk_here\",\n  \"node_name\": \"Custom Node Name\",\n  \"version\": \"4\"\n}\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"Entry created successfully\",\n  \"data\": {\n    \"id\": 1,\n    \"ip\": \"example.com\",\n    \"port\": 443,\n    \"psk\": \"your_psk_here\",\n    \"country_code\": \"US\",\n    \"isp\": \"Example ISP\",\n    \"asn\": 12345,\n    \"node_id\": \"uuid-generated-string\",\n    \"node_name\": \"Custom Node Name\",\n    \"version\": \"4\"\n  }\n}\n```\n\n#### 3. List All Nodes\n```\nGET /entries?token=your_token\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"Entries retrieved successfully\",\n  \"data\": [\n    {\n      \"id\": 1,\n      \"ip\": \"example.com\",\n      \"port\": 443,\n      \"psk\": \"your_psk_here\",\n      \"country_code\": \"US\",\n      \"isp\": \"Example ISP\",\n      \"asn\": 12345,\n      \"node_id\": \"uuid-string\",\n      \"node_name\": \"Custom Node Name\",\n      \"version\": \"4\"\n    }\n  ]\n}\n```\n\n#### 4. Delete Node by IP\n```\nDELETE /entry/:ip?token=your_token\n```\n\n**Example:** `DELETE /entry/192.168.1.1?token=your_token`\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"Entry deleted successfully\"\n}\n```\n\n#### 5. Delete Node by Node ID\n```\nDELETE /entry/node/:node_id?token=your_token\n```\n\n**Example:** `DELETE /entry/node/uuid-string?token=your_token`\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"Entry deleted successfully\"\n}\n```\n\n#### 6. Generate Subscription Link\n```\nGET /subscribe?token=your_token\n```\n\n**Response:** Plain text subscription content compatible with Surge:\n```\n🇺🇸 Custom Node Name = snell, example.com, 443, psk = your_psk_here, version = 4\n🇯🇵 JP Node = snell, jp.example.com, 443, psk = another_psk, version = 4\n```\n\n#### 7. Modify Node\n```\nPUT /modify/:node_id?token=your_token\n```\n\n**Request Body:**\n```json\n{\n  \"node_name\": \"New Node Name\",\n  \"ip\": \"new.example.com\"\n}\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"Node updated successfully\"\n}\n```\n\n### Data Models\n\n#### Entry Model\n```json\n{\n  \"id\": 1,\n  \"ip\": \"string\",\n  \"port\": 443,\n  \"psk\": \"string\",\n  \"country_code\": \"string\",\n  \"isp\": \"string\", \n  \"asn\": 12345,\n  \"node_id\": \"string\",\n  \"node_name\": \"string\",\n  \"version\": \"string\"\n}\n```\n\n#### API Response Model\n```json\n{\n  \"status\": \"success|error|warning\",\n  \"message\": \"string\",\n  \"data\": \"object|array (optional)\"\n}\n```\n\n### Notes\n- The `node_id` is automatically generated when creating entries\n- IP addresses can be domains or direct IPs - geolocation info is automatically resolved\n- Default version is \"4\" if not specified\n- All authenticated endpoints return 401 if token is invalid\n- 404 responses are returned for non-existent resources\n\n## TODO\n\n- [x] **Backend API Server**: RESTful API with authentication\n- [x] **Web UI**: Full-featured browser interface\n- [x] **iOS App**: Native mobile application\n- [x] **Node Management**: Add, delete, rename, and configure nodes\n- [x] **Relay Nodes**: Support for sub-nodes and transit routing\n- [x] **Subscription Generation**: Automatic link generation and updates\n- [ ] **Node Health Monitoring**: Real-time health checks and alerts\n- [ ] **Advanced Analytics**: Usage statistics and performance metrics\n- [ ] **Android App**: Native Android application\n- [ ] **Multi-user Support**: User accounts and permission management\n\n## Web UI Source Code\n\nThe Snell Panel project consists of multiple components:\n\n- **Backend API Server**: Open source (this repository) - Go-based RESTful API server\n- **Web UI Frontend**: Closed source - Browser-based management interface\n- **iOS App**: Closed source - Native iOS application\n\n**We are currently not considering open-sourcing the frontend code (Web UI and iOS App) at this time.** The backend API server remains fully open source and provides complete programmatic access to all functionality.\n\n## Contributing\n\nWe welcome contributions to the Snell Panel backend server! Here's how you can help:\n\n### Development Setup\n\n**Prerequisites:**\n- Go 1.24+ installed\n- PostgreSQL database (local or remote)\n- Git\n\n**Local Development:**\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/missuo/snell-panel.git\n   cd snell-panel\n   ```\n\n2. **Set up environment**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your configuration\n   ```\n\n3. **Install dependencies**\n   ```bash\n   go mod tidy\n   ```\n\n4. **Run in development mode**\n   ```bash\n   go run .\n   ```\n\n### Testing\n\n```bash\ngo mod tidy\ngo test ./...\n```\n\n### Building\n\n**For local platform:**\n```bash\ngo mod tidy\ngo build .\n```\n\n**Cross-platform builds:**\n```bash\n# Linux\nGOOS=linux GOARCH=amd64 go build -o snell-panel-linux .\n\n# macOS\nGOOS=darwin GOARCH=amd64 go build -o snell-panel-macos .\n\n# Windows  \nGOOS=windows GOARCH=amd64 go build -o snell-panel-windows.exe .\n```\n\n### Contributing Guidelines\n\n- Fork the repository and create a feature branch\n- Write clear commit messages\n- Add tests for new functionality\n- Ensure all tests pass before submitting\n- Update documentation as needed\n- Submit a pull request with a clear description\n\n## License\n\nThis project is licensed under GPL-3.0.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmissuo%2Fsnell-panel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmissuo%2Fsnell-panel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmissuo%2Fsnell-panel/lists"}