离线部署OneAPI无网络家用住宅服务器完整流程

如果你的家用住宅服务器没有稳定的互联网连接，但又想运行 OneAPI（一个用于统一管理多种 AI API 密钥的开源工具），离线部署是最好的选择。
本文按零基础可执行的方式，把整个流程拆成四步：准备离线文件、上传到服务器、完成安装、验证并排查常见问题。

1. 离线环境下的准备工作

部署前先确定 OneAPI 的安装方式。
推荐使用 Docker 容器，因为它的依赖打包最干净；
也可以用二进制文件直接运行。
你需要在一台能联网的电脑上提前下载好以下资源：

• Docker 离线安装包：去 Docker 官方 GitHub Release 页面 下载对应 CPU 架构（通常是 amd64）的 docker-*.tgz 文件。
• OneAPI 的 Docker 镜像：在能联网的电脑上执行 docker pull justsong/one-api 拉取最新镜像，然后用 docker save -o one-api.tar justsong/one-api 导出成 .tar 文件。
• 依赖工具：如果不用 Docker，也可从 OneAPI 的 GitHub Release 页下载 one-api 二进制文件（Linux amd64 版本）和 one-api.db（空数据库模板）。

将上述文件通过 U 盘、内网 scp 或直接拷贝到家用服务器的任意目录，例如 /tmp/offline/。

2. 在无网络服务器上安装 Docker（离线方式）

如果你已有 Docker 或想直接用二进制，可跳过这一步。
否则按以下命令安装离线 Docker：

# 解压下载的 docker-*.tgz
sudo tar -xzvf /tmp/offline/docker-*.tgz -C /usr/local/bin/

# 创建 docker 用户组并添加当前用户（避免每次 sudo）
sudo groupadd docker
sudo usermod -aG docker $USER

# 启动 dockerd 守护进程（建议使用 systemd 管理，这里先手动启动验证）
sudo dockerd &

运行 docker version 查看 Client 和 Server 版本，如果都显示正常说明 Docker 安装成功。
注意因为是离线环境，启动 dockerd 时可能会提示无法连接官方仓库，但不影响本地镜像的使用。

3. 导入 OneAPI 镜像并创建容器

将之前导出的 one-api.tar 上传到服务器，执行：

# 导入镜像
docker load -i /tmp/offline/one-api.tar

# 查看镜像是否导入成功
docker images | grep one-api

然后创建并启动容器，建议用 docker run 并指定端口和持久化数据目录：

sudo docker run -d --name one-api \
  -p 3000:3000 \
  -v /home/youruser/one-api/data:/data \
  justsong/one-api

• -p 3000:3000 将容器的 3000 端口映射到宿主机，你可以按需要改成其他端口。
• -v /home/youruser/one-api/data:/data 用于持久化数据库文件，避免容器删除后数据丢失。

如果一切顺利，运行 docker ps 会看到 one-api 容器处于 UP 状态。

4. 配置反向代理与访问验证（避坑指南）

避坑 1：防火墙与端口占用

家用服务器可能忘了放行端口。
先检查 3000 端口是否被其他程序占用：

sudo lsof -i:3000

如果被占，换一个端口（比如 3100），然后重新启动容器。

避坑 2：浏览器无法访问

在局域网另一台电脑输入 http://你的服务器IP:3000。
如果你用的不是路由器的网关 IP（如 192.168.x.x），而是住宅内网其他子网，请确保网络互通。

避坑 3：数据库初始化报错

第一次启动时 OneAPI 会自动创建 /data/one-api.db。
如果容器日志中出现 can't open database，检查数据目录权限：

sudo chown -R 1000:1000 /home/youruser/one-api/data

（容器内默认用户 UID 1000）

常见问题（FAQ）

Q：没有 Docker 也不想装 Docker，怎么运行 OneAPI？
A：下载 one-api 二进制文件和 one-api.db 到同一目录，直接运行 ./one-api 即可。二进制文件需要可执行权限 chmod +x one-api。默认监听 3000 端口。

Q：服务器重启后容器不见了？
A：使用 docker run 时加上 --restart=always 参数，例如：

sudo docker run -d --restart=always --name one-api -p 3000:3000 -v /data/one-api:/data justsong/one-api

Q：内网其他设备访问不了，怎么办？
A：检查服务器防火墙（ufw / firewalld）是否允许 3000 端口入站。同时确保 Docker 容器的端口映射正确，可用 curl http://localhost:3000 先在本机验证。

验证服务是否正常工作

1. 在服务器本地执行 curl http://localhost:3000/api/status，返回 JSON 且含 "success": true 则表示 API 正常。
2. 打开浏览器访问 http://服务器IP:3000，看到 OneAPI 登录页面（默认账号 root / 密码 123456）即为部署成功。
3. 登录后进入「渠道」页面添加一个 API 密钥（即使没有真实密钥也可以添加测试渠道），然后在「令牌」页面生成令牌，再用 curl 或 Postman 调用测试渠道，验证转发是否正常。

按照以上步骤，即使你的住宅服务器完全离线，也能顺利运行 OneAPI。
遇到报错时优先检查数据目录权限、端口占用和 Docker 服务状态，大多数问题都能用这三招解决。