TencentOS Server 4 部署 Coze Studio 完整指南

mwq30123
0 阅读3分钟

TencentOS Server 4 部署 Coze Studio 完整指南

本文记录在 TencentOS Server 4 上从零安装 Docker，到完整部署运行 Coze Studio 的全过程，包含踩坑记录与解决方案。

目录

  1. 环境准备
  2. 安装 Docker
  3. 修复 daemon.json 冲突
  4. 安装 Docker Compose
  5. 部署 Coze Studio
  6. 修复外部访问问题
  7. 访问与配置
  8. 常用运维命令

一、环境准备

系统要求

配置项要求
操作系统TencentOS Server 4.x (x86_64)
CPU2 核及以上
内存4 GB 及以上（推荐 8 GB）
磁盘50 GB 及以上可用空间
网络可访问公网（拉取镜像）

前置依赖

# 安装 Git（后续克隆源码需要）
dnf install -y git

# 确认系统版本
cat /etc/tlinux-release

二、安装 Docker

为什么不用 docker-ce？

TencentOS Server 4 的 $releasever=4，而 Docker 官方源（download.docker.com）只收录到 CentOS 7/8，直接配置官方源会报 404 错误：

Errors during downloading metadata for repository 'docker-ce-stable':
  - Status code: 404 for https://download.docker.com/linux/centos/4/x86_64/stable/repodata/repomd.xml

解决方案：TencentOS Server 4 内置集成了 Moby 组件，直接通过 dnf 安装，无需配置额外源。

清理残留的 docker-ce 源

# 禁用 docker-ce 官方源
dnf config-manager --disable docker-ce-stable 2>/dev/null || true

# 删除 repo 文件（彻底清除）
rm -f /etc/yum.repos.d/docker-ce.repo \
      /etc/yum.repos.d/docker*.repo

# 卸载旧版本相关包（如有）
dnf remove -y \
    docker docker-ce docker-ce-cli docker-ce-rootless-extras \
    docker-client docker-common docker-latest docker-latest-logrotate \
    docker-engine containerd containerd.io 2>/dev/null || true

安装 Moby

# 清理缓存，刷新元数据
dnf clean all
dnf makecache

# 安装 Moby（TencentOS 4 官方适配 Docker 实现）
dnf install -y moby

启动 Docker 服务

systemctl enable docker
systemctl start docker

# 验证服务状态
systemctl status docker
docker version

三、修复 daemon.json 配置冲突

问题现象

配置 /etc/docker/daemon.json 后执行 systemctl restart docker 失败，查看日志：

journalctl -xeu docker.service --no-pager | grep "level="

关键报错信息：

unable to configure the Docker daemon with file /etc/docker/daemon.json:
the following directives are specified both as a flag and in the configuration file:
log-driver: (from flag: journald, from file: json-file)

根本原因

TencentOS 4 的 Moby docker.service unit 文件中硬编码了 --log-driver=journald，若 daemon.json 中再配置 log-driver，两处冲突导致 dockerd 拒绝启动。

解决方案

daemon.json 中去掉 log-driver 和 log-opts 字段，仅保留以下配置：

cat > /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": ["https://mirror.ccs.tencentyun.com"],
  "storage-driver": "overlay2"
}
EOF

systemctl daemon-reload
systemctl restart docker
systemctl status docker

说明：日志由 journald 统一管理，使用 journalctl -u docker 查看容器日志。

四、安装 Docker Compose

方式一：dnf 安装（推荐）

dnf install -y docker-compose-plugin

# 验证
docker compose version

方式二：下载独立二进制（dnf 源无此包时）

mkdir -p /usr/local/bin
curl -fsSL "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64" \
     -o /usr/local/bin/docker-compose

# 注意：需先确认文件下载成功再 chmod
if [ -f /usr/local/bin/docker-compose ]; then
    chmod +x /usr/local/bin/docker-compose
    docker-compose version
else
    echo "下载失败，请检查网络"
fi

⚠️ 踩坑：不要将 curl 下载和 chmod 用 && 写在同一行后接 ||，这会导致 curl 失败时 chmod 仍然执行，报 cannot access 错误。应分步执行。

五、部署 Coze Studio

Step 1：克隆源码

git clone https://github.com/coze-dev/coze-studio.git /opt/coze-studio
cd /opt/coze-studio

Step 2：生成 .env 配置文件

⚠️ 踩坑：.env.example 不在仓库根目录，而在 docker/ 子目录下。.env 也需放在同一目录，否则 docker compose 无法读取。

# 确认模板位置
find /opt/coze-studio -name ".env.example"
# 输出：/opt/coze-studio/docker/.env.example

# 从模板创建 .env
cp /opt/coze-studio/docker/.env.example /opt/coze-studio/docker/.env

Step 3：启动服务

cd /opt/coze-studio/docker
docker compose up -d

首次启动需拉取所有镜像，视网络情况可能需要 10 ~ 30 分钟，请耐心等待。

Step 4：验证容器状态

cd /opt/coze-studio/docker
docker compose ps

所有容器均应显示 Up 或 healthy 状态，共包含以下服务：

容器名说明
coze-server后端服务（Go/Hertz）
coze-web前端 Nginx 服务
coze-mysql数据库
coze-redis缓存
coze-elasticsearch搜索引擎
coze-milvus向量数据库
coze-minio对象存储
coze-etcd配置中心
coze-nsqd / nsqlookupd / nsqadmin消息队列

