TencentOS Server 4 部署 Coze Studio 完整指南

mwq301232026-03-24 19:18

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)
CPU 2 核及以上
内存 4 GB 及以上（推荐 8 GB）
磁盘 50 GB 及以上可用空间
网络 可访问公网（拉取镜像）

前置依赖

bash 复制代码 
# 安装 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 错误：

bash 复制代码 
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 源

bash 复制代码 
# 禁用 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

python 复制代码 
# 清理缓存，刷新元数据
dnf clean all
dnf makecache

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

启动 Docker 服务

bash 复制代码 
systemctl enable docker
systemctl start docker

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

三、修复 daemon.json 配置冲突

问题现象

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

perl 复制代码 
journalctl -xeu docker.service --no-pager | grep "level="

关键报错信息：

sql 复制代码 
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 字段，仅保留以下配置：

bash 复制代码 
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 安装（推荐）

bash 复制代码 
dnf install -y docker-compose-plugin

# 验证
docker compose version

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

bash 复制代码 
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：克隆源码

bash 复制代码 
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 无法读取。

bash 复制代码 
# 确认模板位置
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：启动服务

bash 复制代码 
cd /opt/coze-studio/docker
docker compose up -d

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

Step 4：验证容器状态

bash 复制代码 
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 访问失败。

排查步骤

perl 复制代码 
# 查看端口绑定情况
ss -tlnp | grep 8888

输出：

ruby 复制代码 
LISTEN 0  4096  127.0.0.1:8888  0.0.0.0:*

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

bash 复制代码 
# docker-compose.yml 第 425 行
ports:
  - "${WEB_LISTEN_ADDR:-8888}:80"

解决方案

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

bash 复制代码 
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 格式的服务

八、常用运维命令

bash 复制代码 
# 进入 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 适配版）

bash 复制代码 
#!/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

bash 复制代码 
#!/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 源 404 TOS4 的 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

相关推荐
IT_陈寒1 小时前
一文搞懂JavaScript的核心概念
前端·人工智能·后端
IT_陈寒1 小时前
Java开发者必看！5个提升开发效率的隐藏技巧，你用过几个？
前端·人工智能·后端
做cv的小昊2 小时前
结合代码读3DGS论文（10）——ICLR 2025 3DGS加速&压缩新工作Sort-Free 3DGS论文及代码解读
论文阅读·人工智能·游戏·计算机视觉·3d·图形渲染·3dgs
机器之心2 小时前
龙虾之后，为什么说「主动式智能」才是Agent的终极形态？
人工智能·openai
智算菩萨2 小时前
GPT-5.4 Pro与Thinking模型全面研究报告
人工智能·gpt·ai·chatgpt·ai-native
团子和二花2 小时前
openclaw平替之nanobot源码解析（八）：Gateway进阶——定时任务与心跳机制
人工智能·gateway
机器之心2 小时前
昨晚，OpenClaw大更新，亲手终结「旧插件」时代
人工智能·openai
码路高手2 小时前
Trae-Agent源码重点
人工智能·架构
剑穗挂着新流苏3122 小时前
114_PyTorch 进阶：模型保存与读取的两大方式及“陷阱”避坑指南
人工智能·pytorch·深度学习
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06OpenClaw 使用和管理 MCP 完全指南07UV安装并设置国内源08“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）09让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南10AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南