Cherry Studio 部署指南本文档由部署文档智能体生成项目代号Cherry Studio1. 环境准备1.1 操作系统要求推荐: Ubuntu 22.04 LTS / CentOS 8 / macOS 12最低要求: 4GB RAM, 20GB 磁盘空间1.2 系统依赖安装Ubuntu/Debian# 更新包管理器sudoaptupdatesudoaptupgrade-y# 安装基础工具sudoaptinstall-ycurlwgetgitbuild-essential# 安装 Python 3.10sudoaptinstall-ypython3.10 python3.10-venv python3.10-dev# 安装 Node.js 18.xcurl-fsSLhttps://deb.nodesource.com/setup_18.x|sudo-Ebash-sudoaptinstall-ynodejs# 安装 PostgreSQL 15sudoaptinstall-ypostgresql postgresql-contrib# 安装 Redissudoaptinstall-yredis-server# 安装 Nginxsudoaptinstall-ynginxCentOS/RHEL# 启用 EPEL 仓库sudodnfinstall-yepel-release# 安装基础工具sudodnfinstall-ycurlwgetgitgccmake# 安装 Python 3.10sudodnfinstall-ypython3.10 python3.10-devel# 安装 Node.js 18.xcurl-fsSLhttps://rpm.nodesource.com/setup_18.x|sudobash-sudodnfinstall-ynodejs# 安装 PostgreSQL 15sudodnfinstall-yhttps://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpmsudodnf-qymodule disable postgresqlsudodnfinstall-ypostgresql15-server postgresql15-contrib# 安装 Redissudodnfinstall-yredis# 安装 Nginxsudodnfinstall-ynginxmacOS# 安装 Homebrew如果未安装/bin/bash-c$(curl-fsSLhttps://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)# 安装基础工具brewinstallcurlwgetgit# 安装 Python 3.10brewinstallpython3.10# 安装 Node.js 18.xbrewinstallnode18# 安装 PostgreSQL 15brewinstallpostgresql15# 安装 Redisbrewinstallredis# 启动服务brew services start postgresql15 brew services start redis2. 获取代码# 克隆 Cherry Studio 代码库gitclone https://github.com/cherry-studio/cherry-studio.gitcdcherry-studio# 或者使用 SSH# git clone gitgithub.com:cherry-studio/cherry-studio.git3. 安装项目依赖3.1 后端依赖Python# 创建虚拟环境python3.10-mvenv venv# 激活虚拟环境sourcevenv/bin/activate# Linux/macOS# 或# venv\Scripts\activate # Windows# 升级 pippipinstall--upgradepip# 安装 Python 依赖pipinstall-rrequirements.txt# 安装开发依赖可选pipinstall-rrequirements-dev.txt3.2 前端依赖Node.js# 进入前端目录cdfrontend# 安装 Node.js 依赖npminstall# 构建前端资源npmrun build# 返回项目根目录cd..4. 配置4.1 复制配置文件模板# 复制环境变量模板cp.env.example .env# 复制 Django 设置模板cpconfig/settings/local.example.py config/settings/local.py4.2 配置环境变量编辑.env文件修改以下关键配置# 数据库配置 DATABASE_URLpostgresql://cherry_user:your_passwordlocalhost:5432/cherry_studio # Redis 配置 REDIS_URLredis://localhost:6379/0 # Django 密钥生成新的 SECRET_KEY$(python -c import secrets; print(secrets.token_urlsafe(50))) # 调试模式生产环境设为 False DEBUGTrue # 允许的主机 ALLOWED_HOSTSlocalhost,127.0.0.1 # 静态文件 URL STATIC_URL/static/ MEDIA_URL/media/ # 邮件配置可选 EMAIL_HOSTsmtp.gmail.com EMAIL_PORT587 EMAIL_USE_TLSTrue EMAIL_HOST_USERyour_emailgmail.com EMAIL_HOST_PASSWORDyour_app_password4.3 配置 Django 设置编辑config/settings/local.py根据需要进行调整# 数据库配置DATABASES{default:{ENGINE:django.db.backends.postgresql,NAME:cherry_studio,USER:cherry_user,PASSWORD:your_password,HOST:localhost,PORT:5432,}}# 缓存配置CACHES{default:{BACKEND:django_redis.cache.RedisCache,LOCATION:redis://localhost:6379/1,OPTIONS:{CLIENT_CLASS:django_redis.client.DefaultClient,}}}5. 数据库初始化5.1 创建数据库和用户# 登录 PostgreSQLsudo-upostgres psql# 在 PostgreSQL 中执行以下命令CREATE DATABASE cherry_studio;CREATEUSERcherry_user WITH PASSWORDyour_password;GRANT ALL PRIVILEGES ON DATABASE cherry_studio TO cherry_user;ALTER DATABASE cherry_studio OWNER TO cherry_user;\q5.2 运行数据库迁移# 确保在虚拟环境中sourcevenv/bin/activate# 运行迁移python manage.py migrate# 创建超级用户python manage.py createsuperuser# 按照提示输入用户名、邮箱和密码5.3 加载初始数据可选# 加载 fixtures 数据python manage.py loaddata initial_data.json# 或运行自定义初始化脚本python scripts/initialize_data.py6. 启动服务6.1 开发环境启动方式一使用 Django 开发服务器# 启动后端服务python manage.py runserver0.0.0.0:8000# 在另一个终端启动前端开发服务器cdfrontendnpmrun dev方式二使用 Docker Compose如果项目支持# 复制 Docker 配置文件cpdocker-compose.example.yml docker-compose.yml# 启动所有服务docker-composeup-d# 查看日志docker-composelogs-f6.2 生产环境部署配置 Gunicorn# 安装 Gunicornpipinstallgunicorn# 创建 Gunicorn 配置文件sudonano/etc/systemd/system/cherry-studio.service添加以下内容[Unit] DescriptionCherry Studio Gunicorn Service Afternetwork.target postgresql.service redis.service [Service] Userwww-data Groupwww-data WorkingDirectory/opt/cherry-studio EnvironmentPATH/opt/cherry-studio/venv/bin ExecStart/opt/cherry-studio/venv/bin/gunicorn \ --workers 4 \ --bind unix:/opt/cherry-studio/cherry-studio.sock \ config.wsgi:application [Install] WantedBymulti-user.target配置 Nginxsudonano/etc/nginx/sites-available/cherry-studio添加以下内容server { listen 80; server_name your-domain.com; location /static/ { alias /opt/cherry-studio/staticfiles/; } location /media/ { alias /opt/cherry-studio/media/; } location / { proxy_pass http://unix:/opt/cherry-studio/cherry-studio.sock; 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; } }启用配置并重启服务# 收集静态文件python manage.py collectstatic--noinput# 启用 Nginx 配置sudoln-s/etc/nginx/sites-available/cherry-studio /etc/nginx/sites-enabled/sudonginx-tsudosystemctl restart nginx# 启动 Gunicorn 服务sudosystemctl daemon-reloadsudosystemctl start cherry-studiosudosystemctlenablecherry-studio7. 验证部署7.1 检查服务状态# 检查 Gunicorn 状态sudosystemctl status cherry-studio# 检查 Nginx 状态sudosystemctl status nginx# 检查 PostgreSQL 状态sudosystemctl status postgresql# 检查 Redis 状态sudosystemctl status redis7.2 测试 API 端点# 测试健康检查端点curlhttp://localhost:8000/api/health/# 测试 API 文档curlhttp://localhost:8000/api/docs/# 测试管理后台需要登录curl-Ihttp://localhost:8000/admin/7.3 浏览器访问打开浏览器访问http://localhost:8000开发环境或访问http://your-domain.com生产环境访问管理后台http://your-domain.com/admin/8. 常见问题问题 1: 数据库连接失败错误现象:django.db.utils.OperationalError: could not connect to server可能原因:PostgreSQL 服务未运行数据库用户权限不足连接配置错误解决方案:# 检查 PostgreSQL 服务状态sudosystemctl status postgresql# 重启 PostgreSQLsudosystemctl restart postgresql# 检查用户权限sudo-upostgres psql-c\lsudo-upostgres psql-c\du# 验证连接psql-hlocalhost-Ucherry_user-dcherry_studio问题 2: 端口被占用错误现象:Error: That port is already in use可能原因: 其他服务占用了 8000 端口解决方案:# 查找占用端口的进程sudolsof-i:8000# 杀死占用进程sudokill-9PID# 或使用其他端口python manage.py runserver0.0.0.0:8001问题 3: 静态文件 404 错误错误现象: 页面样式丢失控制台显示静态文件 404可能原因:静态文件未收集Nginx 配置错误权限问题解决方案:# 收集静态文件python manage.py collectstatic--noinput# 检查静态文件目录权限sudochown-Rwww-data:www-data /opt/cherry-studio/staticfiles/sudochmod-R755/opt/cherry-studio/staticfiles/# 检查 Nginx 配置sudonginx-tsudosystemctl reload nginx问题 4: Redis 连接失败错误现象:redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379可能原因:Redis 服务未启动Redis 配置错误防火墙阻止连接解决方案:# 启动 Redis 服务sudosystemctl start redissudosystemctlenableredis# 检查 Redis 状态redis-cliping# 应该返回 PONG# 检查防火墙sudoufw statussudoufw allow6379问题 5: 内存不足错误现象: 服务崩溃日志显示Killed或Out of memory可能原因: 服务器内存不足解决方案:# 减少 Gunicorn worker 数量# 修改 /etc/systemd/system/cherry-studio.service# 将 --workers 4 改为 --workers 2# 重启服务sudosystemctl daemon-reloadsudosystemctl restart cherry-studio# 增加交换空间临时解决方案sudofallocate-l2G /swapfilesudochmod600/swapfilesudomkswap/swapfilesudoswapon/swapfile9. 附录项目结构说明cherry-studio/ ├── config/ # Django 项目配置 ├── apps/ # Django 应用 ├── frontend/ # 前端代码React/Vue ├── static/ # 静态文件 ├── media/ # 用户上传文件 ├── requirements.txt # Python 依赖 ├── manage.py # Django 管理脚本 └── .env.example # 环境变量模板相关链接官方文档GitHub 仓库问题反馈社区讨论备份与恢复# 备份数据库pg_dump-Ucherry_user cherry_studiobackup_$(date%Y%m%d).sql# 恢复数据库psql-Ucherry_user cherry_studiobackup_20240101.sql# 备份媒体文件tar-czfmedia_backup_$(date%Y%m%d).tar.gz media/注意: 本部署指南基于通用模板生成具体配置可能因 Cherry Studio 的实际代码结构而有所不同。请参考项目根目录下的README.md或DEPLOYMENT.md获取最新部署说明。
Cherry Studio 部署指南
发布时间:2026/5/20 11:33:46
Cherry Studio 部署指南本文档由部署文档智能体生成项目代号Cherry Studio1. 环境准备1.1 操作系统要求推荐: Ubuntu 22.04 LTS / CentOS 8 / macOS 12最低要求: 4GB RAM, 20GB 磁盘空间1.2 系统依赖安装Ubuntu/Debian# 更新包管理器sudoaptupdatesudoaptupgrade-y# 安装基础工具sudoaptinstall-ycurlwgetgitbuild-essential# 安装 Python 3.10sudoaptinstall-ypython3.10 python3.10-venv python3.10-dev# 安装 Node.js 18.xcurl-fsSLhttps://deb.nodesource.com/setup_18.x|sudo-Ebash-sudoaptinstall-ynodejs# 安装 PostgreSQL 15sudoaptinstall-ypostgresql postgresql-contrib# 安装 Redissudoaptinstall-yredis-server# 安装 Nginxsudoaptinstall-ynginxCentOS/RHEL# 启用 EPEL 仓库sudodnfinstall-yepel-release# 安装基础工具sudodnfinstall-ycurlwgetgitgccmake# 安装 Python 3.10sudodnfinstall-ypython3.10 python3.10-devel# 安装 Node.js 18.xcurl-fsSLhttps://rpm.nodesource.com/setup_18.x|sudobash-sudodnfinstall-ynodejs# 安装 PostgreSQL 15sudodnfinstall-yhttps://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpmsudodnf-qymodule disable postgresqlsudodnfinstall-ypostgresql15-server postgresql15-contrib# 安装 Redissudodnfinstall-yredis# 安装 Nginxsudodnfinstall-ynginxmacOS# 安装 Homebrew如果未安装/bin/bash-c$(curl-fsSLhttps://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)# 安装基础工具brewinstallcurlwgetgit# 安装 Python 3.10brewinstallpython3.10# 安装 Node.js 18.xbrewinstallnode18# 安装 PostgreSQL 15brewinstallpostgresql15# 安装 Redisbrewinstallredis# 启动服务brew services start postgresql15 brew services start redis2. 获取代码# 克隆 Cherry Studio 代码库gitclone https://github.com/cherry-studio/cherry-studio.gitcdcherry-studio# 或者使用 SSH# git clone gitgithub.com:cherry-studio/cherry-studio.git3. 安装项目依赖3.1 后端依赖Python# 创建虚拟环境python3.10-mvenv venv# 激活虚拟环境sourcevenv/bin/activate# Linux/macOS# 或# venv\Scripts\activate # Windows# 升级 pippipinstall--upgradepip# 安装 Python 依赖pipinstall-rrequirements.txt# 安装开发依赖可选pipinstall-rrequirements-dev.txt3.2 前端依赖Node.js# 进入前端目录cdfrontend# 安装 Node.js 依赖npminstall# 构建前端资源npmrun build# 返回项目根目录cd..4. 配置4.1 复制配置文件模板# 复制环境变量模板cp.env.example .env# 复制 Django 设置模板cpconfig/settings/local.example.py config/settings/local.py4.2 配置环境变量编辑.env文件修改以下关键配置# 数据库配置 DATABASE_URLpostgresql://cherry_user:your_passwordlocalhost:5432/cherry_studio # Redis 配置 REDIS_URLredis://localhost:6379/0 # Django 密钥生成新的 SECRET_KEY$(python -c import secrets; print(secrets.token_urlsafe(50))) # 调试模式生产环境设为 False DEBUGTrue # 允许的主机 ALLOWED_HOSTSlocalhost,127.0.0.1 # 静态文件 URL STATIC_URL/static/ MEDIA_URL/media/ # 邮件配置可选 EMAIL_HOSTsmtp.gmail.com EMAIL_PORT587 EMAIL_USE_TLSTrue EMAIL_HOST_USERyour_emailgmail.com EMAIL_HOST_PASSWORDyour_app_password4.3 配置 Django 设置编辑config/settings/local.py根据需要进行调整# 数据库配置DATABASES{default:{ENGINE:django.db.backends.postgresql,NAME:cherry_studio,USER:cherry_user,PASSWORD:your_password,HOST:localhost,PORT:5432,}}# 缓存配置CACHES{default:{BACKEND:django_redis.cache.RedisCache,LOCATION:redis://localhost:6379/1,OPTIONS:{CLIENT_CLASS:django_redis.client.DefaultClient,}}}5. 数据库初始化5.1 创建数据库和用户# 登录 PostgreSQLsudo-upostgres psql# 在 PostgreSQL 中执行以下命令CREATE DATABASE cherry_studio;CREATEUSERcherry_user WITH PASSWORDyour_password;GRANT ALL PRIVILEGES ON DATABASE cherry_studio TO cherry_user;ALTER DATABASE cherry_studio OWNER TO cherry_user;\q5.2 运行数据库迁移# 确保在虚拟环境中sourcevenv/bin/activate# 运行迁移python manage.py migrate# 创建超级用户python manage.py createsuperuser# 按照提示输入用户名、邮箱和密码5.3 加载初始数据可选# 加载 fixtures 数据python manage.py loaddata initial_data.json# 或运行自定义初始化脚本python scripts/initialize_data.py6. 启动服务6.1 开发环境启动方式一使用 Django 开发服务器# 启动后端服务python manage.py runserver0.0.0.0:8000# 在另一个终端启动前端开发服务器cdfrontendnpmrun dev方式二使用 Docker Compose如果项目支持# 复制 Docker 配置文件cpdocker-compose.example.yml docker-compose.yml# 启动所有服务docker-composeup-d# 查看日志docker-composelogs-f6.2 生产环境部署配置 Gunicorn# 安装 Gunicornpipinstallgunicorn# 创建 Gunicorn 配置文件sudonano/etc/systemd/system/cherry-studio.service添加以下内容[Unit] DescriptionCherry Studio Gunicorn Service Afternetwork.target postgresql.service redis.service [Service] Userwww-data Groupwww-data WorkingDirectory/opt/cherry-studio EnvironmentPATH/opt/cherry-studio/venv/bin ExecStart/opt/cherry-studio/venv/bin/gunicorn \ --workers 4 \ --bind unix:/opt/cherry-studio/cherry-studio.sock \ config.wsgi:application [Install] WantedBymulti-user.target配置 Nginxsudonano/etc/nginx/sites-available/cherry-studio添加以下内容server { listen 80; server_name your-domain.com; location /static/ { alias /opt/cherry-studio/staticfiles/; } location /media/ { alias /opt/cherry-studio/media/; } location / { proxy_pass http://unix:/opt/cherry-studio/cherry-studio.sock; 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; } }启用配置并重启服务# 收集静态文件python manage.py collectstatic--noinput# 启用 Nginx 配置sudoln-s/etc/nginx/sites-available/cherry-studio /etc/nginx/sites-enabled/sudonginx-tsudosystemctl restart nginx# 启动 Gunicorn 服务sudosystemctl daemon-reloadsudosystemctl start cherry-studiosudosystemctlenablecherry-studio7. 验证部署7.1 检查服务状态# 检查 Gunicorn 状态sudosystemctl status cherry-studio# 检查 Nginx 状态sudosystemctl status nginx# 检查 PostgreSQL 状态sudosystemctl status postgresql# 检查 Redis 状态sudosystemctl status redis7.2 测试 API 端点# 测试健康检查端点curlhttp://localhost:8000/api/health/# 测试 API 文档curlhttp://localhost:8000/api/docs/# 测试管理后台需要登录curl-Ihttp://localhost:8000/admin/7.3 浏览器访问打开浏览器访问http://localhost:8000开发环境或访问http://your-domain.com生产环境访问管理后台http://your-domain.com/admin/8. 常见问题问题 1: 数据库连接失败错误现象:django.db.utils.OperationalError: could not connect to server可能原因:PostgreSQL 服务未运行数据库用户权限不足连接配置错误解决方案:# 检查 PostgreSQL 服务状态sudosystemctl status postgresql# 重启 PostgreSQLsudosystemctl restart postgresql# 检查用户权限sudo-upostgres psql-c\lsudo-upostgres psql-c\du# 验证连接psql-hlocalhost-Ucherry_user-dcherry_studio问题 2: 端口被占用错误现象:Error: That port is already in use可能原因: 其他服务占用了 8000 端口解决方案:# 查找占用端口的进程sudolsof-i:8000# 杀死占用进程sudokill-9PID# 或使用其他端口python manage.py runserver0.0.0.0:8001问题 3: 静态文件 404 错误错误现象: 页面样式丢失控制台显示静态文件 404可能原因:静态文件未收集Nginx 配置错误权限问题解决方案:# 收集静态文件python manage.py collectstatic--noinput# 检查静态文件目录权限sudochown-Rwww-data:www-data /opt/cherry-studio/staticfiles/sudochmod-R755/opt/cherry-studio/staticfiles/# 检查 Nginx 配置sudonginx-tsudosystemctl reload nginx问题 4: Redis 连接失败错误现象:redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379可能原因:Redis 服务未启动Redis 配置错误防火墙阻止连接解决方案:# 启动 Redis 服务sudosystemctl start redissudosystemctlenableredis# 检查 Redis 状态redis-cliping# 应该返回 PONG# 检查防火墙sudoufw statussudoufw allow6379问题 5: 内存不足错误现象: 服务崩溃日志显示Killed或Out of memory可能原因: 服务器内存不足解决方案:# 减少 Gunicorn worker 数量# 修改 /etc/systemd/system/cherry-studio.service# 将 --workers 4 改为 --workers 2# 重启服务sudosystemctl daemon-reloadsudosystemctl restart cherry-studio# 增加交换空间临时解决方案sudofallocate-l2G /swapfilesudochmod600/swapfilesudomkswap/swapfilesudoswapon/swapfile9. 附录项目结构说明cherry-studio/ ├── config/ # Django 项目配置 ├── apps/ # Django 应用 ├── frontend/ # 前端代码React/Vue ├── static/ # 静态文件 ├── media/ # 用户上传文件 ├── requirements.txt # Python 依赖 ├── manage.py # Django 管理脚本 └── .env.example # 环境变量模板相关链接官方文档GitHub 仓库问题反馈社区讨论备份与恢复# 备份数据库pg_dump-Ucherry_user cherry_studiobackup_$(date%Y%m%d).sql# 恢复数据库psql-Ucherry_user cherry_studiobackup_20240101.sql# 备份媒体文件tar-czfmedia_backup_$(date%Y%m%d).tar.gz media/注意: 本部署指南基于通用模板生成具体配置可能因 Cherry Studio 的实际代码结构而有所不同。请参考项目根目录下的README.md或DEPLOYMENT.md获取最新部署说明。