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:
你的用户名
402
marketing-agent/docs/deployment/README.md
Normal file
402
marketing-agent/docs/deployment/README.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# Deployment Guide for Marketing Intelligence Agent System
|
||||
|
||||
This guide covers various deployment options for the Marketing Intelligence Agent System.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Docker Deployment](#docker-deployment)
|
||||
- [Kubernetes Deployment](#kubernetes-deployment)
|
||||
- [CI/CD Pipeline](#cicd-pipeline)
|
||||
- [Environment Configuration](#environment-configuration)
|
||||
- [Security Best Practices](#security-best-practices)
|
||||
- [Monitoring and Maintenance](#monitoring-and-maintenance)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### System Requirements
|
||||
|
||||
- **CPU**: Minimum 8 cores (16 cores recommended for production)
|
||||
- **Memory**: Minimum 16GB RAM (32GB recommended for production)
|
||||
- **Storage**: Minimum 100GB SSD storage
|
||||
- **Network**: Stable internet connection with low latency
|
||||
|
||||
### Software Requirements
|
||||
|
||||
- Docker 20.10+ and Docker Compose 2.0+
|
||||
- Kubernetes 1.24+ (for K8s deployment)
|
||||
- Helm 3.10+ (for K8s deployment)
|
||||
- Git
|
||||
- Node.js 18+ (for local development)
|
||||
|
||||
### External Services
|
||||
|
||||
- Telegram account with API credentials
|
||||
- Anthropic API key (for Claude AI)
|
||||
- OpenAI API key (optional, for safety checks)
|
||||
- SMTP server or email service (for notifications)
|
||||
- S3-compatible storage (for backups)
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Quick Start
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/yourcompany/marketing-agent.git
|
||||
cd marketing-agent
|
||||
```
|
||||
|
||||
2. Copy environment template:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
3. Edit `.env` file with your configurations:
|
||||
```bash
|
||||
# Required configurations
|
||||
ANTHROPIC_API_KEY=your_anthropic_api_key
|
||||
JWT_SECRET=your_jwt_secret
|
||||
MONGO_ROOT_PASSWORD=secure_password
|
||||
REDIS_PASSWORD=secure_password
|
||||
# ... other configurations
|
||||
```
|
||||
|
||||
4. Build and start services:
|
||||
```bash
|
||||
# Build all images
|
||||
./scripts/docker-build.sh
|
||||
|
||||
# Start services
|
||||
docker-compose up -d
|
||||
|
||||
# Wait for services to be ready
|
||||
./scripts/wait-for-services.sh
|
||||
```
|
||||
|
||||
5. Initialize admin user:
|
||||
```bash
|
||||
docker-compose exec api-gateway node scripts/init-admin.js
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
|
||||
For production deployment, use the production compose file:
|
||||
|
||||
```bash
|
||||
# Build with production optimizations
|
||||
./scripts/docker-build.sh --tag v1.0.0 --registry ghcr.io/yourcompany
|
||||
|
||||
# Deploy with production settings
|
||||
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
||||
```
|
||||
|
||||
### SSL/TLS Configuration
|
||||
|
||||
1. Place SSL certificates in `infrastructure/ssl/`:
|
||||
```
|
||||
infrastructure/ssl/
|
||||
├── cert.pem
|
||||
├── key.pem
|
||||
└── dhparam.pem
|
||||
```
|
||||
|
||||
2. Update nginx configuration:
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
ssl_certificate /etc/nginx/ssl/cert.pem;
|
||||
ssl_certificate_key /etc/nginx/ssl/key.pem;
|
||||
# ... other SSL settings
|
||||
}
|
||||
```
|
||||
|
||||
## Kubernetes Deployment
|
||||
|
||||
### Using Helm
|
||||
|
||||
1. Add Helm dependencies:
|
||||
```bash
|
||||
cd helm/marketing-agent
|
||||
helm dependency update
|
||||
```
|
||||
|
||||
2. Create namespace:
|
||||
```bash
|
||||
kubectl create namespace marketing-agent
|
||||
```
|
||||
|
||||
3. Create secrets:
|
||||
```bash
|
||||
kubectl create secret generic marketing-agent-secrets \
|
||||
--from-literal=anthropic-api-key=$ANTHROPIC_API_KEY \
|
||||
--from-literal=jwt-secret=$JWT_SECRET \
|
||||
-n marketing-agent
|
||||
```
|
||||
|
||||
4. Install the chart:
|
||||
```bash
|
||||
helm install marketing-agent ./helm/marketing-agent \
|
||||
--namespace marketing-agent \
|
||||
--values ./helm/marketing-agent/values.yaml \
|
||||
--values ./helm/marketing-agent/values.prod.yaml
|
||||
```
|
||||
|
||||
### Manual Kubernetes Deployment
|
||||
|
||||
If not using Helm, apply the manifests directly:
|
||||
|
||||
```bash
|
||||
kubectl apply -f infrastructure/k8s/namespace.yaml
|
||||
kubectl apply -f infrastructure/k8s/configmap.yaml
|
||||
kubectl apply -f infrastructure/k8s/secrets.yaml
|
||||
kubectl apply -f infrastructure/k8s/deployments/
|
||||
kubectl apply -f infrastructure/k8s/services/
|
||||
kubectl apply -f infrastructure/k8s/ingress.yaml
|
||||
```
|
||||
|
||||
### Scaling
|
||||
|
||||
Horizontal Pod Autoscaling is configured for key services:
|
||||
|
||||
```bash
|
||||
# Check HPA status
|
||||
kubectl get hpa -n marketing-agent
|
||||
|
||||
# Manual scaling
|
||||
kubectl scale deployment marketing-agent-api-gateway --replicas=5 -n marketing-agent
|
||||
```
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
The project includes comprehensive CI/CD pipelines:
|
||||
|
||||
#### Continuous Integration (.github/workflows/ci.yml)
|
||||
- Code linting and formatting
|
||||
- Security scanning
|
||||
- Unit and integration tests
|
||||
- Docker image building
|
||||
- E2E testing
|
||||
- Performance testing
|
||||
|
||||
#### Continuous Deployment (.github/workflows/cd.yml)
|
||||
- Automatic deployment to staging on main branch
|
||||
- Production deployment on version tags
|
||||
- Database migrations
|
||||
- Blue-green deployment
|
||||
- Automated rollback on failure
|
||||
|
||||
#### Security Scanning (.github/workflows/security.yml)
|
||||
- Container vulnerability scanning
|
||||
- SAST (Static Application Security Testing)
|
||||
- Secret scanning
|
||||
- Dependency auditing
|
||||
- Infrastructure security checks
|
||||
|
||||
### Setting up CI/CD
|
||||
|
||||
1. Configure GitHub secrets:
|
||||
```
|
||||
AWS_ACCESS_KEY_ID
|
||||
AWS_SECRET_ACCESS_KEY
|
||||
ANTHROPIC_API_KEY
|
||||
SLACK_WEBHOOK
|
||||
DOCKER_REGISTRY_USERNAME
|
||||
DOCKER_REGISTRY_PASSWORD
|
||||
```
|
||||
|
||||
2. Configure deployment environments in GitHub:
|
||||
- staging
|
||||
- production
|
||||
|
||||
3. Enable branch protection rules for main branch
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create environment-specific files:
|
||||
- `.env.development`
|
||||
- `.env.staging`
|
||||
- `.env.production`
|
||||
|
||||
Key configurations:
|
||||
|
||||
```bash
|
||||
# Application
|
||||
NODE_ENV=production
|
||||
LOG_LEVEL=info
|
||||
|
||||
# Security
|
||||
JWT_SECRET=<generate-with-openssl-rand>
|
||||
ENCRYPTION_KEY=<32-byte-key>
|
||||
|
||||
# Database
|
||||
MONGODB_URI=mongodb://user:pass@mongodb:27017/marketing_agent
|
||||
REDIS_PASSWORD=<secure-password>
|
||||
|
||||
# External Services
|
||||
ANTHROPIC_API_KEY=<your-key>
|
||||
TELEGRAM_SYSTEM_URL=<your-telegram-system-url>
|
||||
|
||||
# Monitoring
|
||||
GRAFANA_ADMIN_PASSWORD=<secure-password>
|
||||
ELASTIC_PASSWORD=<secure-password>
|
||||
```
|
||||
|
||||
### Configuration Management
|
||||
|
||||
Use ConfigMaps for non-sensitive configurations:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: marketing-agent-config
|
||||
data:
|
||||
NODE_ENV: "production"
|
||||
LOG_LEVEL: "info"
|
||||
RATE_LIMIT_WINDOW: "60000"
|
||||
RATE_LIMIT_MAX: "100"
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### 1. Secret Management
|
||||
|
||||
- Use Kubernetes secrets or external secret managers (Vault, AWS Secrets Manager)
|
||||
- Rotate secrets regularly
|
||||
- Never commit secrets to version control
|
||||
|
||||
### 2. Network Security
|
||||
|
||||
- Enable network policies to restrict traffic
|
||||
- Use TLS for all communications
|
||||
- Implement proper CORS policies
|
||||
|
||||
### 3. Container Security
|
||||
|
||||
- Run containers as non-root user
|
||||
- Use minimal base images (Alpine)
|
||||
- Scan images for vulnerabilities
|
||||
- Keep dependencies updated
|
||||
|
||||
### 4. Access Control
|
||||
|
||||
- Implement RBAC in Kubernetes
|
||||
- Use service accounts with minimal permissions
|
||||
- Enable audit logging
|
||||
|
||||
### 5. Data Protection
|
||||
|
||||
- Encrypt data at rest
|
||||
- Use TLS for data in transit
|
||||
- Implement proper backup encryption
|
||||
- Follow GDPR compliance guidelines
|
||||
|
||||
## Monitoring and Maintenance
|
||||
|
||||
### Health Checks
|
||||
|
||||
All services expose health endpoints:
|
||||
- `/health` - Basic health check
|
||||
- `/health/live` - Liveness probe
|
||||
- `/health/ready` - Readiness probe
|
||||
|
||||
### Metrics and Monitoring
|
||||
|
||||
1. Access Grafana dashboards:
|
||||
```
|
||||
http://localhost:3032 (Docker)
|
||||
https://grafana.your-domain.com (K8s)
|
||||
```
|
||||
|
||||
2. Key metrics to monitor:
|
||||
- API response times
|
||||
- Error rates
|
||||
- Message delivery success rate
|
||||
- System resource usage
|
||||
- Database performance
|
||||
|
||||
### Logging
|
||||
|
||||
Centralized logging with Elasticsearch:
|
||||
|
||||
```bash
|
||||
# View logs
|
||||
docker-compose logs -f api-gateway
|
||||
|
||||
# Search logs in Elasticsearch
|
||||
curl -X GET "localhost:9200/logs-*/_search?q=error"
|
||||
```
|
||||
|
||||
### Backup and Recovery
|
||||
|
||||
Automated backups are configured to run daily:
|
||||
|
||||
```bash
|
||||
# Manual backup
|
||||
./scripts/backup.sh
|
||||
|
||||
# Restore from backup
|
||||
./scripts/restore.sh backup-20240115-020000.tar.gz
|
||||
```
|
||||
|
||||
### Maintenance Tasks
|
||||
|
||||
1. **Database maintenance**:
|
||||
```bash
|
||||
# MongoDB optimization
|
||||
docker-compose exec mongodb mongosh --eval "db.adminCommand({compact: 'campaigns'})"
|
||||
|
||||
# Redis memory optimization
|
||||
docker-compose exec redis redis-cli --raw MEMORY DOCTOR
|
||||
```
|
||||
|
||||
2. **Log rotation**:
|
||||
```bash
|
||||
# Configured in Docker with max-size and max-file
|
||||
# For K8s, use log shipping solutions
|
||||
```
|
||||
|
||||
3. **Update dependencies**:
|
||||
```bash
|
||||
# Check for updates
|
||||
npm audit
|
||||
|
||||
# Update dependencies
|
||||
npm update
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
Common issues and solutions:
|
||||
|
||||
1. **Service not starting**:
|
||||
- Check logs: `docker-compose logs <service>`
|
||||
- Verify environment variables
|
||||
- Check resource availability
|
||||
|
||||
2. **Database connection issues**:
|
||||
- Verify connection strings
|
||||
- Check network connectivity
|
||||
- Ensure database is initialized
|
||||
|
||||
3. **Performance issues**:
|
||||
- Check resource usage
|
||||
- Review slow query logs
|
||||
- Enable performance profiling
|
||||
|
||||
4. **Deployment failures**:
|
||||
- Check CI/CD logs
|
||||
- Verify credentials and permissions
|
||||
- Review deployment prerequisites
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Review [API Documentation](../api/README.md)
|
||||
- Configure [Monitoring Dashboards](../monitoring/README.md)
|
||||
- Set up [Backup Strategy](../backup/README.md)
|
||||
- Implement [Disaster Recovery Plan](../disaster-recovery/README.md)
|
||||
Reference in New Issue
Block a user