住宅主机用Docker Compose一键启动OneAPI：完整图文教程

许多想在本地搭建AI API聚合网关的朋友选择了OneAPI，但一想到要在自家电脑上配置环境就头疼。
其实只要你的机器支持Docker，用Compose文件就能一键拉起服务。
下面直接从零开始，让你在住宅主机上顺利完成部署。

准备环境：安装Docker和Docker Compose

1. 检查或安装Docker

打开终端（Windows推荐使用PowerShell或WSL2），输入：

docker --version

如果显示版本号（如Docker version 24.0.7），说明Docker已安装。
若没安装，根据你的系统操作：

• Linux（Ubuntu/Debian）：一键安装脚本

  curl -fsSL https://get.docker.com -o get-docker.sh
  sudo sh get-docker.sh

• Windows：下载Docker Desktop并安装，确保启用WSL2后端。
• macOS：同样下载Docker Desktop即可。

2. 确认Docker Compose可用

新版本Docker将Compose集成到docker compose命令中（注意没有横杠）。
验证：

docker compose version

如果提示命令不存在，请使用旧版独立安装：

sudo apt install docker-compose   # Linux

或从官方GitHub下载二进制文件。
建议统一使用docker compose（新版）。

编写docker-compose.yml文件

在你想存放OneAPI数据的目录（例如~/oneapi）下新建文件docker-compose.yml：

mkdir ~/oneapi && cd ~/oneapi
vim docker-compose.yml

（不会vim可以用nano）写入以下内容：

version: '3.8'
services:
  oneapi:
    image: justsong/one-api:latest
    container_name: one-api
    restart: always
    ports:
      - "3000:3000"          # 主机端口映射：3000
    volumes:
      - ./data:/data        # 数据持久化（日志、数据库等）
    environment:
      - SQL_DSN=oneapi.db   # 使用SQLite，文件存放在/data下
      - REDIS_CONN_STRING=
      - SESSION_SECRET=your_random_secret_here   # 替换为随机长字符串
      - TZ=Asia/Shanghai

重点说明：

• ports左侧的3000是宿主机端口，如果被占用可改为3001:3000。
• SESSION_SECRET一定要改成一串随机的长字符串（可用openssl rand -hex 32生成）。
• 首次启动后OneAPI会自动在./data目录下生成SQLite数据库文件。

一键启动OneAPI

在~/oneapi目录下执行：

docker compose up -d

等待拉取镜像并启动。
几秒后输入：

docker compose ps

如果STATUS显示Up，说明服务正常运行。
打开浏览器访问http://你住宅主机的IP:3000（若在本机则http://localhost:3000），应该能进入OneAPI登录页面。
默认账号root，密码123456。
记得第一时间修改默认密码。

避坑指南与常见问题

1. 端口被占用或防火墙阻止

• 如果容器启动后无法访问，先检查docker compose logs oneapi是否有错误。
• 如果是端口冲突，修改docker-compose.yml中的ports映射，例如3001:3000，然后docker compose up -d重新创建。
• 住宅主机通常有Windows防火墙或Linux firewalld/iptables。开放端口：
• Linux：sudo ufw allow 3000，或sudo firewall-cmd --add-port=3000/tcp --permanent。
• Windows：在防火墙高级设置中添加入站规则。

2. 数据持久化后迁移注意

volumes挂载的./data目录包含了所有配置和日志。
如果要备份或迁移，只需拷贝整个data文件夹到新主机，重新执行docker compose up -d即可。

3. 如何配置反向代理（可选）

如果想用域名访问（如oneapi.example.com），可以在同主机上部署Nginx或Caddy。
以Nginx为例：

server {
    listen 80;
    server_name oneapi.example.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

之后再申请SSL证书即可启用HTTPS。

验证部署是否成功

登录后台后，进入“令牌”页面，添加一个渠道（例如OpenAI或自建模型），然后测试对话。
你也可以用命令行验证API是否正常：

curl http://localhost:3000/api/status

返回JSON数据则代表服务可用。

常见问题解答

Q：启动时报错“port is already allocated”？
A：说明3000端口被其他程序占用。修改docker-compose.yml中左侧端口号，然后重新docker compose up -d。

Q：如何更新OneAPI到最新版？
A：执行docker compose pull && docker compose up -d即可。

Q：能否将数据库改为MySQL？
A：可以。修改environment中的SQL_DSN为MySQL连接字符串，并额外部署一个MySQL容器（注意网络连通）。但新手推荐直接用SQLite，无需额外配置。

如果你正在配置住宅主机上的OneAPI，建议先按本文步骤完整执行，再根据自己的模型渠道做微调；
遇到异常时优先查看docker compose logs oneapi排查日志。
成功部署后，你就可以把各大AI模型统一管理，方便后续调用。