绿联NAS部署One API：用Docker搭建大模型统一网关

1. 为什么要把 One API 部署在绿联 NAS 上

1.1 我先说清楚 One API 到底解决了什么问题

这两年大模型服务越来越多，OpenAI、Claude、Gemini、国内各家国产模型数都数不过来。我自己的使用场景就很典型：写脚本要用 GPT-4o，做长文本总结想试 Claude，偶尔还得调用国内模型的接口做备案合规的项目。每个服务都有独立的 Key、独立的 Base URL、独立的计费方式，代码里到处是不同厂商的 SDK，切模型就跟换手机卡一样麻烦。

后来我接触到 One API 这个开源项目，相当于把所有大模型渠道收编到一个网关后面。你只需要维护一套 API Key，所有下游应用都指向 One API 的统一地址，由它负责把请求转发到真正的模型服务商。这样做的好处不只是少记几个 Key，更关键的是可以在一个面板里统一查看所有渠道的调用量、余额消耗、错误日志，还能给不同的同事或项目分配独立的令牌和额度。

但问题来了，One API 是个常驻服务，不能老挂在个人电脑上，关机就断。我一开始想租一台云服务器，后来一算账，一年下来费用不少，而且数据都在别人机器上，心里总觉得不踏实。正好家里有一台绿联 NAS 常年开着，24 小时在线、功耗又低，直接在上面用 Docker 部署一个 One API 容器，既省了云服务器费用，数据也完全在自己手里。绿联 NAS 的 Docker 功能做得比较完善，图形界面和命令行都能操作，对没有专门服务器的小团队或者个人开发者来说，这是性价比非常高的方案。

1.2 绿联 NAS 跑 One API 的优势

绿联 NAS 用的是 UGOS Pro 系统，自带 Docker 应用中心，不需要自己折腾底层系统。相比群晖或者飞牛，绿联的 Docker 管理界面更接近常规的容器管理工具，有镜像仓库、容器列表、日志查看、端口映射设置这些基础功能，新手也能比较快上手。

从硬件条件来说，One API 是一个轻量级的 Go 或 Node 服务，内存占用通常在几十 MB 到一两百 MB 左右，对 NAS 的 CPU 和内存压力很小。绿联的几款主流机型，哪怕是双盘位入门款，跑这个服务都绰绰有余。我自己的机器上除了 One API 还跑了 Jellyfin、qbittorrent、Home Assistant 这些容器，One API 长期运行下来几乎没有影响 NAS 的整体负载。

从使用场景来说，内网部署还有一个天然优势：下行带宽不受公网限制。如果你的下游应用也在家里或者办公室内网，比如用 Ollama 做本地推理再配合 One API 做统一出口，延迟极低。就算要公网访问，只要做好反向代理和 HTTPS，也能实现随时随地调用。

1.3 部署前的方案选型思考

在正式动手之前，有几个决策点想清楚，后面会少踩很多坑：

第一是数据存储方式。One API 默认支持 SQLite 和 MySQL 两种后端。SQLite 适合单机小规模使用，文件即数据库，备份就是拷贝一个文件，对 NAS 场景来说非常友好。MySQL 适合多实例或大规模高并发场景，但对个人或小团队来说反而增加运维负担。我强烈建议用默认的 SQLite，配合定时备份文件就足够了。

第二是版本选择。One API 的官方镜像经历了仓库迁移，老用户可能记得 justsong/one-api 这个镜像名，现在维护地址已经迁移到 songquanpeng/one-api。镜像名不一样，但功能和数据格式基本延续。部署的时候直接用新地址，避免看着旧教程敲错镜像名。

第三是端口规划。One API 默认监听 3000 端口，但 NAS 上很多应用都喜欢抢端口。我自己就遇到过 3000 被 Grafana 占掉的情况。所以部署前最好先规划好端口映射，比如宿主机 3000 被占就映射成 13000。这个思路同样适用于后续各种容器部署。

这些决策确定了，整个部署过程就会非常顺。下面我按实际操作的顺序，把每一步都拆开讲。

