MAX-API

🚀 快速开始

默认使用 SQLite，本地体验无需额外数据库。

```bash

按需修改 docker-compose.yml 中的数据库、Redis 密码和环境变量

docker compose up -d ```

[!WARNING] 将本项目作为面向公众的生成式 AI 服务或 API 服务运营时，应先完成上游授权、备案、内容安全、实名、日志留存、税务、支付和用户协议等合规事项。

---

🚢 部署

部署要求

Docker Compose

```bash git clone https://github.com/MAX-API-Next/MAX-API.git cd MAX-API

修改 docker-compose.yml：

Docker 命令

SQLite：

docker run --name max-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  cscitechtop/max-api:latest

MySQL：

docker run --name max-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(mysql:3306)/max-api" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  cscitechtop/max-api:latest

多机部署注意事项

[!WARNING] - 必须设置相同的 SESSION_SECRET，否则不同节点之间登录状态不一致。 - 使用共享 Redis 时必须设置相同的 CRYPTO_SECRET，否则加密数据无法解密。 - 多节点建议设置 NODE_NAME，便于在日志和审计信息中定位来源节点。 - 生产环境应使用外部数据库、外部 Redis、HTTPS 反向代理和可靠的备份策略。

---

2. 启动服务，数据持久化到当前目录 ./data

docker run --name max-api -d --restart always \ -p 3000:3000 \ -e TZ=Asia/Shanghai \ -v ./data:/data \ cscitechtop/max-api:latest

🆚 为什么使用网关

---

💖 感谢使用 MAX API

如果这个项目对你有帮助，欢迎给我们一个 ⭐ Star。

官方文档 • 问题反馈 • 最新发布

<sub>Built with ❤️ by MAX-API-Next</sub>

</div>

🔧 治理配置

初始治理配置建议

1. 部署完成后进入控制台，创建或确认管理员账号。
2. 配置系统设置、用户注册策略、登录方式和安全限制。
3. 添加上游渠道，填写合法授权的 API Key、Base URL、模型列表、模型映射和渠道设置。
4. 根据组织结构配置用户分组、令牌分组、模型限制、额度策略和价格规则，将模型能力纳入访问控制。
5. 为应用、Agent 或工作流创建独立令牌，按业务线、环境或风险级别配置模型范围和额度。
6. 在运营设置中配置失败重试、日志记录、缓存策略和消费统计。
7. 如需管理员侧内容审计，应在合规前提下进入“系统设置 → 安全与限制 → 日志审计”启用，并确保“记录配额使用量（日志维护）”已开启。

渠道能力矩阵与配置校验

渠道新建或编辑时，系统会根据渠道类型展示能力矩阵，并给出实时配置校验结果。矩阵中的接口名称保留原始技术表述，例如 chat/completions、responses、embeddings、rerank、video tasks，说明文字使用中文，便于管理员判断当前渠道能承担哪些模型和任务。

配置校验覆盖以下常见问题：

• 新建渠道缺少 API Key、模型列表为空、需要 Base URL 或额外配置但未填写。
• Base URL 误填到 /v1 结尾，导致系统再次拼接上游路径。
• setting、param_override、header_override、settings 等字段不是 JSON 对象。
• Vertex AI 区域配置缺少 default，或服务账号密钥不是有效 JSON。
• Codex 渠道凭证缺少 access_token 或 account_id。
• 当前渠道不支持模型发现，但开启了上游模型检查或自动同步。
• 视频任务查询路径缺少 {task_id}、{operation_name} 或 {upstream_task_id} 占位符。

推荐环境变量

<details> <summary>查看常用环境变量</summary>

</details>

- 按需设置 SESSION_SECRET、CRYPTO_SECRET、NODE_NAME

- 生产环境建议配置反向代理与 HTTPS

docker compose up -d ```

MAX API

🍥 AI 模型治理、AgentOps 与 AGI 应用服务基础设施

<p align="center"> <strong>简体中文</strong> | <a href="./README.zh_TW.md">繁體中文</a> | <a href="./README.en.md">English</a> | <a href="./README.fr.md">Français</a> | <a href="./README.ja.md">日本語</a> </p>

<p align="center"> <a href="https://raw.githubusercontent.com/MAX-API-Next/MAX-API/main/LICENSE"> <img src="https://img.shields.io/github/license/MAX-API-Next/MAX-API?color=brightgreen" alt="license"> </a><a href="https://github.com/MAX-API-Next/MAX-API/releases/latest"> <img src="https://img.shields.io/github/v/release/MAX-API-Next/MAX-API?color=brightgreen&include_prereleases" alt="release"> </a><a href="https://hub.docker.com/r/cscitechtop/max-api"> <img src="https://img.shields.io/badge/docker-dockerHub-blue" alt="docker"> </a><a href="https://goreportcard.com/report/github.com/MAX-API-Next/MAX-API"> <img src="https://goreportcard.com/badge/github.com/MAX-API-Next/MAX-API" alt="GoReportCard"> </a> </p>

