Cherry Studio Enterprise
安装与部署

Docker 部署

使用 Docker 和 Docker Compose 部署 Cherry Studio Enterprise

这个文档详细介绍了如何使用 Docker 和 Docker Compose 部署 Cherry Studio Enterprise API 服务。

特性

  • 双服务集成：单容器内同时运行 API 服务（3670端口）和管理后台（3680端口）
  • 数据持久化：支持数据卷挂载，确保数据安全
  • 环境配置：灵活的环境变量配置
  • 健康检查：内置健康检查机制
  • 自动重启：支持容器自动重启策略

快速开始

前置条件

  • Docker 20.10+
  • Docker Compose 2.0+（可选）
  • PostgreSQL 数据库（生产环境）

使用 Docker Compose

services:
  api:
    image: cherrystudio/cherry-studio-enterprise-api:latest
    container_name: cherry-studio-enterprise
    ports:
      - '3670:3670'
      - '3680:3680'
    environment:
      - API_URL=https://api.demo.cherry-ai.com
      - JWT_SECRET=your-secure-jwt-secret-at-least-32-characters
      - DB_HOST=1Panel-postgresql-UmXp
      - DB_PORT=5432
      - DB_USERNAME=cherry-studio-enterprise
      - DB_PASSWORD=${DB_PASSWORD}
      - DB_NAME=cherry-studio-enterprise
      - DB_TYPE=postgres
      - DB_SSL=false
    volumes:
      - ./data:/app/data
    restart: unless-stopped

完整生产环境配置（含数据库）

services:
  # PostgreSQL 数据库
  postgres:
    image: postgres:15-alpine
    container_name: cherry-studio-enterprise-postgres
    environment:
      POSTGRES_USER: cherry-studio-enterprise
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: cherry-studio-enterprise
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - '5432:5432'
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U cherry-studio-enterprise']
      interval: 10s
      timeout: 5s
      retries: 5

  # Cherry Studio API
  api:
    image: cherrystudio/cherry-studio-enterprise-api:latest
    container_name: cherry-studio-enterprise
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - '3670:3670'
      - '3680:3680'
    environment:
      # 服务配置
      - API_URL=https://api.your-domain.com
      - ADMIN_APP_NAME=Cherry Studio Enterprise

      # 安全配置
      - JWT_SECRET=${JWT_SECRET:-your-secure-jwt-secret-at-least-32-characters}

      # 数据库配置
      - DB_TYPE=postgres
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_USERNAME=cherry-studio-enterprise
      - DB_PASSWORD=${POSTGRES_PASSWORD}
      - DB_NAME=cherry-studio-enterprise
      - DB_SSL=false

    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

    restart: unless-stopped

    healthcheck:
      test: ['CMD', 'wget', '--quiet', '--tries=1', '--spider', 'http://localhost:3670/health']
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  postgres_data:
    driver: local

启动和管理

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 停止并删除数据卷（危险操作）
docker-compose down -v

配置说明

端口映射

容器端口服务说明
3670API 服务RESTful API 接口，供客户端调用
3680Admin 后台Web 管理界面，用于系统配置和管理

环境变量

核心配置

变量名描述默认值必填
API_PORTAPI 服务端口3670否
ADMIN_PORTAdmin 后台端口3680否
API_URLAPI 基础 URL-是
JWT_SECRETJWT 加密密钥-是
ADMIN_APP_NAME管理后台应用名称Cherry Studio否
ADMIN_APP_LOGO_URL管理后台 Logo URL-否
ADMIN_BASE_PATH管理后台基础路径/否

数据库配置

变量名描述默认值说明
DB_TYPE数据库类型postgres仅支持 postgres
DB_HOST数据库主机-PostgreSQL 必填
DB_PORT数据库端口5432PostgreSQL 默认端口
DB_USERNAME数据库用户名-PostgreSQL 必填
DB_PASSWORD数据库密码-PostgreSQL 必填
DB_NAME数据库名称-PostgreSQL 必填
DB_SSL是否启用 SSLfalsePostgreSQL SSL 连接

