离线部署OneAPI住宅无网络服务器教程

理解离线场景：为什么要在无网络的服务器上装 OneAPI？

OneAPI 是一款用于聚合和管理多种 AI API（如 OpenAI、Claude 等）的开源工具，通常部署在有公网或内网访问的服务器上。
如果你的住宅服务器无法连接互联网（比如仅通过局域网使用），就需要提前下载好所有依赖文件，再通过 U 盘等介质传输过去。
本文会一步一步教你完成这个流程，即使你不懂 Linux，也能照着做。

准备工作：硬件、软件和要下载的文件清单

在执行操作前，请确认你手头有以下东西：

1. 一台能联网的电脑（用来下载 OneAPI 的安装包）
2. 一个足够大的 U 盘（建议 2GB 以上，用于存放镜像或二进制文件）
3. 住宅服务器已安装 Docker（如果没有，需要先离线安装 Docker，步骤本文暂不展开，可参考站内另一篇 Docker 离线安装教程）
4. 服务器开放的端口（OneAPI 默认使用 3000 端口，请确保防火墙允许，或者在启动时修改）
5. 准备好 SSH 工具（如 PuTTY 或直接使用服务器本地终端）

你需要下载的关键文件：

• OneAPI 的 Docker 镜像：推荐使用官方镜像 ghcr.io/songquanpeng/one-api:latest。
• 或二进制文件：如果不想用 Docker，也可以从 GitHub Releases 下载对应架构的二进制文件和前端资源。
• SQLite 数据库：OneAPI 自带了嵌入式数据库，无需额外安装；但如果想用 MySQL 或 PostgreSQL，需要提前下载驱动。

分步操作：从下载到启动的全过程

第一步：在联网电脑上下载并保存 Docker 镜像

打开你联网电脑的终端（Windows 可以用 PowerShell 或 CMD），执行以下命令拉取镜像并保存为 tar 文件：

docker pull ghcr.io/songquanpeng/one-api:latest
docker save -o one-api.tar ghcr.io/songquanpeng/one-api:latest

执行完毕后，当前目录下会生成一个 one-api.tar 文件。
把它复制到 U 盘里。

第二步：将镜像传输到无网络服务器

将 U 盘插入住宅服务器，把 one-api.tar 拷贝到服务器的某个目录，比如 /opt/one-api/：

mkdir -p /opt/one-api
cp /mnt/usb/one-api.tar /opt/one-api/

注意：请根据你服务器的实际挂载路径调整 /mnt/usb。也可以使用 scp 命令从局域网其他电脑传输。

第三步：加载镜像并启动容器

进入文件目录，加载镜像：

cd /opt/one-api
docker load -i one-api.tar

加载成功后，确认镜像已出现：

docker images | grep one-api

然后启动容器：

docker run -d --restart=always --name one-api -p 3000:3000 ghcr.io/songquanpeng/one-api:latest

-d 表示后台运行，--restart=always 保证服务器重启后容器自动启动，-p 3000:3000 将容器内 3000 端口映射到宿主机。

第四步：检查容器是否正常运行

docker ps -a | grep one-api

如果状态是 Up 就说明启动成功了。
如果需要查看启动日志：

docker logs one-api

避坑指南：常见问题与解决办法

• 端口已被占用：如果你服务器上已经有其他服务占用 3000 端口，启动时会报错。可以修改映射端口，比如 -p 3001:3000，然后通过 http://服务器IP:3001 访问。
• 默认管理员账户：OneAPI 首次访问时的默认账号是 root，密码 123456。请登录后立即修改。
• 数据库文件权限：OneAPI 默认使用 SQLite 数据库文件 data.db，如果容器启动后频繁报错，可能是 /opt/one-api/data.db 的权限不对，可以进入容器检查或删除旧数据库重新生成。
• 镜像架构不匹配：如果你的住宅服务器是 ARM 架构（如树莓派），记得下载 ARM64 版本的镜像。拉取时可以用 arm64v8 标签，或者直接从 releases 下载对应二进制。

效果验证：确认 OneAPI 已可用

在浏览器地址栏输入：http://你服务器的IP:3000。
如果看到 OneAPI 的登录页面，说明部署成功。

登录后，你可以添加一个测试渠道（例如本地自建的 API 或其他能访问的 AI 接口），然后创建一个令牌，用 curl 测试一下：

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的令牌" \
  -d '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello"}]}'

如果返回了正常的 JSON 响应，说明整个离线部署流程完全走通了。

常见问题（FAQ）

Q：我服务器没有安装 Docker，能不能直接用二进制文件？
A：可以。去 GitHub Releases 下载对应系统和架构的二进制压缩包，解压后执行 ./one-api 即可启动。但需要提前安装可执行依赖（例如 glibc 版本），离线环境可能比较麻烦。建议还是优先用 Docker，只需准备一个 Docker 离线安装包即可。

Q：我可以在本地电脑和服务器之间用网线直连传输文件吗？
A：可以。设置固定 IP 后，使用 scp 或 rsync 传输。但注意网线直连需要两台设备在同一网段。

如果你正在处理离线部署 OneAPI 住宅无网络服务器的场景，建议先按照本文的步骤完整执行一遍，再根据自己的环境做微调；
遇到异常时优先回看避坑和高频问题部分。