十点还有几分钟

Preface#

In today's rapidly developing AI technology, chatbots have become important tools in many scenarios. AstrBot, as a multi-platform large model robot infrastructure, combined with NapCat, which implements the OneBot protocol based on headless QQNT, allows us to easily build a powerful QQ chatbot. This tutorial will detail how to deploy these two components using Docker on an Ubuntu system.

What is AstrBot?#

AstrBot is an easy-to-use multi-platform chatbot and development framework with the following features:

Core Features#

• Multi-platform support: Supports various messaging platforms such as QQ, WeChat, Telegram, Feishu, DingTalk, etc.

• Easy to use: Supports various deployment methods such as Docker, Windows one-click installer, etc.

• High scalability: Fully modular architecture based on event bus and pipeline design.

• Large language model integration: Supports multiple model providers such as OpenAI, Anthropic, DeepSeek, and Zhiyu AI.

Main Functions#

• Quickly build, deploy, and manage cross-platform intelligent chatbots.

• Built-in AI knowledge base capability, eliminating complex deployment.

• Supports Docker-based sandboxed code executors.

• Allows large models to access the internet for web searches.

What is NapCat?#

NapCat (NapCatQQ) is the implementation end of the OneBot protocol based on headless QQNT, essentially running a QQNT instance to provide stable protocol support for QQ bot development.

NapCat Features#

• Stable and reliable: Based on the official QQ client, with better stability.

• Complete functionality: Supports various message types such as text, images, voice, files, etc.

• Easy to deploy: Provides various deployment methods such as Docker and one-click scripts.

• Web management interface: Provides an intuitive Web UI for configuration and management.

System Requirements#

Before starting the deployment, please ensure your Ubuntu system meets the following requirements:

• Ubuntu 18.04 or higher.

• At least 2GB RAM.

• At least 10GB of available disk space.

• Stable internet connection.

• A QQ number (preferably not a newly created QQ number).

• A mobile phone with camera functionality for QR code login.

Preparations#

Update the System#

First, update the Ubuntu system to the latest state:

sudo apt update && sudo apt upgrade -y

Note: This tutorial assumes you have already installed Docker and Docker Compose. If not, please refer to the official Docker documentation for installation.

Configure Firewall Ports#

Before deployment, ensure that the relevant ports can be accessed normally. Choose the corresponding configuration method based on the server type:

Foreign Servers (e.g., AWS, DigitalOcean, Vultr, etc.)#

Foreign servers typically use UFW (Uncomplicated Firewall) for firewall management, but UFW is disabled by default on Ubuntu systems:

    # First check the UFW status
    sudo ufw status

    # If it shows "Status: inactive", the firewall is not enabled, no additional configuration is needed.
    # If you need to enable the firewall (optional), you can execute the following steps:
 
    # Allow SSH port (important: avoid being locked out)
    sudo ufw allow 22

    # Allow AstrBot Web management interface port
    sudo ufw allow 6180

    # Allow NapCat Web management interface port
    sudo ufw allow 6099
  
    # Allow NapCat communication port
    sudo ufw allow 3000
    sudo ufw allow 3001
   
    # Allow AstrBot and NapCat communication port
    sudo ufw allow 6199

# Enable UFW firewall
sudo ufw enable

    # Check firewall status
    sudo ufw status    

Note: In most cases, foreign VPS has UFW disabled by default, allowing direct service deployment without firewall configuration.

Domestic Servers (e.g., Alibaba Cloud, Tencent Cloud, Huawei Cloud, etc.)#

Domestic servers mainly manage ports through the security group of the cloud service provider's console:

Cloud Service Provider Security Group Configuration:

You need to add the following inbound rules in the security group of the cloud service provider's console:

Specific Operation Steps:

• Alibaba Cloud: Go to ECS console → Security Group → Configure Rules → Add Security Group Rules.

• Tencent Cloud: Go to CVM console → Security Group → Inbound Rules → Add Rules.