2. 部署前置准备：绿联 NAS 环境与 One API 镜像选型

2.1 绿联 NAS 的 Docker 环境确认

绿联目前的系统版本基本都内置了 Docker，不需要额外安装。在桌面或者应用列表里找到 Docker 图标，点进去确认版本信息。如果找不到，可以去应用中心搜索安装，一般两三分钟就能装好。

装好 Docker 之后，我建议顺手开启 SSH 功能。虽然图形界面可以完成大部分容器操作，但后面查日志、进容器内部看配置、手动执行一些命令，SSH 会方便很多。绿联在控制面板的终端设置里可以开启 SSH，默认端口 22，开启后用自己的 NAS 账号密码就能登录。这里有个安全提醒：如果 NAS 暴露在公网，SSH 端口最好改掉，或者只允许内网访问。

确认 Docker 环境的时候，顺手看一下存储空间的目录结构。绿联的共享文件夹通常挂载在 /volume1 下，你的 Docker 数据目录最好放在一个专门的共享文件夹里，比如 /volume1/docker。这样后续做备份、迁移都清晰明了，不会出现数据散落在系统盘的情况。

2.2 镜像选型与数据目录规划

One API 的镜像有几个标签可以选择，我最常用的是 latest 和带具体版本号的标签。对于生产环境，按理说应该锁定版本号避免意外升级，但 One API 输出更新比较频繁，功能迭代快，我个人在 NAS 这种非关键环境直接用 latest，图省事。如果你比较谨慎，可以用 docker image inspect 查看镜像的创建时间，再决定是否使用最新版。

数据目录规划方面，我建议在 /volume1/docker 下单独建一个 one-api 文件夹，里面再分 data 子目录。One API 会把 SQLite 数据库文件、日志等写入数据目录，宿主机上做好目录映射后，即使容器被删除重建，数据也不会丢。

具体命令就是在 SSH 终端里执行：

bash复制mkdir -p /volume1/docker/one-api/data

这里要注意目录权限。绿联的共享文件夹默认权限可能不允许 Docker 容器写入，如果后面启动容器后发现数据库创建失败，多半就是权限问题。最简单的处理方式是在图形界面右键文件夹设置权限，或者在终端执行 chmod 命令调整。

2.3 端口规划与初步参数确定

前面提到 One API 默认端口是 3000，我们需要把它映射到宿主机上一个空闲端口。怎么判断端口是否被占用？在 SSH 终端执行：

bash复制netstat -tlnp | grep 3000

如果没有任何输出，说明 3000 空闲，可以直接用。如果有输出，就换一个端口，比如 13000、15000 这类不常用端口。端口映射的原则是容器内端口保持不变，宿主机端口按需调整。所以无论宿主机用哪个端口，容器内始终监听 3000。

除了端口，还有几个环境变量值得提前想清楚：

• TZ 时区变量，设置为 Asia/Shanghai，保证日志时间和我们一致。
• SESSION_SECRET 会话密钥，如果不设置，One API 会随机生成一个，但每次重启容器都可能变化，导致登录态失效。建议手动指定一个随机字符串。
• SQLITE_PATH 可以指定 SQLite 文件路径，默认在数据目录下会自动创建，一般不用改。

这些参数会在 docker-compose 文件里统一配置。比一个个敲 docker run 命令要清晰得多，出错也容易排查。

3. 实操部署全流程：从拉镜像到第一次跑通

3.1 用 Docker Compose 一键部署

绿联 NAS 的 Docker 图形界面虽然能用，但配置环境变量和多个端口映射的时候比较繁琐，容易漏项。我更推荐在 SSH 终端里用 docker-compose 的方式部署，一个 YAML 文件把容器配置固化下来，后续升级、重建都只需要基于同一份配置操作。

首先进入 one-api 目录，创建一个 docker-compose.yml 文件：

bash复制cd /volume1/docker/one-api
vi docker-compose.yml

文件内容如下，我解释一下每项配置的作用：

yaml复制version: '3.4'

