Coze 部署完整教程｜附源码

本文将带你从 0 到 1 完成一个 基于 Coze API 的私有化 Web 聊天助手部署。
你将学会如何创建 Coze Bot、获取 API Token、编写后端服务、接入前端页面，并使用 Docker / Docker Compose 部署到服务器。
文末附完整源码，可直接复制运行。

一、Coze 是什么？

Coze 是一个 AI Bot / Agent 搭建平台，可以通过可视化方式快速创建智能体，并支持：

• 大模型对话
• 插件调用
• 工作流编排
• 知识库检索
• 多渠道发布
• API 调用集成

对于开发者来说，Coze 最有价值的能力之一就是：
你可以在 Coze 上配置 Bot，然后通过 API 将它集成到自己的网站、App、企业系统或客服系统中。

本文的目标不是简单介绍 Coze 的使用，而是完整演示：

1. 在 Coze 创建 Bot；
2. 获取 Bot ID 和访问 Token；
3. 编写 Node.js 后端服务；
4. 编写前端聊天页面；
5. 使用 Docker 部署；
6. 配置 Nginx 反向代理；
7. 给出完整源码。

二、部署架构说明

本文采用的部署架构如下：

用户浏览器
   │
   ▼
前端页面 index.html
   │
   ▼
Node.js 后端服务
   │
   ▼
Coze API
   │
   ▼
Coze Bot / Workflow / Knowledge

为什么不直接让前端调用 Coze API？

原因很简单：

• API Token 不能暴露在浏览器中；
• 后端可以统一做权限校验；
• 后端可以记录日志；
• 后端可以做限流、防刷；
• 后端可以适配不同模型或不同 Bot；
• 后端可以处理流式响应、错误重试等逻辑。

所以推荐方式是：

前端只请求自己的后端，后端再去请求 Coze API。

三、准备工作

在开始之前，你需要准备以下内容。

1. 一台服务器

推荐配置：

如果只是测试，本地电脑也可以运行。

2. 安装 Docker 和 Docker Compose

如果你的服务器还没有安装 Docker，可以执行：

curl -fsSL https://get.docker.com | bash

启动 Docker：

systemctl enable docker
systemctl start docker

检查版本：

docker -v

安装 Docker Compose：

apt update
apt install docker-compose-plugin -y

检查：

docker compose version

3. 创建 Coze Bot

进入 Coze 平台，创建一个新的 Bot。

你可以按照以下步骤操作：

1. 登录 Coze；
2. 新建 Bot；
3. 配置 Bot 名称、角色设定；
4. 选择合适的大模型；
5. 根据需要添加知识库、插件或工作流；
6. 发布 Bot；
7. 获取 Bot ID。

一个简单的 Bot Prompt 示例：

你是一个专业、耐心、表达清晰的 AI 助手。
你的任务是帮助用户解决技术问题，包括但不限于：
1. 编程开发；
2. 服务器部署；
3. Linux 运维；
4. Docker 使用；
5. AI 工具集成。

回答时请尽量结构化，必要时提供代码示例。

4. 获取 Coze API Token

进入 Coze 的开发者设置或 API 管理页面，创建访问令牌。

你需要准备两个关键参数：

COZE_API_TOKEN=你的 Coze API Token
COZE_BOT_ID=你的 Bot ID

注意：

• Token 不要提交到 GitHub；
• Token 不要写死在前端代码里；
• 生产环境建议定期更换 Token；
• 如果有权限控制，尽量使用最小权限 Token。

四、项目目录结构

本文项目结构如下：

coze-web-chat/
├── docker-compose.yml
├── Dockerfile
├── package.json
├── server.js
├── .env.example
├── public/
│   └── index.html
└── nginx/
    └── default.conf

这个项目包含：

• 一个 Node.js 后端；
• 一个静态前端页面；
• 一个 Dockerfile；
• 一个 docker-compose.yml；
• 一个可选的 Nginx 配置。

五、后端源码

下面是完整后端源码。

1. package.json

{
  "name": "coze-web-chat",
  "version": "1.0.0",
  "description": "A simple web chat demo powered by Coze API",
  "main": "server.js",
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "dev": "node server.js"
  },
  "dependencies": {
    "axios": "^1.7.7",
    "cors": "^2.8.5",
    "dotenv": "^16.4.5",
    "express": "^4.18.3"
  }
}

2. .env.example

PORT=3000

# Coze API 配置
COZE_API_TOKEN=your_coze_api_token
COZE_BOT_ID=your_coze_bot_id

# 如果你使用的是不同区域的 API，请根据官方文档调整
COZE_API_BASE_URL=https://api.coze.com

复制一份：

cp .env.example .env

然后修改 .env：