六、修复外部访问问题

问题现象

服务启动后，本机 localhost:8888 可访问，但通过服务器 IP 访问失败。

排查步骤

# 查看端口绑定情况
ss -tlnp | grep 8888

输出：

LISTEN 0  4096  127.0.0.1:8888  0.0.0.0:*

根本原因：docker-compose.yml 中端口映射通过环境变量 WEB_LISTEN_ADDR 控制，默认值为 8888（即绑定 127.0.0.1），导致只有本机可以访问。

# docker-compose.yml 第 425 行
ports:
  - "${WEB_LISTEN_ADDR:-8888}:80"

解决方案

在 .env 中覆盖该变量，绑定到 0.0.0.0：

echo 'WEB_LISTEN_ADDR=0.0.0.0:8888' >> /opt/coze-studio/docker/.env

# 重启服务使配置生效
cd /opt/coze-studio/docker
docker compose down
docker compose up -d

# 确认已绑定 0.0.0.0
ss -tlnp | grep 8888
# 期望输出：LISTEN 0  4096  0.0.0.0:8888  0.0.0.0:*

⚠️ 云服务器额外步骤：需在控制台安全组中放行 TCP 入方向 8888 端口，否则外部仍无法访问。

七、访问与配置

访问地址

功能地址
主页http://<服务器IP>:8888/
注册账号http://<服务器IP>:8888/sign
管理后台http://<服务器IP>:8888/admin
模型管理http://<服务器IP>:8888/admin/#model-management

首次使用步骤

  1. 注册账号：访问 /sign 页面，输入用户名和密码完成注册（第一个注册的账号为管理员）
  2. 配置模型：进入 /admin/#model-management，添加 LLM 模型的 API Key
  3. 开始使用：访问主页 /，创建 Agent 或工作流

支持的模型

Coze Studio 支持接入多种 LLM 服务，包括但不限于：

  • 火山方舟（Doubao） ：字节跳动自研模型
  • OpenAI：GPT-4o、GPT-4 等
  • Ollama：本地部署的开源模型
  • 其他兼容 OpenAI API 格式的服务

八、常用运维命令

# 进入 docker 工作目录（所有 compose 命令需在此目录执行）
cd /opt/coze-studio/docker

# 查看容器运行状态
docker compose ps

# 查看实时日志（所有服务）
docker compose logs -f

# 查看指定服务日志
docker compose logs -f coze-server
docker compose logs -f coze-web

# 停止所有服务（数据保留）
docker compose down

# 启动服务
docker compose up -d

# 重启指定服务
docker compose restart coze-server

# 更新镜像并重启
docker compose pull
docker compose up -d

# 查看资源占用
docker stats

附录：一键修复脚本汇总

安装 Docker（TencentOS Server 4 适配版）

#!/bin/bash
set -e

# 清除 docker-ce 官方源（避免 404）
rm -f /etc/yum.repos.d/docker-ce.repo /etc/yum.repos.d/docker*.repo
dnf remove -y docker docker-ce containerd.io 2>/dev/null || true

# 安装 Moby
dnf clean all && dnf makecache
dnf install -y moby

# 配置 daemon.json（注意：不能包含 log-driver）
mkdir -p /etc/docker
cat > /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": ["https://mirror.ccs.tencentyun.com"],
  "storage-driver": "overlay2"
}
EOF

systemctl enable docker
systemctl start docker
docker version

部署 Coze Studio

#!/bin/bash
set -e

INSTALL_DIR="/opt/coze-studio"

# 克隆源码
git clone https://github.com/coze-dev/coze-studio.git "$INSTALL_DIR"

# 生成 .env（注意路径在 docker/ 子目录）
cp "$INSTALL_DIR/docker/.env.example" "$INSTALL_DIR/docker/.env"

# 开放外部访问
echo 'WEB_LISTEN_ADDR=0.0.0.0:8888' >> "$INSTALL_DIR/docker/.env"

# 启动服务
cd "$INSTALL_DIR/docker"
docker compose up -d

echo "部署完成，访问 http://$(hostname -I | awk '{print $1}'):8888"

为 Coze Studio 配置模型

Coze Studio 是基于大语言模型的 AI 应用开发平台，首次部署并启动 Coze Studio 开源版之前，你需要先在 Coze Studio 项目里配置模型服务，否则创建智能体或者工作流时，无法正常选择模型。

可以通过配置管理后台 http://localhost:8888/admin/#model-management 来添加火山删除模型。

踩坑总结

问题原因解决方案
docker-ce 源 404TOS4 的 releasever=4，官方源无此版本改用 dnf install moby
docker 服务启动失败daemon.json 与 unit 文件中 log-driver 冲突daemon.json 中删除 log-driver 配置
.env.example 找不到文件在 docker/ 子目录，非仓库根目录cp docker/.env.example docker/.env
外部 IP 无法访问端口绑定在 127.0.0.1.env 中设置 WEB_LISTEN_ADDR=0.0.0.0:8888
docker-compose 安装报错&& 连接导致 chmod 在文件不存在时执行分步执行 curl 和 chmod

文档版本：v1.0 | 系统环境：TencentOS Server 4 x86_64 | Docker：Moby 28.4.0 | Coze Studio：latest

avatar
文章
阅读
粉丝