MAX-API

🚀 快速开始

本地体验默认使用 SQLite，只需 Docker：

MAX_API_IMAGE=cscitechtop/max-api:latest@sha256:006d5d86887a261baab4d71ec3797d429e3771a4836e5899734aee0e7f66f2ab

docker pull "$MAX_API_IMAGE"

docker run --name max-api -d --restart always -p 127.0.0.1:3000:3000 -e TZ=Asia/Shanghai -v ./data:/data "$MAX_API_IMAGE"

启动后访问：<http://localhost:3000>

接下来完成三件事：

1. 创建或确认管理员账号。
2. 添加一个具有合法授权的上游渠道和 API Key。
3. 创建访问令牌，把应用中的 Base URL 指向 MAX API。

[!TIP] 生产环境请固定使用已确认的正式版标签，升级前请备份数据库并准备回滚方案。 [!WARNING] SQLite 适合本地体验、开发和小规模测试。正式环境建议使用仍在供应商安全支持周期内的 MySQL（建议 8.4 LTS）或 PostgreSQL（建议 14+），并配置 Redis、HTTPS、备份和恢复方案。项目兼容性下限仍为 MySQL ≥ 5.7.8、PostgreSQL ≥ 9.6，但不建议将其用于生产。

🚢 部署指南

以下步骤以正式版为例。请固定版本标签和对应提交，并在升级前完成备份、校验和回滚准备。

推荐使用 Docker Compose：

```bash MAX_API_VERSION=v1.0.5 MAX_API_COMMIT=74a7ed3e4e2989c7e6f32b88a6b55e8446d2534e git clone --branch "$MAX_API_VERSION" --depth 1 https://github.com/MAX-API-Next/MAX-API.git cd MAX-API

actual_commit="$(git rev-parse HEAD)" if [ "$actual_commit" != "$MAX_API_COMMIT" ]; then echo "Unexpected commit: $actual_commit" >&2 exit 1 fi

修改 docker-compose.yml 中的数据库、Redis 密码和密钥

docker compose up -d ```

部署检查

多节点必须统一 SESSION_SECRET，并为每个节点使用不同的 NODE_NAME。CRYPTO_SECRET 为可选覆盖项，未设置时使用 SESSION_SECRET；如显式设置，则所有节点必须使用相同值。独立日志库使用 LOG_SQL_DSN；错误性能统计需要按需启用 ERROR_LOG_ENABLED。完整环境变量和源码构建说明见 详细文档。

💖 感谢使用 MAX API

如果这个项目对你有帮助，欢迎给我们一个 ⭐ Star、关注 Releases、提交可复现 Issue，或参与 MAX-API-Next 社区共建。

项目仓库 • 参与共建 • 最新发布 • MAX-API-Next 社区

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

</div>

MAX API

🌐 加入 MAX-API-Next 社区

MAX API 不只是一个代码仓库，也是一项面向 AI Models、Agents、AgentOps 与 AGI 工程化的长期开放协作。无论你正在部署模型网关、开发 Agent、适配新模型、研究评测与治理，还是愿意改进文档和国际化，都欢迎加入社群交流并参与共建。

加入社群，你可以更快获取版本动态、模型与协议变化、部署经验、问题排查线索和社区共建机会。

<p align="center"> <strong>QQ 群：950126533</strong> • <strong>微信群：搜索 MAX-API</strong> </p>

MAX API 2.0 技术亮点

• Evidence-driven SmartOps：把资源告警、渠道/模型性能、数据质量状态和计费结算证据汇聚到统一运维入口，并保留人工审阅与真实财务状态之间的边界。
• 面向先进模型协议持续演进：增强 Responses、Claude Messages、Gemini 与 Ollama 的 Reasoning、缓存键、惩罚参数、工具定义和多轮 Tool Context 兼容。
• 可恢复的计费与异步任务语义：通过幂等 settlement、持久化 effect、任务 ID 和明确的 pending/manual 状态，避免异常重试导致重复扣费、错误退款或任务丢失。
• 高风险操作分作用域重新验证：Passkey、2FA、Telegram、API Token 与会话撤销采用 scope-bound step-up verification，并通过 session_generation 及时撤销旧会话。
• 跨数据库与持续验证：核心数据路径兼容 SQLite、MySQL 和 PostgreSQL；Go 测试、前端 Bun 测试、TypeScript 类型检查、JSON 包装规则和测试镜像同步共同构成发布门禁。

💡 为什么需要 MAX API

一句话概括：供应商负责提供模型，Agent 框架负责编排业务，MAX API 负责统一接入并守住治理边界。

🔌 模型、接口与扩展

实际可用能力取决于你的上游授权、渠道配置、模型映射和供应商支持。MAX API 负责治理这些能力，不提供模型服务本身。

覆盖 OpenAI、Claude、Gemini、Azure、AWS Bedrock、Vertex AI、Ollama 及多种国内模型平台，也可治理 Codex、Dify、RAGFlow 和多模态任务服务。具体支持范围以当前版本和渠道类型为准。