orangeqiu/ztoapi repository overview

⁠OpenAI兼容API代理 for Z.ai GLM-4.5

这是一个为Z.ai GLM-4.5模型提供OpenAI兼容API接口的代理服务器。它允许你使用标准的OpenAI API格式与Z.ai的GLM-4.5模型进行交互，支持流式和非流式响应。

⁠✨ 主要功能

• 🔄 OpenAI API兼容: 完全兼容OpenAI的API格式，无需修改客户端代码
• 🌊 流式响应支持: 支持实时流式输出，提供更好的用户体验
• 🔐 身份验证: 支持API密钥验证，确保服务安全
• 🛠️ 灵活配置: 通过环境变量进行灵活配置
• 🐳 Docker支持: 提供Docker镜像，便于部署
• 🌍 CORS支持: 支持跨域请求，便于前端集成
• 📝 思考过程展示: 智能处理并展示模型的思考过程
• 📊 实时监控仪表板: 提供Web仪表板，实时显示API转发情况和统计信息

⁠🚀 快速开始

⁠环境要求

• Go 1.23 或更高版本
• Z.ai 的访问令牌

⁠本地部署

1. 克隆仓库

   git clone https://github.com/your-username/ZtoApi.git
   cd ZtoApi
   

   Copy

2. 配置环境变量

   cp config.env .env.local
   # 编辑 .env.local 文件，设置你的 ZAI_TOKEN
   

   Copy

3. 启动服务

   # 使用启动脚本（推荐）
   ./start.sh
   
   # 或直接运行
   go run main.go
   

   Copy

4. 测试服务

   curl http://localhost:9090/v1/models
   

   Copy

5. 访问API文档

   启动服务后，可以通过浏览器访问以下地址查看完整的API文档：

   http://localhost:9090/docs
   

   Copy

   API文档提供了以下功能：

   • 详细的API端点说明
   • 请求参数和响应格式
   • 多种编程语言的使用示例（Python、cURL、JavaScript）
   • 错误处理说明

6. 访问Dashboard

   启动服务后，可以通过浏览器访问以下地址查看实时监控仪表板：

   http://localhost:9090/dashboard
   

   Copy

   Dashboard提供了以下功能：

   • 实时显示API请求统计信息（总请求数、成功请求数、失败请求数、平均响应时间）
   • 显示最近100条请求的详细信息（时间、方法、路径、状态码、耗时、客户端IP）
   • 数据每5秒自动刷新一次

⁠Docker部署

1. 构建镜像

   docker build -t zto-api .
   

   Copy

2. 运行容器

   docker run -p 9090:9090 \
     -e ZAI_TOKEN=your_z_ai_token \
     -e DEFAULT_KEY=your_api_key \
     zto-api
   

   Copy

⁠Render部署

1. Fork这个仓库到你的GitHub账户

2. 在Render上创建新的Web Service：

   • 连接你的GitHub仓库
   • 选择Docker作为环境
   • 设置以下环境变量：
   • ZAI_TOKEN: Z.ai 的访问令牌 (可选，不提供将使用匿名token)
   • DEFAULT_KEY: 客户端API密钥 (可选，默认: sk-your-key)
   • MODEL_NAME: 显示的模型名称 (可选，默认: GLM-4.5)
   • PORT: 服务监听端口 (Render会自动设置)

3. 部署完成后，使用Render提供的URL作为OpenAI API的base_url

⁠⚙️ 环境变量配置

本项目支持通过环境变量进行配置，提供灵活的部署和运行选项。

⁠🚀 快速开始

⁠1. 使用启动脚本（推荐）

macOS/Linux:

./start.sh

Windows:

start.bat

⁠2. 手动设置环境变量

macOS/Linux:

export ZAI_TOKEN="your_z_ai_token_here"
export DEFAULT_KEY="sk-your-custom-key"
export PORT="9090"
go run main.go

Windows:

set ZAI_TOKEN=your_z_ai_token_here
set DEFAULT_KEY=sk-your-custom-key
set PORT=9090
go run main.go

⁠3. Docker运行