如需配置 Casdoor 单点登录 (SSO)，请参阅 单点登录配置。

数据持久化

应用数据存储在 /app/data 目录，包括：

  • 上传的文件
  • 知识库数据
  • 应用配置

建议将此目录挂载到宿主机，确保数据持久化：

volumes:
  - ./data:/app/data # 应用数据
  - ./logs:/app/logs # 日志文件（可选）

部署最佳实践

1. 安全配置

JWT 密钥管理：

# 生成强随机密钥
openssl rand -base64 32

2. 网络配置

使用自定义网络：

services:
  api:
    networks:
      - cherry-network

networks:
  cherry-network:
    driver: bridge

配置反向代理（Nginx）：

server {
    listen 80;
    server_name api.your-domain.com;

    location / {
        proxy_pass http://localhost:3670;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name admin.your-domain.com;

    location / {
        proxy_pass http://localhost:3680;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

3. 性能优化

资源限制：

services:
  api:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

健康检查配置：

healthcheck:
  test: ['CMD', 'curl', '-f', 'http://localhost:3670/health']
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

4. 日志管理

配置日志驱动：

services:
  api:
    logging:
      driver: 'json-file'
      options:
        max-size: '10m'
        max-file: '3'

监控与维护

查看日志

# 实时查看日志
docker logs -f cherry-studio-enterprise

# 查看最后 100 行日志
docker logs --tail 100 cherry-studio-enterprise

# 查看特定时间段的日志
docker logs --since 2024-01-01 --until 2024-01-02 cherry-studio-enterprise

性能监控

# 查看容器资源使用
docker stats cherry-studio-enterprise

# 查看容器详细信息
docker inspect cherry-studio-enterprise

# 进入容器调试
docker exec -it cherry-studio-enterprise sh

更新升级

# 拉取最新镜像
docker-compose pull

# 停止并重新启动服务
docker-compose down
docker-compose up -d

故障排除

常见问题

1. 容器无法启动

# 检查容器日志
docker logs cherry-studio-enterprise

# 检查端口占用
netstat -tulpn | grep -E '3670|3680'

# 检查 Docker 守护进程
systemctl status docker

2. 数据库连接失败

  • 确认数据库服务正在运行
  • 检查网络连接和防火墙设置
  • 验证数据库凭据是否正确
  • 确保数据库已创建并有正确的权限

3. 权限问题

# 修复数据目录权限
sudo chown -R 1000:1000 ./data

# 或在容器内修复
docker exec cherry-studio-enterprise \
  chown -R node:node /app/data

4. 内存不足

# 增加 Docker 内存限制
docker update --memory 4g cherry-studio-enterprise

# 或在 docker-compose.yml 中配置
deploy:
  resources:
    limits:
      memory: 4G

注意事项

  1. 生产环境安全：

    • 必须更改默认的 JWT_SECRET
    • 使用强密码保护数据库
    • 启用 HTTPS/TLS
    • 定期更新镜像版本

  2. 数据持久化：

    • 始终挂载数据卷到宿主机

  3. 性能考虑：

    • 根据负载调整资源限制
    • 使用外部 PostgreSQL 以获得更好的性能
    • 配置适当的健康检查参数

  4. 网络安全：

    • 仅暴露必要的端口
    • 使用防火墙规则限制访问
    • 在生产环境中使用反向代理

相关文档

云应用部署

腾讯云应用市场一键部署 Cherry Studio 企业版

Helm 部署

使用 Helm 将 Cherry Studio Enterprise 部署到 Kubernetes 集群

On this page

特性快速开始前置条件使用 Docker Compose完整生产环境配置（含数据库）启动和管理配置说明端口映射环境变量核心配置数据库配置数据持久化部署最佳实践1. 安全配置2. 网络配置3. 性能优化4. 日志管理监控与维护查看日志性能监控更新升级故障排除常见问题1. 容器无法启动2. 数据库连接失败3. 权限问题4. 内存不足注意事项相关文档