🐳 Docker Deployment Guide

Docker is like a big box that packages MaiBot and everything it needs together, ready to run with one click!

📋 Preparation

You need to install:

• Docker (like installing a virtual machine)
• Docker Compose (Docker's helper)

🚀 5-Minute Quick Deployment

1. Download MaiBot

git clone https://github.com/Mai-with-u/MaiBot.git
cd MaiBot

2. One-Click Start!

docker compose up -d

First startup will automatically generate configuration files, then stop and wait for you to configure.

📦 What's in Docker?

Docker will start several services at once, like a team:

• core — MaiBot core, the robot's brain 🧠
• napcat — QQ connector, lets the robot get on QQ 📱
• sqlite-web — Database tool, view what the robot remembers 📊

⚙️ Environment Variables (Advanced Usage)

Core Service Settings

• TZ — Timezone, e.g. Asia/Shanghai
• EULA_AGREE — Skip agreement confirmation (advanced, usually don't worry about it)

QQ Service Settings

• NAPCAT_UID — User ID (usually use default)
• NAPCAT_GID — User group ID (usually use default)

💾 Where is Data Saved?

Docker will save important data in these locations on your computer:

Bot Data

• Config files: ./docker-config/mmc/ (robot settings)
• Runtime data: ./data/MaiMBot/ (chat history, memories, etc.)
• Plugins: ./data/MaiMBot/plugins/ (extra features)
• Logs: ./data/MaiMBot/logs/ (operation records)

QQ Data

• QQ config: ./docker-config/napcat/
• Login info: ./data/qq/ (no need to log in again next startup)

🔌 Port Information

• Web interface — Port 18001, open http://localhost:18001 in browser
• NapCat Web UI — Port 6099, NapCat web configuration panel
• Database tool — Port 8120, used to view robot data

📋 Complete Steps (Step by Step)

# 1. Download
git clone https://github.com/Mai-with-u/MaiBot.git
cd MaiBot

# 2. First startup (will generate config files)
docker compose up -d

# 3. Change config (important!)
# Open ./docker-config/mmc/bot_config.toml and fill in QQ number
# Open ./docker-config/mmc/model_config.toml and fill in API key

# 4. Restart to apply config
docker compose restart core

# 5. View logs
docker compose logs -f core

🔧 Common Problems

Container exits immediately after starting?

Check logs for the reason:

docker compose logs core

90% of the time it's because:

• Config files not filled correctly (especially API key)
• QQ number filled wrong

Not enough memory?

Docker uses quite a bit of memory, recommend at least 2GB free memory.

Want to stop the bot?

docker compose down

Want to restart?

docker compose restart