Migration Guide

​

Overview

​

Version Compatibility

​

Current Requirements

• NapCat Version: Always use the latest stable release
• NTQQ Version: Compatible with currently supported NTQQ versions
• Community Access: Requires NapCat >= 4.17.31 (join key valid for latest 100 versions)

​

Migration Checklist

1. Backup your configuration
   cp onebot11.json onebot11.json.backup
   
2. Review release notes
   • Check GitHub Releases for changes
   • Look for breaking changes
   • Note deprecated features
3. Test in development
   • Test the new version in a dev environment first
   • Verify all network adapters work
   • Test critical API calls
4. Update incrementally
   • Don’t skip major versions
   • Update one major version at a time if possible

​

Configuration Changes

​

Network Configuration Structure

{
  "network": {
    "httpServers": [{...}],
    "httpSseServers": [{...}],
    "httpClients": [{...}],
    "websocketServers": [{...}],
    "websocketClients": [{...}],
    "plugins": [{...}]
  }
}

​

Required Fields

{
  "name": "unique-name",
  "enable": true,
  "port": 3000  // or "url" for clients
}

​

Token Configuration

{
  "token": "your_secret_token"  // Previously may have been "access_token"
}

​

Heartbeat Configuration

{
  "heartInterval": 30000  // 30 seconds in milliseconds
}

​

API Changes

​

Response Format

{
  "status": "ok",
  "retcode": 0,
  "data": {...},
  "echo": "..."
}

​

Error Codes

​

Message Format

{
  "messagePostFormat": "array"  // or "string"
}

• "array" - OneBot 11 message segment array (recommended)
• "string" - CQ code format string

​

Network Adapter Changes

​

HTTP Server

{
  "httpServers": [{
    "name": "http-server",
    "enable": true,
    "port": 3000,
    "host": "127.0.0.1",
    "enableCors": true,
    "enableWebsocket": false,
    "token": "",
    "debug": false
  }]
}

• Added enableWebsocket option to enable WebSocket on same port
• Supports request bodies up to 5000MB (previously limited)
• Improved JSON5 parsing support

​

WebSocket Server

{
  "websocketServers": [{
    "name": "websocket-server",
    "enable": true,
    "host": "127.0.0.1",
    "port": 3001,
    "token": "",
    "heartInterval": 30000,
    "enableForcePushEvent": true
  }]
}

• heartInterval now in milliseconds
• Added enableForcePushEvent option
• Maximum payload size: 50MB

​

WebSocket Client (Reverse)

{
  "websocketClients": [{
    "name": "websocket-client",
    "enable": true,
    "url": "ws://localhost:8082",
    "token": "",
    "reconnectInterval": 5000,
    "heartInterval": 30000
  }]
}

• Added automatic reconnection
• reconnectInterval configurable (default: 5000ms)
• Sends X-Self-ID header
• Sends x-client-role: Universal for Koishi compatibility

​

HTTP Client (Webhook)

{
  "httpClients": [{
    "name": "http-client",
    "enable": true,
    "url": "http://localhost:8080",
    "token": ""
  }]
}

• HMAC-SHA1 signature in X-Signature header
• Sends X-Self-ID header
• Supports quick action responses

​

Authentication Changes

​

Token Authentication

Authorization: Bearer your_token

?access_token=your_token

ws://localhost:3001/?access_token=your_token

​

Signature Verification

const crypto = require('crypto');
const hmac = crypto.createHmac('sha1', token);
hmac.update(body);
const signature = 'sha1=' + hmac.digest('hex');

​

Deprecated Features

​

Legacy Configuration Format

{
  "http": {
    "enable": true,
    "port": 3000
  }
}

{
  "network": {
    "httpServers": [{
      "name": "http-server",
      "enable": true,
      "port": 3000
    }]
  }
}

​

Single Network Adapter

{
  "network": {
    "httpServers": [
      {"name": "public", "port": 3000},
      {"name": "private", "port": 3001}
    ]
  }
}

​

New Features

​

HTTP Server WebSocket Support

{
  "httpServers": [{
    "port": 3000,
    "enableWebsocket": true
  }]
}

• / - Event WebSocket
• /api - API WebSocket

​

JSON5 Support

{
  // Comments are allowed
  action: 'send_msg',  // Trailing commas OK
  params: {
    message: 'Hello',
  },
}

​

Debug Mode

{
  "debug": true
}

​

Report Self Message

{
  "reportSelfMessage": false  // Default: don't report self messages
}

​

Breaking Changes by Version

​

Version 4.x

• Network configuration moved to network object
• Adapters now in typed arrays (httpServers, websocketServers, etc.)
• Each adapter requires unique name field

• Standardized token field name
• HMAC signature for webhooks
• Token sent in Authorization header for reverse WebSocket

• Response format strictly follows OneBot 11
• Error codes standardized
• Echo parameter handling improved

​

Version 3.x to 4.x

1. Update configuration structure
   // Old
   {"http": {...}}
   
   // New
   {"network": {"httpServers": [{...}]}}
   
2. Update authentication code
   • Check for Authorization header
   • Verify HMAC signatures for webhooks
3. Update API response handling
   • Parse retcode instead of status
   • Handle new error codes
4. Update WebSocket connection logic
   • Handle lifecycle events
   • Update heartbeat handling
   • Handle reconnection events

​

Common Migration Issues

​

Configuration Not Loading

1. Validate JSON syntax
2. Check file location
3. Restart NapCat completely
4. Check logs for parsing errors

​

Authentication Failures

1. Update token field name to token
2. Update authentication header format
3. Verify token matches in config and client

​

WebSocket Connection Issues

1. Update connection URL format
2. Update authentication method
3. Handle new lifecycle events
4. Update heartbeat interval (now in milliseconds)

​

Missing Events

1. Check reportSelfMessage setting
2. Verify adapter is enabled
3. Connect to correct endpoint (/ for events)
4. Check message format setting

​

Testing After Migration

​

Basic Connectivity

# Test HTTP API
curl http://localhost:3000/get_login_info

# Test with authentication
curl -H "Authorization: Bearer token" http://localhost:3000/get_login_info

​

WebSocket Connection

const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:3001/?access_token=token');

ws.on('open', () => console.log('Connected'));
ws.on('message', (data) => console.log('Received:', data.toString()));
ws.on('error', (err) => console.error('Error:', err));

​

Send Test Message

curl -X POST http://localhost:3000/send_private_msg \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token" \
  -d '{"user_id": 12345678, "message": "Test"}'

​

Webhook Testing

// Test webhook signature verification
const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/', express.json(), (req, res) => {
  const signature = req.headers['x-signature'];
  const body = JSON.stringify(req.body);
  const hmac = crypto.createHmac('sha1', 'token');
  hmac.update(body);
  const expected = 'sha1=' + hmac.digest('hex');
  
  console.log('Signature:', signature === expected ? 'Valid' : 'Invalid');
  console.log('Event:', req.body);
  
  res.json({});
});

app.listen(8080);

​

Rollback Plan

1. Stop NapCat
   # Kill the process
   pkill napcat
   
2. Restore backup
   mv onebot11.json.backup onebot11.json
   
3. Reinstall previous version
   • Download previous release
   • Replace with backed-up version
4. Restart
   ./napcat
   

​

Getting Help

1. Check Troubleshooting Guide
2. Review GitHub Issues
3. Join Community Groups
4. Check FAQ

• Current NapCat version
• Previous NapCat version
• Configuration file (remove sensitive tokens)
• Error messages from logs
• Steps you’ve already tried

​

Next Steps

• Review Configuration Guide
• Check API Documentation
• Read Best Practices
• Join the Community