Production Deployment

Deploy NapCat in production environments with systemd, PM2, or Docker

Overview

NapCat can be deployed in various production environments. This guide covers deployment methods, environment configuration, monitoring, and security best practices.

Deployment Methods

Using systemd (Linux)

1. Create Service File

   Create a systemd service file at /etc/systemd/system/napcat.service:

   [Unit]
   Description=NapCat QQ Bot Service
   After=network.target
   
   [Service]
   Type=simple
   User=napcat
   WorkingDirectory=/opt/napcat
   ExecStart=/usr/bin/node /opt/napcat/napcat.js
   Restart=always
   RestartSec=10
   StandardOutput=journal
   StandardError=journal
   SyslogIdentifier=napcat
   
   # Environment variables
   Environment="NODE_ENV=production"
   Environment="NAPCAT_DISABLE_BYPASS=0"
   
   [Install]
   WantedBy=multi-user.target
   
2. Enable and Start Service

   # Reload systemd configuration
   sudo systemctl daemon-reload
   
   # Enable service to start on boot
   sudo systemctl enable napcat
   
   # Start the service
   sudo systemctl start napcat
   
   # Check service status
   sudo systemctl status napcat
   
3. View Logs

   # View real-time logs
   sudo journalctl -u napcat -f
   
   # View logs from specific time
   sudo journalctl -u napcat --since "1 hour ago"
   

Using PM2

PM2 is a production process manager for Node.js applications.

1. Install PM2

   npm install -g pm2
   
2. Create Ecosystem File

   Create ecosystem.config.js in your NapCat directory:

   ecosystem.config.js

   module.exports = {
     apps: [{
       name: 'napcat',
       script: './napcat.js',
       instances: 1,
       exec_mode: 'fork',
       autorestart: true,
       watch: false,
       max_memory_restart: '1G',
       env: {
         NODE_ENV: 'production',
         NAPCAT_DISABLE_BYPASS: '0'
       },
       error_file: './logs/pm2-error.log',
       out_file: './logs/pm2-out.log',
       log_date_format: 'YYYY-MM-DD HH:mm:ss Z'
     }]
   }
   
3. Start with PM2

   # Start application
   pm2 start ecosystem.config.js
   
   # Save PM2 configuration
   pm2 save
   
   # Setup PM2 to start on system boot
   pm2 startup
   
4. PM2 Management Commands

   # View status
   pm2 status
   
   # View logs
   pm2 logs napcat
   
   # Restart
   pm2 restart napcat
   
   # Stop
   pm2 stop napcat
   
   # Monitor resources
   pm2 monit
   

Using Docker

1. Create Dockerfile

   Dockerfile

   FROM node:20-alpine
   
   # Install dependencies
   RUN apk add --no-cache \
       ffmpeg \
       chromium \
       nss \
       freetype \
       harfbuzz \
       ca-certificates \
       ttf-freefont
   
   # Set working directory
   WORKDIR /app
   
   # Copy application files
   COPY package*.json ./
   RUN npm ci --only=production
   
   COPY . .
   
   # Create directories
   RUN mkdir -p /app/data /app/logs /app/config
   
   # Set environment variables
   ENV NODE_ENV=production
   ENV NAPCAT_DISABLE_BYPASS=0
   
   # Expose WebUI port (default 6099)
   EXPOSE 6099
   
   # Start NapCat
   CMD ["node", "napcat.js"]
   
2. Create Docker Compose File

   docker-compose.yml

   version: '3.8'
   
   services:
     napcat:
       build: .
       container_name: napcat
       restart: unless-stopped
       ports:
         - "6099:6099"    # WebUI
         - "3000:3000"    # HTTP API (optional)
         - "3001:3001"    # WebSocket (optional)
       volumes:
         - ./data:/app/data
         - ./logs:/app/logs
         - ./config:/app/config
       environment:
         - NODE_ENV=production
         - NAPCAT_DISABLE_BYPASS=0
       networks:
         - napcat_network
   
   networks:
     napcat_network:
       driver: bridge
   