services:
  one-api:
    image: songquanpeng/one-api:latest
    container_name: one-api
    restart: always
    ports:
      - "13000:3000"
    volumes:
      - ./data:/data
    environment:
      - TZ=Asia/Shanghai
      - SESSION_SECRET=请替换成一串随机字符

端口映射我把宿主机端口改成了 13000，避免和 NAS 上其他服务冲突。数据目录映射到当前目录下的 data 文件夹，也就是 /volume1/docker/one-api/data。容器重启策略设为 always，这样 NAS 重启或者容器意外退出后，Docker 会自动把它拉起来，不需要手动干预。

写好之后执行：

bash复制docker-compose up -d

第一次运行会自动拉取镜像，需要一点时间。拉取完成后，执行 docker ps 看一下容器状态，确认 STATUS 是 Up，端口映射正常。然后就可以通过浏览器访问 http://NAS的IP:13000 登录 One API 管理面板了。

3.2 首次登录与必要配置

One API 首次访问会进入初始化页面，默认管理员账号是 root，默认密码是 123456。这个默认密码是老外开源项目的常见套路，但安全性很差，登录后第一件事就是改密码。

登录之后，我建议按顺序做几件事：

第一，修改管理员密码。在用户管理或个人设置里找到修改密码入口，换成自己的强密码。顺便把登录用户名如果不需要 root 这个名字，也可以新建一个管理员账号再删掉旧的。

第二，检查系统设置里的基础配置。One API 有些选项会影响后续功能，比如“允许用户注册”这个开关，如果你的 NAS 服务只给自己用，建议关闭，避免被别人注册账号蹭额度。还有“令牌有效期”之类的参数，根据自己需求调整。

第三，确认数据库文件已经正常生成。在 SSH 终端里回到 /volume1/docker/one-api/data 目录，执行 ls 查看，正常情况下能看到 SQLite 数据库文件和日志文件。这一步是为了确认容器对该目录有写权限，为后续数据安全打底。

3.3 接入第一个大模型渠道：以 OpenAI 兼容接口为例

One API 最核心的概念是“渠道”。一个渠道代表一个大模型服务的接入配置，包括渠道类型、API 地址、密钥、支持的模型列表等。接入渠道后，One API 才能把请求转发到对应的服务商。

在管理面板左侧菜单点击“渠道”，然后选择“添加渠道”。渠道类型下拉框里有非常多选项，OpenAI、Anthropic、Google Gemini、国产各家模型都有内置模板。目前 OpenAI 兼容接口基本成了行业标准，连很多国产服务商都提供 OpenAI 兼容的调用方式，所以我就以“OpenAI”渠道类型为例演示。

填写渠道配置的时候，有几个关键字段：

• 名称：自己看得懂就行，比如 gpt4o-prod。
• 代理地址：也就是服务商的 Base URL。如果直接用 OpenAI 官方接口，留空即可；如果用某个中转服务或云厂商的兼容端点，就填完整地址。
• API Key：服务商给你的密钥。
• 模型列表：指定这个渠道可以处理哪些模型，多个模型用逗号分隔。这里有一个容易搞混的点：填写的模型名是“实际请求的模型名”，也就是下游应用请求时用到的名字，One API 会按这个名字匹配渠道。

配置完成后点击提交，然后在渠道列表里点击“测试”，One API 会向服务商发一个测试请求。如果测试通过，说明渠道接入成功。

我第一次部署的时候在模型列表这一栏纠结了很久。后来搞清楚了，模型列表就是告诉 One API：当客户端请求这些模型时，可以走这个渠道。如果某个渠道只支持部分模型，就只填那些模型名。多个渠道可以配置相同的模型名，One API 会自动负载均衡，甚至可以根据渠道的优先级进行故障转移。

3.4 创建令牌并使用工具完成一次真实调用

渠道配置好之后，接下来要创建“令牌”。令牌是下游应用真正使用的 API Key，它屏蔽了底层渠道的密钥信息。

在管理面板左侧点击“令牌”，选择“添加令牌”。这里可以设置令牌名称、过期时间、额度限制等。如果只是自己用，可以不做限制；如果要分给同事或者不同项目，建议每个用途生成一个独立令牌，并设置相应额度，方便后续审计和管控。

