OIAPI 使用指南

版本:26.11.16.28

这份指南面向普通用户和管理员,包含快速开始、页面定位、API Key、2FA、接口调用、管理后台和排障。

1. 快速开始

注册

  1. 打开首页。
  2. 点击右上角“注册”。
  3. 填写邮箱、昵称、密码。
  4. 如果开启邮箱验证,输入邮件里的 6 位验证码。
  5. 完成验证后登录。

页面:

  • 注册:/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

页面创建

  1. 登录。
  2. 打开 /dashboard/keys。
  3. 点击“创建密钥”。
  4. 填写名称,例如 bot-prod。
  5. 勾选权限:
    • api:call:调用接口
    • profile:read:读取资料
  6. 可选设置生效时间和到期时间。
  7. 提交。

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:

  1. 左侧选择接口。
  2. 填写参数。
  3. 点击运行。
  4. 查看状态码、耗时、原始响应。
  5. 使用生成的 curl 示例。

请求目标:

  • 公开接口直接请求 API 域名(API_PUBLIC_URL),地址与接口详情的 curl 示例一致;跨域由服务端域名白名单放行。
  • 需登录或私有接口走同源 BFF /api/v1/*,复用 httpOnly 登录 Cookie 与 CSRF。

不要把私密响应贴到公开地方。

6. 两步验证 TOTP

开启

  1. 打开 /dashboard/profile。
  2. 找到“两步验证”卡片。
  3. 点击“开启”。
  4. 扫码或手动输入密钥。
  5. 输入当前 6 位动态码。
  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
  • 发生时间(含时区)

定位顺序:

  1. 用户中心日志
  2. 管理后台日志中心
  3. 网关最近错误
  4. ClickHouse 或回退日志

文档入口:

  • /guide:使用指南
  • /docs:API 契约
  • /changelog:版本变更