SurfSense/_bmad-output/admin-guide.md

Hướng Dẫn Quản Trị SurfSense

Dành cho Administrators

---

📖 Giới Thiệu

Tài liệu này hướng dẫn administrators cách quản lý và vận hành hệ thống SurfSense.

---

🚀 Yêu Cầu Hệ Thống

Backend Server (Production)

• CPU: 4+ cores
• RAM: 8GB+
• Storage: 100GB+ SSD
• OS: Ubuntu 22.04 LTS

Database

• PostgreSQL 15+
• RAM: 4GB+
• Storage: 50GB+

Dependencies

• Python 3.11+
• Node.js 18+
• Docker & Docker Compose
• Redis

---

---

🔑 Default Admin Account

Tài khoản quản trị mặc định:

• Email: admin@surfsense.ai
• Password: password123

Warning

Bảo mật quan trọng: Đổi mật khẩu ngay sau khi đăng nhập lần đầu!

---

👥 Quản Lý Users

Tạo User Mới

Via CLI:

cd surfsense_backend
python manage.py create-user \
  --email user@example.com \
  --name "John Doe" \
  --role user \
  --plan pro

Phân Quyền (Roles)

Role	Permissions
user	Sử dụng tất cả tính năng end-user
admin	Quản lý users, xem analytics
superadmin	Quản lý toàn bộ hệ thống

Thay đổi role:

python manage.py set-role --email user@example.com --role admin

Quản Lý Plans

Plan	Limits
Free	100 captures/month, 50 AI queries/month, 1GB storage
Pro	Unlimited captures, 500 AI queries/month, 10GB storage
Enterprise	Unlimited everything, custom AI models

---

⚙️ Cấu Hình Hệ Thống

Environment Variables

File: surfsense_backend/.env

DATABASE_URL=postgresql://user:password@localhost:5432/surfsense
REDIS_URL=redis://localhost:6379/0

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

JWT_SECRET=your-secret-key
JWT_EXPIRY=3600

ENABLE_RESEARCH_MODE=true
RATE_LIMIT_PER_MINUTE=60
LOG_LEVEL=INFO

Database Migrations

cd surfsense_backend
alembic upgrade head

---

📊 Monitoring

Health Check

curl https://api.surfsense.ai/health

Response:

{
  "status": "healthy",
  "services": {
    "database": "up",
    "redis": "up",
    "vector_db": "up"
  }
}

Logs

# Real-time logs
tail -f surfsense_backend/logs/app.log

# Docker logs
docker logs -f surfsense_backend

Performance Metrics

Via Admin Dashboard:

• Active Users (real-time, daily, monthly)
• API Response Times (p50, p95, p99)
• Error Rates
• Storage Usage

---

🔐 Bảo Mật

SSL/TLS

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d api.surfsense.ai

Backup

Automated backup script:

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/surfsense"

pg_dump -U surfsense surfsense > $BACKUP_DIR/db_$DATE.sql
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz /var/surfsense/uploads

# Keep last 7 days
find $BACKUP_DIR -type f -mtime +7 -delete

Cron job (2AM daily):

0 2 * * * /usr/local/bin/backup.sh >> /var/log/surfsense-backup.log 2>&1

---

🛠️ Troubleshooting

Backend Không Start

# Check logs
tail -n 100 surfsense_backend/logs/app.log

# Test database
python -c "from app.db import engine; engine.connect()"

# Check port
lsof -i :8000

AI Queries Timeout

# Test AI endpoint
curl -X POST http://localhost:8000/api/ai/chat \
  -H "Authorization: Bearer <token>" \
  -d '{"message": "test"}'

# Check queue
redis-cli LLEN ai_query_queue

Slow Search

-- Create indexes
CREATE INDEX idx_content_user_id ON content(user_id);
CREATE INDEX idx_content_tags ON content USING GIN(tags);

---

📦 Deployment

Docker Compose

version: '3.8'
services:
  backend:
    build: ./surfsense_backend
    ports: ["8000:8000"]
    depends_on: [db, redis]
  
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: surfsense
      POSTGRES_PASSWORD: password
  
  redis:
    image: redis:7-alpine
  
  qdrant:
    image: qdrant/qdrant
    ports: ["6333:6333"]

Deploy:

docker-compose up -d

---

Cập nhật: 2026-01-31 | Version: 1.0