1. 为什么要在 NAS 上折腾 Octopus手里攒了好几个大模型的 API Key这大概是过去一年里很多 AI 玩家的真实写照。DeepSeek 用来写代码智谱用来处理中文长文本Kimi 用来啃 PDF偶尔还想调一下本地跑的 Ollama 模型做点隐私相关的活儿。结果就是浏览器里开着四五个标签页每个平台一套界面、一套计费逻辑、一套调用方式写个小脚本还得在代码里硬编码一堆base_url和api_key改一次配置就得重新翻一遍文档。Octopus 这个项目解决的正是这个痛点——它把自己定位成一个 LLM API 的聚合网关你只需要在它里面配置好各个厂商的渠道对外就暴露一套统一的 OpenAI 兼容接口。任何支持自定义base_url的客户端比如 Chatbox、NextChat、LobeChat、沉浸式翻译甚至你自己写的 Python 脚本都只需要填一个地址、一个 Key剩下的路由、负载均衡、失败重试全部交给 Octopus 处理。那为什么非要部署在 NAS 上我自己的考虑有三点。第一NAS 是 7x24 小时开机的把它当成家里的 AI 网关手机、平板、电脑、电视盒子随时都能连上不用每次开电脑才想起来服务没启动。第二数据不出内网API Key 集中存在自己家里比散落在各个客户端里安全得多尤其是家里有小孩或者多人共用设备的情况。第三NAS 上跑 Docker 太方便了群晖、绿联、飞牛这些系统现在都有图形化的容器管理拉个镜像、映射个端口、挂个配置目录十分钟就能跑起来比在云服务器上还要配安全组、配域名省心。这篇文章我会把整个部署过程拆开讲清楚从 NAS 环境准备、Docker 部署、渠道配置、模型映射到客户端接入和常见坑的排查。不管你是刚入手 NAS 的新手还是已经玩了一段时间 Docker 的老玩家都能照着做下来。核心关键词就几个NAS、Octopus、API、大模型、LLM围绕这几个词把该说的都说透。2. 部署前的整体设计与选型思路2.1 Octopus 到底是个什么东西先把概念理清楚不然后面配置渠道的时候容易懵。Octopus 本质上是一个反向代理 路由分发的服务它自己不产生任何 AI 能力只是站在你和各个大模型厂商之间做中转。你可以把它想象成家里的路由器宽带只有一根但路由器可以分给手机、电脑、电视同时用而且还能根据设备类型分配不同的带宽策略。它对外暴露的接口格式是OpenAI 兼容格式也就是/v1/chat/completions这一套。这是目前事实上的行业标准几乎所有主流客户端都支持。对内它维护着一张渠道表每个渠道包含厂商地址、API Key、支持的模型列表、权重、优先级等信息。当你发来一个请求Octopus 会根据请求里的模型名去匹配对应的渠道然后转发出去拿到结果再原样返回。这个设计带来的好处很直接客户端零改造。你不需要去研究每个厂商的 SDK 差异也不需要为了换模型去改代码只要在 Octopus 后台加一个渠道所有客户端立刻就能用上新模型。2.2 为什么选 Docker 而不是直接装NAS 上部署软件有几种方式套件中心安装、手动编译、Docker。Octopus 官方推荐的就是 Docker我实测下来也确实是最省事的路径原因有几个。依赖隔离。Octopus 是 Go 写的理论上编译出来是个单文件二进制但它依赖数据库默认 SQLite也可以接 MySQL和前端静态资源。直接装在 NAS 系统里万一和系统自带的库版本冲突排查起来非常痛苦。Docker 把这些全打包在镜像里跟宿主机系统完全隔离。升级方便。新版本出来拉新镜像、删旧容器、重新起一个配置目录挂载出来数据不丢。手动安装的话升级还得考虑二进制替换、数据库迁移麻烦得多。迁移成本低。哪天你从群晖换到绿联或者从老电脑 NAS 换到新机器把配置目录拷过去Docker Compose 文件改个路径就能跑几乎零成本。提示如果你的 NAS 是 ARM 架构比如某些瑞芯微芯片的机型拉镜像前一定要确认 Octopus 有没有对应的 arm64 版本否则会报exec format error。x86 机型J4105、N100、3865U 这些基本不用担心。2.3 硬件和系统的最低要求Octopus 本身非常轻量它不做推理只做转发所以对硬件的要求极低。我整理了一个参考表项目最低要求推荐配置说明CPU双核 x86_64四核 N100/J4105转发几乎不吃 CPU内存512MB 可用2GB 可用主要给数据库和并发连接存储1GB10GB日志和数据库会慢慢增长系统支持 Docker 的 Linux群晖 DSM 7.x / 飞牛 / 绿联内核 4.x 以上网络内网可达固定内网 IP建议给 NAS 设静态 IP这里要特别说一下内存。很多人看到转发不吃资源就以为 256MB 够了实际上如果你开了请求日志、并发量又比较大SQLite 写入会占用不少内存。我自己的机器是 J4105 8GBOctopus 容器常驻内存大概在 150MB 到 300MB 之间波动完全无压力。2.4 网络规划端口和访问方式部署前先想清楚两件事容器端口映射到宿主机哪个端口以及怎么访问管理后台。Octopus 默认监听容器内的3000端口。映射到宿主机时我建议避开常用的 80、443、5000群晖 DSM 占用、8080很多 NAS 的 Web 服务占用。我自己用的是33000好记又不容易冲突。访问方式分两种场景。纯内网使用直接http://NAS的IP:33000就行简单直接。需要外网访问这里我不展开讲具体方案只提醒一点——管理后台的登录密码一定要设强密码因为后台能看到你所有的 API Key。如果只是自己家里用内网访问完全够没必要折腾外网暴露。3. 核心细节解析与实操要点3.1 镜像选择与版本策略Octopus 的镜像在 Docker Hub 上有官方仓库标签策略一般是latest加版本号。我的建议是不要用 latest而是锁定一个具体的版本号比如v1.x.x。原因很简单latest 随时可能变某天你重启容器发现行为不一样了排查半天才发现是自动升级了。具体操作上先去项目的 Release 页面看一眼最新稳定版是哪个然后拉对应的 tag。如果你用的是群晖的 Container Manager在映像里搜索的时候可以直接输入完整标签如果用命令行就是docker pull octopus/octopus:v1.x.x注意镜像名和标签以你实际查到的为准不同时期项目可能调整命名。拉之前先在 Docker Hub 搜一下确认。3.2 目录挂载数据持久化的关键容器一删数据就没这是新手最容易踩的坑。Octopus 需要持久化的主要是两块数据库文件和配置文件。默认情况下它用 SQLite数据库文件在容器内的/data目录下。所以启动容器时必须把宿主机的某个目录挂载到/data。我在 NAS 上的做法是在 Docker 共享文件夹下建一个octopus目录里面再分data和logs两个子目录/volume1/docker/octopus/ ├── data/ # 数据库和配置 └── logs/ # 日志可选挂载的时候把/volume1/docker/octopus/data映射到容器内的/data。这样即使你把容器删了重新拉镜像只要这个目录还在所有渠道配置、用户、日志都还在。3.3 环境变量的取舍Octopus 支持通过环境变量覆盖一些默认配置常见的有监听端口、数据库类型、日志级别等。但我的经验是能用后台界面配的就别用环境变量。原因在于环境变量是启动时读取的改了必须重启容器才生效而后台界面改完即时生效还能随时回滚。只有几个场景适合用环境变量一是首次启动时指定数据库连接如果你要用 MySQL 而不是 SQLite二是设置初始管理员账号密码三是调整日志级别做排查。其他像渠道、模型映射这些全部在后台配。3.4 渠道配置的核心逻辑这是整个 Octopus 最核心的部分也是最容易配错的地方。一个渠道代表一个上游厂商的一个接入点包含以下关键字段类型OpenAI、Azure、Anthropic、自定义等决定了请求怎么组装Base URL厂商的接口地址比如 DeepSeek 是https://api.deepseek.comAPI Key你在该厂商申请的密钥模型列表这个渠道支持哪些模型名权重和优先级多个渠道支持同一模型时怎么分配流量这里有个非常重要的概念叫模型映射。举个例子你希望客户端统一用gpt-4o这个名字但实际上后端可能路由到 DeepSeek 或者智谱。这时候就在渠道里配置映射关系把客户端请求的模型名翻译成厂商实际支持的模型名。这样做的好处是客户端配置永远不用改后端换厂商对用户透明。3.5 安全细节Key 的保护API Key 泄露的后果不用我多说轻则被人白嫖额度重则账单爆炸。Octopus 在这方面做了几件事后台登录需要密码、Key 在数据库里是加密存储的、对外接口需要单独的访问令牌。但你自己也要注意几点第一管理后台不要暴露到公网内网用就内网用。第二给客户端分发的令牌要单独生成不要直接用后台管理员密码。第三定期轮换上游 Key尤其是发现某个渠道调用量异常的时候。第四日志里不要打印完整 KeyOctopus 默认会脱敏但你自己写脚本调用的时候要注意。4. 实操过程与核心环节实现4.1 第一步确认 NAS 的 Docker 环境不同 NAS 系统检查方式略有差异但核心就一条能不能正常跑容器。群晖 DSM 7.x 的话去套件中心确认 Container Manager 已安装并启动。绿联和飞牛一般自带 Docker 管理界面。老电脑自己装的系统命令行执行docker version docker compose version两条命令都能正常输出版本号说明环境 OK。如果docker compose报错可能是只装了 docker 没装 compose 插件需要单独补一下。提示有些 NAS 的 Docker 默认存储位置在系统盘容器多了容易把系统盘撑满。建议在 Docker 设置里把存储位置改到大容量数据盘。4.2 第二步创建目录结构SSH 登录 NAS或者用文件管理器图形化操作都行。我习惯用命令行一条命令搞定mkdir -p /volume1/docker/octopus/data mkdir -p /volume1/docker/octopus/logs注意路径要换成你自己 NAS 的实际路径。群晖一般是/volume1/绿联可能是/mnt/或者别的飞牛也有自己的约定。不确定的话在 Docker 管理界面里看一下现有容器的挂载路径就知道了。创建完之后确认一下权限。如果 Docker 以非 root 用户运行要保证这个目录对该用户可读写chmod -R 755 /volume1/docker/octopus4.3 第三步编写 Docker Compose 文件我强烈建议用 Compose 而不是docker run因为配置写在文件里下次迁移或者重建直接复用不用回忆当初敲了什么参数。在/volume1/docker/octopus/下建一个docker-compose.ymlversion: 3.8 services: octopus: image: octopus/octopus:v1.x.x container_name: octopus restart: unless-stopped ports: - 33000:3000 volumes: - /volume1/docker/octopus/data:/data - /volume1/docker/octopus/logs:/app/logs environment: - TZAsia/Shanghai - LOG_LEVELinfo healthcheck: test: [CMD, wget, -q, --spider, http://localhost:3000/health] interval: 30s timeout: 5s retries: 3几个参数解释一下。restart: unless-stopped保证 NAS 重启后容器自动起来除非你手动停过。TZ设成上海时区不然日志时间对不上排查问题的时候很抓狂。healthcheck是可选的但加上之后 Docker 能自动检测服务是否健康配合一些监控工具很好用。镜像标签记得换成你实际确认过的版本号。路径也要换成你自己的。4.4 第四步启动并验证在 compose 文件所在目录执行docker compose up -d-d是后台运行。执行完看一下状态docker compose ps如果 STATUS 显示Up或者healthy说明起来了。再看一眼日志确认没有报错docker compose logs -f --tail50日志里出现类似 server started on :3000 的字样就对了。然后浏览器打开http://NAS的IP:33000应该能看到登录界面。注意如果打不开先检查防火墙。群晖的 DSM 防火墙默认可能拦截非标准端口需要在安全性-防火墙里放行 33000。另外确认一下 NAS 的 IP 没变建议在路由器里给 NAS 绑定静态 IP 或者 DHCP 保留。4.5 第五步初始化管理员账号首次访问会引导你创建管理员账号。密码一定要设复杂一点至少 12 位大小写加数字加符号。这个账号能看所有 API Key价值很高。创建完之后登录进去先别急着加渠道去设置里把这几项确认一下站点名称随便填、日志保留天数建议 7 到 30 天太长占空间、是否允许注册自己用就关掉。4.6 第六步配置第一个渠道以 DeepSeek 为例走一遍完整流程。在后台找到渠道菜单点新增渠道名称DeepSeek 官方渠道类型OpenAI因为 DeepSeek 兼容 OpenAI 格式Base URLhttps://api.deepseek.comAPI Key粘贴你申请的 Key模型手动填入deepseek-chat、deepseek-reasoner保存之后Octopus 一般会自动测试连通性。如果显示绿色或者已启用说明通了。如果报错先检查 Key 有没有多余空格再检查 Base URL 有没有写错有些厂商要带/v1有些不带看文档。4.7 第七步配置模型映射和负载均衡假设你现在有两个渠道都支持deepseek-chat一个是官方一个是某个第三方中转。你希望优先用官方官方挂了自动切到中转。这时候就在两个渠道上都填deepseek-chat然后设置优先级官方设 10中转设 5。Octopus 会优先走优先级高的失败后自动降级。如果你希望两个渠道轮流分担流量那就把权重设成一样比如都是 1它会按权重随机分配。这个功能在某个渠道有速率限制的时候特别有用。模型映射的配置在渠道详情里格式一般是客户端模型名:上游模型名。比如你想让客户端统一请求gpt-4o实际路由到 DeepSeek就填gpt-4o:deepseek-chat。这样客户端那边完全感知不到后端换厂商了。4.8 第八步生成访问令牌并接入客户端渠道配好之后去令牌菜单生成一个访问令牌。这个令牌是给客户端用的跟上游 API Key 是两回事。生成的时候可以设置额度限制、过期时间、允许的模型范围建议按客户端分别生成方便追踪用量。以 Chatbox 为例接入步骤是设置里选自定义 OpenAI 兼容API 地址填http://NAS的IP:33000/v1API Key 填刚才生成的令牌模型名填你在映射里配的那个比如gpt-4o。保存之后发一条消息测试能正常回复就成功了。LobeChat、NextChat、沉浸式翻译这些客户端的配置逻辑完全一样都是填 base_url 和 key区别只在界面位置。这就是统一网关的价值——配一次处处能用。5. 常见问题与排查技巧实录5.1 容器起不来或者反复重启这是最常见的问题排查顺序如下。先看日志docker compose logs --tail100 octopus如果日志里报permission denied基本是挂载目录权限问题执行chmod -R 777临时验证一下生产环境别用 777确认后改回 755。如果报database is locked说明 SQLite 文件被占用可能是上次容器没正常退出删掉data目录下的.db-wal和.db-shm文件再重启。如果报exec format error就是架构不匹配换对应架构的镜像。5.2 渠道测试失败但 Key 明明是对的这种情况我遇到过好几次原因五花八门。整理成表格方便对照现象可能原因解决方法401 UnauthorizedKey 错误或过期重新复制注意首尾空格404 Not FoundBase URL 路径不对确认是否要加/v1403 ForbiddenIP 被限制或额度耗尽登录厂商后台查看超时NAS 出网有问题容器内ping测试模型不存在模型名写错对照厂商文档核对其中超时最容易被忽略。NAS 如果配了特殊的 DNS 或者网关容器可能出不了网。进容器测试docker exec -it octopus sh wget -qO- https://api.deepseek.com能返回内容说明网络通返回不了就是网络问题检查 NAS 的 DNS 设置。5.3 客户端能连上但回复很慢先区分是网络慢还是上游慢。在 Octopus 的日志里看请求耗时如果 Octopus 到上游的耗时就很长那是厂商的问题换渠道或者换时段。如果 Octopus 处理很快但客户端收到慢那可能是客户端本身的问题或者 NAS 到客户端的网络有问题。还有一个容易被忽略的点流式输出。有些客户端默认开流式如果 Octopus 的某个渠道不支持流式就会卡住。检查渠道配置里有没有开流式支持没有的话在客户端关掉流式试试。5.4 多个渠道同名模型怎么排查走了哪个Octopus 的日志里一般会记录实际命中的渠道。如果日志不够详细可以临时把某个渠道禁用看请求是否还能成功以此判断路由。更规范的做法是给每个渠道配不同的标签然后在日志里按标签过滤。5.5 数据库越来越大怎么办SQLite 用久了会膨胀尤其是开了详细日志的情况下。两个办法一是定期在后台清理日志设置里可以配自动清理二是直接对数据库做 vacuum。进容器执行docker exec -it octopus sh # 找到数据库文件位置一般在 /data 下不过更省事的做法是一开始就用 MySQL。如果你 NAS 上已经跑了 MySQL绿联、群晖都能装把 Octopus 的数据库指向 MySQL性能和可维护性都好很多。配置方式是在环境变量里指定数据库连接串具体格式看项目文档。5.6 我踩过的几个坑第一个坑是时区。刚开始没设TZ日志时间全是 UTC排查问题的时候对不上本地时间白白多花了半小时。第二个坑是端口冲突33000 一开始被我另一个服务占了容器起来但访问不了后来换成 33001 才好。第三个坑是Key 里的空格从网页复制的时候经常带一个尾随空格肉眼看不出来粘贴进去就报 401后来养成习惯先粘到记事本里看一眼。还有一个不算坑但值得说的别把所有渠道都设成同一个优先级。我有次配了三个渠道全是默认优先级结果请求随机分配某个不稳定的渠道时不时超时体验很差。后来把稳定的设高优先级不稳定的设低问题就没了。6. 进阶玩法与后续扩展6.1 接入本地 Ollama 做兜底如果你 NAS 性能还行或者有另一台机器跑着 Ollama可以把本地模型也配成一个渠道。好处是当所有云端渠道都挂了或者额度用完的时候本地模型能兜底虽然慢一点但至少能用。配置的时候类型选 OpenAI 兼容Base URL 填 Ollama 的地址加/v1模型名填你本地拉下来的模型。6.2 用量统计和成本控制Octopus 后台一般有用量统计功能能看到每个令牌、每个渠道的调用次数和 token 消耗。结合各厂商的计费单价可以大致算出成本。我的做法是给每个家庭成员或者每个用途单独生成令牌月底一看就知道谁用得多。如果某个令牌用量异常直接禁用不影响其他人。6.3 配合自动化脚本因为 Octopus 暴露的是标准 OpenAI 接口你现有的任何调用 OpenAI 的脚本只需要改base_url和api_key两行就能用上所有后端模型。比如你有个批量处理文档的 Python 脚本原来写死了 OpenAI现在改成from openai import OpenAI client OpenAI( base_urlhttp://NAS的IP:33000/v1, api_key你在Octopus生成的令牌 ) response client.chat.completions.create( modelgpt-4o, # 实际路由到哪个后端由Octopus决定 messages[{role: user, content: 你好}] )这样后端换模型、加渠道脚本完全不用动。对于经常做实验、对比不同模型效果的人来说这个价值非常大。6.4 备份策略配置目录一定要纳入 NAS 的备份计划。群晖用 Hyper Backup绿联和飞牛也有各自的备份工具。备份频率看你的配置变动频率我是一周一次保留最近 4 个版本。备份的时候注意如果 Octopus 正在运行SQLite 文件可能处于写入状态最好先停容器再备份或者用数据库自带的备份命令导出。6.5 什么时候该考虑换 MySQLSQLite 在单用户、低并发场景下完全够用。但如果你满足以下任意一条就该考虑换 MySQL 了并发请求经常超过 20、日志保留超过 30 天、数据库文件超过 500MB、或者你打算多人共用。换的过程不复杂导出 SQLite 数据、导入 MySQL、改环境变量重启具体步骤项目文档里有照着做就行。整套折腾下来最大的感受是统一入口这件事本身就值回票价。以前每加一个新模型就要在四五个客户端里各配一遍现在只在 Octopus 里加一个渠道所有客户端立刻可用。NAS 常年开机这个特性又让这个网关随时在线手机在外面也能连回家里用。如果你手里也有 NAS又正好在玩各种大模型这套方案值得花一个周末搭起来。