部署Team-API让团队使用大模型更简单，每个人都可以登陆查看自己的用量详情了！
·
本教程面向首次接触 Team-API 的用户，手把手指导你完成从零开始的部署和基础配置。
项目地址： https://github.com/qianfree/team-api
1. 项目简介
Team-API 是一个多租户大模型 API 网关 SaaS 平台，主要功能包括：
- 统一接入主流大模型供应商（OpenAI、Claude、Gemini、DeepSeek 等）
- 多租户管理，支持为不同组织/团队独立计费
- OpenAI 兼容的 API 接口，无需修改现有代码即可接入
- 智能渠道调度，自动故障转移和负载均衡
- 实时计费和用量监控
部署架构
┌─────────────────────────────────────────────────────────────┐
│ Team-API │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 管理后台 │ │ 租户控制台 │ │ AI 代理接口 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ PostgreSQL │ Redis │ AI 供应商（OpenAI/Claude...）│
└─────────────────────────────────────────────────────────────┘
2. 环境准备
2.1 硬件要求
| 资源 | 最低配置 | 推荐配置 |
|---|---|---|
| CPU | 2 核 | 4 核+ |
| 内存 | 4 GB | 8 GB+ |
| 磁盘 | 20 GB | 50 GB+（SSD 推荐） |
2.2 软件要求
方式一：Docker 部署（推荐新手）
- Docker 20.10+
- Docker Compose 2.0+
方式二：源码部署（开发者）
- Go 1.25+
- PostgreSQL 15+
- Redis 7+
- Node.js 18+ 和 bun（仅开发时需要）
2.3 检查 Docker 环境
# 检查 Docker 版本
docker --version
# 检查 Docker Compose 版本
docker compose version
# 如果没有安装，请访问 https://docs.docker.com/engine/install/ 获取安装指南
3. Docker Compose 快速部署（推荐）
这是最简单的部署方式，适合大多数用户。所有服务（PostgreSQL、Redis、应用）将通过 Docker Compose 一键启动。
3.1 获取项目代码
# 克隆项目仓库
git clone https://github.com/qianfree/team-api.git
# 进入项目目录
cd team-api
3.2 修改配置文件
第一步：修改 docker-compose.yaml 中的默认密码
编辑 manifest/docker/docker-compose.yaml 文件：
# 使用你喜欢的编辑器打开
vim manifest/docker/docker-compose.yaml
必须修改的密码项：
# 第 31 行左右：PostgreSQL 密码
environment:
POSTGRES_PASSWORD: team_api_secret # ← 改为你的强密码
# 第 53 行左右：Redis 密码
command: redis-server --appendonly yes --requirepass redis_secret # ← 改为你的强密码
安全建议：
- 密码长度至少 16 位
- 包含大小写字母、数字和特殊字符
- 记住你设置的密码，后续配置需要用到
第二步：创建并编辑应用配置文件
# 进入 docker 配置目录
cd manifest/docker
# 复制示例配置文件
cp config.example.yaml config.yaml
# 编辑配置文件
vim config.yaml
config.yaml 关键配置说明：
# 数据库配置 - 与 docker-compose.yaml 中的密码保持一致
database:
default:
type: "pgsql"
link: "pgsql:team_api:你的PostgreSQL密码@tcp(postgres:5432)/team_api?sslmode=disable"
# ^用户名 ^密码 ^主机:端口 ^数据库名
# Redis 配置 - 与 docker-compose.yaml 中的密码保持一致
redis:
default:
address: "redis:6379"
pass: "你的Redis密码"
db: 0
# JWT 密钥 - 必须修改为随机字符串，用于登录令牌加密
jwt:
secret: "team-api-jwt-secret-key-please-change-me" # ← 改为随机字符串
生成安全的 JWT 密钥：
# Linux/macOS - 生成 32 位随机字符串
openssl rand -base64 32
# 或者使用以下命令生成
echo $(date +%s%N | sha256sum | base64 | head -c 32)
3.3 启动服务
# 在项目根目录执行
docker compose -f manifest/docker/docker-compose.yaml up -d
输出示例：
[+] Running 4/4
✔ Network team-api-network Created
✔ Volume "postgres_data" Created
✔ Volume "redis_data" Created
✔ Container team-api-postgres Started
✔ Container team-api-redis Started
✔ Container team-api-app Started
3.4 检查服务状态
# 查看所有容器状态
docker compose -f manifest/docker/docker-compose.yaml ps
# 预期输出：所有服务状态为 "Up" 或 "healthy"
NAME STATUS PORTS
team-api-app Up (healthy) 0.0.0.0:18888->18888/tcp
team-api-postgres Up (healthy) 5432/tcp
team-api-redis Up (healthy) 6379/tcp
3.5 查看日志（如有问题）
# 查看所有服务日志
docker compose -f manifest/docker/docker-compose.yaml logs
# 仅查看应用日志
docker compose -f manifest/docker/docker-compose.yaml logs app
# 实时跟踪日志
docker compose -f manifest/docker/docker-compose.yaml logs -f app
4. 系统初始化配置
首次启动后，需要完成系统初始化配置。
4.1 访问初始化页面
在浏览器中打开：
http://localhost:18888
如果是远程服务器部署，将 localhost 替换为服务器 IP 地址。
4.2 创建管理员账号
初始化页面会要求你创建管理后台的第一个管理员账号：
| 字段 | 说明 | 示例 |
|---|---|---|
| 用户名 | 管理员登录名 | admin |
| 邮箱 | 联系邮箱 | admin@example.com |
| 密码 | 至少 8 位，包含字母和数字 | Admin@123456 |
| 确认密码 | 再次输入密码 | Admin@123456 |
4.3 登录管理后台
初始化完成后，会自动跳转到管理后台登录页面：
http://localhost:18888/api/admin/
使用刚才创建的管理员账号登录。
4.4 管理后台界面说明
登录后，你会看到管理后台的主界面，包含以下主要模块：
| 模块 | 功能说明 |
|---|---|
| 仪表盘 | 系统概览、用量统计 |
| 租户管理 | 创建和管理租户组织 |
| 模型管理 | 配置 AI 模型和定价 |
| 渠道管理 | 添加和管理 AI 供应商渠道 |
| API 密钥 | 管理各租户的 API Key |
| 计费账单 | 查看交易记录和账单 |
| 系统设置 | 全局配置和系统参数 |
5. 添加 AI 模型渠道
在使用 API 之前，需要先配置 AI 供应商渠道（即你的 API Key）。
5.1 进入渠道管理
- 在管理后台左侧菜单点击「渠道管理」
- 点击「新增渠道」按钮
5.2 填写渠道信息
以配置 OpenAI 渠道为例：
| 字段 | 说明 | 示例值 |
|---|---|---|
| 渠道名称 | 自定义名称 | OpenAI 官方 |
| 供应商类型 | 选择 AI 供应商 | OpenAI |
| API Key | 你的 API Key | sk-xxxxxxxxxxxxx |
| API 基础地址 | API 端点地址 | https://api.openai.com/v1 |
| 启用状态 | 是否启用此渠道 | 开 |
获取 API Key 的位置：
| 供应商 | 获取地址 |
|---|---|
| OpenAI | https://platform.openai.com/api-keys |
| Anthropic Claude | https://console.anthropic.com/settings/keys |
| Google Gemini | https://makersuite.google.com/app/apikey |
| DeepSeek | https://platform.deepseek.com/api_keys |
5.3 配置模型定价
- 进入「模型管理」页面
- 找到你想启用的模型（如
gpt-4o） - 点击「编辑定价」
- 设置价格（单位：美元/1K Tokens）
| 模型 | 输入价格（$/1K） | 输出价格（$/1K） |
|---|---|---|
| gpt-4o | 0.005 | 0.015 |
| gpt-4o-mini | 0.00015 | 0.0006 |
| claude-3-5-sonnet-20241022 | 0.003 | 0.015 |
价格参考： 可在供应商官网查看最新定价。
6. 创建租户和 API Key
租户（Tenant）代表一个组织或团队，每个租户有独立的 API Key 和额度管理。
6.1 创建租户
- 进入「租户管理」页面
- 点击「新增租户」
- 填写租户信息：
| 字段 | 说明 | 示例 |
|---|---|---|
| 租户名称 | 组织名称 | 示例科技公司 |
| 租户代码 | 唯一标识（用于登录） | demo-tech |
| 管理员邮箱 | 初始管理员邮箱 | admin@demo-tech.com |
| 管理员密码 | 初始管理员密码 | Tenant@123456 |
| 初始额度 | 赠送的初始金额（USD） | 10.00 |
6.2 获取租户控制台访问
租户创建成功后，有两种方式访问租户控制台：
方式一：通过管理后台跳转
在租户列表中，点击该租户的「登录控制台」按钮。
方式二：直接访问租户控制台
http://localhost:18888/api/tenant/
使用租户管理员账号登录（用户名格式：邮箱 或 管理员用户名@租户代码）。
6.3 创建 API Key
在租户控制台中创建 API Key：
- 登录租户控制台
- 进入「API 密钥」页面
- 点击「创建密钥」
- 填写密钥信息：
| 字段 | 说明 | 示例 |
|---|---|---|
| 密钥名称 | 自定义名称 | 生产环境 Key |
| 关联项目 | 选择项目 | 默认项目 |
| 模型权限 | 选择允许的模型 | 全部模型 |
| 额度限制 | 设置此 Key 的最大额度 | 100.00 USD |
- 点击「创建」，复制并保存 API Key（只显示一次！）
API Key 示例：
sk-tenant-abc123xyz789def456
7. 测试 API 调用
现在你已经完成了所有配置，可以测试 API 调用了。
7.1 使用 curl 测试
curl http://localhost:18888/v1/chat/completions \
-H "Authorization: Bearer sk-tenant-你的API-Key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [
{"role": "user", "content": "你好，请介绍一下你自己"}
],
"max_tokens": 100
}'
7.2 使用 Python 测试
import openai
# 配置 API
openai.api_base = "http://localhost:18888/v1"
openai.api_key = "sk-tenant-你的API-Key"
# 发起请求
response = openai.ChatCompletion.create(
model="gpt-4o",
messages=[
{"role": "user", "content": "你好，请介绍一下你自己"}
],
max_tokens=100
)
print(response.choices[0].message.content)
7.3 验证结果
如果配置正确，你会收到 AI 模型的响应。同时在租户控制台的「用量统计」中可以看到本次调用的计费记录。
7.4 项目截图
8. 常见问题
Q1: 容器启动失败，提示数据库连接错误
原因： config.yaml 中的数据库密码与 docker-compose.yaml 不一致。
解决： 检查两个文件中的密码是否完全一致。
# docker-compose.yaml
POSTGRES_PASSWORD: my-secret-password
# config.yaml
link: "pgsql:team_api:my-secret-password@tcp(postgres:5432)/team_api?sslmode=disable"
Q2: 无法访问初始化页面，显示 404
原因： 数据库未正确初始化或迁移未执行。
解决： 查看应用日志，确认数据库迁移是否成功。
docker compose -f manifest/docker/docker-compose.yaml logs app | grep migrate
Q3: API 调用返回 401 Unauthorized
原因： API Key 错误或无效。
解决：
- 检查 API Key 是否正确复制
- 确认 API Key 所在租户是否有足够额度
- 检查 API Key 是否已启用
Q4: AI 模型调用失败，提示渠道不可用
原因： 渠道配置错误或 API Key 无效。
解决：
- 在管理后台「渠道管理」检查渠道状态
- 验证供应商 API Key 是否有效
- 检查服务器是否能访问供应商 API（网络问题）
Q5: 大陆用户如何访问 OpenAI/Claude API
原因： 这些服务在国内无法直接访问。
解决： 在 config.yaml 中配置代理：
channel_proxy_url: "http://你的代理地址:端口"
Q6: 如何修改服务端口
修改方式：
- 编辑
manifest/docker/docker-compose.yaml，修改端口映射：
ports:
- "18888:18888" # 改为 "8000:18888" 则通过 8000 端口访问
- 重启服务：
docker compose -f manifest/docker/docker-compose.yaml down
docker compose -f manifest/docker/docker-compose.yaml up -d
Q7: 如何备份数据
数据库备份：
# 备份数据库到本地文件
docker exec team-api-postgres pg_dump -U team_api team_api > backup.sql
# 恢复数据库
docker exec -i team-api-postgres psql -U team_api team_api < backup.sql
Q8: 如何升级到新版本
# 1. 拉取最新代码
git pull origin main
# 2. 重新构建镜像
docker compose -f manifest/docker/docker-compose.yaml build --no-cache
# 3. 重启服务
docker compose -f manifest/docker/docker-compose.yaml up -d
# 4. 执行数据库迁移（如果有）
docker exec team-api-app goose -dir migrations postgres "连接字符串" up
9. 下一步
部署完成后，你可以：
- 配置更多渠道：添加多个供应商，实现智能调度和容灾
- 设置套餐订阅：为不同规模的租户提供差异化服务
- 配置监控告警：及时发现异常使用和系统问题
- 自定义品牌：修改租户控制台的 Logo 和配色
更多高级配置请参考项目文档。
祝你使用愉快！
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
11
0- 0
已为社区贡献4条内容
所有评论(0)