标题：One-API 部署实战：从踩坑到统一接口的全过程
## 前言
最近需要把家里跑的 Ollama 模型和一个统一的 API 入口整合起来。目标是：用一个 API 地址（api.baomum.com）、一个 API Key，就能访问内网 Ollama 上的所有模型（qwen3、qwen2.5 等）。
试了 new-api、one-api，踩了不少坑。这篇文章把过程和关键点记录下来。
## 架构设计
“`
用户/客户端 → 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 二进制直接运行，不用 Docker 镜像。
### 坑2：「找不到可用渠道」
在 MySQL 里直接插 channels 表创建渠道，然后 API 调用始终返回「找不到可用渠道」。
阅读源码后发现 one-api 不是直接查 channels 表的 `models` 字段来匹配的。它有一个 **abilities 表**，存储 `(group, model, channel_id)` 的三元组。创建渠道时系统自动生成 abilities 记录，如果跳过 API/WebUI 直接插数据库，abilities 表就是空的。
**解决方案**：通过 API 或 WebUI 创建渠道，不要手动操作数据库。
### 坑3：API Key 需要 sk- 前缀
one-api v0.6.10 的 API Key 在调用时必须加 `sk-` 前缀。数据库里存的 key 是纯文本（48 位随机字符），但 HTTP 请求的 `Authorization: Bearer` 要用 `sk-{db_key}` 的格式。
否则返回「无效的令牌」。
### 坑4：分组匹配缓存
渠道分组修改后，已有的 Token 不会立即生效。需要重新保存一次 Token 来刷新缓存。渠道的 group 和 Token 的 group 必须匹配（都设为 `default`）。
### 坑5：SESSION_SECRET 必须固定
如果不固定 SESSION_SECRET，重启 one-api 后所有 Session 和 Token 缓存都会失效。
### 坑6：SSH 端口复用与 MySQL 连接
宝塔面板的 MySQL 占用了 3306 端口。one-api 的 SQL_DSN 需要正确配置，密码要匹配 MySQL root 密码。
## 关键配置步骤
### 1. 下载 one-api
用国内加速镜像下载 v0.6.10 release：
“`bash
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 模式）
“`bash
export SESSION_SECRET=*** SQL_DSN=”root:密码@tcp(127.0.0.1:3306)/one_api?charset=utf8mb4&parseTime=True&loc=Local”
./one-api
“`
系统会自动创建数据库表并生成默认管理员（root/123456）。
### 3. 开启自用模式
登录 WebUI（http://ip:3000），在系统设置中开启「自用模式」，否则需要配置模型乘数和价格。
### 4. 创建渠道
通过 API 创建 Ollama 渠道（type=1 = OpenAI 兼容模式）：
“`bash
curl -X POST http://localhost:3000/api/channel/ \
-H “Content-Type: application/json” \
-d ‘{
“type”: 1,
“name”: “Ollama”,
“base_url”: “http://内网IP:11434”,
“models”: “qwen3:4b,qwen2.5-7b-q4:latest”,
“group”: “default”
}’
“`
### 5. 创建 API Key
“`bash
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}’
“`
返回的 key 在调用时加 `sk-` 前缀。
### 6. Nginx 反代
“`nginx
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”;
}
}
“`
## 完整调用示例
“`bash
curl -sk -X POST https://api.baomum.com/v1/chat/completions \
-H “Authorization: Bearer *** \
-H “Content-Type: application/json” \
-d ‘{“model”:”qwen2.5-7b-q4:latest”,”messages”:[{“role”:”user”,”content”:”你好”}],”stream”:false,”max_tokens”:100}’
“`
## 验证结果
测试通过：
– ✅ 本地 one-api 到 Ollama 调用成功
– ✅ 外网 HTTPS 到 one-api 到 Ollama 调用成功
– ✅ 模型列表正常返回（5个模型全部可用）
– ✅ SSL 证书自动续期已配置
## 总结
One-API 本身没有问题，核心是配置细节：
1. 渠道必须通过 API/WebUI 创建，才能自动同步 abilities 表
2. API Key 调用时要加 sk- 前缀
3. 分组必须匹配（Token.group = Channel.group）
4. SESSION_SECRET 要固定
5. 遇到问题先查官方文档和社区 Issue