docker run -p 9090:9090 \
  -e ZAI_TOKEN=your_z_ai_token_here \
  -e DEFAULT_KEY=sk-your-custom-key \
  -e PORT=9090 \
  zto-api

⁠📋 环境变量列表

⁠🔑 必需配置

无必需配置。所有配置都有合理的默认值。

⁠⚙️ 可选配置

⁠⚙️ 可选配置

⁠🔧 高级配置

⁠📁 配置文件

⁠支持的配置文件（按优先级排序）

1. .env.local - 本地环境配置（推荐）
2. .env - 环境配置
3. config.env - 配置模板

⁠配置文件示例

# 复制配置文件
cp config.env .env.local

# 编辑配置文件
nano .env.local

⁠🔐 获取 Z.ai Token

⁠方法1：浏览器开发者工具

1. 登录 Z.ai⁠
2. 打开浏览器开发者工具（F12）
3. 切换到 Network 标签页
4. 发送一条消息
5. 在请求中找到 Authorization 头部的 Bearer token

⁠方法2：Cookie 方式

1. 登录 Z.ai 后，在开发者工具中查看 Cookies
2. 找到包含认证信息的 cookie

⁠方法3：匿名Token

本项目支持自动获取匿名token，无需手动配置。当 ANON_TOKEN_ENABLED 常量为 true 时，系统会自动为每次对话获取不同的匿名token，避免共享记忆。

⁠🎯 使用示例

⁠基本配置

# .env.local
ZAI_TOKEN=eyJhbGciOiJFUzI1NiIs...
DEFAULT_KEY=sk-my-secret-key
MODEL_NAME=GLM-4.5-Pro
PORT=9000
DEBUG_MODE=false

⁠生产环境配置

# .env.production
ZAI_TOKEN=your_production_token
DEFAULT_KEY=sk-production-key
MODEL_NAME=GLM-4.5
PORT=9090
DEBUG_MODE=false
DEFAULT_STREAM=true

⁠开发环境配置

# .env.development
ZAI_TOKEN=your_dev_token
DEFAULT_KEY=sk-dev-key
MODEL_NAME=GLM-4.5-Dev
PORT=8080
DEBUG_MODE=true
DEFAULT_STREAM=true
DASHBOARD_ENABLED=true

⁠📊 Dashboard功能

本项目提供了一个Web仪表板，用于实时监控API转发情况和统计信息。

⁠功能特点

• 实时显示API请求统计信息（总请求数、成功请求数、失败请求数、平均响应时间）
• 显示最近100条请求的详细信息（时间、方法、路径、状态码、耗时、客户端IP）
• 数据每5秒自动刷新一次
• 响应式设计，支持各种设备访问

⁠访问方式

启动服务后，通过浏览器访问以下地址：

http://localhost:9090/dashboard

⁠配置选项

通过 DASHBOARD_ENABLED 环境变量控制Dashboard功能的开启和关闭：

# 启用Dashboard（默认）
DASHBOARD_ENABLED=true

# 禁用Dashboard
DASHBOARD_ENABLED=false

⁠使用场景

• 开发调试: 实时查看API请求情况，便于调试和问题排查
• 性能监控: 监控API响应时间和成功率，评估系统性能
• 安全审计: 查看请求来源和频率，发现异常访问模式

⁠🔄 重启服务

修改环境变量后，需要重启服务使配置生效：

# 停止当前服务
Ctrl+C

# 重新启动
./start.sh

⁠🚨 注意事项

1. Token 安全: 不要将真实的 Z.ai token 提交到代码仓库
2. 配置文件: 建议将 .env.local 添加到 .gitignore
3. 权限设置: 确保启动脚本有执行权限 (chmod +x start.sh)
4. 端口冲突: 确保配置的端口没有被其他服务占用
5. 匿名Token: 使用匿名token时，每次对话都会有独立的上下文
6. 思考过程: 项目会自动处理模型的思考过程，可通过 THINK_TAGS_MODE 常量调整显示方式

⁠📖 API使用示例

⁠Python示例

import openai

# 配置客户端
client = openai.OpenAI(
    api_key="your-api-key",  # 对应 DEFAULT_KEY
    base_url="http://localhost:9090/v1"
)

