Initial commit: Telegram Management System
Some checks failed
Deploy / deploy (push) Has been cancelled
Some checks failed
Deploy / deploy (push) Has been cancelled
Full-stack web application for Telegram management - Frontend: Vue 3 + Vben Admin - Backend: NestJS - Features: User management, group broadcast, statistics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
你的用户名
495
marketing-agent/DEPLOYMENT.md
Normal file
495
marketing-agent/DEPLOYMENT.md
Normal file
@@ -0,0 +1,495 @@
|
||||
# Telegram Marketing Agent System - Deployment Guide
|
||||
|
||||
This guide provides comprehensive instructions for deploying the Telegram Marketing Agent System in various environments.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Prerequisites](#prerequisites)
|
||||
2. [Environment Setup](#environment-setup)
|
||||
3. [Local Development](#local-development)
|
||||
4. [Docker Deployment](#docker-deployment)
|
||||
5. [Kubernetes Deployment](#kubernetes-deployment)
|
||||
6. [Production Deployment](#production-deployment)
|
||||
7. [Monitoring & Maintenance](#monitoring--maintenance)
|
||||
8. [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### System Requirements
|
||||
|
||||
- **OS**: Linux (Ubuntu 20.04+ recommended), macOS, or Windows with WSL2
|
||||
- **CPU**: 4+ cores recommended
|
||||
- **RAM**: 16GB minimum, 32GB recommended
|
||||
- **Storage**: 50GB+ free space
|
||||
- **Network**: Stable internet connection with open ports
|
||||
|
||||
### Software Requirements
|
||||
|
||||
- Docker 20.10+ and Docker Compose 2.0+
|
||||
- Node.js 18+ and npm 8+
|
||||
- Git
|
||||
- MongoDB 5.0+
|
||||
- PostgreSQL 14+
|
||||
- Redis 7.0+
|
||||
- RabbitMQ 3.9+
|
||||
- Elasticsearch 8.0+ (optional)
|
||||
- ClickHouse (optional)
|
||||
|
||||
### API Keys Required
|
||||
|
||||
1. **Anthropic API Key** - For Claude AI integration
|
||||
2. **OpenAI API Key** - For content moderation
|
||||
3. **Google Cloud Project** - For additional NLP services
|
||||
4. **Telegram API Credentials** - API ID and Hash
|
||||
|
||||
## Environment Setup
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-org/telegram-marketing-agent.git
|
||||
cd telegram-marketing-agent/marketing-agent
|
||||
```
|
||||
|
||||
### 2. Create Environment File
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` and add your API keys and configuration:
|
||||
|
||||
```env
|
||||
# Required API Keys
|
||||
ANTHROPIC_API_KEY=your_anthropic_api_key
|
||||
OPENAI_API_KEY=your_openai_api_key
|
||||
GOOGLE_CLOUD_PROJECT=your_project_id
|
||||
|
||||
# JWT Secret (generate a secure random string)
|
||||
JWT_SECRET=your-super-secret-key-min-32-chars
|
||||
|
||||
# Telegram Configuration
|
||||
TELEGRAM_API_ID=your_telegram_api_id
|
||||
TELEGRAM_API_HASH=your_telegram_api_hash
|
||||
|
||||
# Update other configurations as needed
|
||||
```
|
||||
|
||||
### 3. Generate Secure Keys
|
||||
|
||||
```bash
|
||||
# Generate JWT Secret
|
||||
openssl rand -base64 32
|
||||
|
||||
# Generate Encryption Key
|
||||
openssl rand -hex 32
|
||||
```
|
||||
|
||||
## Local Development
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
# Install dependencies for all services
|
||||
for service in services/*; do
|
||||
if [ -d "$service" ]; then
|
||||
echo "Installing dependencies for $service"
|
||||
cd "$service"
|
||||
npm install
|
||||
cd ../..
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### 2. Start Infrastructure Services
|
||||
|
||||
```bash
|
||||
# Start databases and message brokers
|
||||
docker-compose up -d postgres mongodb redis rabbitmq elasticsearch
|
||||
```
|
||||
|
||||
### 3. Run Database Migrations
|
||||
|
||||
```bash
|
||||
# MongoDB indexes
|
||||
docker exec -it marketing_mongodb mongosh marketing_agent --eval '
|
||||
db.tasks.createIndex({ taskId: 1 }, { unique: true });
|
||||
db.campaigns.createIndex({ campaignId: 1 }, { unique: true });
|
||||
db.sessions.createIndex({ sessionId: 1 }, { unique: true });
|
||||
db.sessions.createIndex({ updatedAt: 1 }, { expireAfterSeconds: 2592000 });
|
||||
'
|
||||
```
|
||||
|
||||
### 4. Start Services Individually
|
||||
|
||||
```bash
|
||||
# Terminal 1: API Gateway
|
||||
cd services/api-gateway
|
||||
npm run dev
|
||||
|
||||
# Terminal 2: Orchestrator
|
||||
cd services/orchestrator
|
||||
npm run dev
|
||||
|
||||
# Terminal 3: Claude Agent
|
||||
cd services/claude-agent
|
||||
npm run dev
|
||||
|
||||
# Continue for other services...
|
||||
```
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### 1. Build All Services
|
||||
|
||||
```bash
|
||||
# Build all Docker images
|
||||
docker-compose build
|
||||
```
|
||||
|
||||
### 2. Start All Services
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
docker-compose up -d
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
|
||||
# Check service health
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
### 3. Initialize Data
|
||||
|
||||
```bash
|
||||
# Create admin user
|
||||
curl -X POST http://localhost:3000/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "admin",
|
||||
"password": "secure_password",
|
||||
"email": "admin@example.com"
|
||||
}'
|
||||
```
|
||||
|
||||
### 4. Access Services
|
||||
|
||||
- **API Gateway**: http://localhost:3000
|
||||
- **API Documentation**: http://localhost:3000/api-docs
|
||||
- **RabbitMQ Management**: http://localhost:15672 (admin/admin)
|
||||
- **Grafana**: http://localhost:3001 (admin/admin)
|
||||
- **Prometheus**: http://localhost:9090
|
||||
|
||||
## Kubernetes Deployment
|
||||
|
||||
### 1. Create Namespace
|
||||
|
||||
```bash
|
||||
kubectl create namespace marketing-agent
|
||||
```
|
||||
|
||||
### 2. Create Secrets
|
||||
|
||||
```bash
|
||||
# Create secret for API keys
|
||||
kubectl create secret generic api-keys \
|
||||
--from-literal=anthropic-api-key=$ANTHROPIC_API_KEY \
|
||||
--from-literal=openai-api-key=$OPENAI_API_KEY \
|
||||
--from-literal=jwt-secret=$JWT_SECRET \
|
||||
-n marketing-agent
|
||||
```
|
||||
|
||||
### 3. Apply Configurations
|
||||
|
||||
```bash
|
||||
# Apply all Kubernetes manifests
|
||||
kubectl apply -f infrastructure/kubernetes/ -n marketing-agent
|
||||
|
||||
# Check deployment status
|
||||
kubectl get pods -n marketing-agent
|
||||
kubectl get services -n marketing-agent
|
||||
```
|
||||
|
||||
### 4. Setup Ingress
|
||||
|
||||
```bash
|
||||
# Apply ingress configuration
|
||||
kubectl apply -f infrastructure/kubernetes/ingress.yaml -n marketing-agent
|
||||
```
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### 1. Security Hardening
|
||||
|
||||
#### SSL/TLS Configuration
|
||||
|
||||
```nginx
|
||||
# nginx/conf.d/ssl.conf
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name api.yourdomain.com;
|
||||
|
||||
ssl_certificate /etc/ssl/certs/your-cert.pem;
|
||||
ssl_certificate_key /etc/ssl/private/your-key.pem;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||
|
||||
location / {
|
||||
proxy_pass http://api-gateway:3000;
|
||||
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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Environment Variables
|
||||
|
||||
```bash
|
||||
# Production .env
|
||||
NODE_ENV=production
|
||||
LOG_LEVEL=warn
|
||||
DEBUG=false
|
||||
|
||||
# Use strong passwords
|
||||
POSTGRES_PASSWORD=$(openssl rand -base64 32)
|
||||
RABBITMQ_DEFAULT_PASS=$(openssl rand -base64 32)
|
||||
```
|
||||
|
||||
### 2. Database Setup
|
||||
|
||||
#### PostgreSQL
|
||||
|
||||
```sql
|
||||
-- Create production database
|
||||
CREATE DATABASE marketing_agent_prod;
|
||||
CREATE USER marketing_prod WITH ENCRYPTED PASSWORD 'strong_password';
|
||||
GRANT ALL PRIVILEGES ON DATABASE marketing_agent_prod TO marketing_prod;
|
||||
|
||||
-- Enable extensions
|
||||
\c marketing_agent_prod
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
CREATE EXTENSION IF NOT EXISTS "pgcrypto";
|
||||
```
|
||||
|
||||
#### MongoDB
|
||||
|
||||
```javascript
|
||||
// Create production user
|
||||
use marketing_agent_prod
|
||||
db.createUser({
|
||||
user: "marketing_prod",
|
||||
pwd: "strong_password",
|
||||
roles: [
|
||||
{ role: "readWrite", db: "marketing_agent_prod" }
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
### 3. Scaling Configuration
|
||||
|
||||
#### Docker Swarm
|
||||
|
||||
```bash
|
||||
# Initialize swarm
|
||||
docker swarm init
|
||||
|
||||
# Deploy stack
|
||||
docker stack deploy -c docker-compose.prod.yml marketing-agent
|
||||
|
||||
# Scale services
|
||||
docker service scale marketing-agent_api-gateway=3
|
||||
docker service scale marketing-agent_orchestrator=2
|
||||
```
|
||||
|
||||
#### Kubernetes HPA
|
||||
|
||||
```yaml
|
||||
apiVersion: autoscaling/v2
|
||||
kind: HorizontalPodAutoscaler
|
||||
metadata:
|
||||
name: api-gateway-hpa
|
||||
spec:
|
||||
scaleTargetRef:
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
name: api-gateway
|
||||
minReplicas: 2
|
||||
maxReplicas: 10
|
||||
metrics:
|
||||
- type: Resource
|
||||
resource:
|
||||
name: cpu
|
||||
target:
|
||||
type: Utilization
|
||||
averageUtilization: 70
|
||||
```
|
||||
|
||||
### 4. Backup Strategy
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# backup.sh
|
||||
|
||||
# Backup MongoDB
|
||||
docker exec marketing_mongodb mongodump \
|
||||
--uri="mongodb://localhost:27017/marketing_agent" \
|
||||
--out=/backup/mongodb-$(date +%Y%m%d)
|
||||
|
||||
# Backup PostgreSQL
|
||||
docker exec marketing_postgres pg_dump \
|
||||
-U marketing_user marketing_agent \
|
||||
> /backup/postgres-$(date +%Y%m%d).sql
|
||||
|
||||
# Backup Redis
|
||||
docker exec marketing_redis redis-cli BGSAVE
|
||||
|
||||
# Upload to S3
|
||||
aws s3 sync /backup s3://your-backup-bucket/$(date +%Y%m%d)/
|
||||
```
|
||||
|
||||
## Monitoring & Maintenance
|
||||
|
||||
### 1. Health Checks
|
||||
|
||||
```bash
|
||||
# Check all services health
|
||||
curl http://localhost:3000/health/services
|
||||
|
||||
# Individual service health
|
||||
curl http://localhost:3001/health # Orchestrator
|
||||
curl http://localhost:3002/health # Claude Agent
|
||||
```
|
||||
|
||||
### 2. Prometheus Alerts
|
||||
|
||||
```yaml
|
||||
# prometheus/alerts.yml
|
||||
groups:
|
||||
- name: marketing-agent
|
||||
rules:
|
||||
- alert: ServiceDown
|
||||
expr: up{job="api-gateway"} == 0
|
||||
for: 5m
|
||||
annotations:
|
||||
summary: "API Gateway is down"
|
||||
|
||||
- alert: HighErrorRate
|
||||
expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
|
||||
for: 5m
|
||||
annotations:
|
||||
summary: "High error rate detected"
|
||||
```
|
||||
|
||||
### 3. Log Management
|
||||
|
||||
```bash
|
||||
# View logs
|
||||
docker-compose logs -f api-gateway
|
||||
|
||||
# Export logs
|
||||
docker logs marketing_api_gateway > api-gateway.log
|
||||
|
||||
# Log rotation
|
||||
cat > /etc/logrotate.d/marketing-agent << EOF
|
||||
/var/log/marketing-agent/*.log {
|
||||
daily
|
||||
rotate 14
|
||||
compress
|
||||
delaycompress
|
||||
missingok
|
||||
notifempty
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### 4. Performance Tuning
|
||||
|
||||
```javascript
|
||||
// Redis optimization
|
||||
// redis.conf
|
||||
maxmemory 2gb
|
||||
maxmemory-policy allkeys-lru
|
||||
save 900 1
|
||||
save 300 10
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### 1. Service Connection Errors
|
||||
|
||||
```bash
|
||||
# Check network connectivity
|
||||
docker network ls
|
||||
docker network inspect marketing-agent_marketing_network
|
||||
|
||||
# Restart services
|
||||
docker-compose restart api-gateway
|
||||
```
|
||||
|
||||
#### 2. Database Connection Issues
|
||||
|
||||
```bash
|
||||
# Test MongoDB connection
|
||||
docker exec -it marketing_mongodb mongosh --eval "db.adminCommand('ping')"
|
||||
|
||||
# Test PostgreSQL connection
|
||||
docker exec -it marketing_postgres psql -U marketing_user -d marketing_agent -c "SELECT 1"
|
||||
```
|
||||
|
||||
#### 3. Memory Issues
|
||||
|
||||
```bash
|
||||
# Check memory usage
|
||||
docker stats
|
||||
|
||||
# Increase memory limits in docker-compose.yml
|
||||
services:
|
||||
claude-agent:
|
||||
mem_limit: 2g
|
||||
memswap_limit: 2g
|
||||
```
|
||||
|
||||
#### 4. API Rate Limiting
|
||||
|
||||
```javascript
|
||||
// Adjust rate limits in config
|
||||
rateLimiting: {
|
||||
windowMs: 15 * 60 * 1000,
|
||||
max: 200 // Increase limit
|
||||
}
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
export DEBUG=true
|
||||
export LOG_LEVEL=debug
|
||||
|
||||
# Run with verbose output
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
### Support
|
||||
|
||||
For additional support:
|
||||
- Check logs in `/logs` directory
|
||||
- Review error messages in Grafana dashboards
|
||||
- Contact support team with service logs and error details
|
||||
|
||||
## Security Checklist
|
||||
|
||||
- [ ] Change all default passwords
|
||||
- [ ] Enable SSL/TLS for all external endpoints
|
||||
- [ ] Configure firewall rules
|
||||
- [ ] Enable audit logging
|
||||
- [ ] Set up backup automation
|
||||
- [ ] Configure monitoring alerts
|
||||
- [ ] Review and update dependencies regularly
|
||||
- [ ] Implement rate limiting
|
||||
- [ ] Enable CORS properly
|
||||
- [ ] Rotate API keys periodically
|
||||
Reference in New Issue
Block a user