创建令牌后，会得到一个形如 sk-xxxx 的令牌字符串，注意这个字符串只在创建时完整显示一次，之后在列表里只会显示掩码。所以创建完马上复制保存。

接下来是验证环节。我习惯用 curl 测一下整个链路是否打通：

bash复制curl http://NAS的IP:13000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好，请用一句话介绍你自己"}]
  }'

正常的话，会返回一段 JSON 格式的响应，里面包含模型的回复内容。这一步验证通过，说明 One API 已经成功接管了请求转发，下游只需要记住统一地址 http://NAS的IP:13000 和一个令牌即可。

拿到统一接口之后，很多第三方客户端都能直接接入了。比如 ChatBox、OpenCat、LobeChat 这类应用，配置的时候 API 地址填 One API 的地址，密钥填令牌，模型名填渠道里配置的模型名，就能把所有模型切换操作收归到一个面板里。我的所有个人项目现在都是这套玩法，代码里只写 One API 的地址，换模型只需要改请求里的 model 字段，不用再动 SDK 配置。

4. 进阶玩法：把 One API 用得更顺手

4.1 接入本地 Ollama 等私有模型

One API 对接云厂商模型只是基本功，它还能把本地部署的私有模型也挂进来统一管理。我自己在 NAS 上跑了一台 Ollama，部署了 qwen2.5 之类的开源模型，配合 One API 就能实现云厂商和本地模型在同一套接口下的无缝切换。

Ollama 从 0.1.x 版本开始提供 OpenAI 兼容接口，默认监听 11434 端口。在 One API 中添加渠道时，渠道类型可以选择“Ollama”，然后填写代理地址为 http://NAS的IP:11434，API Key 可以随便填一个占位符因为 Ollama 本地不校验密钥，模型列表填你本地拉取的模型名。

这样配置之后，下游应用的调用逻辑就统一了：业务高峰期用云端模型，预算敏感场景切到本地模型，代码里只改 model 字段。尤其是家里网络不稳定或者想控制成本的时候，本地模型兜底很实用。我甚至见过有人用 One API 的“模型重定向”功能，把请求中的 gpt-4o 自动映射到本地 qwen2.5，对业务代码完全透明。

4.2 模型重定向、分组与配额管理

One API 的“模型重定向”是个很有意思的功能。简单说，它允许你把一个模型名映射到另一个模型名。比如你代码里写死了 gpt-4o，但某天你发现某个国产模型效果差不多且价格便宜很多，就可以在不需要改代码的情况下，设置 gpt-4o 重定向到 qwen-max。

这个功能操作路径在“模型重定向”菜单里，填入来源模型名和目标模型名即可。需要注意目标模型名必须是某个渠道里已经配置的模型，否则会找不到渠道。

分组和配额管理也是 One API 的优势。你可以在“分组”里创建不同小组，比如 group-a、group-b，然后把不同令牌归属到不同分组。结合渠道的分组属性，就能实现精细化管控。举个例子，给测试环境用的令牌只允许访问便宜的模型，生产环境令牌可以访问全量模型。这在多租户场景下非常有用。

配额管理方面，One API 会根据渠道返回的 Token 使用量自动扣费。给同事发令牌的时候可以设置额度上限，防止有人把额度用完影响其他人。日志页面会记录每一次请求的明细，包括模型、Token 数、耗时和状态码，排查问题很方便。

4.3 备份、升级与迁移

NAS 上的数据，任何服务都得考虑备份问题。One API 的所有核心数据都存在 SQLite 文件里，备份就是把整个 data 目录打包拷贝。我个人的做法是每周定时把 /volume1/docker/one-api/data 目录同步到一块独立磁盘，再加一份到云盘做异地容灾。One API 数据更新频繁，做得勤快一点总没坏处。

升级方面，由于我们用的是 docker-compose 管理，操作非常方便：

bash复制docker-compose pull
docker-compose up -d

