xiaozhi-esp32 -java

Xiaozhi ESP32 Server Java provides a complete back-end and front-end management platform for Xiaozhi ESP32 devices. The server uses Spring Boot for the back end and Vue.js with Ant Design for the front end, backed by MySQL and Redis for data storage and caching. The system exposes a management UI to configure devices, users, roles, and conversations, and it also offers MCP integration points (via SSE MCP) for extending capabilities with other tools and services. You can access the web UI to manage devices, view chat history, configure LLMs, and set up hooks and agents. For programmatic access, the server exposes REST APIs and real-time channels (WebSocket/SSE) to monitor device state, issue commands, and coordinate actions across a fleet of ESP32 devices. The included MCP integration points allow you to connect additional tools and services and orchestrate multi-step workflows within the platform.

Prerequisites:

• Docker and Docker Compose (recommended) or a Java runtime if you prefer native deployment
• MySQL and Redis (or use Dockerized versions)
• Git

Option A: Run with Docker (recommended)

1. Ensure you have a MySQL and Redis instance available and reachable by the container. Set the connection details in environment variables or a docker-compose file.
2. Pull and run the Docker image:

# Using the official image name from the README
docker pull joey-zhou/xiaozhi-esp32-server-java

# Run with required environment variables (adjust values as needed)
docker run -d --name xiaozhi-esp32-server-java \
  -e SPRING_DATASOURCE_URL="jdbc:mysql://<HOST>:<PORT>/<DB_NAME>" \
  -e SPRING_DATASOURCE_USERNAME="<DB_USERNAME>" \
  -e SPRING_DATASOURCE_PASSWORD="<DB_PASSWORD>" \
  -e REDIS_HOST="<REDIS_HOST>" \
  -e REDIS_PORT="<REDIS_PORT>" \
  -p 8080:8080 \
  joey-zhou/xiaozhi-esp32-server-java

Option B: Run locally with Java (if you build from source)

1. Install Java (OpenJDK 17+), Maven, and a database setup as above.
2. Clone the repository and build:

git clone https://github.com/joey-zhou/xiaozhi-esp32-server-java.git
cd xiaozhi-esp32-server-java
mvn clean package -DskipTests

3. Run the jar (adjust the path to the built jar):

java -jar target/xiaozhi-esp32-server-java-*.jar

Configuration notes:

• Ensure MySQL and Redis are reachable from the server.
• Configure application.properties or environment variables for DB/Redis connections as needed.
• If you deploy with Docker, consider a docker-compose setup to manage MySQL, Redis, and the server together.

Tips and common considerations:

• The UI is Vue-based and requires the server to serve the backend APIs and the frontend assets. Ensure CORS and API paths are correctly configured if you proxy or host separately.
• For MCP integration, use the SSE MCP endpoints provided by the backend to connect additional tools or services.
• Monitor logs for startup issues related to database connections or port binding. If the server cannot connect to MySQL/Redis, verify network accessibility and credentials.
• Back up configuration and data regularly; enable Redis persistence if using Redis as a cache layer.
• When deploying in production, consider configuring a reverse proxy (e.g., Nginx) and enabling TLS for the web UI endpoints.