1. 为什么要在NAS上折腾Octopus手里攒了好几个大模型的API KeyDeepSeek一个、智谱一个、Kimi一个偶尔还想试试本地跑的Ollama。每次写代码或者调试Agent光是在不同平台的文档页、控制台、API端点之间来回切换就够让人头大的。更别提有些平台免费额度用完就得换换完还得改代码里的base_url和key改来改去项目里全是硬编码维护起来想死的心都有。Octopus这个项目就是冲着这个痛点来的。它本质上是一个大模型API聚合网关你可以把它理解成一个“API路由器”——所有上游的大模型服务OpenAI兼容格式的、各家私有协议的都接到Octopus上然后你只需要记住一个地址、一个Key就能调用背后所有模型。想换模型在Octopus的管理界面点一下就行代码一行不用动。那为什么非要部署在NAS上理由很实在。第一NAS是7x24小时开着的你不可能为了调个API专门开一台云服务器电费和维护成本都不划算。第二数据在自己手里API Key、调用日志、对话记录全在本地不用担心第三方平台哪天跑路或者改政策。第三群晖、绿联、飞牛这些NAS系统现在都支持Docker部署一个Octopus容器就是几分钟的事门槛比想象中低得多。这篇文章适合谁看如果你手头有NAS不管是群晖、威联通、绿联还是自己DIY的飞牛系统并且你正在用或者打算用多个大模型API那这篇内容就是给你写的。我会从架构思路、部署实操、配置细节到踩坑排查完整走一遍。即使你之前没怎么碰过Docker跟着步骤也能跑起来。注意本文所有操作均在本地NAS环境完成不涉及任何外部网络穿透或代理配置纯粹是局域网内的服务部署。2. Octopus的核心架构与选型逻辑2.1 它到底解决了什么问题先把这个事情说透。假设你手上有三个模型来源DeepSeek的官方API、智谱的GLM、还有本地Ollama跑的Qwen。没有Octopus的时候你的代码大概长这样# 调用DeepSeek client OpenAI(base_urlhttps://api.deepseek.com/v1, api_keysk-deepseek-xxx) # 调用智谱 client OpenAI(base_urlhttps://open.bigmodel.cn/api/paas/v4, api_keyxxx) # 调用本地Ollama client OpenAI(base_urlhttp://192.168.1.100:11434/v1, api_keyollama)每换一个模型就要改base_url和key。如果项目里有十几处调用那就是十几处修改。而且一旦某个平台的免费额度用完或者服务出问题你得挨个去改。有了Octopus之后代码变成这样client OpenAI(base_urlhttp://192.168.1.100:8080/v1, api_keyoctopus-xxx) # 模型名指定为 deepseek-chat 或 glm-4 或 qwen2.5所有上游的差异都被Octopus吃掉了。它对外暴露统一的OpenAI兼容接口对内负责路由、鉴权、格式转换、负载均衡。这就是API网关模式的核心价值——把复杂性收敛到一个点上。2.2 为什么选Octopus而不是其他方案市面上类似的聚合方案不少有One API、New API、LiteLLM Proxy等等。我选Octopus主要看中几点第一部署轻量。Octopus的镜像体积不大对NAS这种资源有限的设备很友好。群晖J4105这种级别的CPU跑起来内存占用在200MB以内完全不影响NAS本身的文件服务。第二管理界面直观。它有一个Web管理后台添加渠道、查看调用日志、设置模型映射都在浏览器里点点就行不需要去改配置文件再重启容器。对于不熟悉命令行的用户来说这一点很关键。第三支持渠道类型丰富。除了标准的OpenAI兼容接口它还支持Azure、Claude、Gemini等不同协议的渠道甚至可以把多个相同模型的渠道做成负载均衡池。这意味着你如果有两个DeepSeek的Key可以都加进去Octopus会自动轮询。第四日志和统计做得细。每次调用的token消耗、响应时间、成功失败状态都有记录。对于需要控制成本的场景这个功能很实用——你能清楚看到哪个模型烧钱最多。当然它也不是没有缺点。相比LiteLLM那种纯Python库的方案Octopus多了一层网络转发理论上会多几毫秒延迟。但实测下来局域网内这个延迟基本可以忽略换来的是管理上的巨大便利。2.3 NAS部署的硬件门槛很多人担心NAS性能不够。我拿手头的设备做个对比NAS型号CPU内存Octopus运行情况群晖DS220Intel Celeron J40252GB流畅运行内存占用约180MB群晖DS920Intel Celeron J41254GB流畅运行可同时跑其他容器绿联DXP4800Intel N1008GB非常流畅响应迅速老电脑DIYJ41058GB流畅运行无压力结论很明确只要你的NAS能跑Docker就能跑Octopus。它本身不涉及模型推理只是一个转发层CPU和内存消耗都很低。真正吃资源的是你本地跑的Ollama模型那是另一回事。实操心得如果你的NAS内存只有2GB建议把Octopus和其他重型容器比如Plex、虚拟机错开运行避免内存争抢导致容器被OOM Killer干掉。3. 部署前的准备工作3.1 确认Docker环境群晖用户打开套件中心搜索“Container Manager”DSM 7.2以上或“Docker”DSM 7.0以下安装即可。绿联和飞牛系统一般自带Docker管理界面。如果你是用老电脑DIY的NASSSH进去执行docker --version docker-compose --version两条命令都有输出说明环境没问题。如果没有docker-compose可以单独安装sudo apt install docker-compose-plugin3.2 规划目录结构我不建议把Octopus的数据目录放在Docker默认的volume里因为那样备份和迁移都很麻烦。最好在NAS的存储空间里建一个专用目录比如/volume1/docker/octopus/ ├── data/ # 数据库和配置文件 ├── logs/ # 运行日志 └── docker-compose.yml群晖用户注意/volume1是你的存储空间挂载点具体名称可能不同在File Station里看一下就知道。绿联的路径通常是/mnt/media_rw/xxx或者通过Docker管理界面直接映射。3.3 获取镜像Octopus的镜像可以从GitHub Container Registry拉取。如果你的NAS网络环境拉取Docker Hub比较慢可以配置镜像加速。在群晖的Container Manager里进入“注册表”设置添加一个加速地址即可。SSH方式的话直接docker pull ghcr.io/bestrui/octopus:latest如果拉取失败检查一下NAS的DNS设置改成223.5.5.5或者114.114.114.114通常能解决。注意不要从不明来源下载镜像也不要用别人打包好的“整合版”API Key这种东西一旦泄露后果比你想的严重。4. 完整部署实操流程4.1 编写docker-compose配置我习惯用docker-compose来管理因为配置清晰、迁移方便。在/volume1/docker/octopus/目录下创建docker-compose.ymlversion: 3.8 services: octopus: image: ghcr.io/bestrui/octopus:latest container_name: octopus restart: unless-stopped ports: - 8080:8080 volumes: - ./data:/app/data - ./logs:/app/logs environment: - TZAsia/Shanghai - OCTOPUS_ADMIN_KEYyour_admin_key_here - OCTOPUS_LOG_LEVELinfo healthcheck: test: [CMD, wget, -q, --spider, http://localhost:8080/health] interval: 30s timeout: 10s retries: 3几个关键参数解释一下ports左边是NAS上的端口右边是容器内端口。8080如果被占用了改成8081、9090都行。volumes把容器内的数据目录映射到NAS本地这样重启容器数据不丢。OCTOPUS_ADMIN_KEY管理后台的登录密钥一定要改成一个复杂字符串不要用默认值。TZ时区设置影响日志时间显示设成Asia/Shanghai方便排查问题。4.2 启动容器SSH进入目录执行cd /volume1/docker/octopus docker-compose up -d看到Container octopus Started就说明启动成功了。用docker ps确认一下状态docker ps | grep octopus状态显示Up且没有频繁重启就没问题。如果显示Restarting用docker logs octopus看日志通常是端口冲突或者权限问题。群晖用户如果不想用SSH也可以在Container Manager的“项目”功能里直接粘贴上面的compose内容点击部署。图形化操作更直观适合不熟悉命令行的朋友。4.3 首次访问与初始化浏览器打开http://你的NAS IP:8080应该能看到Octopus的登录界面。输入你设置的OCTOPUS_ADMIN_KEY进入管理后台。第一次进去界面可能是英文的在设置里改成中文。然后你需要做几件事修改默认密码如果初始化时有默认账号第一时间改掉。配置渠道把你手上的API Key逐个添加进去。创建访问令牌生成一个给客户端用的Key这个Key和上游的Key是分开的泄露了可以随时吊销。4.4 添加第一个渠道以DeepSeek为例在管理后台找到“渠道”或“Channels”菜单点击添加。需要填的信息字段填写内容说明渠道名称DeepSeek官方随便起方便识别渠道类型OpenAI兼容DeepSeek用的是OpenAI格式Base URLhttps://api.deepseek.com/v1注意结尾的/v1API Keysk-你的DeepSeek Key从DeepSeek控制台获取模型列表deepseek-chat, deepseek-reasoner手动填写或自动获取填完之后点“测试”如果显示连接成功就说明配置没问题。然后把这个渠道启用。同样的方式你可以添加智谱、Kimi、Ollama等渠道。Ollama的Base URL填http://你的NAS IP:11434/v1Key随便填一个非空值就行。4.5 配置模型映射与负载均衡这是Octopus比较实用的一个功能。假设你添加了两个DeepSeek的渠道两个不同的Key可以在“模型映射”里把deepseek-chat这个模型名同时指向两个渠道并设置权重。这样当其中一个Key的额度用完或者限流时请求会自动切到另一个。具体操作在模型管理里找到deepseek-chat编辑它的渠道绑定勾选两个渠道权重都设为1。保存后Octopus会按轮询方式分发请求。实操心得负载均衡虽然好用但要注意不同渠道的响应速度可能差异很大。如果你的应用对延迟敏感建议还是指定单一渠道把另一个作为备用。5. 客户端接入与调用测试5.1 用curl快速验证部署完成后先用最简单的命令测试一下curl http://192.168.1.100:8080/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的Octopus令牌 \ -d { model: deepseek-chat, messages: [{role: user, content: 你好}] }如果返回正常的JSON响应说明整条链路通了。如果报错根据错误信息排查401是令牌不对404是模型名没配置502是上游渠道连不上。5.2 在Python项目中接入把原来代码里的base_url和api_key换掉就行from openai import OpenAI client OpenAI( base_urlhttp://192.168.1.100:8080/v1, api_key你的Octopus令牌 ) response client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 写一段Python快速排序}] ) print(response.choices[0].message.content)想换模型只改model参数就行其他一律不动。这就是统一网关带来的便利。5.3 接入常见AI客户端很多AI客户端支持自定义OpenAI兼容端点比如ChatBox、NextChat、LobeChat等。以ChatBox为例设置里选择“OpenAI API兼容”API Host填http://192.168.1.100:8080API Key填Octopus令牌模型名手动输入deepseek-chat或从列表选择配置好之后你在ChatBox里就能随意切换背后的大模型而不用每次去改设置。5.4 日志查看与用量统计Octopus的日志功能值得单独说一下。在管理后台的“日志”页面你能看到每次调用的详细信息请求时间使用的模型上游渠道输入token数输出token数响应耗时状态码这些数据对于成本控制很有帮助。比如你发现某个模型每天消耗几十万token就可以考虑换成更便宜的替代品或者设置用量上限。注意日志里可能包含你的对话内容如果涉及敏感信息建议定期清理日志或者关闭详细日志记录。6. 常见问题与排查技巧实录6.1 容器启动失败现象docker-compose up -d之后docker ps看不到容器或者状态一直是Restarting。排查思路先看日志docker logs octopus --tail 50常见原因一端口被占用。群晖的8080端口可能被Web Station占了换成其他端口。常见原因二目录权限不对。SSH进去执行sudo chown -R 1000:1000 /volume1/docker/octopus/data把目录所有者改成容器内用户。常见原因三镜像拉取不完整。删掉本地镜像重新拉。6.2 调用返回401现象curl测试返回{error: invalid api key}。排查检查Authorization头里的令牌是不是Octopus生成的令牌不是上游的Key。检查令牌有没有过期或被禁用。检查请求头格式必须是Bearer xxx中间有空格。6.3 调用返回502或超时现象请求发出后很久没响应或者返回Bad Gateway。排查在Octopus后台测试对应渠道的连通性。如果是Ollama渠道确认Ollama服务在运行且OLLAMA_HOST设置为0.0.0.0否则容器内访问不到。如果是外部API检查NAS的DNS能不能解析域名nslookup api.deepseek.com试一下。检查NAS的防火墙有没有拦截出站请求。6.4 模型名不识别现象返回model not found。排查在Octopus的模型列表里确认该模型名已添加。检查模型名拼写大小写敏感。如果用了模型映射确认映射规则正确。6.5 响应速度慢现象通过Octopus调用比直连慢很多。排查局域网内正常延迟增加应该在10ms以内如果超过100ms检查NAS负载。关闭不必要的日志记录减少磁盘IO。如果NAS同时在跑下载任务或媒体转码CPU争抢会导致转发变慢。6.6 常见问题速查表问题现象可能原因解决方法容器频繁重启端口冲突/权限不足换端口/改目录权限401未授权令牌错误用Octopus令牌而非上游Key502网关错误上游不可达检查渠道连通性和DNS模型不存在模型未添加在后台添加模型映射响应慢NAS负载高关闭其他重型容器日志不记录日志级别设置调整为info或debug数据丢失未映射volume检查compose的volumes配置实操心得遇到问题先看日志90%的答案都在日志里。docker logs octopus -f可以实时跟踪日志输出调试的时候非常有用。7. 进阶玩法与安全建议7.1 结合本地Ollama做混合路由如果你NAS性能足够可以同时跑Ollama和Octopus。把Ollama作为一个渠道加进去然后在Octopus里设置路由规则简单任务走本地Ollama免费复杂任务走云端API付费。这样既能省钱又能保证效果。具体做法是在Octopus的模型映射里把qwen2.5:7b指向本地Ollama渠道把deepseek-chat指向云端渠道。客户端根据任务类型选择不同模型名即可。7.2 设置用量限额Octopus支持为每个令牌设置额度上限。比如你给某个应用分配的令牌可以限制每天最多调用1000次或者每月最多消耗100万token。超过限额自动拒绝防止意外烧钱。这个功能在多人共用或者测试环境下特别有用。你不用担心某个脚本写错了导致无限循环调用API。7.3 安全加固要点第一不要暴露到公网。Octopus设计上是局域网使用的如果你确实需要外部访问建议通过其他安全方式并且一定要启用HTTPS和强密码。第二定期轮换Key。上游API Key和Octopus令牌都建议每隔几个月换一次。Octopus支持多令牌管理换的时候可以平滑过渡。第三限制管理后台访问。如果NAS上有防火墙可以设置只允许特定IP访问8080端口的管理界面。第四备份配置文件。data目录里存着所有渠道配置和令牌信息定期备份到其他存储位置。万一NAS出问题恢复起来很快。7.4 性能优化小技巧如果NAS内存充足可以给Octopus容器设置内存限制防止它占用过多资源在compose里加mem_limit: 512m。关闭不需要的渠道减少启动时的初始化时间。如果调用量很大考虑把日志级别调到warn减少磁盘写入。定期清理旧日志避免占满存储空间。我在实际使用中最大的体会是Octopus这种工具的价值不在于技术有多复杂而在于它把一件烦人的事情变简单了。以前切换模型要改代码、重启服务现在在浏览器里点两下就搞定。对于同时用好几个大模型的人来说这种效率提升是实打实的。最后再分享一个小技巧如果你在测试阶段不确定哪个模型效果好可以在Octopus里把同一个问题同时发给多个渠道对比响应质量和速度。虽然它本身没有这个功能但你可以写个简单的脚本循环调用不同模型名把结果收集起来对比。这个做法在我选型的时候帮了不少忙。