Octopus 是一款专为个人用户和开发者设计的简单、美观且高效的大语言模型（LLM）API聚合与负载均衡代理服务工具。随着市面上大模型数量激增，如何高效管理各个厂商的API与多张密钥成为了难题。Octopus 提供了一站式解决方案，能够将多渠道的 LLM API 集中到一个统一的本地管理面板中进行配置与分发。不论底层接口是 OpenAI、Anthropic 还是 Gemini 格式，Octopus 都可以实现无缝的协议转换，让前端应用能够以统一的接口标准调用全网模型。此外，平台支持为单一渠道挂载多个 API Key，并通过智能优选、轮询、随机或故障转移等多种负载均衡策略，彻底解决高并发场景下的限流与报错问题。凭借直观可视化的用户界面，Octopus 内置了请求统计、Token 消耗监控、成本账单追踪以及自动同步上游模型定价等高级功能，完美满足极客玩家对多模型接口调用的深度管理需求。
功能列表
- 多渠道大语言模型聚合：支持在一个系统中统一管理和配置多个主流大语言模型（LLM）提供商的 API 渠道，将零散的接口集中整合收拢。
- 灵活的多密钥（Multi-Key）分发机制：支持针对同一个模型渠道配置多个不同的 API Key，系统会自动轮换使用，有效避免由于单个 Key 触发速率限制（Rate Limit）而导致的请求失败。
- 高可用全方位负载均衡：内置企业级的流量分发策略，包括轮询（Round Robin）、随机（Random）、故障转移（Failover）以及自定义权重分配（Weighted），保证所有外部调用的稳定流畅。
- 全自动跨平台协议转换：原生支持协议适配转译，可实现 OpenAI Chat、OpenAI Responses、Anthropic API 以及 Gemini 等接口标准之间的自适应兼容，让老旧客户端也无缝调用新平台大模型。
- 智能端点测速与优选：对于绑定了多个端点（Endpoint）的渠道，系统会自动计算各节点的网络请求延迟，并智能把流量分发给当前响应最快的节点。
- 自动化价格与模型同步：自动从 models.dev 上游开源库抓取最新模型定价数据并同步至本地账单系统；同时支持自动刷新并同步当前底层渠道支持的最新模型列表。
- 可视化数据统计与看板：提供极简且数据丰富的前端面板（Web UI），实时记录每一次接口请求的网络状态、Token 精确消耗量以及对应的流水成本财务追踪。
- 轻量级且兼容多重数据库引擎：服务架构极致轻量，默认支持本地 SQLite 进行分钟级零配置部署，同时支持平滑接入 MySQL 或 PostgreSQL 用于处理更庞大的日志数据持久化存储。
使用帮助
🚀 Octopus 安装与详细操作全景指南
Octopus 致力于为个人开发者与 AI 爱好者提供最高效、极简的 LLM API 管理体验。为了让你能够快速上手并充分发挥这套架构的全部潜力，本使用指南将从基础的系统部署、环境配置，再到深度的多渠道聚合与客户端接入，为你提供一套全面且保姆级的操作指导。请仔细阅读并跟着步骤部署，打造你的私人大模型调度中枢。
📦 一、服务部署与初始化设置
Octopus 服务端被编译为单一可执行文件，且内嵌了经过优化的 Web 前端资源，这意味着它的部署过程被简化到了极致，完全告别复杂的环境配置。
1. 使用 Docker 进行容器化部署（强烈推荐）
对于绝大多数用户而言，Docker 提供了纯净且易于维护的隔离环境。请确保你的宿主机或服务器已安装好 Docker，然后在终端执行以下一键启动命令：
docker run -d \
--name octopus \
-v /你的本地绝对路径/data:/app/data \
-p 8080:8080 \
chruxc/octopus
💡 最佳实践指南： 命令中的 -v 参数负责将容器内的 /app/data 目录持久化挂载到你的本地磁盘上。这一步极其重要，Octopus 默认生成的 SQLite 数据库（记录了所有统计账单）和系统核心 config.json 配置文件都会存放在这里。数据持久化能够防止由于容器重启或销毁而导致你的 API Key 资产和历史统计数据丢失。
如果你是一个习惯使用编排工具的高阶玩家，也可以直接创建一个 docker-compose.yml 文件：
wget https://raw.githubusercontent.com/chicring/octopus/refs/heads/dev/docker-compose.yml
docker compose up -d
2. 二进制文件直接运行与源码编译
如果你没有容器环境，或是希望在个人的 Windows/macOS 电脑上快速运行，可以直接前往项目的 GitHub Releases 页面，下载对应操作系统的二进制压缩包。将其解压后，打开终端输入 ./octopus start 即可秒速运行服务。
对于想要参与二次开发的极客，需要确保系统安装有 Go 1.24+ 与 Node.js 18+ 环境。克隆代码仓库后，首先进 web 目录使用 pnpm install && pnpm run build 编译出前端静态资源并移动至后端的 static 目录，最后通过 go run main.go start 完成整体工程编译与启动。
3. 首次登录与管理员凭证修改
无论通过何种方式启动服务，系统默认会在本地监听 8080 端口。打开任意浏览器访问 http://localhost:8080，即可看到清爽的管理后台。
- 默认登录账户：
admin - 默认登录密码：
admin
⚠️ 安全警告： 你的管理面板不仅掌握着你花钱购买的高价值 API 密钥，还对外暴露了转发端点。因此首次进入控制台后，首要任务就是前往系统“设置（Settings）”页面，将默认密码修改为强密码结构。
🛠️ 二、从零配置渠道聚合与智能路由
成功登录后，Dashboard 看板映入眼帘。我们需要依照“自下而上”的逻辑建立服务：首先配置底层的供应渠道（Channel），然后再配置对外分发的业务组（Group）。
步骤 1：录入与配置底层 API 渠道（Channel Management）
渠道可以通俗地理解为你的“API供应商”。
- 在左侧导航栏点击 渠道管理，随后点击右上角的“新增渠道”。
- 选择提供商类型：系统预设了 OpenAI Chat、Anthropic、Gemini 等多种模型协议。选择正确的类型决定了底层请求的组装和解析方式。
- 填写基础链接 (Base URL)：这里有一个核心设计，Octopus 具备智能路由补全功能，因此你不需要填写具体的长请求路径。举个例子，如果你接入的是 OpenAI 官方，只需直接填写
https://api.openai.com/v1即可，系统在转发时会自动在其后方智能拼接上/chat/completions等对应路由地址。 - 填入 API Key 矩阵池：为了解决高频调用导致的账号封禁或受限并发问题，Octopus 允许你在单个渠道下换行配置多个同一提供商的 API Key。系统在处理海量请求时，会自动在这几个 Key 中流转分配流量。
步骤 2：组建虚拟负载均衡群组（Group Management）
仅仅配置好渠道后，系统还无法直接对外提供服务。我们需要将这些零散的渠道“打包”成一个对外的虚拟模型。
- 进入 分组管理 页面，新建一个业务分组。
- 定义虚拟模型名称：这里的“分组名称”就是外部客户端发请求时所传入的
model字段名称。例如，将其命名为gpt-4o-pro。 - 绑定下层真实渠道：在下方勾选刚刚建立的能够提供 gpt-4o 对话服务的具体物理渠道（例如混合勾选官方直连节点和廉价第三方中转节点）。
- 选择流量分配与路由策略（核心亮点）：
- 轮询 (Round Robin)：每次新的 API 请求会按照设定的顺序挨个请求底层渠道，保证各个节点承载流量均等。
- 随机 (Random)：完全随机选取，适合节点数量极大且稳定性无差别的场景。
- 故障转移 (Failover)：为高稳定性生产环境设计！你可以设置一个高优先级的“廉价代理渠道”为主力，一旦该渠道发生网络报错、余额耗尽或拥堵超时，Octopus 会自动阻断错误返回，并在后台将请求无缝重定向至低优先级但最稳定的“官方备用渠道”。你的客户端甚至只会感觉响应慢了半秒，绝不会收到烦人的报错红字。
- 权重分配 (Weighted)：根据不同渠道的价格高低或者账单余额，为节点分配任意 1-100 的权重比例，精准管控各节点流量拆分。
步骤 3：精细化账单核算与模型单价同步（Price Management）
在多渠道混合环境下，计算具体的资金消耗往往让人头疼，Octopus 为此引入了自动化账单系统：
- 默认情况下，Octopus 会在后台静默连接至 GitHub 著名的开源模型定价库
models.dev，自动为你抓取并更新全球各大主流模型的官方实时单价。 - 当你在渠道中挂载了一些独家或非标准私有模型时，系统会自动在面板中记录下这些“无价”模型，你可在此页面手动设定自定义的
Input和Output单价。
依靠此功能结合 Dashboard 上的月度/日度统计报表，开发者能够精准查明哪个应用场景消耗了最多的资金。
💻 三、零代码修改：兼容全平台的客户端接入
服务端配置大功告成。Octopus 架构最为强大的优势在于：不论你在面板里塞进了多少不同格式的杂牌模型，对外暴露时，Octopus 提供的是完美且标准的 OpenAI 接口协议！你可以把它当作全能的万能中间件。
场景 1：在代码中使用 OpenAI 官方 SDK 对接
对于已有项目代码，你无需做任何推倒重来，仅仅只需覆盖重写 base_url 参数：
from openai import OpenAI
# 初始化客户端，将链接指向刚刚部署完成的 Octopus 本地或远程服务点
client = OpenAI(
base_url="http://127.0.0.1:8080/v1",
api_key="sk-octopus-你的系统授权Token"
)
# 重点注意：此处的 model 参数，必须填写在 Octopus "分组管理" 中建立的【虚拟名称】！
completion = client.chat.completions.create(
model="gpt-4o-pro",
messages=[{"role": "user", "content": "请用Python帮我写一个快速排序算法。"}]
)
print(completion.choices[0].message.content)
场景 2：为系统级命令行智能体赋能（以 Claude Code 为例）
部分严格的官方工具要求请求必须具备原生参数结构。假设你希望给 Anthropic 官方出的 Claude Code 命令行助手使用廉价的中转代理节点，你可以修改本地的 ~/.claude/settings.json 让 Octopus 充当“欺骗中间人”：
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8080",
"ANTHROPIC_AUTH_TOKEN": "sk-octopus-你的授权Token",
"ANTHROPIC_MODEL": "这里填入Octopus里设定的Sonnet组名",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "这里填入Octopus里设定的Sonnet组名"
}
}
配置生效后，Claude Code 的底层调用将被重定向至 Octopus，系统会自动完成 Anthropic 原生请求到后端中转代理的协议翻译与无损分发。
终极数据防丢小贴士： 由于需要处理海量文本并发，为了保障系统读写极限性能，Octopus 会将每一次的 API 吞吐与 Token 消耗统计数据暂存于内存中，再根据配置文件每隔数分钟统一批量写入 SQLite/MySQL 数据库。因此，无论你是需要更新 Octopus 还是停机维护，切记不要使用 kill -9 暴力强杀进程。请在终端发送 SIGTERM 信号或直接按下 Ctrl+C 平滑关闭，程序会自动将内存中最后一批“末班车数据”安全落盘。
应用场景
- 多 API Key 额度池化与并发防阻断
如果你手中拥有多个免费额度有限或高并发频控严格的小额度第三方 API Key，如果前端应用直连，极易因瞬间高频请求触发 Rate Limit。使用 Octopus 将这些 Key 加入统一物理渠道池，系统将实施动态均衡轮询分发，在单一接口背后掩盖复杂的调度，彻底打通速率封锁瓶颈。 - 多模态及跨品牌大模型前端无损接入
对于常常同时需要对接使用 ChatGPT、Claude 和 Gemini 等多种模型进行对照评估的个人开发者，不同厂家的私有协议格式会导致应用端请求代码结构极其臃肿。通过 Octopus 强大的原生协议转换网关，所有的模型都被映射为一套标准的 OpenAI 接口格式出入，完美兼容任何 IDE 插件、Chatbox 客户端或沉浸式翻译等第三方效率工具。 - 主从节点灾备冗余与高可用故障转移
针对资金有限但又有业务强依赖场景，开发者往往采购非常便宜但不稳定的第三方中转通道。应用 Octopus 后，你可以将该低价渠道设定为主节点，官方高价渠道设为备用节点。日常承载走廉价通道降本增效，一旦主节点遇到网络拥堵崩溃，网关层会实现毫秒级“故障转移（Failover）”智能切换至官方节点，客户端业务请求保持 100% 顺畅。 - 内部应用场景精细化计费与财务账单追踪
当个人将大模型能力同步分享给多个私人子项目、个人博客、终端插件或朋友圈好友使用时，往往难以分摊算账。由于 Octopus 支持自动化同步模型市场标准单价及自定义模型定价单价，内置报表看板能深度解剖记录每次请求消耗的具体 Token 数量与所对应的美分价格，帮助建立可视透明的资金成本仪表盘。
QA
- Octopus 的配置信息和统计账单数据默认存放在哪里？我可以使用其他数据库吗？
出于免维护与轻量化的原则，Octopus 系统默认采用单文件的 SQLite 数据库，数据和自生成的config.json均放置在挂载的本地data/data.db目录。对于有更大吞吐量或希望进行跨服务器数据隔离的进阶用户，可通过修改配置文件，原生平滑接入更高性能的 MySQL 或 PostgreSQL 数据库环境。 - 我不小心使用了弱密码启动，该如何修改管理面板的管理员密码？
请在服务完成初次部署后，使用默认初始账户admin/ 密码admin登入后台。然后第一时间点击界面右上角个人中心或左下角设定（Settings）按钮，根据提示立刻更新设定新的高强度密码，避免被公网机器扫描截获从而造成账户内的 API 资产被恶意盗刷。 - 我的第三方 AI 应用插件只支持输入 OpenAI 格式接口，但我希望底层调用 Anthropic Claude 模型，这行得通吗？
完全可以。由于 Octopus 原生集成了高性能的跨协议转译器。你只需要在“渠道管理”正确录入 Claude 服务的地址和密钥参数，随后只要对外部调用的插件填写 Octopus 的局域网或公网路由网关，系统即会自动接收客户端标准的 OpenAI/chat/completions请求协议并在底层无损翻译为 Anthropic 协议进行对话，整个过程对调用端完全透明。 - 如果不慎遭遇服务器断电或者强行终止系统进程，会导致已消耗的账单流水记录丢失吗？
有可能会出现少许数据丢失。鉴于统计请求需要极高的 IO 并发资源响应，Octopus 采用了内存优先的统计策略，所有最近几分钟内的 Request 次数和 Token 账单日志会存放在进程缓存池中，定期批量压入底层数据库。若采取kill -9此类强制销毁手段，尚未来得及持久化到数据库的这几分钟数据将会归零。请始终利用规范的程序停止指令（例如按下Ctrl+C）等待优雅停机（Graceful Shutdown）完毕即可。 - 在填写渠道 Base URL 时，需要像 Postman 调试那样加入类似
/chat/completions的请求后缀吗？
不需要。系统的请求构建器具备智能感知能力，你仅需填入域名和版本标识这一前置根路径即可（如https://api.openai.com/v1、https://api.anthropic.com/v1等）。对于模型交互的差异化端点后缀，Octopus 在发起代理请求时会自动组装拼接，切勿画蛇添足。
