One-API 部署实战：从踩坑到统一接口的全过程

前言

最近需要把家里跑的 Ollama 模型和一个统一的 API 入口整合起来。目标是：用一个 API 地址（api.baomum.com）、一个 API Key，就能访问内网 Ollama 上的所有模型。

架构设计

用户/客户端 → https://api.baomum.com
                      ↓
              Nginx (SSL 证书)
                      ↓
         one-api v0.6.10 (localhost:3000)
                      ↓
            Ollama (内网服务器:11434)

踩坑记录

坑1：Docker 版 one-api 绑定随机端口

justsong/one-api 的 Docker 镜像启动后不监听 3000 端口，而是每次重启绑定随机端口。改用官方 release 二进制直接运行即可。

坑2：「找不到可用渠道」

在 MySQL 里直接插 channels 表创建渠道，API 调用始终返回「找不到可用渠道」。

原因是 one-api 不直接查 channels 表的 models 字段，而是通过 abilities 表存储 (group, model, channel_id) 三元组来匹配。跳过 API/WebUI 直接操作数据库，abilities 表就是空的。

解决方案：通过 API 或 WebUI 创建渠道。

坑3：API Key 需要 sk- 前缀

one-api v0.6.10 要求调用时 Authorization: Bearer *** sk-{db_key} 格式，否则返回「无效的令牌」。

坑4：分组匹配缓存

修改渠道分组后，已有 Token 不会立即生效，需要重新保存 Token 刷新缓存。渠道和 Token 的 group 必须匹配（都设为 default）。

坑5：SESSION_SECRET 必须固定

不固定 SESSION_SECRET，重启后所有 session 和 token 缓存失效。

坑6：MySQL 连接问题

宝塔面板的 MySQL 占 3306 端口，SQL_DSN 需要正确配置密码。

关键配置步骤

1. 下载 one-api

wget -O /root/one-api "https://gh-proxy.com/https://github.com/songquanpeng/one-api/releases/download/v0.6.10/one-api"
chmod +x /root/one-api

2. 启动（MySQL 模式）

export SESSION_SECRET=*** SQL_DSN="root:密码@tcp(127.0.0.1:3306)/one_api?charset=utf8mb4&parseTime=True&loc=Local"
./one-api

3. 创建 API Key

curl -X POST http://localhost:3000/api/token/   -H "Content-Type: application/json"   -d '{"name":"mykey","remain_quota":99999999,"unlimited_quota":true,"expired_time":-1}'

4. Nginx 反代（HTTPS）

server {
    listen 443 ssl http2;
    server_name api.baomum.com;
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

总结

One-API 本身没有问题，核心是配置细节：

1. 渠道必须通过 API/WebUI 创建，自动同步 abilities 表
2. API Key 调用时要加 sk- 前缀
3. 分组必须匹配（Token.group = Channel.group）
4. SESSION_SECRET 要固定
5. 遇到问题先查官方文档和社区 Issue