3. Deploy with Docker Compose

   # Build and start
   docker-compose up -d
   
   # View logs
   docker-compose logs -f napcat
   
   # Restart
   docker-compose restart napcat
   
   # Stop
   docker-compose down
   

Environment Variables

Configure NapCat behavior using environment variables:

systemd

# In /etc/systemd/system/napcat.service
Environment="NODE_ENV=production"
Environment="NAPCAT_DISABLE_BYPASS=0"
Environment="NAPCAT_LOG_LEVEL=info"

Available Environment Variables

Variable	Description	Default
NODE_ENV	Node.js environment mode	development
NAPCAT_DISABLE_BYPASS	Disable protocol bypass features	0 (enabled)
NAPCAT_LOG_LEVEL	Logging level (debug/info/warn/error)	info

From napcat.ts:50-58, bypass features can be controlled via environment variable or config file. The bypass system enables protocol optimizations.

Monitoring

Health Checks

Implement health monitoring to ensure service availability:

// Health check endpoint
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
    uptime: process.uptime()
  })
})

Log Monitoring

systemd

# Monitor logs in real-time
journalctl -u napcat -f

# Search for errors
journalctl -u napcat | grep ERROR

Resource Monitoring

# System resources with PM2
pm2 monit

# Docker resource usage
docker stats napcat

# System-wide monitoring
htop

Security Best Practices

Always secure your NapCat deployment in production environments!

1. Network Security

docker-compose.yml

services:
  napcat:
    # Only expose necessary ports
    ports:
      - "127.0.0.1:6099:6099"  # WebUI only on localhost
    # Use internal network for service communication
    networks:
      - internal_network

networks:
  internal_network:
    internal: true

2. File Permissions

# Set appropriate ownership
sudo chown -R napcat:napcat /opt/napcat

# Restrict permissions
chmod 750 /opt/napcat
chmod 640 /opt/napcat/config/*.json

3. Authentication

Enable WebUI authentication in your config:

config.json

{
  "webui": {
    "token": "your-secure-random-token-here",
    "loginRequired": true
  }
}

4. Firewall Configuration

# UFW (Ubuntu)
sudo ufw allow from 192.168.1.0/24 to any port 6099
sudo ufw enable

# firewalld (CentOS/RHEL)
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="6099" protocol="tcp" accept'
sudo firewall-cmd --reload

5. Reverse Proxy with SSL

Use nginx as a reverse proxy with SSL:

server {
    listen 443 ssl http2;
    server_name napcat.example.com;

    ssl_certificate /etc/ssl/certs/napcat.crt;
    ssl_certificate_key /etc/ssl/private/napcat.key;

    location / {
        proxy_pass http://127.0.0.1:6099;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Backup and Recovery

Backup Essential Data

#!/bin/bash
# backup-napcat.sh

BACKUP_DIR="/backup/napcat/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Backup configuration
cp -r /opt/napcat/config "$BACKUP_DIR/"

# Backup data
cp -r /opt/napcat/data "$BACKUP_DIR/"

# Backup logs (optional)
cp -r /opt/napcat/logs "$BACKUP_DIR/"

echo "Backup completed: $BACKUP_DIR"

Automated Backups with Cron

# Add to crontab
crontab -e

# Daily backup at 2 AM
0 2 * * * /opt/napcat/backup-napcat.sh

Troubleshooting

Service Won’t Start

# Check service status
systemctl status napcat

# View detailed logs
journalctl -xeu napcat

# Check file permissions
ls -la /opt/napcat

High Memory Usage

ecosystem.config.js

// Add memory limit in PM2
max_memory_restart: '1G'

Connection Issues

# Test port availability
netstat -tlnp | grep 6099

# Check firewall rules
sudo ufw status

Next Steps

Login Methods

Configure QQ account login

Message Handling

Handle messages and events