PORT=3000
COZE_API_TOKEN=pat_xxxxxxxxxxxxxxxxx
COZE_BOT_ID=xxxxxxxxxxxxxxxx
COZE_API_BASE_URL=https://api.coze.com

如果你使用的是国内环境，请以 Coze 官方文档提供的 API 地址为准。

3. server.js

import express from "express";
import cors from "cors";
import axios from "axios";
import dotenv from "dotenv";
import path from "path";
import { fileURLToPath } from "url";

dotenv.config();

const app = express();

const PORT = process.env.PORT || 3000;
const COZE_API_TOKEN = process.env.COZE_API_TOKEN;
const COZE_BOT_ID = process.env.COZE_BOT_ID;
const COZE_API_BASE_URL = process.env.COZE_API_BASE_URL || "https://api.coze.com";

if (!COZE_API_TOKEN || !COZE_BOT_ID) {
  console.error("请先配置 COZE_API_TOKEN 和 COZE_BOT_ID");
  process.exit(1);
}

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

app.use(cors());
app.use(express.json());
app.use(express.static(path.join(__dirname, "public")));

/**
 * 健康检查接口
 */
app.get("/api/health", (req, res) => {
  res.json({
    code: 0,
    message: "service is running"
  });
});

/**
 * 聊天接口
 */
app.post("/api/chat", async (req, res) => {
  try {
    const { message, userId } = req.body;

    if (!message || typeof message !== "string") {
      return res.status(400).json({
        code: 400,
        message: "message 不能为空"
      });
    }

    const requestBody = {
      bot_id: COZE_BOT_ID,
      user_id: userId || "web_user",
      query: message,
      stream: false
    };

    const response = await axios.post(
      `${COZE_API_BASE_URL}/open_api/v2/chat`,
      requestBody,
      {
        headers: {
          Authorization: `Bearer ${COZE_API_TOKEN}`,
          "Content-Type": "application/json"
        },
        timeout: 60000
      }
    );

    const data = response.data;

    /**
     * 不同版本 API 返回结构可能存在差异。
     * 这里做一个兼容处理：
     */
    let answer = "";

    if (data?.messages && Array.isArray(data.messages)) {
      const msg = data.messages.find(item => item.type === "answer");
      answer = msg?.content || "";
    }

    if (!answer && data?.data?.messages) {
      const msg = data.data.messages.find(item => item.type === "answer");
      answer = msg?.content || "";
    }

    if (!answer) {
      answer = JSON.stringify(data, null, 2);
    }

    res.json({
      code: 0,
      message: "success",
      data: {
        answer
      }
    });
  } catch (error) {
    console.error("Coze API 请求失败：", error?.response?.data || error.message);

    res.status(500).json({
      code: 500,
      message: "Coze API 请求失败",
      error: error?.response?.data || error.message
    });
  }
});

app.listen(PORT, () => {
  console.log(`Coze web chat server is running on port ${PORT}`);
});

六、前端源码

创建文件：

mkdir -p public
vim public/index.html

写入以下内容：

  
  
  
  



  

    
Coze Web Chat
    
一个基于 Coze API 的私有化聊天助手示例
  

  

    

      
你好，我是你的 Coze AI 助手，请问有什么可以帮你？
    
  

  

    
    发送
  
  
提示：请不要在前端暴露 Coze API Token。

七、本地运行测试

安装依赖：

npm install

启动服务：

npm start

访问：

http://localhost:3000

如果页面可以打开，并且提问后能得到 Coze Bot 的回复，说明本地部署成功。

八、Docker 部署

1. Dockerfile

在项目根目录创建 Dockerfile：

FROM node:20-alpine

WORKDIR /app

COPY package.json package-lock.json* ./

RUN npm install --production

COPY . .

EXPOSE 3000

CMD ["npm", "start"]

2. docker-compose.yml

services:
  coze-web-chat:
    build: .
    container_name: coze-web-chat
    restart: always
    ports:
      - "3000:3000"
    env_file:
      - .env

3. 构建并启动

docker compose up -d --build

查看容器：

docker ps

查看日志：

docker logs -f coze-web-chat

访问：

http://服务器IP:3000

如果可以正常访问，说明 Docker 部署成功。

九、使用 Nginx 反向代理

如果你想通过域名访问，例如：

https://chat.example.com

可以配置 Nginx。

1. 安装 Nginx

apt update
apt install nginx -y

2. Nginx 配置示例

创建配置文件：

vim /etc/nginx/conf.d/coze-web-chat.conf

写入：

server {
    listen 80;
    server_name chat.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 120s;
    }
}

检查配置：

nginx -t

重载 Nginx：

systemctl reload nginx

十、配置 HTTPS 证书

推荐使用 Certbot 自动申请 HTTPS 证书。