# 非流式请求
response = client.chat.completions.create(
    model="GLM-4.5",
    messages=[{"role": "user", "content": "你好，请介绍一下自己"}]
)

print(response.choices[0].message.content)

# 流式请求
response = client.chat.completions.create(
    model="GLM-4.5",
    messages=[{"role": "user", "content": "请写一首关于春天的诗"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

⁠curl示例

# 非流式请求
curl -X POST http://localhost:9090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "GLM-4.5",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

# 流式请求
curl -X POST http://localhost:9090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "GLM-4.5",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

⁠JavaScript示例

const fetch = require('node-fetch');

async function chatWithGLM(message, stream = false) {
  const response = await fetch('http://localhost:9090/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-api-key'
    },
    body: JSON.stringify({
      model: 'GLM-4.5',
      messages: [{ role: 'user', content: message }],
      stream: stream
    })
  });

  if (stream) {
    // 处理流式响应
    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      
      const chunk = decoder.decode(value);
      const lines = chunk.split('\n');
      
      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') {
            console.log('\n流式响应完成');
            return;
          }
          
          try {
            const parsed = JSON.parse(data);
            const content = parsed.choices[0]?.delta?.content;
            if (content) {
              process.stdout.write(content);
            }
          } catch (e) {
            // 忽略解析错误
          }
        }
      }
    }
  } else {
    // 处理非流式响应
    const data = await response.json();
    console.log(data.choices[0].message.content);
  }
}

// 使用示例
chatWithGLM('你好，请介绍一下JavaScript', false);

⁠🔧 故障排除

⁠常见问题

1. 连接失败

   • 检查服务是否正常运行：curl http://localhost:9090/v1/models
   • 访问API文档：http://localhost:9090/docs
   • 确认端口配置正确

2. 认证失败

   • 检查 DEFAULT_KEY 环境变量设置
   • 确认请求头中的 Authorization 格式正确

3. Z.ai Token无效

   • 检查 ZAI_TOKEN 环境变量设置
   • 确认Token未过期

4. 思考过程显示异常

   • 检查 DEBUG_MODE 是否启用
   • 查看服务日志获取详细信息

5. 端口被占用: 修改 PORT 环境变量或停止占用端口的服务

6. 权限不足: 确保启动脚本有执行权限

7. 配置未生效: 重启服务或检查配置文件语法

8. 流式响应问题: 确认 DEFAULT_STREAM 设置正确，检查客户端是否支持流式响应

⁠调试模式

启用调试模式以获取详细日志：

export DEBUG_MODE=true
go run main.go

⁠网络问题排查

如果遇到网络连接问题，可以尝试：

1. 检查防火墙设置
2. 确认 UPSTREAM_URL 可访问
3. 测试网络连通性：

   curl https://chat.z.ai/api/chat/completions
   

   Copy

⁠性能优化

1. 减少日志输出: 设置 DEBUG_MODE=false
2. 调整超时时间: 修改代码中的 http.Client 超时设置
3. 使用反向代理: 在生产环境中建议使用 Nginx 等反向代理

⁠🤝 贡献指南

欢迎提交 Issue 和 Pull Request！请确保：

1. 代码符合 Go 的代码风格
2. 提交前运行测试
3. 更新相关文档
4. 遵循项目的代码结构和命名规范

⁠开发流程

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/new-feature
3. 提交更改：git commit -am 'Add new feature'
4. 推送分支：git push origin feature/new-feature
5. 提交 Pull Request

⁠📄 许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE⁠ 文件。

⁠⚠️ 免责声明

本项目与 Z.ai 官方无关，使用前请确保遵守 Z.ai 的服务条款。开发者不对因使用本项目而产生的任何问题负责。 本项目与 Z.ai 官方无关，使用前请确保遵守 Z.ai 的服务条款。开发者不对因使用本项目而产生的任何问题负责。 本项目与 Z.ai 官方无关，使用前请确保遵守 Z.ai 的服务条款。开发者不对因使用本项目而产生的任何问题负责。

⁠📞 联系方式

如有问题或建议，请通过以下方式联系：

• 提交 Issue⁠