系统会自动拉取新的 latest 镜像、删除旧容器、基于同一份数据目录重建新容器。因为数据目录单独映射，升级不会影响已有配置。不过升级前还是建议先备份 data 目录，万一新版本有兼容性问题还能快速回滚。回滚的方法就是对 docker-compose.yml 里的 image 标签指定旧版本号，再重新 up 一遍。

迁移场景也顺便提一下。如果你之后想从绿联 NAS 换到群晖、飞牛或者其他设备，只需要在目标机器上装好 Docker，把 data 目录拷贝过去，再跑一份相同的 docker-compose.yml 即可。因为整个服务都是容器化的，迁移成本几乎为零。

5. 常见问题与排查技巧实录

5.1 容器起不来或一直重启

这种情况我在部署过程中遇到过，仔细排查后绝大部分是数据目录权限或端口冲突导致的。容器起不来的话，第一步看日志：

bash复制docker logs one-api

如果日志里有类似 permission denied 的提示，基本就是 data 目录的写权限问题。在绿联上，共享文件夹默认权限可能比较严格，需要在终端执行 chmod 修改，比如 chmod 755 /volume1/docker/one-api/data。也可以去图形界面的文件夹权限设置里，把 Everyone 的写入权限打开，简单粗暴但有效。

如果是端口已被占用，日志里一般会有 bind: address already in use 的信息。这时候改宿主机端口映射即可，容器内端口不用动。

5.2 渠道测试失败类问题

渠道测试失败是最常见的故障场景，一般集中在三个地方：

第一是 API Key 错误或过期。这个没什么好说的，去服务商后台重新生成一个，确认粘贴的时候没有多余空格。

第二是代理地址不对。如果用的是 OpenAI 官方接口，代理地址留空；如果用中转服务，地址要填完整，注意有没有 http:// 前缀和路径。很多中转商会在文档里写清楚 Base URL，照着填就行。

第三是网络问题。如果服务商接口需要走代理才能访问，而 NAS 没有配置相应的代理，请求就会超时。One API 在环境变量里可以配置代理，但我个人建议这种情况直接通过 DNS 解析层解决，或者选择国内可直连的服务商，省心很多。

我整理了一张排查速查表，方便对照解决：

5.3 访问与权限类问题

部署完成后，如果局域网内其他设备访问不到 One API 面板，先检查绿联的防火墙设置。绿联控制面板里的安全设置可能默认拦截了部分端口，需要把映射出去的端口加入白名单。另外，如果开启了 Docker 网络隔离，也要确认端口映射正确发布到宿主机网卡上。

还有一个容易忽略的问题：绿联系统升级后偶尔会重置防火墙规则或 Docker 网络配置。遇到"之前能用突然不能用了"的情况，优先检查这两个地方。

权限方面，如果下游应用调用时报 403 Forbidden，很有可能是 One API 的令牌没有启用，或者令牌过期了。去令牌列表看看状态，重新生成一个测试令牌就能定位问题。另外，也有可能是你用了错误的密钥字段，One API 的令牌要求放在 Authorization 头里，用 Bearer 前缀。

踩过几次坑之后，我现在的习惯是：每次部署完先不急着接业务，花五分钟用 curl 把渠道测试、令牌调用、日志查看这三个环节都走一遍，确认链路完整再交付使用。这个习惯帮我省了很多后面排查的时间。

6. 写在最后的实操心得

我在绿联 NAS 上部署 One API 已经跑了几个月，整体非常稳定。期间经历过几次 NAS 系统版本升级、容器重启，One API 都能通过 restart 策略自动恢复，数据也没有丢过。对一个指望它做统一 API 网关的服务来说，这个稳定性已经超出我的预期。

如果你也是一个人或者小团队用大模型，手头又正好有一台常开的 NAS，我真心建议花半小时把 One API 部署起来。先接一个最常用的模型跑通流程，再逐步把其他渠道加进去，你会发现管理大模型这件事瞬间清爽很多。最后再分享一个小技巧：记得给 data 目录做一个每日自动备份任务，哪怕只是一条 crontab 命令，也比出了问题再想办法强得多。