乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > Coze Studio 安装与配置指南

Coze Studio 安装与配置指南

当前时间： 2026-08-15 05:29:06 分类：办公文件 评论(0)
Coze Studio 安装与配置指南

📌 阅读提示：本安装指南基于 Coze Studio 开源版 2026 年 6 月的代码快照编写。Coze Studio 持续迭代，配置方式、文件路径、环境变量等可能随版本更新而变化，请以 Coze Studio GitHub 仓库 的最新文档和 Release Notes 为准。

系列导航：上篇已介绍了 Coze 平台整体能力与核心概念，本文为 AI Agent 技术文章系列第 9 篇（中），将讲解 Coze Studio 开源版的本地部署与配置。

01 环境要求

在安装 Coze Studio 之前，请确保您的电脑满足以下最低系统要求：

  • CPU：2 Core 及以上；

  • 内存：4 GB 及以上；

  • Docker：提前安装 Docker、Docker Compose，并启动 Docker 服务。

建议配置：8 Core / 16 GB 以上可获得更流畅的体验。

02 安装 Docker

Windows

  1. 启用 Hyper-V：

    • "我的电脑"右键"属性"进入系统设置页面；

    • 搜索"程序"，找到"启用或关闭 Windows 功能"；

    • 勾选 Hyper-V 和 适用于 Linux 的 Windows 子系统；

    • 点击确定后重启计算机。

  2. 下载并安装 Docker Desktop：

    • 访问 Docker 官网下载 Windows 版本；

    • 双击安装文件，一路Next，点击Finish完成安装；

    • 启动Docker Desktop，确认状态栏显示 "Running"。

macOS

  1. 访问 Docker 官网下载 macOS 版本；

  2. 选择 Apple 芯片版本或 Intel 芯片版本；

  3. 双击安装包，拖拽 Docker 到 Applications 文件夹；

  4. 启动 Docker Desktop。

Linux

# Ubuntu/Debiansudo apt-get updatesudo apt-get install docker.io docker-composesudo systemctl start dockersudo systemctl enable docker
# Linux 用户可修改 /etc/docker/daemon.json 添加上述配置，然后执行 sudo systemctl restart docker 使其生效。

Docker 镜像源配置（国内用户）：如果拉取镜像速度慢，可在 Docker Desktop 的 Settings → Docker Engine 中配置镜像加速器：

{"registry-mirrors": ["https://hub.rat.dev/"]}

03 获取源码

# 克隆代码（需要安装 Git）git clone https://github.com/coze-dev/coze-studio.git# 或者直接在 GitHub 下载 ZIP 包并解压

解压后，进入coze-studio文件夹可看到以下文件清单，其中README.md是英文配置教程，README.zh_CN.md是中文配置教程，可结合本教程一起使用进行配置。

04 配置模型服务

Coze Studio 是基于大语言模型（LLM）的 AI 应用开发平台。首次部署前必须配置模型服务，否则创建智能体或工作流时无法正常选择模型。

以下以 DeepSeek 为例演示配置过程：

步骤 1：复制模型配置模板

cd coze-studio# 复制 DeepSeek 模型配置模板（macOS/Linux）cp backend/conf/model/template/model_template_deepseek.yaml backend/conf/model/deepseek.yaml# Windows 用户请使用 copy 命令copy backend\conf\model\template\model_template_deepseek.yaml backend\conf\model\deepseek.yaml

步骤 2：获取 DeepSeek API Key

  1. 访问 DeepSeek 开放平台。

  2. 注册/登录 DeepSeek 账号。

  3. 获取 API Key：

    • 进入左侧菜单 "API Keys" 页面；

    • 点击 "创建 API Key"；

    • 输入密钥名称（如 coze-studio-key），点击确认；

    • 立即复制生成的密钥（仅显示一次，关闭后无法再次查看）。

  4. 确认可用模型：

    • DeepSeek 开放平台默认提供 deepseek-v4-flash和 deepseek-v4-pro两个模型；

    • 本示例使用 deepseek-v4-flash（通用对话模型）。

注意：原来deepseek-v3的两个模型，deepseek-chat 与 deepseek-reasoner 两个模型名将于北京时间 2026/07/24 23:59 弃用。出于兼容考虑，二者分别对应 deepseek-v4-flash 的非思考与思考模式。DeepSeek API 为按量计费，新注册用户通常有一定额度的免费体验 Token。请确保账户有余额或已充值，否则 API 调用会失败。

步骤 3：修改配置文件

使用文本编辑器打开 backend/conf/model/deepseek.yaml，修改以下字段：

# 第一行：模型 ID，自行定义，必须是非 0 整数，全局唯一id: 155166# 模型名称（用于在 Coze Studio 界面中显示）name: "deepseek-v4-flash"# 向下滚动到 meta.conn_config 部分meta:  conn_config:    base_url: "https://api.deepseek.com/v1"# DeepSeek API 基础地址    api_key: "sk-your-deepseek-api-key-here"# 替换为你的 DeepSeek API Key    model: "deepseek-v4-flash"# 模型标识：deepseek-v4-flash 或 deepseek-v4-pro

