OIAPI 使用指南
版本:26.11.16.28
这份指南面向普通用户和管理员,包含快速开始、页面定位、API Key、2FA、接口调用、管理后台和排障。
1. 快速开始
注册
- 打开首页。
- 点击右上角“注册”。
- 填写邮箱、昵称、密码。
- 如果开启邮箱验证,输入邮件里的 6 位验证码。
- 完成验证后登录。
页面:
- 注册:/register
- 登录:/login
密码至少 10 位,包含大小写字母、数字、符号中的三类。
登录
支持邮箱密码、第三方登录和两步验证。
开启 2FA 后,密码通过会进入第二步:
- 身份验证器 6 位动态码
- 或一次性恢复码
登录后入口
- 用户中心:/dashboard
- 账号资料:/dashboard/profile
- API Key:/dashboard/keys
- 用量:/dashboard/usage
- 调用日志:/dashboard/logs
- 通知:/dashboard/notifications
2. 页面地图
| 功能 | 页面 | 说明 |
|---|---|---|
| 接口目录 | / | 首页即公开接口 |
| 接口详情 | /apis/:slug | 参数、示例、复制地址 |
| 在线调试 | /playground | 浏览器调用 |
| API 文档 | /docs | 鉴权、错误码、响应 |
| 使用指南 | /guide | 本教程 |
| 登录 | /login | 密码、OAuth、2FA |
| 注册 | /register | 新账号 |
| 用户中心 | /dashboard | 账号概览 |
| 账号资料 | /dashboard/profile | 昵称、密码、设备、2FA |
| API Key | /dashboard/keys | 创建、撤销 |
| 用量 | /dashboard/usage | 调用量与额度 |
| 调用日志 | /dashboard/logs | 请求明细 |
| 通知 | /dashboard/notifications | 邮件、Webhook |
| 公告 | /announcements | 平台公告 |
| 更新日志 | /changelog | 版本变更 |
| 管理后台 | /admin | 仅管理员 |
| 网关管理 | /admin/gateway | 健康、证书、路由 |
| 用户管理 | /admin/users | 角色、封禁、2FA 重置 |
| 内容管理 | /admin/content | 公告、分类、更新日志 |
| 定时任务 | /admin/tasks | 周期任务、运行记录 |
| 风控与渠道 | /admin/security | IP 规则、OAuth、封禁 |
| 日志中心 | /admin/logs | 调用、错误日志 |
| 系统设置 | /admin/settings | 站点、主题、安全、限流 |
| 功能开关 | /admin/features | 注册、OAuth、2FA |
3. 创建 API Key
页面创建
- 登录。
- 打开 /dashboard/keys。
- 点击“创建密钥”。
- 填写名称,例如 bot-prod。
- 勾选权限:
- api:call:调用接口
- profile:read:读取资料
- 可选设置生效时间和到期时间。
- 提交。
Secret 只显示一次,格式类似:
oak_xxxxxxxx_yyyyyyyyyyyyyyyy
立即保存。数据库只保存哈希,丢失只能撤销重建。
接口创建
API Key 不能创建 API Key,必须用用户 Access Token:
curl -X POST https://api.example.com/v1/me/keys \
-H "authorization: Bearer <accessToken>" \
-H "content-type: application/json" \
-d '{"name":"bot-prod","scopes":["api:call"],"expiresInDays":365}'
返回 data.secret,只出现一次。
给机器人使用
curl https://api.example.com/v1/ip/inspect \
-H "x-api-key: oak_xxxxxxxx_yyyyyyyyyyyyyyyy" \
-H "content-type: application/json" \
-d '{"ip":"1.1.1.1"}'
也支持:
Authorization: ApiKey oak_xxxxxxxx_yyyyyyyyyyyyyyyy
建议每个机器人独立 Key、设置到期时间、不要写进 Git、泄露后立即撤销。
4. 调用接口
找到接口
首页或 /docs 查看接口目录。详情页包含方法、路径、参数、示例、限制、权限和复制地址。
curl
curl -X POST https://api.example.com/v1/gateway/json.format \
-H "content-type: application/json" \
-d '{"json":"{\"a\":1}"}'
JavaScript
const res = await fetch('https://api.example.com/v1/...', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-api-key': process.env.OIAPI_API_KEY,
},
body: JSON.stringify({}),
});
const data = await res.json();
if (data.code !== 1) throw new Error(data.message);
Python
import os, requests
res = requests.post(
"https://api.example.com/v1/...",
headers={"x-api-key": os.environ["OIAPI_API_KEY"]},
json={},
timeout=30,
)
payload = res.json()
if payload["code"] != 1:
raise RuntimeError(payload["message"])
响应结构
成功:
{
"code": 1,
"message": "ok",
"data": {},
"meta": {
"requestId": "...",
"timestamp": "2026-11-12T11:00:00.000Z",
"reqTimestamp": 1794423600000,
"latencyMs": 12
}
}
失败:
{
"code": 0,
"message": "参数错误",
"data": null,
"error_code": "VALIDATION_FAILED",
"meta": { "requestId": "...", "timestamp": "...", "reqTimestamp": 0 }
}
成功时 data 恒为对象:列表在 data.items,标量在 data.value;旧 /api 与 /v1 一致。失败且无数据时 data 为 null。
业务分支按 code 和 error_code 判断,不要依赖文案。
常见错误
| error_code | 含义 | 处理 |
|---|---|---|
| VALIDATION_FAILED | 参数不合法 | 查看 details |
| UNAUTHORIZED | 未登录或 Key 无效 | 检查凭证 |
| FORBIDDEN | 权限不足 | 检查 scopes |
| RATE_LIMITED | 限流 | 退避重试 |
| QUOTA_EXCEEDED | 额度用完 | 等次日或升级 |
| ENDPOINT_DISABLED | 接口停用 | 查看公告 |
| INTERNAL_ERROR | 服务异常 | 带 requestId 反馈 |
5. 在线调试
打开 /playground:
- 左侧选择接口。
- 填写参数。
- 点击运行。
- 查看状态码、耗时、原始响应。
- 使用生成的 curl 示例。
请求目标:
- 公开接口直接请求 API 域名(
API_PUBLIC_URL),地址与接口详情的 curl 示例一致;跨域由服务端域名白名单放行。 - 需登录或私有接口走同源 BFF
/api/v1/*,复用 httpOnly 登录 Cookie 与 CSRF。
不要把私密响应贴到公开地方。
6. 两步验证 TOTP
开启
- 打开 /dashboard/profile。
- 找到“两步验证”卡片。
- 点击“开启”。
- 扫码或手动输入密钥。
- 输入当前 6 位动态码。
- 保存 8 个恢复码。
兼容 Google Authenticator、Microsoft Authenticator、1Password 等标准 TOTP。
登录
密码通过后输入 6 位动态码,或未使用的恢复码。
恢复码
每个只能使用一次,只显示一次,建议离线保存。
关闭
在资料页点击“关闭”,需要当前密码和动态码/恢复码。
设备丢失且恢复码丢失时,联系管理员重置。
全站开关
管理员在 /admin/features 控制“全站两步验证(TOTP)”。
关闭后不再校验已有 2FA,用户不能新开,已保存密钥保留。
7. 登录设备与账号安全
页面:/dashboard/profile 的“安全”卡片。
可以看到:
- 当前设备
- 其他活跃会话
- 创建时间、IP
支持退出单个设备;修改密码会退出其它设备。设备多时列表在卡片内滚动。
8. 用量与日志
用量
/dashboard/usage 查看调用量、错误量、按接口/Key 消耗、额度。
调用日志
/dashboard/logs 按成功/失败、接口、时间筛选,查看 requestId、状态码、耗时、IP。
8.1 开发者 Webhook
独立页面:/dashboard/webhooks
- 最多 5 个端点
- 事件订阅、HMAC 签名、重试、投递记录
- Secret 只显示一次
通知设置负责邮件;Webhook 负责系统集成,两者不重复发送。
9. 通知设置
/dashboard/notifications 支持邮件、Webhook、事件订阅。
可订阅 Key 创建、额度预警、公告、安全提醒、状态事件。
Webhook 需要合法 URL;关闭通知不会删除历史记录。
10. 管理后台
仅 admin/owner 可访问。
平台概览
/admin 包含用户、Key、接口数、24 小时调用/错误、7/30 天趋势、平均耗时、Top 10 接口占比、平台流量分析、热门接口和快捷开关。
图表支持悬停提示;窗口不可见时自动暂停刷新。
网关管理
/admin/gateway 包含版本、运行时长、风控模式、ClickHouse 状态、证书剩余天数、Host 路由、最近错误。
可修改 H1/H2/H3、HTTP/HTTPS 同时访问、Hosts、静态目录、证书路径或 PEM、ACME。
保存会重启网关。
用户管理
/admin/users 可搜索用户、修改昵称/角色/状态、封禁/解封、查看 2FA 状态、重置用户 2FA。
重置 2FA 会清除密钥和恢复码,用户需重新绑定。
内容管理
/admin/content 有三个标签:
- 公告
- 更新日志
- 分类
更新日志支持手动新建、从 Git 自动读取、粘贴 Git log、勾选展示提交、草稿/发布。
定时任务
/admin/tasks 支持 HTTP 请求、命令/动作、周期执行、查看运行历史、详情查看。
操作菜单中的“详情”打开任务编辑与运行记录。
风控与渠道
/admin/security 包含 IP allow/deny、临时风控封禁与解封、OAuth 渠道、额度方案、参数/连接/地域规则。
日志中心
/admin/logs 查看调用日志、错误日志,按 requestId 搜索,查看详情预览。
主题与外观
- 右上角调色盘可独立切换明暗、强调色、UI 套件、密度、动效。
- 支持自定义主题:背景、卡片、文字、边框、强调色、圆角、动效。
- 自定义主题保存在当前浏览器;详见 ops/docs/themes.md。
系统设置与功能开关
/admin/settings:站点、主题、安全、限流、注册、日志保留、OTel、ClickHouse。
OTel 开启/修改采集地址后需要重启 API;ClickHouse 保存后下一次分析请求生效。
/admin/features:注册、验证码、前端防火墙、OAuth、Playground、文档、公告、更新日志、RSS、计费、邮件、2FA。
11. 常见问题
Key 创建后还能看 Secret 吗
不能。Secret 只返回一次,丢失请撤销后重建。
为什么 401
- 没带 Key
- Key 被撤销
- Key 过期或未生效
- scope 不足
- 登录态过期
为什么 429
触发限流或额度。查看响应头和 error_code,退避重试。
为什么 403
可能是账号封禁、IP deny、动态风控、接口权限不足。
2FA 动态码不正确
- 检查设备时间是否自动同步
- 尝试恢复码
- 联系管理员重置
更新日志为什么没显示
只有 published 状态会出现在 /changelog;草稿在后台可见。
页脚版本是什么
平台版本,格式为年后两位.月.日.小版本号,例如 26.11.16.28。
12. 安全建议
- 管理员必须开启 2FA
- 每个机器人独立 Key
- Key 设置到期时间
- 不在前端代码硬编码 Key
- 恢复码离线保存
- 管理后台限制来源 IP
- 不在公开渠道贴 requestId + 完整响应
- 泄露后立即撤销 Key/会话
13. 获取帮助
优先提供:
- requestId
- 接口路径
- 状态码和 error_code
- 发生时间(含时区)
定位顺序:
- 用户中心日志
- 管理后台日志中心
- 网关最近错误
- ClickHouse 或回退日志
文档入口:
- /guide:使用指南
- /docs:API 契约
- /changelog:版本变更