<p align="center"> <a href="#-项目定位">项目定位</a> • <a href="#-发布渠道">发布渠道</a> • <a href="#-治理框架">治理框架</a> • <a href="#-适用场景">适用场景</a> • <a href="#-快速开始">快速开始</a> • <a href="#-核心能力">核心能力</a> • <a href="#-治理配置">治理配置</a> • <a href="#-架构概览">架构概览</a> • <a href="#-ai-模型与接口支持">模型与接口</a> • <a href="#-部署">部署</a> • <a href="#-常见问题">FAQ</a> • <a href="#-许可证">许可证</a> </p>

</div>

---

🤖 AI 模型与接口支持

实际可用模型取决于你的上游授权、渠道配置、模型映射和服务商支持情况。MAX API 的重点是把这些模型能力纳入统一治理，而不是提供上游模型服务本身。

支持的主要接口

<details> <summary>查看接口类别</summary>

• 聊天接口：/v1/chat/completions
• 响应接口：/v1/responses
• 图像接口：/v1/images/*
• 音频接口：/v1/audio/*
• 视频接口：/v1/videos/*
• 嵌入接口：/v1/embeddings
• 重排序接口：/v1/rerank
• 实时对话：OpenAI Realtime 兼容接口
• Claude Messages：Claude 原生格式入口
• Gemini：Google Gemini 格式入口

</details>

AI 模型治理

❓ 常见问题

<details> <summary><strong>MAX API 会提供模型服务或 API Key 吗？</strong></summary>

不会。MAX API 是模型与 Agent 工作负载的网关治理层，不提供上游模型账号、API Key、基础模型训练能力或模型服务本身。使用者需要自行获得合法授权的上游服务。

</details>

<details> <summary><strong>MAX API 和 Agent 框架是什么关系？</strong></summary>

MAX API 不替代 Dify、LangChain、MCP Server、工作流引擎或业务 Agent 应用。它位于这些应用与上游模型服务之间，负责模型接入、令牌隔离、成本核算、路由容灾、日志观测和管理员审计等治理能力。

</details>

<details> <summary><strong>为什么强调 AI 模型治理？</strong></summary>

在真实组织中，模型不只是一个 API 名称，还涉及供应商、价格、上下文长度、协议格式、权限范围、稳定性和审计边界。MAX API 的价值在于把这些分散变量统一配置、统一观察和统一核算。

</details>

<details> <summary><strong>支持哪些数据库？</strong></summary>

支持 SQLite、MySQL ≥ 5.7.8 和 PostgreSQL ≥ 9.6。本地体验可使用 SQLite；生产环境建议使用 MySQL 或 PostgreSQL，并做好备份。

</details>

<details> <summary><strong>能否从 New API / One API 迁移？</strong></summary>

项目兼容 New API 与原版 One API 的主要数据结构，通常可以复用既有数据。迁移前仍建议备份数据库，并在测试环境验证渠道、倍率、用户、令牌和日志数据。

</details>

<details> <summary><strong>多机部署需要注意什么？</strong></summary>

必须统一 SESSION_SECRET。如果使用共享 Redis，也必须统一 CRYPTO_SECRET。否则可能出现登录状态不一致、缓存数据无法解密或任务状态异常。

</details>

<details> <summary><strong>图像生成、流式响应或大响应被截断怎么办？</strong></summary>

可调大 STREAM_SCANNER_MAX_BUFFER_MB。4K 图像、base64 图片、长流式响应等场景可能需要更大的扫描缓冲。

</details>

<details> <summary><strong>请求体过大返回 413 怎么办？</strong></summary>

调整 MAX_REQUEST_BODY_MB。该限制按解压后的请求体大小计算，用于防止超大请求或 zip bomb 导致内存暴涨。

</details>

<details> <summary><strong>用户能看到管理员日志审计中的输入输出内容吗？</strong></summary>

正常用户日志接口会过滤管理员专用字段，普通用户无法在自助使用日志中看到管理员审计内容。数据库管理员、系统管理员或拥有管理员日志接口权限的人仍可能访问相关数据，因此应按合规要求严格控制权限。

</details>

<details> <summary><strong>为什么 Docker 构建时提示 catalog: 依赖无法解析？</strong></summary>

前端使用 Bun workspace，catalog: 依赖定义在 web/package.json。构建时不能用 web/default/package.json 覆盖 workspace 根 package.json，并且需要保留 web/bun.lock。

</details>

---