配置示例（完整参考）：

id: 155166name: "deepseek-v4-flash"model_type: "chat"model_provider: "deepseek"meta:  conn_config:    base_url: "https://api.deepseek.com/v1"    api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"    model: "deepseek-v4-flash"  max_tokens: 8192  temperature: 0.7

注意事项：

  • id 上线后请勿修改，确保全局唯一；

  • api_key 必须以 sk- 开头；

  • 如需使用推理模型（deepseek-v4-pro），将 model 改为 deepseek-v4-pro；

  • 如果使用其他模型（如 OpenAI、Qwen），可从 template 目录复制对应的模板文件。

05 部署并启动服务

cd coze-studio# macOS / Linuxmake web# Windowscd dockercp .env.example .envdocker compose -f ./docker/docker-compose.yml up# 或者后台运行（推荐）docker compose --profile'*' up -d

首次部署需要拉取镜像、构建本地镜像，可能耗时较久（5-15 分钟），请耐心等待。如果看到提示 "Container coze-server Started"，表示 Coze Studio 服务已成功启动。

上述 Docker Compose 方式适合开发测试和快速验证。如需将 Coze Studio 部署到生产环境，建议关注以下事项：

硬件配置建议

环境类型CPU内存存储适用场景
开发测试4 核以上16 GB100 GB SSD功能验证、原型开发
生产环境8 核以上32 GB200 GB SSD企业级正式部署

操作系统推荐使用 Ubuntu 22.04 LTS。

外部中间件配置

Coze Studio 依赖 MySQL、Redis、Elasticsearch、MinIO 等一系列基础服务。Docker Compose 方式默认在容器内启动这些服务，生产环境建议替换为外部独立部署的中间件，以提高稳定性和可维护性：

中间件用途生产建议
MySQL 8.4存储结构化数据使用外部 MySQL，开启主从备份
Redis 8.0缓存和会话管理使用外部 Redis 集群
Elasticsearch 8.18知识库全文检索3 节点起步，配置持久化存储
MinIO对象存储（文件/文档）使用外部对象存储服务

配置外部中间件时，需修改 docker/.env 文件中的连接地址、端口和凭证信息。

Kubernetes 生产部署

对于大规模生产环境，Coze Studio 官方提供了 Helm Chart 部署方案，位于 helm/charts/opencoze/ 目录。通过 Helm 可实现：

  • 所有有状态服务的持久化存储配置（persistence.enabled: true）；

  • 通过 values.yaml 统一管理 MySQL、Redis、Elasticsearch、MinIO 等组件的资源配置；

  • 使用 LoadBalancer 或 Ingress 对外暴露服务。

安全与性能调优

  1. HTTPS 配置：生产环境务必启用 HTTPS，可通过 Nginx 反向代理或 Ingress 配置 SSL 证书；

  2. 模型并发调优：修改 backend/conf/model/ 下的模型配置文件，调整 max_concurrent_requests 参数；

  3. Elasticsearch 优化：建议预分配 20GB 虚拟内存，避免 ES 初始化失败；

  4. 日志管理：配置 ELK 或类似日志系统实现请求追踪和异常监控；

  5. 密钥管理：生产环境请修改 docker/.env 中的所有默认密钥（AES 密钥、数据库密码等）。

参考文档：详细的 Kubernetes 部署指南请参考 Coze Studio DeepWiki。

06 访问与初始化

  1. 注册账号：访问 http://localhost:8888/sign，输入用户名、密码完成注册。

  2. 配置模型：访问 http://localhost:8888/admin/#model-management，确认模型已正确加载或使用该界面也可以进行模型配置，比上面步骤 3直接修改配置文件更方便。

  3. 开始使用：访问 http://localhost:8888/，进入 Coze Studio 工作台。

提示：如果某个检查项失败，请参考下方"常见问题排查"表格定位问题或将问题发给deepseek、豆包等大模型对话界面让其协助排查。

07 常见问题排查

问题原因解决方案
Ports are not available: exposing port TCP 0.0.0.0:3306本地 MySQL 占用了 3306 端口修改 docker/docker-compose.yml 中 MySQL 的对外端口为 3307
[MY-012960] Cannot create redo log filesMySQL 数据文件损坏清空 docker/data 和 docker/volumes 目录，重新启动
elasticsearch-setup service didn't complete successfully: exit 127脚本换行符问题（Windows）用编辑器将 volumes/elasticsearch/setup_es.sh 的换行符从 CRLF 改为 LF
command not found: dockerDocker 未加入 PATH检查安装时是否勾选"添加到 PATH"，或重启电脑
镜像拉取失败网络问题配置 Docker 镜像加速器后重试

下一篇

第 9 篇（下）：Coze 实战案例——搭建"AI周报通"智能体

环境已经准备好，下一篇我们将用一个完整案例把前面学到的能力串起来：从 Coze 页面版的零代码搭建，到 Coze Studio 开源版的工作流编排，实现一个能自动生成 AI 行业周报的"AI周报通"智能体。