Coze 部署和配置手册
原
GrissomFI约 15 分钟
GrissomFI约 15 分钟Coze 部署和配置手册
1. 系统概述与架构
1.1 平台概述
Coze Studio 是一个基于 Docker 容器化部署的 AI 应用开发平台，采用微服务架构设计。本手册详细介绍了 Coze Studio 的部署架构、组件配置和部署步骤。
1.2 系统架构
Coze Studio 采用分层架构设计，包含以下核心组件：
1.2.1 应用层
• coze-web: 前端 Web 应用，基于 Nginx 提供静态资源服务 • coze-server: 后端 API 服务，提供业务逻辑处理
1.2.2 数据存储层
• MySQL: 关系型数据库，存储业务数据 • Redis: 缓存数据库，提供高性能缓存服务 • Elasticsearch: 搜索引擎，提供全文检索功能 • MinIO: 对象存储服务，存储文件和媒体资源 • Milvus: 向量数据库，支持 AI 向量检索
1.2.3 基础设施层
• etcd: 分布式键值存储，提供服务发现和配置管理 • NSQ: 消息队列系统，包含 nsqlookupd、nsqd、nsqadmin三个组件
1.3 系统组件详细配置
本节将基于 Docker Compose 配置 对各组件的详细配置进行说明。
1.3.1 MySQL 数据库
镜像版本: mysql:8.4.5
端口配置:
• 内部端口: 3306 • 外部端口: 未暴露（仅内网访问，端口已注释）
环境变量:
MYSQL_ROOT_PASSWORD=your_secure_password # 管理员密码
MYSQL_DATABASE=opencoze # 数据库名称
MYSQL_USER=coze # 业务用户名
MYSQL_PASSWORD=coze123 # 业务用户密码存储配置:
• 数据目录: ./data/mysql:/var/lib/mysql• 初始化脚本: ./volumes/mysql/schema.sql
健康检查:
• 检查间隔: 10 秒 • 超时时间: 5 秒 • 重试次数: 5 次 • 启动等待: 30 秒
1.3.2 Redis 缓存
镜像版本: bitnami/redis:8.0
端口配置:
• 内部端口: 6379 • 外部端口: 未暴露（仅内网访问，端口已注释）
环境变量:
REDIS_AOF_ENABLED=no # 关闭 AOF 持久化
REDIS_PORT_NUMBER=6379 # 服务端口
REDIS_IO_THREADS=4 # IO 线程数
ALLOW_EMPTY_PASSWORD=yes# 允许空密码存储配置:
• 数据目录: ./data/bitnami/redis:/bitnami/redis/data
健康检查:
• 检查间隔: 5 秒 • 超时时间: 10 秒 • 重试次数: 10 次
1.3.3 Elasticsearch 搜索引擎
镜像版本: bitnami/elasticsearch:8.18.0
端口配置:
• 内部端口: 9200 • 外部端口: 未暴露（仅内网访问，端口已注释）
特殊配置:
• 安装 analysis-smartcn中文分词插件• 自动初始化索引结构 • 支持自定义配置文件
存储配置:
• 数据目录: ./data/bitnami/elasticsearch:/bitnami/elasticsearch/data• 配置文件: ./volumes/elasticsearch/elasticsearch.yml• 插件包: ./volumes/elasticsearch/analysis-smartcn.zip
1.3.4 MinIO 对象存储
镜像版本: minio/minio:RELEASE.2025-06-13T11-33-47Z-cpuv1
端口配置:
• API 端口: 9000（内部，端口已注释） • 控制台端口: 9001（内部，端口已注释）
环境变量:
MINIO_ROOT_USER=minioadmin # 管理员用户名
MINIO_ROOT_PASSWORD=minioadmin123 # 管理员密码
MINIO_DEFAULT_BUCKETS=opencoze,milvus # 默认存储桶存储配置:
• 数据目录: ./data/minio:/data• 默认图标: ./volumes/minio/default_icon/• 插件图标: ./volumes/minio/official_plugin_icon/
1.3.5 etcd 配置中心
镜像版本: bitnami/etcd:3.5
端口配置:
• 客户端端口: 2379（内部，端口已注释） • 节点通信端口: 2380（内部，端口已注释）
环境变量:
ETCD_AUTO_COMPACTION_MODE=revision # 自动压缩模式
ETCD_AUTO_COMPACTION_RETENTION=1000 # 保留版本数
ETCD_QUOTA_BACKEND_BYTES=4294967296 # 后端存储配额（4GB）
ALLOW_NONE_AUTHENTICATION=yes# 允许无认证访问1.3.6 Milvus 向量数据库
镜像版本: milvusdb/milvus:v2.5.10
端口配置:
• 服务端口: 19530（内部，端口已注释） • 健康检查端口: 9091（内部，端口已注释）
依赖服务:
• etcd（配置存储） • MinIO（数据存储）
环境变量:
ETCD_ENDPOINTS=etcd:2379 # etcd 连接地址
MINIO_ADDRESS=minio:9000 # MinIO 连接地址
MINIO_BUCKET_NAME=milvus # 存储桶名称1.3.7 NSQ 消息队列
镜像版本: nsqio/nsq:v1.2.1
组件说明:
1. nsqlookupd: 服务发现组件
• 端口: 4160（TCP）、4161（HTTP）（端口已注释）
• 端口: 4150（TCP）、4151（HTTP）（端口已注释）
• 端口: 4171（HTTP）（端口已注释）
1.3.8 Coze Server 后端服务
镜像版本: cozedev/coze-studio-server:latest
端口配置:
• API 端口: 8888（内部，端口已注释） • 管理端口: 8889（内部，端口已注释）
依赖服务:
• MySQL（数据存储） • Redis（缓存） • Elasticsearch（搜索） • MinIO（文件存储） • Milvus（向量检索）
1.3.9 Coze Web 前端服务
镜像版本: cozedev/coze-studio-web:latest
端口配置:
• HTTP 端口: 80（容器内部） • 外部访问端口: 8888（可配置）
配置文件:
• Nginx 主配置: ./nginx/nginx.conf• 代理配置: ./nginx/conf.d/default.conf
1.3.10 网络拓扑
所有服务运行在同一个 Docker 网络 coze-network 中，采用桥接模式：
┌─────────────────────────────────────────────────────────────┐
│ coze-network (bridge) │
├─────────────────┬───────────────────────────────────────────┤
│ Frontend │ Backend Services │
├─────────────────┼───────────────────────────────────────────┤
│ coze-web:80 │ coze-server:8888 │
│ (→ :8888) │ │
├─────────────────┼───────────────────────────────────────────┤
│ Data Layer │ Infrastructure │
├─────────────────┼───────────────────────────────────────────┤
│ mysql:3306 │ etcd:2379,2380 │
│ redis:6379 │ nsqlookupd:4160,4161 │
│ elasticsearch: │ nsqd:4150,4151 │
│ 9200 │ nsqadmin:4171 │
│ minio:9000,9001 │ │
│ milvus:19530, │ │
│ 9091 │ │
└─────────────────┴───────────────────────────────────────────┘1.3.11 端口列表总结
2. 部署前准备
2.1 本地存储目录规划
在开始部署之前，我们需要创建以下本地存储目录用于数据持久化。
注意：所有目录都基于项目根目录(/)的相对路径。
2.1.1 数据存储目录
# 创建数据存储根目录
mkdir -p ./data
# MySQL 数据库存储
mkdir -p ./data/mysql
# Redis 缓存数据存储
mkdir -p ./data/bitnami/redis
# Elasticsearch 搜索引擎数据存储
mkdir -p ./data/bitnami/elasticsearch
# MinIO 对象存储数据
mkdir -p ./data/minio2.1.2 配置文件目录
# 创建配置文件根目录
mkdir -p ./volumes
# MySQL 初始化脚本目录
mkdir -p ./volumes/mysql
# Elasticsearch 配置文件目录
mkdir -p ./volumes/elasticsearch
# MinIO 图标资源目录
mkdir -p ./volumes/minio/default_icon
mkdir -p ./volumes/minio/official_plugin_icon
# Nginx 配置文件目录
mkdir -p ./nginx/conf.d2.1.3 目录权限设置
# 设置数据目录权限（确保 Docker 容器可以读写）
sudochown -R 1001:1001 ./data/bitnami
sudochmod -R 755 ./data
# 设置配置文件目录权限
sudochmod -R 755 ./volumes
sudochmod -R 755 ./nginx2.1.4 目录结构总览
完成目录创建后，项目根目录下的存储结构如下：
coze-studio/
├── data/ # 数据持久化根目录
│ ├── mysql/ # MySQL 数据库文件
│ ├── bitnami/
│ │ ├── redis/ # Redis 缓存数据
│ │ └── elasticsearch/ # Elasticsearch 索引数据
│ └── minio/ # MinIO 对象存储数据
├── volumes/ # 配置文件根目录
│ ├── mysql/
│ │ └── schema.sql # MySQL 初始化脚本
│ ├── elasticsearch/
│ │ ├── elasticsearch.yml # Elasticsearch 配置
│ │ └── analysis-smartcn.zip # 中文分词插件
│ └── minio/
│ ├── default_icon/ # 默认图标资源
│ └── official_plugin_icon/ # 官方插件图标
├── nginx/ # Nginx 配置目录
│ ├── nginx.conf # 主配置文件
│ └── conf.d/
│ └── default.conf # 代理配置文件
└── docker-compose.yml # Docker Compose 配置文件注意事项：
1. 磁盘空间：确保 ./data目录所在磁盘有足够空间（建议至少 50GB）2. 备份策略：定期备份 ./data和./volumes目录3. 权限管理：避免使用 root权限运行容器，确保目录权限正确设置4. 路径一致性：所有路径必须与 docker-compose.yml中的卷映射配置保持一致
注意：真实部署的时候，需要考虑对数据盘做 RAID 或者进行数据备份，以免数据丢失。
3. 部署步骤
3.1 环境准备（单节点）
3.1.1 系统要求
• 操作系统：Linux (Ubuntu 18.04+, CentOS 7+) • CPU：4核心以上 • 内存：8GB以上（推荐16GB） • 磁盘：50GB以上可用空间 • 网络：稳定的互联网连接
3.1.2 安装 Docker 和 Docker Compose
# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose-plugin
# CentOS/RHEL
sudo yum install docker docker-compose-plugin
# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker
# 将当前用户添加到docker组
sudo usermod -aG docker $USER
newgrp docker3.1.3 配置系统参数
# 增加文件描述符限制
echo"* soft nofile 65536" >> /etc/security/limits.conf
echo"* hard nofile 65536" >> /etc/security/limits.conf
# 配置内核参数（Elasticsearch需要）
echo"vm.max_map_count=262144" >> /etc/sysctl.conf
sysctl -p
# 创建必要的目录
sudomkdir -p /opt/coze-studio/{data,logs,config}
sudochown -R $USER:$USER /opt/coze-studio3.2 下载和配置
3.2.1 获取项目文件
# 克隆项目代码
git clone https://github.com/coze-dev/coze-studio.git
cd coze-studio/docker
# 或者下载发布包
wget https://github.com/coze-dev/coze-studio/releases/latest/download/coze-studio-docker.tar.gz
tar -xzf coze-studio-docker.tar.gz
cd coze-studio-docker3.2.2 配置环境变量
# 复制环境配置文件
cp .env.example .env
# 编辑配置文件
vim .env
# 必须修改的配置项：
WEB_LISTEN_ADDR=0.0.0.0:8888 # 允许外部访问
MYSQL_ROOT_PASSWORD=your_secure_password
MINIO_ROOT_PASSWORD=your_secure_password
PLUGIN_AES_AUTH_SECRET=your_16_byte_secret
PLUGIN_AES_STATE_SECRET=your_16_byte_secret
PLUGIN_AES_OAUTH_TOKEN_SECRET=your_16_byte_secret3.2.3 准备初始化文件
# 检查必要的目录和文件
ls -la volumes/
ls -la volumes/mysql/
ls -la volumes/elasticsearch/
ls -la volumes/minio/
# 如果缺少初始化文件，创建基本结构
mkdir -p volumes/{mysql,elasticsearch,minio,nginx}
mkdir -p data/{mysql,redis,elasticsearch,minio}3.3 启动服务
3.3.1 分步启动（推荐）
# 第一步：启动基础设施服务
docker-compose up -d mysql redis etcd
# 等待服务就绪（约30-60秒）
docker-compose logs -f mysql
# 看到 "ready for connections" 后按 Ctrl+C 退出
# 第二步：启动存储和搜索服务
docker-compose up -d elasticsearch minio milvus
# 等待服务就绪（约60-120秒）
docker-compose ps
# 第三步：启动消息队列
docker-compose up -d nsqlookupd nsqd nsqadmin
# 第四步：启动应用服务
docker-compose up -d coze-server
# 等待后端服务就绪
docker-compose logs -f coze-server
# 看到服务启动成功日志后按 Ctrl+C 退出
# 第五步：启动前端服务
docker-compose up -d coze-web3.3.2 一键启动
# 启动所有服务
docker-compose up -d
# 查看启动进度
docker-compose logs -f3.4 验证部署
3.4.1 检查服务状态
# 查看所有服务状态
docker-compose ps
# 查看异常服务日志（如果有服务显示 "Exit" 或 "Restarting"）
docker-compose logs [service_name]服务状态说明：Up = 正常运行，Exit = 异常退出，Restarting = 重启中
3.4.2 健康检查
# 快速验证关键服务
docker-compose exec mysql mysql -u root -p -e "SELECT 1" && \
docker-compose exec redis redis-cli ping && \
curl -f http://localhost:8888/health && \
echo"✅ 所有服务正常"详细的监控和故障排除请参考第 7 章。
3.4.3 访问应用
# 检查Web服务
curl -I http://localhost:8888
# 在浏览器中访问
# http://your-server-ip:88883.5 初始化配置
3.5.1 创建管理员账户
访问 http://your-server-ip:8888 进行首次设置：
• 设置管理员邮箱和密码 • 配置基本系统设置 • 添加AI模型配置
3.5.2 配置 AI 模型
在管理界面中配置：
• 添加聊天模型（如 GPT、Claude等）• 配置嵌入模型 • 设置模型参数和限制
3.5.3 测试功能
• 创建测试Bot • 上传测试文档到知识库 • 进行对话测试
3.6 多节点部署（生产环境）
架构设计:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Load Balancer │ │ Application │ │ Data Layer │
│ (2-3 台) │ │ Cluster │ │ Cluster │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ Nginx/HAProxy │───▶│ coze-web × 3+ │ │ MySQL Master │
│ + Keepalived │ │ coze-server × 3+│ │ MySQL Slaves×2+ │
│ │ │ │ │ Redis Cluster×3+│
│ │ │ │ │ ES Cluster × 3+ │
│ │ │ │ │ MinIO Cluster×4+│
│ │ │ │ │ Milvus Cluster×3│
└─────────────────┘ └─────────────────┘ └─────────────────┘机器配置建议:
1. 负载均衡层 (2-3 台)
• 配置: 4C8G，50GB SSD • 组件: Nginx/HAProxy + Keepalived • 说明: 采用主备模式，确保高可用性
• 配置: 8C16G，100GB SSD • 组件: coze-web + coze-server • 扩展: 根据并发量水平扩展
MySQL 集群 (3 台):
Redis 集群 (3 台):
Elasticsearch 集群 (3 台):
MinIO 集群 (4 台):
Milvus 集群 (3 台):
• 配置: 8C32G，500GB SSD • 组件: Query Node + Data Node + Index Node
• 配置: 4C16G，2TB HDD • 模式: 分布式模式，4 节点
• 配置: 8C32G，1TB SSD • 角色: Master + Data + Ingest
• 配置: 4C16G，200GB SSD • 模式: 3 主 3 从模式
• Master: 8C32G，500GB SSD • Slave: 8C16G，500GB SSD × 2
部署策略:
1. 负载均衡层
• 使用 Nginx 或 HAProxy 进行负载均衡 • 配置 SSL 终止和健康检查 • 实现会话保持（如需要）
• coze-web: 无状态，可水平扩展 • coze-server: 无状态，可水平扩展 • 使用容器编排工具（Kubernetes/Docker Swarm）
• MySQL: 主从复制或 MySQL Cluster • Redis: Redis Cluster 或 Sentinel 模式 • Elasticsearch: 多节点集群 • MinIO: 分布式模式 • Milvus: 集群模式 • etcd: 3/5/7 节点集群
配置示例（Kubernetes）:
# 应用层 Deployment
apiVersion:apps/v1
kind:Deployment
metadata:
name:coze-server
spec:
replicas:3
selector:
matchLabels:
app:coze-server
template:
metadata:
labels:
app:coze-server
spec:
containers:
-name:coze-server
image:cozedev/coze-studio-server:latest
ports:
-containerPort:8888
env:
-name:MYSQL_HOST
value:"mysql-service"
-name:REDIS_ADDR
value:"redis-service:6379"
# 其他环境变量...4. 配置说明
4.1 基础服务配置
4.1.1 服务器配置
# 服务器监听地址和端口
export LISTEN_ADDR=":8888"# 服务器监听端口
export LOG_LEVEL="debug"# 日志级别
export MAX_REQUEST_BODY_SIZE=1073741824 # 最大请求体大小（1GB）
export SERVER_HOST="http://localhost${LISTEN_ADDR}"# 服务器主机地址
export USE_SSL="0"# 是否启用SSL
export SSL_CERT_FILE=""# SSL证书文件路径
export SSL_KEY_FILE=""# SSL私钥文件路径4.1.2 数据库配置
# MySQL 数据库配置
export MYSQL_ROOT_PASSWORD=root # MySQL root 密码
export MYSQL_DATABASE=opencoze # 数据库名称
export MYSQL_USER=coze # 数据库用户名
export MYSQL_PASSWORD=coze123 # 数据库密码
export MYSQL_HOST=mysql # 数据库主机
export MYSQL_PORT=3306 # 数据库端口
export MYSQL_DSN="${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(${MYSQL_HOST}:${MYSQL_PORT})/${MYSQL_DATABASE}?charset=utf8mb4&parseTime=True"
export ATLAS_URL="mysql://${MYSQL_USER}:${MYSQL_PASSWORD}@${MYSQL_HOST}:${MYSQL_PORT}/${MYSQL_DATABASE}?charset=utf8mb4&parseTime=True"
# Redis 配置
export REDIS_AOF_ENABLED=no # AOF 持久化
export REDIS_IO_THREADS=4 # IO 线程数
export ALLOW_EMPTY_PASSWORD=yes# 允许空密码
export REDIS_ADDR="redis:6379"# Redis 地址
export REDIS_PASSWORD=""# Redis 密码（可选）4.1.3 消息队列配置
# 消息队列类型配置
export COZE_MQ_TYPE="nsq"# nsq / kafka / rmq
export MQ_NAME_SERVER="nsqd:4150"# NSQ 服务器地址
# RocketMQ 配置（如使用 RocketMQ）
export RMQ_ACCESS_KEY=""# RocketMQ 访问密钥
export RMQ_SECRET_KEY=""# RocketMQ 密钥4.2 存储配置
4.2.1 文件上传组件配置
# 文件上传组件类型
export FILE_UPLOAD_COMPONENT_TYPE="storage"# storage / imagex4.2.2 火山引擎 ImageX 配置
# 火山引擎 ImageX（如使用）
export VE_IMAGEX_AK=""# ImageX Access Key
export VE_IMAGEX_SK=""# ImageX Secret Key
export VE_IMAGEX_SERVER_ID=""# ImageX 服务器ID
export VE_IMAGEX_DOMAIN=""# ImageX 域名
export VE_IMAGEX_TEMPLATE=""# ImageX 模板
export VE_IMAGEX_UPLOAD_HOST="https://imagex.volcengineapi.com"# ImageX 上传地址4.2.3 对象存储配置
# 存储组件配置
export STORAGE_TYPE="minio"# minio / tos / s3
export STORAGE_UPLOAD_HTTP_SCHEME="http"# http / https（如果网站使用https，必须设置为https）
export STORAGE_BUCKET="opencoze"# 存储桶名称
# MinIO 配置
export MINIO_ROOT_USER=minioadmin # MinIO 用户名
export MINIO_ROOT_PASSWORD=minioadmin123 # MinIO 密码
export MINIO_DEFAULT_BUCKETS=milvus # 默认存储桶
export MINIO_AK=$MINIO_ROOT_USER# MinIO Access Key
export MINIO_SK=$MINIO_ROOT_PASSWORD# MinIO Secret Key
export MINIO_ENDPOINT="minio:9000"# MinIO 端点
export MINIO_API_HOST="http://${MINIO_ENDPOINT}"# MinIO API 地址
# TOS 配置（火山引擎对象存储）
export TOS_ACCESS_KEY= # TOS Access Key
export TOS_SECRET_KEY= # TOS Secret Key
export TOS_ENDPOINT=https://tos-cn-beijing.volces.com # TOS 端点
export TOS_BUCKET_ENDPOINT=https://opencoze.tos-cn-beijing.volces.com # TOS 存储桶端点
export TOS_REGION=cn-beijing # TOS 区域
# S3 配置（AWS S3 兼容存储）
export S3_ACCESS_KEY= # S3 Access Key
export S3_SECRET_KEY= # S3 Secret Key
export S3_ENDPOINT= # S3 端点
export S3_BUCKET_ENDPOINT= # S3 存储桶端点
export S3_REGION= # S3 区域4.2.4 Elasticsearch 配置
# Elasticsearch 搜索引擎配置
export ES_ADDR="http://elasticsearch:9200"# Elasticsearch 地址
export ES_VERSION="v8"# Elasticsearch 版本
export ES_USERNAME=""# Elasticsearch 用户名（可选）
export ES_PASSWORD=""# Elasticsearch 密码（可选）4.2.5 向量存储配置
# 向量存储类型
export VECTOR_STORE_TYPE="milvus"# milvus / vikingdb
# Milvus 向量数据库配置
export MILVUS_ADDR="milvus:19530"# Milvus 地址
export MILVUS_USER=""# Milvus 用户名（可选）
export MILVUS_PASSWORD=""# Milvus 密码（可选）
# VikingDB 向量数据库配置（火山引擎）
export VIKING_DB_HOST=""# VikingDB 主机
export VIKING_DB_REGION=""# VikingDB 区域
export VIKING_DB_AK=""# VikingDB Access Key
export VIKING_DB_SK=""# VikingDB Secret Key
export VIKING_DB_SCHEME=""# VikingDB 协议
export VIKING_DB_MODEL_NAME=""# VikingDB 模型名称（如未设置需配置嵌入模型）4.3 AI 模型配置
AI 模型配置是 Coze Studio 的核心部分，包括嵌入模型、聊天模型和内置聊天模型的配置。
以下表格列出了 Coze Studio 中所有可能需要配置的模型类型：
| 嵌入模型 | ARK_EMBEDDING_OPENAI_EMBEDDING_、OLLAMA_EMBEDDING_、GEMINI_EMBEDDING_、HTTP_EMBEDDING_ | |||
| 聊天模型 | MODEL_ | |||
| 内置聊天模型 | NL2SQL_BUILTIN_CM_ | |||
M2Q_BUILTIN_CM_ | ||||
IA_BUILTIN_CM_ | ||||
WKR_BUILTIN_CM_ | ||||
| Rerank 模型 | VIKINGDB_RERANK_ | |||
| OCR 模型 | VE_OCR_PADDLEOCR_OCR_ |
配置说明：
1. 嵌入模型：用于将文本转换为向量表示，是知识库功能的基础 2. 聊天模型：用于生成对话回复，支持配置多个模型实例 3. 内置聊天模型：为特定功能提供专用的 AI 能力，可独立配置 4. Rerank 模型：用于优化搜索结果的相关性排序 5. OCR 模型：用于从图像中提取文本内容
配置优先级：
• 内置聊天模型支持功能级别的独立配置（如 NL2SQL_BUILTIN_CM_TYPE）• 如果功能级别配置不存在，则回退到通用配置（如 BUILTIN_CM_TYPE）• 这种设计允许为不同功能配置不同的模型，提高系统灵活性