Content
# Auto Ski Info Subscribe
**X (Twitter) Tweet Monitoring System** - Automatic scraping and AI analysis based on Cookie authentication
[](https://opensource.org/licenses/MIT)
[](https://www.docker.com/)
[](https://www.python.org/)
[](https://reactjs.org/)
## 📋 Project Introduction
Automated monitoring of tweets from specific accounts on X (Twitter), performing content analysis and classification through AI, and supporting data exposure to other services via the MCP (Model Context Protocol).
### 🎯 Core Features
- **🔐 Cookie Authentication** - Use your own X account Cookie without the need to apply for an official API
- **📡 Automatic Monitoring** - Regularly fetch the latest tweets from specified accounts
- **🤖 AI Analysis** - Integrate Google Gemini AI for sentiment analysis, content summarization, and topic extraction
- **🔌 MCP Protocol** - Expose tweet resources to other services via the MCP protocol
- **🎨 Web Interface** - React frontend provides account management and tweet browsing
- **☁️ Cloud Deployment** - Supports deployment on Docker and Google Cloud Run
## 🏗️ Tech Stack
**Frontend**
- React 18 + Ant Design
- React Query + React Router
**Backend**
- Django 4.2 + Django REST Framework
- Playwright (headless browser crawler)
- Celery + Redis (scheduled tasks)
- Google Gemini AI (content analysis)
**Deployment**
- Docker + Docker Compose
- Nginx (reverse proxy)
- Google Cloud Run (optional)
## 🚀 Quick Start
### Prerequisites
- Docker & Docker Compose
- Google Gemini API Key (for AI analysis)
### 1. Configure Environment Variables
```bash
```
# Copy Environment Variable Template
cp backend/.env.example backend/.env
# Edit backend/.env and fill in your configuration
```
**Required Configuration**:
```ini
# AI Services
AI_API_KEY_GOOGLE=your_gemini_api_key
# Django Configuration
DEBUG=True
SECRET_KEY=your-secret-key-change-in-production
ALLOWED_HOSTS=localhost,127.0.0.1
```
### 2. Start the Service
```bash
```
# Clone the Repository
git clone https://github.com/YOUR_USERNAME/auto-ski-info-subscribe.git
cd auto-ski-info-subscribe
# Start All Services
docker-compose up -d
# View Logs
docker-compose logs -f
```
### 3. Accessing the Application
- **Frontend Interface**: http://localhost:3000
- **Backend API**: http://localhost:8000
- **API Documentation**: http://localhost:8000/swagger/
- **Admin Panel**: http://localhost:8000/admin/
- Default User: `admin`
- Default Password: `admin@123`
## 📖 Usage Instructions
### Add Monitoring Account
1. Access the front-end interface and log in
2. Go to the "Account Management" page
3. Click "Add Account" and fill in:
- X Username (for example, if `@example`, fill in `example`)
- Display Name (optional)
- Enable Monitoring
### View Tweets
- The system automatically fetches tweets from enabled accounts every 15 minutes.
- View all collected data on the "Tweet List" page.
- Supports filtering by account, sentiment, and time.
### MCP Resource Interface
Tweet data is exposed through the MCP protocol:
```http
# Get a Single Tweet
GET /api/mcp/tweets/{tweet_id}
# Get Account Tweet List
GET /api/mcp/accounts/{account_id}/tweets/
# Search Tweets
GET /api/mcp/tweets/search/?q=keyword&sentiment=positive
```
## 🐳 Development Debugging
### Docker Container Debugging
The project supports real-time debugging within a Docker container:
```powershell
```
# Using PowerShell Script (Windows)
.\docker-dev.ps1
# Select Operation:
# 1 - First Build
# 2 - Start the Service
# 9 - Database Migration
### VS Code Debugging
1. Press `Ctrl+Shift+D` to open the debug panel
2. Select `🐳 Docker: Full Stack Debug`
3. Press `F5` to start debugging
**Debug Configuration**:
- `🐳 Docker: Full Stack Debug` - Debug both frontend and backend simultaneously
- `Docker: Backend (Remote)` - Backend debugging (port 5678)
- `Docker: Frontend (Chrome)` - Frontend debugging
See [DOCKER_DEBUG.md](DOCKER_DEBUG.md) for the complete guide.
## ☁️ Cloud Deployment
### Google Cloud Run
```bash
```
# Install gcloud CLI and Authenticate
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
# Configure Secrets
chmod +x setup-secrets.sh
./setup-secrets.sh YOUR_PROJECT_ID
# Deploy Application
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID
```
**Current Configuration** (`cloudbuild.yaml`):
- CPU: 1 core
- Memory: 512Mi
- Instance Count: 0-10 (auto-scaling)
- Cost: $0/month when no traffic
## 🔧 Configuration and Customization
### Adjusting Monitoring Frequency
Edit `backend/auto_ski_info/celery.py`:
```python
app.conf.beat_schedule = {
'monitor-x-accounts': {
'task': 'x_monitor.tasks.monitor_all_active_accounts',
'schedule': crontab(minute='*/15'), # Change to */30 for 30 minutes
},
}
```
### Custom AI Prompts
Edit the `GeminiService` class methods in `backend/ai_service/services.py`.
## 🛠️ Troubleshooting
### Celery Task Not Executing
- Check Redis: `docker-compose ps redis`
- View Worker Logs: `docker-compose logs celery`
- Manual Test: `docker-compose exec backend python manage.py shell`
### Unable to Fetch Tweets
- Ensure the target account is a public account
- Check the username format (without `@`)
- View Playwright logs: `docker-compose logs backend | grep playwright`
## 📚 Related Documents
- **[DOCKER_DEBUG.md](DOCKER_DEBUG.md)** - Docker container debugging guide
- **[LOCAL_SETUP.md](LOCAL_SETUP.md)** - Local development environment setup
- **[backend/MCP_INTEGRATION.md](backend/MCP_INTEGRATION.md)** - MCP (Message Communication Protocol) integration instructions
## 🔐 Security and Compliance
### API Key Security
- ⚠️ **Never expose** your API key
- ✅ Store it in a `.env` file and add it to `.gitignore`
- ✅ Use Secret Manager in production environments
### Usage Restrictions
- ⚠️ Comply with X (Twitter) Terms of Service
- ⚠️ It is recommended to have an interval of 15-30 minutes to avoid excessive frequency
- ⚠️ For personal learning and research only, not for commercial use
- ⚠️ Only scrape publicly available information, respect privacy
## 🤝 Contribution Guidelines
We welcome contributions! Please follow the process below:
1. Fork this repository
2. Create a branch: `git checkout -b feature/amazing-feature`
3. Commit your code: `git commit -m 'Add amazing feature'`
4. Push the branch: `git push origin feature/amazing-feature`
5. Create a Pull Request
**Code Standards**:
- Python: PEP 8
- JavaScript: ESLint + Prettier
- Commit: Semantic commit messages (`feat:`, `fix:`, `docs:`)
## 📄 License
This project is open source under the [MIT License](LICENSE).
## ⚠️ Disclaimer
**This project is for learning and technical research purposes only.**
- Users must comply with X (Twitter) Terms of Service and relevant laws and regulations.
- Users assume all legal responsibilities arising from the use of this tool.
- Developers are not responsible for account bans or other consequences.
- Please do not use this tool for any illegal or infringing activities.
**By using this tool, you indicate that you have read and agree to the above disclaimer.**
---
**Star ⭐ this project if it has been helpful to you!**