安装：

apt install certbot python3-certbot-nginx -y

申请证书：

certbot --nginx -d chat.example.com

完成后访问：

https://chat.example.com

十一、常见问题排查

1. 页面能打开，但发送消息失败

优先检查后端日志：

docker logs -f coze-web-chat

常见原因：

• .env 没有配置；
• COZE_API_TOKEN 错误；
• COZE_BOT_ID 错误；
• Coze API 地址不正确；
• Bot 没有发布；
• 服务器无法访问 Coze API。

2. 返回 401 Unauthorized

通常是 Token 问题：

Authorization: Bearer xxxxxx

请确认：

• Token 是否复制完整；
• Token 是否过期；
• Token 是否有调用 Bot 的权限；
• API 区域是否匹配。

3. 返回 404 Not Found

可能是 API 地址或接口路径不正确。

本文示例使用：

/open_api/v2/chat

如果 Coze 官方接口版本发生变化，请以官方最新文档为准。

4. 回复内容为空

可能原因：

• Bot 没有正确配置；
• Bot 没有发布；
• 返回结构与示例不一致；
• Bot 调用了插件但插件失败；
• 工作流没有正确输出。

你可以临时打印完整返回：

console.log(JSON.stringify(response.data, null, 2));

然后根据真实字段调整解析逻辑。

十二、生产环境优化建议

如果你要把这个项目用于正式业务，建议继续增加以下能力。

1. 用户鉴权

不要让任何人都能调用你的接口，否则可能导致 Token 被间接滥用，产生大量费用。

可以增加：

• 登录态校验；
• JWT 鉴权；
• 企业微信 / 飞书登录；
• IP 白名单；
• API Key 管理。

2. 请求限流

可以使用 express-rate-limit：

npm install express-rate-limit

示例：

import rateLimit from "express-rate-limit";

const limiter = rateLimit({
  windowMs: 60 * 1000,
  max: 30,
  message: {
    code: 429,
    message: "请求过于频繁，请稍后再试"
  }
});

app.use("/api/chat", limiter);

3. 日志记录

建议记录：

• 用户 ID；
• 提问内容；
• 响应耗时；
• 错误状态；
• Token 消耗；
• IP 地址。

但要注意隐私合规，不要记录敏感信息。

4. 流式输出

本文为了简单，使用的是非流式返回：

stream: false

如果你希望实现类似 ChatGPT 的逐字输出效果，可以使用 Coze 支持的流式接口，并在前端使用 ReadableStream 或 SSE 接收数据。

5. 多 Bot 路由

如果你有多个业务场景，可以在后端维护多个 Bot ID：

const botMap = {
  customerService: "bot_id_1",
  codeAssistant: "bot_id_2",
  documentQA: "bot_id_3"
};

前端传入场景：

{
  "scene": "codeAssistant",
  "message": "帮我解释这段代码"
}

后端根据 scene 选择对应 Bot。

十三、完整部署命令汇总

如果你已经准备好了源码，可以直接执行：

git clone your-repo-url coze-web-chat
cd coze-web-chat

cp .env.example .env
vim .env

docker compose up -d --build
docker logs -f coze-web-chat

访问：

http://服务器IP:3000

如果配置了域名和 HTTPS，则访问：

https://chat.example.com

十四、源码汇总

最终项目结构如下：

coze-web-chat/
├── docker-compose.yml
├── Dockerfile
├── package.json
├── server.js
├── .env.example
└── public/
    └── index.html

核心文件包括：

• server.js：后端接口服务；
• public/index.html：前端聊天页面；
• Dockerfile：镜像构建文件；
• docker-compose.yml：容器编排文件；
• .env.example：环境变量示例。

你可以将本文代码复制到对应文件中，即可完成一个可运行的 Coze Web Chat 项目。

十五、总结

本文完整演示了如何部署一个基于 Coze 的 AI 聊天助手系统。整个流程包括：

1. 创建 Coze Bot；
2. 获取 API Token 和 Bot ID；
3. 编写 Node.js 后端服务；
4. 编写前端聊天页面；
5. 本地运行测试；
6. 使用 Docker 部署；
7. 使用 Nginx 绑定域名；
8. 配置 HTTPS；
9. 处理常见问题；
10. 给出生产环境优化方案。

对于个人开发者来说，这个项目可以作为 AI 助手、知识库问答、客服机器人、编程助手的基础模板。
对于企业团队来说，也可以在此基础上继续扩展登录权限、数据审计、知识库检索、多 Bot 管理、工作流调用等能力。

最后提醒一句：

Coze 的 API 地址、鉴权方式和返回结构可能会随着官方版本更新而变化。实际部署时，请以 Coze 官方最新文档为准，并根据真实返回结果调整代码。