• Huawei Cloud: Go to ECS console → Security Group → Inbound Rules → Add Rules.

Note: In most cases, domestic servers only need to configure the security group without additional system firewall configuration.

Precautions:

• If you only need local access to the Web interface, you can restrict the source IP to your public IP.

• Port 6199 is for internal communication; it is recommended to restrict the source to 127.0.0.1.

• In production environments, it is recommended to use stricter security group rules.

Method 1: One-click Deployment Using Docker Compose (Recommended)#

This is the simplest and most recommended deployment method, allowing simultaneous deployment of AstrBot and NapCat, and automatically configuring their connection.

1. Create Project Directory#

mkdir ~/astrbot-napcat
cd ~/astrbot-napcat

2. Download Docker Compose Configuration File#

curl -o astrbot.yml https://raw.githubusercontent.com/NapNeko/NapCat-Docker/main/compose/astrbot.yml

3. Start the Service#

NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) docker-compose -f ./astrbot.yml up -d

4. Check Service Status#

docker-compose -f ./astrbot.yml ps

5. View NapCat Logs to Get Login QR Code#

docker logs napcat

In the logs, you will see:

• QQ login QR code (use mobile QQ to scan the QR code to log in).

• NapCat WebUI management interface address (usually http://your-server-ip:6099).

6. Scan QR Code to Log in to QQ#

Use the mobile QQ corresponding to the QQ number you want to use as the bot to scan the QR code displayed in the logs to log in.

Method 2: Deploy AstrBot and NapCat Separately#

If you want more flexibility in controlling the deployment process, you can choose to deploy the two components separately.

Deploy NapCat#

1. Run NapCat Using Docker#

docker run -d \
  -e NAPCAT_GID=$(id -g) \
  -e NAPCAT_UID=$(id -u) \
  -p 3000:3000 \
  -p 3001:3001 \
  -p 6099:6099 \
  --name napcat \
  --restart=always \
  mlikiowa/napcat-docker:latest

2. View Logs and Log In#

docker logs napcat

Follow the prompts in the logs to scan the QR code to log in to QQ.

Deploy AstrBot#

1. Run AstrBot Using Docker#

docker run -d \
  -p 6180:6180 \
  -v ~/astrbot_data:/app/data \
  --name astrbot \
  --restart=always \
  soulter/astrbot:latest

2. Access AstrBot Management Interface#

Open a browser and visit http://your-server-ip:6180 to enter the AstrBot Web management interface.

Configure Connection#

Regardless of the deployment method used, you need to configure the connection between AstrBot and NapCat.

Configure aiocqhttp Adapter in AstrBot#

1. Open the AstrBot management panel (http://your-server-ip:6180).

2. Click on the Message Platform in the left menu.

3. Click + Add Adapter.

4. Select aiocqhttp(OneBotv11).

Configuration parameters are as follows:

• ID: Fill in arbitrarily to distinguish different message platform instances (e.g., qq-bot).

• Enable: Check.

• Reverse WebSocket Host Address: 0.0.0.0.

• Reverse WebSocket Port: 6199 (or another unused port).

Click Save to complete the configuration.

Configure Administrator#

1. In the AstrBot management panel, click on the Configuration page.

2. Click on the Other Configuration tab.

3. Find Administrator ID, fill in your QQ number (not the bot's QQ number).

4. Click Save in the bottom right corner.

AstrBot will automatically restart and apply the configuration.

Add WebSocket Client in NapCat#

1. Open the NapCat management panel (http://your-server-ip:6099).

2. Click Network Configuration -> New -> WebSockets Client.

Configuration parameters:

• Enable: Check.

• URL: ws://localhost:6199/ws (Note: the IP here is localhost, the port must match the one configured in AstrBot, and must end with /ws).

• Message Format: Array.

• Heartbeat Interval: 5000.

• Reconnect Interval: 5000.

Click Save to complete the configuration.

Verify Connection#

Check Connection Status#

1. In the AstrBot management panel's Console page, check if there are blue logs similar to the following:

   Copy

   aiocqhttp(OneBot v11) adapter connected.
   

2. If you see this log, the connection is successful.

Test Bot Functionality#

Use your personal QQ number (administrator QQ number) to privately message the bot QQ number, sending the /help command. If the bot replies with help information, the deployment is successful.

Configure Large Language Model#

AstrBot supports various large language model providers, taking OpenAI as an example:

1. Enter Model Configuration#

1. In the AstrBot management panel, click on the Configuration page.

2. Click on the Large Language Model tab.

2. Add Model Provider#

1. Click + Add Provider.

2. Select OpenAI.

3. Fill in the configuration information:

   • API Key: Your OpenAI API key.

   • Base URL: https://api.openai.com/v1 (or another compatible API address).

   • Model Name: gpt-3.5-turbo or gpt-4.

3. Save Configuration#

Click Save to complete the model configuration.

Common Management Commands#

Management Commands for Docker Compose Deployment#

# Check service status
docker-compose -f ./astrbot.yml ps

# View logs
docker-compose -f ./astrbot.yml logs

# Restart service
docker-compose -f ./astrbot.yml restart

# Stop service
docker-compose -f ./astrbot.yml down

# Update service
docker-compose -f ./astrbot.yml pull
docker-compose -f ./astrbot.yml up -d

Management Commands for Separate Deployment#

# Check container status
docker ps

# View NapCat logs
docker logs napcat

# View AstrBot logs
docker logs astrbot

# Restart containers
docker restart napcat
docker restart astrbot

# Stop containers
docker stop napcat astrbot

# Remove containers
docker rm napcat astrbot

Troubleshooting#

Common Issues and Solutions#

1. NapCat Cannot Log in to QQ#

Problem Phenomenon: Login fails or risk control prompts after scanning.

Solution:

• Ensure the QQ number used is not a newly registered account.

• Try logging into that QQ number normally on the phone before scanning.

• Check if the network connection is stable.

• If it still fails, try using a different QQ number.

2. AstrBot and NapCat Connection Failure#

Problem Phenomenon: No successful connection log displayed in the AstrBot console.

Solution:

• Check if the port configurations are consistent.

• Confirm that the WebSocket URL format is correct (must end with /ws).

• Check firewall settings to ensure relevant ports are not blocked.

• View the logs of both services for error messages.

3. Bot Does Not Reply to Messages#

Problem Phenomenon: Sending messages to the bot, but the bot does not reply.

Solution:

• Confirm that the administrator QQ number is configured correctly.

• Check if the large language model configuration is correct.

• View the AstrBot logs to confirm if there are any error messages.

• Try sending the /help command to test basic functionality.

4. Docker Container Fails to Start#

Problem Phenomenon: The container cannot start normally.

Solution:

• Check if the Docker service is running normally: sudo systemctl status docker.

• Confirm that the port is not occupied by other services: netstat -tlnp | grep :port_number.

• View the container logs: docker logs container_name.

• Check if there is sufficient disk space: df -h.

5. Cannot Access Web Management Interface#

Problem Phenomenon: The browser cannot open the AstrBot or NapCat Web interface.

Solution:

• Check if the cloud service provider's security group is configured correctly (this is the most common reason).

• If using a foreign server, check the UFW firewall status: sudo ufw status (usually shows inactive, no action needed).

• Check if the service is running normally: docker ps.

• Try accessing using the server's internal IP.

• Check if the port is correctly mapped: docker port container_name.

Log Viewing#

View Detailed Logs#

# View detailed logs for NapCat
docker logs -f napcat

# View detailed logs for AstrBot
docker logs -f astrbot

# If using Docker Compose
docker-compose -f ./astrbot.yml logs -f

Log File Locations#

• AstrBot logs are usually stored in the container's /app/data/logs/ directory.

• You can map the data volume to save logs to the host machine.

Security Recommendations#

1. Network Security#

• Firewall Configuration:

  • Only open necessary ports, close unnecessary service ports.

  • For the Web management interface, it is recommended to restrict access source IP.

  • Internal communication ports (e.g., 6199) should be restricted to local access.

• Port Security Recommendations:

  Copy

  # Restrict the Web interface to allow access only from specific IPs (using UFW as an example)
  sudo ufw delete allow 6180
  sudo ufw allow from YOUR_IP_ADDRESS to any port 6180
  
  # Restrict NapCat management interface access
  sudo ufw delete allow 6099
  sudo ufw allow from YOUR_IP_ADDRESS to any port 6099
  

• Other Security Measures:

  • If the server is exposed to the public network, it is recommended to use a reverse proxy (e.g., Nginx) and configure SSL certificates.

  • Regularly update the system and Docker images.

  • Consider using VPN or jump hosts to access the management interface.

2. Account Security#

• Do not use important QQ numbers as bot accounts.

• Regularly check the bot's behavior to ensure there are no abnormal activities.

• Reasonably set the bot's permissions and functions.

3. Data Backup#

# Backup AstrBot data
docker cp astrbot:/app/data ./astrbot_backup

# Backup NapCat configuration
docker cp napcat:/app/napcat ./napcat_backup

Advanced Configuration#

1. Configure Plugins#

AstrBot supports a rich plugin ecosystem, and you can install and manage plugins through the Web interface:

1. Click on the Plugins page in the management panel.

2. Browse available plugins and click Install.

3. Configure according to the plugin instructions.

2. Multi-QQ Number Support#

If you need to run multiple QQ bots simultaneously, you can:

1. Create separate NapCat containers for each QQ number.

2. Use different ports to avoid conflicts.

3. Configure multiple aiocqhttp adapters in AstrBot.

3. Custom Configuration#

You can customize more features by modifying configuration files:

• The AstrBot configuration file is located at /app/data/config/.

• The NapCat configuration file is located at /app/napcat/config/.

Effect Demonstration#

After deployment, with simple configuration, the following effects can be achieved:

Final Thoughts#

After all this effort, I believe everyone has successfully built their own QQ chatbot. The AstrBot Web interface is quite well done, and almost all configurations can be completed with a few clicks, eliminating the need to sift through complex configuration files. NapCat, as the QQ protocol end, is also very stable, making it much easier compared to some solutions I have used before.

Some Usage Tips#

In practical use, I found a few small tips to share with everyone:

1. About QQ Number Selection: It is not recommended to use newly registered accounts; it is best to use an account with some history, one that is used for normal chatting.

2. Server Selection: If the budget allows, it is recommended to choose foreign VPS, as the network environment is relatively relaxed. Domestic servers, while fast, have many restrictions.

3. Model Selection: You can choose the free API from Gemini, which is sufficient for personal use. You can also choose DeepSeek's API, which is currently very cheap and performs well.

4. Plugin Ecosystem: The AstrBot plugin ecosystem is quite rich, and you can install some practical plugins based on your needs, such as weather queries, translations, etc.

Overall, this solution is highly recommended. Moreover, once set up, the subsequent maintenance cost is very low. With continuous updates to the project, the functionality will become more and more complete.

That's all for the tutorial. If this article has helped you or if you have any questions, feel free to communicate in the comments section, and I will try to respond.

Finally, I wish everyone can build a satisfactory chatbot!

Related Links#

• AstrBot Official Website

• AstrBot Documentation

• AstrBot GitHub

• NapCat Documentation

• NapCat GitHub

• NapCat Docker

This tutorial is based on the latest versions of AstrBot and NapCat. Please refer to the official documentation for updates.

This article is synchronized and updated to xLog by Mix Space. The original link is https://blog.astrasolis.top/posts/tutorial/docker-astrbot-tutorial