家用住宅主机Linux离线部署OneAPI AI中转站

如果你的家用住宅有一台闲置的Linux主机，又想在内网搭建一个AI中转站来统一管理OpenAI、Qwen等API密钥，那么OneAPI是一个非常合适的工具。
但在家主机经常没有互联网访问权限，这时候离线部署就成了必选项。
本文面向零基础用户，全程拆解如何在没有网络的情况下完成安装和配置。

场景理解与前期准备

首先确认你的Linux主机系统版本（建议Ubuntu 20.04+或CentOS 7+），并登录到终端。
因为是完全离线，你需要一台能上网的机器，从OneAPI的GitHub Releases页面下载对应架构的二进制文件（例如one-api-linux-amd64.tar.gz）。
如果主机没有外网，也可以通过U盘或内网共享文件夹传输。

除了二进制包，还需要提前下载好运行时依赖。
OneAPI使用Go语言编译，二进制本身已包含，无需额外运行环境。
但如果你打算用systemd管理进程，建议提前准备好systemd服务模板。

离线安装OneAPI二进制文件

假设传输后的文件放在/tmp目录下，执行以下解压和安装操作：

cd /tmp
tar -xzf one-api-linux-amd64.tar.gz
mkdir -p /opt/one-api
mv one-api /opt/one-api/
cd /opt/one-api
chmod +x one-api

此时没有启动服务，需要先创建配置目录和数据目录。
OneAPI默认使用当前目录下的config.json，如果没有会自动生成。
我们先初始化一下：

./one-api --port 3000 --log-dir ./logs

这一步只是为了生成默认配置文件，然后按Ctrl+C停止。
目的是让程序创建好logs、data等文件夹，方便后续编辑。

配置服务与开机自启

为了稳定运行，建议将OneAPI注册为systemd服务。
创建服务文件/etc/systemd/system/one-api.service，内容如下：

[Unit]
Description=One API Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/one-api
ExecStart=/opt/one-api/one-api --port 3000
Restart=always

[Install]
WantedBy=multi-user.target

然后执行：

systemctl daemon-reload
systemctl enable one-api
systemctl start one-api

检查服务状态：

systemctl status one-api

如果显示active (running)则成功。

避坑指南：常见问题与解决方案

问题1：端口被占用 用netstat -tlnp | grep 3000检查，如果占用则修改--port参数，或停掉冲突进程。

问题2：防火墙导致无法访问 家用路由器可能有内网防火墙或Linux本机iptables。
执行firewall-cmd --zone=public --add-port=3000/tcp --permanent（CentOS）或ufw allow 3000（Ubuntu），然后重载防火墙。

问题3：配置文件权限错误 确保/opt/one-api目录及子文件属于运行用户（这里是root），否则程序无法读写数据库和日志。

问题4：机器学习平台对接 OneAPI默认支持多种代理协议，如果你在后面配置渠道时遇到连接失败，确认网络可达性：在主机上用curl测试目标API域名是否通。

效果验证与后续设置

在局域网另一台电脑浏览器输入http://你的主机内网IP:3000，应该看到OneAPI登录页面。
默认管理员账号为root，密码123456（首次登录后务必修改）。

添加渠道：登录后点击“渠道” -> “添加渠道”，填写API地址、密钥和模型映射即可。
以后你的应用只需一个统一的OneAPI地址（http://内网IP:3000/v1）和一个密钥就能访问所有添加的模型。

如果你想在内网外也能用，可配置frp或Ngrok等内网穿透工具，但注意安全风险，建议绑定域名并开启HTTPS。

如果你在部署过程中遇到其他异常，优先检查日志文件/opt/one-api/logs/下的输出，常见错误码如500、502多与配置或网络有关。
回到本文避坑部分逐条对照，通常能快速定位问题。