夜雨聆风📌 阅读提示：本安装指南基于 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
启用 Hyper-V：
"我的电脑"右键"属性"进入系统设置页面；
搜索"程序"，找到"启用或关闭 Windows 功能"；
勾选 Hyper-V 和 适用于 Linux 的 Windows 子系统；
点击确定后重启计算机。
下载并安装 Docker Desktop：
访问 Docker 官网下载 Windows 版本；
双击安装文件，一路Next，点击Finish完成安装；
启动Docker Desktop，确认状态栏显示 "Running"。
macOS
访问 Docker 官网下载 macOS 版本；
选择 Apple 芯片版本或 Intel 芯片版本；
双击安装包，拖拽 Docker 到 Applications 文件夹；
启动 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
访问 DeepSeek 开放平台。
注册/登录 DeepSeek 账号。
获取 API Key：
进入左侧菜单 "API Keys" 页面；
点击 "创建 API Key"；
输入密钥名称（如
coze-studio-key），点击确认；立即复制生成的密钥（仅显示一次，关闭后无法再次查看）。
确认可用模型：
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 GB | 100 GB SSD | 功能验证、原型开发 |
| 生产环境 | 8 核以上 | 32 GB | 200 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 对外暴露服务。
安全与性能调优
HTTPS 配置：生产环境务必启用 HTTPS，可通过 Nginx 反向代理或 Ingress 配置 SSL 证书；
模型并发调优：修改
backend/conf/model/下的模型配置文件，调整max_concurrent_requests参数；Elasticsearch 优化：建议预分配 20GB 虚拟内存，避免 ES 初始化失败；
日志管理：配置 ELK 或类似日志系统实现请求追踪和异常监控；
密钥管理：生产环境请修改
docker/.env中的所有默认密钥（AES 密钥、数据库密码等）。
参考文档：详细的 Kubernetes 部署指南请参考 Coze Studio DeepWiki。
06 访问与初始化
注册账号：访问
http://localhost:8888/sign，输入用户名、密码完成注册。
配置模型：访问
http://localhost:8888/admin/#model-management，确认模型已正确加载或使用该界面也可以进行模型配置，比上面步骤 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 files | MySQL 数据文件损坏 | 清空 docker/data 和 docker/volumes 目录，重新启动 |
elasticsearch-setup service didn't complete successfully: exit 127 | 脚本换行符问题（Windows） | 用编辑器将 volumes/elasticsearch/setup_es.sh 的换行符从 CRLF 改为 LF |
command not found: docker | Docker 未加入 PATH | 检查安装时是否勾选"添加到 PATH"，或重启电脑 |
| 镜像拉取失败 | 网络问题 | 配置 Docker 镜像加速器后重试 |
下一篇
第 9 篇（下）：Coze 实战案例——搭建"AI周报通"智能体
环境已经准备好，下一篇我们将用一个完整案例把前面学到的能力串起来：从 Coze 页面版的零代码搭建，到 Coze Studio 开源版的工作流编排，实现一个能自动生成 AI 行业周报的"AI周报通"智能体。
