如何用 Docker 把 Cherry Studio 跑起来：完整容器化部署指南

如何用 Docker 把 Cherry Studio 跑起来：完整容器化部署指南

【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio

Cherry Studio 是一个聚合 300+ 大模型助手、支持智能对话与自主 Agent 的 AI 生产力工作台。如果你不想在每台机器上手动折腾 Node 环境、原生依赖和版本冲突，用 Docker 做容器化部署就是最省心的路线：环境一次性打进镜像，配置外置到文件，迁移和扩容都靠一条命令完成。下面这条路径，从装好 Docker 到跑起一个带健康检查的服务，大约需要半小时。

先花 30 秒理解它内部在干什么，后面看日志、查故障时会轻松很多。Cherry Studio 的对话链路是：渲染进程收到消息后，通过 Electron IPC 传给主进程，由主进程里的 AI Core 完成推理编排（含 Claude Agent SDK 等运行时），再把消息块流式回传渲染层展示，最终由消息服务落盘到 SQLite。

5 分钟内跑起来：最短路径

第 1 步：装好 Docker。以 Ubuntu 为例：

sudo apt-get update sudo apt-get install -y docker.io docker-compose sudo systemctl enable --now docker sudo usermod -aG docker $USER

装完执行newgrp docker让组权限生效，docker --version能输出版本号就算过关。

第 2 步：拿代码。

git clone https://gitcode.com/GitHub_Trending/ch/cherry-studio cd cherry-studio

第 3 步：写一个最小 Dockerfile。核心思路是两段式构建——第一段装依赖、编译，第二段只带走产物，避免构建工具混进运行镜像：

FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . RUN npm run build FROM node:18-alpine WORKDIR /app COPY --from=builder /app/node_modules ./node_modules COPY --from=builder /app/dist ./dist COPY --from=builder /app/package.json ./ RUN apk add --no-cache curl bash EXPOSE 3000 CMD ["npm", "start"]

第 4 步：构建并启动。

docker build -t cherry-studio:local . docker run -d -p 3000:3000 \ -e NODE_ENV=production \ -v cherry-data:/app/data \ --name cherry-studio cherry-studio:local

浏览器访问http://localhost:3000，看到页面加载即成功。

只改 3 个配置点：密钥、数据卷、健康检查

真正决定部署质量的地方不多，重点盯这三个。

① 密钥外置，别写进镜像。在项目根目录建.env（不要提交到版本库），Compose 会自动引用它：

NODE_ENV=production PORT=3000 LLM_PROVIDERS=openai,anthropic,deepseek OPENAI_API_KEY=你的密钥 ANTHROPIC_API_KEY=你的密钥 DEEPSEEK_API_KEY=你的密钥 LOG_LEVEL=info

② 数据卷只挂数据目录。对话、配置都存在容器内的数据目录里，挂一个命名卷就能做到"删容器不丢数据"：

services: cherry-studio: build: . ports: - "3000:3000" env_file: - .env volumes: - app-data:/app/data restart: unless-stopped volumes: app-data:

③ 加健康检查，让容器自己"报告"状态。这是后面监控和自动恢复的地基：

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

start_period给足启动时间很重要——Electron 类应用冷启动比普通 Node 服务慢，设小了会误判为不健康反复重启。

稳定运行：资源限额、监控与安全加固

给容器设上限。多开 Agent 任务时 CPU 和内存可能冲高，在 Compose 里加deploy.resources限制，避免它把宿主机资源吃光：

deploy: resources: limits: memory: 2G cpus: "2"

接上 Prometheus + Grafana。只要服务暴露/metrics，Prometheus 配置里加一个静态目标即可，每 10 秒抓一次；Grafana 起一个容器指向 Prometheus 数据源，就能看到请求量、内存曲线。生产环境建议再配一个日志落盘目录（挂载./logs:/app/logs）并启用日志轮转，排查问题时有据可查。

安全加固三件套。一是运行镜像里创建非 root 用户再切换，防止容器逃逸后拿到宿主机 root：

RUN addgroup -g 1001 -S nodejs && adduser -S cherry -u 1001 USER cherry

二是给容器降权：cap_drop: [ALL]丢掉所有 Linux 能力，security_opt: [no-new-privileges:true]禁止提权，read_only: true加一块小 tmpfs 应付临时文件。三是网络隔离：给 Compose 自定义网络加internal: true，容器只走内网，外部访问只通过端口映射这一个口子。

另外两点值得顺手做了：配置目录用:ro只读挂载；部署前用 trivy 之类工具扫一遍镜像漏洞。

出问题怎么办：高频故障排查思路

日常排查三板斧：

docker-compose ps # 谁活着谁死了 docker-compose logs -f cherry-studio # 实时跟踪日志 docker stats $(docker-compose ps -q) # 资源消耗快照

进容器内确认环境是否正常：docker-compose exec cherry-studio sh -c "node -v && ls /app/dist"。构建阶段慢的话，基本是拉镜像或装依赖受网络影响，换成贴近你网络的镜像源即可。

想深挖 Linux 侧的原生依赖（比如 SQLite 预编译产物）是如何进入打包流程的，可以看仓库里的 Linux 打包文档 和 贡献者开发指南。

进阶：多副本与集群化

单机稳了之后，横向扩展就是加副本的事。Docker Swarm 下把服务声明成 3 副本，滚动更新时逐台替换：

services: cherry-studio: image: cherry-studio:latest deploy: replicas: 3 update_config: parallelism: 1 delay: 10s restart_policy: condition: on-failure max_attempts: 3 resources: limits: cpus: "1" memory: 2G networks: - cherry-network networks: cherry-network: driver: overlay

注意副本之间共享数据要落到外部存储或数据库上，否则各副本各存各的对话记录。

更值得投入的是把"构建-发布"自动化：参考仓库里的 发布工作流文档，在 CI 里跑镜像构建、漏洞扫描、打 tag，人工只做最后一步docker stack deploy。基础镜像定期跟随 node 官方小版本更新，保持安全补丁及时生效。

下一步：先用最短路径跑通单机部署并加上健康检查，再按"稳定运行"一节逐步叠加限额、监控和加固——每个阶段都确认服务正常后再进下一步，比一次性铺开更容易定位问题。

【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio