添加 README.md
This commit is contained in:
386
README.md
Normal file
386
README.md
Normal file
@@ -0,0 +1,386 @@
|
||||
## 17. README.md
|
||||
|
||||
```markdown
|
||||
# 🔒 Secure Site Proxy
|
||||
|
||||
A secure, self-hosted web proxy with authentication, rate limiting, and caching capabilities.
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- 🔐 **Secure Authentication** - Username/password protection with session management
|
||||
- 🚦 **Rate Limiting** - Prevent abuse with configurable request limits
|
||||
- 💾 **Memory Caching** - Intelligent caching for improved performance
|
||||
- 🛡️ **SSRF Protection** - Comprehensive blocking of private networks and internal services
|
||||
- 🔄 **Content Rewriting** - Automatic URL rewriting for seamless proxied browsing
|
||||
- ⏱️ **Session Management** - Secure session handling with automatic expiration
|
||||
- 🐳 **Docker Support** - Easy deployment with Docker and Docker Compose
|
||||
- 📊 **Statistics API** - Monitor cache usage and performance
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Docker and Docker Compose (recommended)
|
||||
- OR Go 1.21+ for manual build
|
||||
|
||||
### Option 1: Docker Compose (Recommended)
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
git clone https://github.com/xofine/siteproxy.git
|
||||
cd siteproxy
|
||||
|
||||
# 2. Create and configure environment file
|
||||
cp .env.example .env
|
||||
nano .env # Edit AUTH_PASSWORD and SESSION_SECRET
|
||||
|
||||
# 3. Deploy
|
||||
docker-compose up -d
|
||||
|
||||
# 4. Check logs
|
||||
docker-compose logs -f
|
||||
|
||||
# 5. Access the service
|
||||
# Open http://localhost:8080 in your browser
|
||||
```
|
||||
|
||||
### Option 2: Manual Build
|
||||
|
||||
```bash
|
||||
# 1. Clone and configure
|
||||
git clone https://github.com/xofine/siteproxy.git
|
||||
cd siteproxy
|
||||
cp .env.example .env
|
||||
nano .env
|
||||
|
||||
# 2. Build
|
||||
go mod init siteproxy
|
||||
go build -o siteproxy .
|
||||
|
||||
# 3. Run
|
||||
./siteproxy
|
||||
|
||||
# 4. Access
|
||||
# Open http://localhost:8080 in your browser
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
All configuration is done through environment variables in the `.env` file.
|
||||
|
||||
### Authentication Settings
|
||||
|
||||
```env
|
||||
AUTH_USERNAME=admin # Login username
|
||||
AUTH_PASSWORD=your_secure_password_here # Login password (CHANGE THIS!)
|
||||
SESSION_SECRET=random_64_char_string # Session encryption key
|
||||
SESSION_TIMEOUT=30m # Session expiration time
|
||||
```
|
||||
|
||||
### Security Settings
|
||||
|
||||
```env
|
||||
RATE_LIMIT_REQUESTS=100 # Max requests per window
|
||||
RATE_LIMIT_WINDOW=1m # Rate limit time window
|
||||
MAX_RESPONSE_SIZE=52428800 # Max response size (50MB)
|
||||
```
|
||||
|
||||
### Proxy Settings
|
||||
|
||||
```env
|
||||
ALLOWED_SCHEMES=http,https # Allowed URL schemes
|
||||
USER_AGENT=Mozilla/5.0... # User agent for requests
|
||||
```
|
||||
|
||||
### Blacklist Configuration
|
||||
|
||||
```env
|
||||
# Domain blacklist (supports wildcards)
|
||||
BLOCKED_DOMAINS=localhost,127.0.0.1,0.0.0.0,*.local,internal,metadata.google.internal,169.254.169.254
|
||||
|
||||
# CIDR blacklist (private networks)
|
||||
BLOCKED_CIDRS=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,169.254.0.0/16,::1/128,fc00::/7,fe80::/10,100.64.0.0/10
|
||||
```
|
||||
|
||||
### Cache Settings
|
||||
|
||||
```env
|
||||
CACHE_ENABLED=true # Enable/disable caching
|
||||
CACHE_MAX_SIZE=104857600 # Max cache size (100MB)
|
||||
CACHE_TTL=1h # Cache entry TTL
|
||||
```
|
||||
|
||||
### Server Settings
|
||||
|
||||
```env
|
||||
PORT=8080 # Server port
|
||||
```
|
||||
|
||||
## 🔒 Security Best Practices
|
||||
|
||||
### Essential Security Measures
|
||||
|
||||
1. **Change Default Credentials**
|
||||
```bash
|
||||
# Generate strong password
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
2. **Use Strong Session Secret**
|
||||
```bash
|
||||
# Generate random session secret
|
||||
openssl rand -hex 32
|
||||
```
|
||||
|
||||
3. **Deploy Behind HTTPS**
|
||||
- Use Nginx, Caddy, or Traefik as reverse proxy
|
||||
- Enable SSL/TLS certificates (Let's Encrypt)
|
||||
|
||||
4. **Use Cloudflare Access**
|
||||
- Add additional authentication layer
|
||||
- Protect against DDoS attacks
|
||||
- Hide origin server IP
|
||||
|
||||
5. **Network Isolation**
|
||||
- Deploy in isolated Docker network
|
||||
- Use firewall rules to restrict access
|
||||
- Disable unnecessary ports
|
||||
|
||||
### Example Nginx Configuration
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name proxy.yourdomain.com;
|
||||
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:8080;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 API Endpoints
|
||||
|
||||
### Public Endpoints
|
||||
|
||||
- `GET /login` - Login page
|
||||
- `POST /login` - Submit credentials
|
||||
- `GET /health` - Health check endpoint
|
||||
|
||||
### Protected Endpoints (Require Authentication)
|
||||
|
||||
- `GET /` - Main proxy interface
|
||||
- `GET /proxy?url=<target>` - Proxy request to target URL
|
||||
- `GET /stats` - Cache statistics (JSON)
|
||||
- `GET /logout` - Logout and clear session
|
||||
|
||||
### Statistics Response Example
|
||||
|
||||
```json
|
||||
{
|
||||
"entries": 42,
|
||||
"size": 15728640
|
||||
}
|
||||
```
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ Browser │
|
||||
└──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Cloudflare │ (Optional)
|
||||
│ Access │
|
||||
└──────┬──────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ SiteProxy │
|
||||
│ ┌───────────┐ │
|
||||
│ │ Auth │ │
|
||||
│ ├───────────┤ │
|
||||
│ │ Rate │ │
|
||||
│ │ Limiter │ │
|
||||
│ ├───────────┤ │
|
||||
│ │ Validator │ │
|
||||
│ ├───────────┤ │
|
||||
│ │ Cache │ │
|
||||
│ ├───────────┤ │
|
||||
│ │ Proxy │ │
|
||||
│ └───────────┘ │
|
||||
└──────┬──────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Target Website │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
siteproxy/
|
||||
├── main.go # Application entry point
|
||||
├── auth/
|
||||
│ ├── middleware.go # Authentication middleware
|
||||
│ └── session.go # Session management
|
||||
├── proxy/
|
||||
│ ├── handler.go # Proxy request handler
|
||||
│ ├── index.go # Main page handler
|
||||
│ └── stats.go # Statistics handler
|
||||
├── security/
|
||||
│ ├── ratelimit.go # Rate limiting
|
||||
│ └── validator.go # URL validation and SSRF protection
|
||||
├── cache/
|
||||
│ └── cache.go # Memory cache implementation
|
||||
├── config/
|
||||
│ └── config.go # Configuration loader
|
||||
├── static/ # Static files (if any)
|
||||
├── .env.example # Example environment variables
|
||||
├── Dockerfile # Docker build configuration
|
||||
├── docker-compose.yml # Docker Compose configuration
|
||||
├── go.mod # Go module definition
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
go test ./...
|
||||
|
||||
# Run with coverage
|
||||
go test -cover ./...
|
||||
|
||||
# Run with race detector
|
||||
go test -race ./...
|
||||
```
|
||||
|
||||
### Building for Production
|
||||
|
||||
```bash
|
||||
# Build optimized binary
|
||||
CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -ldflags="-s -w" -o siteproxy .
|
||||
|
||||
# Build for different platforms
|
||||
GOOS=darwin GOARCH=amd64 go build -o siteproxy-darwin-amd64
|
||||
GOOS=linux GOARCH=amd64 go build -o siteproxy-linux-amd64
|
||||
GOOS=windows GOARCH=amd64 go build -o siteproxy-windows-amd64.exe
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**1. "Unauthorized" error after login**
|
||||
- Check if SESSION_SECRET is set correctly
|
||||
- Clear browser cookies and try again
|
||||
- Verify AUTH_USERNAME and AUTH_PASSWORD in .env
|
||||
|
||||
**2. "Rate limit exceeded" error**
|
||||
- Increase RATE_LIMIT_REQUESTS in .env
|
||||
- Increase RATE_LIMIT_WINDOW for longer time window
|
||||
- Wait for the rate limit window to reset
|
||||
|
||||
**3. "Invalid or blocked URL" error**
|
||||
- Check if target domain is in BLOCKED_DOMAINS
|
||||
- Verify target IP is not in private network range
|
||||
- Ensure URL starts with http:// or https://
|
||||
|
||||
**4. Cache not working**
|
||||
- Verify CACHE_ENABLED=true in .env
|
||||
- Check CACHE_MAX_SIZE is sufficient
|
||||
- Review /stats endpoint for cache statistics
|
||||
|
||||
**5. Docker container won't start**
|
||||
- Check if port 8080 is already in use
|
||||
- Verify .env file exists and is properly formatted
|
||||
- Check Docker logs: `docker-compose logs`
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable verbose logging:
|
||||
|
||||
```bash
|
||||
# Add to .env
|
||||
LOG_LEVEL=debug
|
||||
|
||||
# Or run with environment variable
|
||||
LOG_LEVEL=debug ./siteproxy
|
||||
```
|
||||
|
||||
## 📝 Changelog
|
||||
|
||||
### v1.0.0 (2024-01-XX)
|
||||
|
||||
- Initial release
|
||||
- Basic proxy functionality
|
||||
- Authentication system
|
||||
- Rate limiting
|
||||
- Memory caching
|
||||
- SSRF protection
|
||||
- Docker support
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Please follow these guidelines:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
### Code Style
|
||||
|
||||
- Follow standard Go formatting (`gofmt`)
|
||||
- Add comments for exported functions
|
||||
- Write tests for new features
|
||||
- Update documentation as needed
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## ⚠️ Disclaimer
|
||||
|
||||
This tool is provided for legitimate use only. Users are responsible for:
|
||||
|
||||
- Complying with applicable laws and regulations
|
||||
- Respecting target website terms of service
|
||||
- Not using for malicious purposes
|
||||
- Ensuring proper authorization before proxying content
|
||||
|
||||
The authors are not responsible for misuse of this software.
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- Built with Go standard library
|
||||
- Inspired by various open-source proxy projects
|
||||
- Security best practices from OWASP
|
||||
|
||||
## 📧 Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/xofine/siteproxy/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/xofine/siteproxy/discussions)
|
||||
- **Security**: Report security issues to security@yourdomain.com
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- [Documentation](https://github.com/xofine/siteproxy/wiki)
|
||||
- [Changelog](CHANGELOG.md)
|
||||
- [Contributing Guidelines](CONTRIBUTING.md)
|
||||
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
||||
```
|
||||
Reference in New Issue
Block a user