light-ss-pool

A pool manager for light-ss instances, enabling management of multiple Shadowsocks proxies through subscription URLs.

Features

• Instance Management: Start, stop, restart, and monitor multiple light-ss instances
• Subscription Support: Automatically fetch and parse Shadowsocks configurations from subscription URLs
  • Base64 encoded ss:// URLs
  • Clash YAML format
• Auto-Restart: Automatic restart of failed instances with configurable retry limits
• Health Monitoring: Continuous health checks for all instances
• Speed Testing: Test and rank instances by connection speed
• REST API: Complete management API for automation
• CLI Tool: User-friendly command-line interface

Architecture

light-ss-pool spawns light-ss instances as separate processes for:

• Fault isolation: One instance crash doesn't affect others
• Debuggability: Use standard OS tools (ps, htop, strace)
• Operational flexibility: Manage each instance independently

See ARCHITECTURE.md for detailed architecture decisions.

Quick Start

Prerequisites

• Go 1.22 or later
• light-ss binary installed

Installation

# Clone the repository
git clone https://github.com/TeamTaoist/light-ss-pool.git
cd light-ss-pool

# Build binaries
go build -o light-ss-pool ./cmd/light-ss-pool
go build -o lspc ./cmd/lspc

# Create config directory
mkdir -p data

# Copy example config
cp config.yaml.example config.yaml

# Edit config
vim config.yaml

Start the Pool

# Start pool daemon
./light-ss-pool start

# Check pool status
./lspc pool status

Configuration

Pool Configuration (config.yaml)

server:
  listen: "127.0.0.1:9090"

light_ss:
  binary_path: "light-ss"

storage:
  path: "./data"

Add Subscriptions

# Add a subscription URL
lspc subs add --name "My Subscription" --url "https://example.com/sub" --interval 86400

# Fetch subscription
lspc subs fetch --all

# Generate instances from subscription
lspc subs generate --all

Manage Instances

# List all instances
lspc inst list

# Show instance details
lspc inst show instance-001

# Start specific instance
lspc inst start instance-001

# Start all instances
lspc inst start-all

# Run speed test on instance
lspc speedtest instance-001

# Test subscription servers before creating instances
lspc subs test my-sub --latency-only

# Test a server manually
lspc test --server server.com:8388 --password mypass --cipher aes-256-gcm

Testing Subscription Servers

Test all servers in a subscription before or after creating instances:

# Test all servers (latency + speed)
lspc subs test my-sub

# Test latency only (faster)
lspc subs test my-sub --latency-only

# Force new test (ignore cache)
lspc subs test my-sub --force

# View cached test results
lspc subs test-results my-sub

# Clear test cache
lspc subs test-clear my-sub

Features:

• Tests up to 1000 servers per subscription
• 10 concurrent tests for speed
• 15-second timeout per server
• 2-hour result caching
• Ranked results by speed/latency
• Filter by minimum speed and maximum latency

Testing Servers Manually

Test any Shadowsocks server without creating an instance:

# Basic test
lspc test --server server.com:8388 --password mypass --cipher aes-256-gcm

# Test with plugin
lspc test --server server.com:8388 --password mypass --cipher aes-256-gcm \
  --plugin simple-obfs --plugin-obfs http --plugin-host bing.com

# Latency only (fast)
lspc test --server server.com:8388 --password mypass --cipher aes-256-gcm --latency-only

# JSON output for automation
lspc test --server server.com:8388 --password mypass --cipher aes-256-gcm --json

CLI Commands

Pool Management

• lspc pool status - Show pool status
• lspc pool reload - Reload configuration
• lspc pool shutdown - Graceful shutdown

Instance Management

• lspc inst list - List all instances
• lspc inst show <id> - Show instance details
• lspc inst start <id> - Start instance
• lspc inst stop <id> - Stop instance
• lspc inst restart <id> - Restart instance
• lspc inst start-all - Start all instances

Subscription Management

• lspc subs list - List subscriptions
• lspc subs show <id> - Show subscription details
• lspc subs add --name <name> --url <url> [--interval <seconds>] - Add subscription
• lspc subs update <id> [--name <name>] [--url <url>] [--interval <seconds>] - Update subscription
• lspc subs delete <id> - Delete subscription
• lspc subs enable <id> - Enable subscription
• lspc subs disable <id> - Disable subscription
• lspc subs sync <id> - Sync subscription now
• lspc subs test <id> [--latency-only] [--force] [--json] - Test all servers in subscription
• lspc subs test-results <id> [--json] - View cached test results
• lspc subs test-clear <id> - Clear test result cache

Server Testing

• lspc test --server <addr> --password <pwd> --cipher <cipher> [options] - Test a Shadowsocks server without creating an instance
  • --latency-only - Only test latency, skip download speed test
  • --timeout <seconds> - Test timeout (default: 15)
  • --plugin <name> - Plugin name (e.g., simple-obfs)
  • --plugin-obfs <mode> - Obfuscation mode: http or tls
  • --plugin-host <host> - Obfuscation host header
  • --json - Output as JSON

Speed Testing

• lspc speedtest <id> - Test specific instance
• lspc speedtest --all - Test all instances
• lspc speedtest list - List test results

REST API

All management operations are available via REST API:

# Pool status
curl http://127.0.0.1:9090/api/pool/status

# List instances
curl http://127.0.0.1:9090/api/inst/list

# Start instance
curl -X POST http://127.0.0.1:9090/api/inst/instance-001/start

# Sync subscriptions
curl -X POST http://127.0.0.1:9090/api/subs/my-sub/sync

See API_REFERENCE.md for complete API documentation.

Deployment

Systemd Service

# Copy systemd service file
sudo cp deployment/systemd/light-ss-pool.service /etc/systemd/system/

# Enable and start service
sudo systemctl enable light-ss-pool
sudo systemctl start light-ss-pool

# Check status
sudo systemctl status light-ss-pool

Standalone Daemon

# Start as daemon
./light-ss-pool start --daemon

# Check status
./lspc pool status

# Stop daemon
./light-ss-pool stop

Documentation

• API_REFERENCE.md - Complete HTTP API reference
• ARCHITECTURE.md - System architecture and design decisions

License

[Add license information]

Contributing

[Add contributing guidelines]