快速开始

本页只做一件事：在你自己的电脑上把 OctaFuse 跑起来，并能打开管理台。更细的「怎么配供应商、路由、Key」见 使用指南 各章节。生产或预发部署不在此页展开，见文末链接。

方式 A：Docker（最快跑通）

先决条件

已安装 Docker Compose v2.20+（需支持 service_completed_successfully）。
可访问 GitHub 以下载源码（或你的 fork）。

克隆并启动

git clone https://github.com/OctaFuse/octafuse-gateway.git
cd octafuse-gateway
docker compose -f docker/compose/quickstart.yml up --build

等待容器就绪后，新开终端执行：

curl -sS http://localhost:8787/health

若返回 JSON 且无报错，说明 Proxy（推理入口） 已监听 http://localhost:8787。

登录管理台

浏览器打开 http://localhost:8789（Admin）。
使用默认账号登录：admin / changeme（仅限本地体验；任何对外环境都必须改掉）。

建议的下一步（使用指南顺序）

供应商配置 — 接入上游模型服务
模型配置 — 维护网关识别的模型目录
路由配置 — 把客户端 model 映射到上游
用户管理与 API Key 管理 — 谁可以调用、额度多少

可选：立刻打一条测试请求

在管理台里按使用指南配好 Provider + 路由 + API Key 后，可将下面命令里的密钥与 model 换成你的真实值：

curl -sS http://localhost:8787/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-route-model","messages":[{"role":"user","content":"Hello"}]}'

方式 B：Cloudflare（本地 D1）

不想跑 Docker、或希望与 Worker + D1 生产形态一致时，可在本机用 Wrangler 开发。本地数据持久化在 ./.wrangler/state。

先决条件：Node.js 20+、npm。

git clone https://github.com/OctaFuse/octafuse-gateway.git
cd octafuse-gateway
npm install
npm run db:migrate          # 本地 D1 迁移
npm run dev:proxy           # Proxy → http://127.0.0.1:8787

另开终端：

npm run dev:admin           # Admin 预览 → http://127.0.0.1:8789

管理 API 的 Bearer 须与 D1 system_config.MASTER_KEY 一致（开发种子见仓库 packages/core/migrations-d1/0002_seed.sql）。

更多本地组合（Node + Postgres/MySQL、多套 D1 目录、冒烟脚本）见 GitHub 技术参考 · local-testing-environments。