Software Updates
Update Cherry Studio Enterprise via one-click update in the admin console (Docker Compose) or manual update.
Version Requirement
One-click update requires v0.3.3 or later. If your current version is lower than v0.3.3, update manually to v0.3.3 first, then you can use one-click update.
Update Methods
Method 1: One-Click Update in Admin Console (Recommended)
If you deployed with Docker Compose, you can update directly from the admin console.
Prerequisites
To enable one-click update, configure the following in docker-compose.yml:
- Mount Docker Socket: Allow the container to control Docker
- Mount docker-compose.yml: Allow the container to read and update the config file
Configuration Example
services:
api:
image: cherrystudio/cherry-studio-enterprise-api:v0.4.10
container_name: cherry-studio-enterprise-api
ports:
- '3670:3670'
- '3680:3680'
environment:
# ... other environment variables ...
volumes:
# Application data
- ./data:/app/data
# Required for one-click update
- /var/run/docker.sock:/var/run/docker.sock # Mount Docker Socket
- ./docker-compose.yml:/app/docker-compose.yml # Mount docker-compose.yml
restart: unless-stoppedSteps
- Sign in to the admin console
- Go to the About page
- In the Version Info section, click Check for updates
- If a new version is available, an Update now button and version list will appear
- Select the version and click Update
- The system will automatically:
- Pull the new image
- Update the image version in docker-compose.yml
- Stop old containers
- Start new containers
- The page will refresh after the update completes
Notes
- Service will be briefly interrupted (typically 10-30 seconds)
- Do not close the browser or refresh during the update
- If update fails, check container logs
Method 2: Manual Update
If you did not configure one-click update or prefer manual control, follow these steps:
Pull the new image
# Pull latest version (Docker Hub)
docker pull cherrystudio/cherry-studio-enterprise-api:latest
# Or pull a specific version
docker pull cherrystudio/cherry-studio-enterprise-api:v0.4.10
# China users: use the China mirror for faster pulls:
docker pull docker-registry.cherry-ai.com/public/cherry-studio-enterprise-api:latestUpdate docker-compose.yml
Modify the image tag in docker-compose.yml:
services:
api:
image: cherrystudio/cherry-studio-enterprise-api:v0.4.10 # Update version
# ... other configuration unchanged ...Restart services
# Stop and recreate containers
docker-compose down
docker-compose up -d
# View logs to confirm startup
docker-compose logs -fVerify the update
- Check the version on the About page in the admin console
- Verify the service is running:
curl http://localhost:3670/health
View Version Information
Check current version
- Admin console: Sign in and open the About page
- API: Visit the
/healthendpoint - CLI:
docker inspect cherry-studio-enterprise-api | grep "Image"
View release notes
- Admin console: About > Release Notes
- Online docs: Release Notes
FAQ
1. One-click update button does not appear
Possible causes:
- Docker Socket not mounted
- docker-compose.yml not mounted
- Insufficient Docker Socket permissions
Solutions:
- Confirm required volumes are mounted in
docker-compose.yml - Verify Docker Socket exists:
ls -la /var/run/docker.sock - Check container permissions to access Docker Socket
2. Image pull failure
Possible causes:
- Network connectivity issues
- Docker Hub access restricted
Solutions:
- Check network connectivity
- Configure a Docker registry mirror
- Pull the image manually, then update
3. Service fails to start after update
Troubleshooting steps:
# Check container logs
docker logs cherry-studio-enterprise-api
# Check container status
docker ps -a
# Check port usage
netstat -tulpn | grep -E '3670|3680'Common causes:
- Database connection configuration error
- Port conflicts
- Missing environment variables
Related Documents
- Docker deployment guide - Docker deployment details
- Database configuration guide - PostgreSQL configuration
- Helm deployment guide - Kubernetes deployment