HTTP API

安装与启动

HTTP 组件是可选依赖：

python -m pip install -r requirements-server.txt
$env:SOCIAL_DATABASE_API_TOKEN = "replace-with-a-random-token-at-least-16-chars"
python -m social_database serve

令牌只从环境变量读取，不提供命令行参数，避免出现在进程参数中。服务默认监听 127.0.0.1:8000、启用 /docs，并关闭 Uvicorn 访问日志。成员数据接口都要求：

Authorization: Bearer <SOCIAL_DATABASE_API_TOKEN>

常用环境变量：

变量	默认值	用途
`SOCIAL_DATABASE_API_TOKEN`	无	必填，至少 16 个字符
`SOCIAL_DATABASE_PREVIOUS_API_TOKEN`	空	轮换期间临时接受的旧令牌，非空时至少 16 个字符
`SOCIAL_DATABASE_DB_PATH`	项目默认数据库	SQLite 路径
`SOCIAL_DATABASE_HOST`	`127.0.0.1`	监听地址
`SOCIAL_DATABASE_PORT`	`8000`	监听端口
`SOCIAL_DATABASE_MAX_REQUEST_BYTES`	`67108864`	JSON 请求最大字节数
`SOCIAL_DATABASE_MAX_RECORDS`	`200000`	单批最大记录数
`SOCIAL_DATABASE_DOCS`	`true`	是否提供 `/docs`
`SOCIAL_DATABASE_ACCESS_LOG`	`false`	是否开启可能包含查询词的访问日志

CLI 可以用 serve --db、--host、--port、--no-docs 和 --access-log 覆盖非敏感选项。服务固定使用一个 Uvicorn worker；不要用外部命令启动多个 worker 共同写同一个 SQLite 文件。

接口

无需认证且不返回数据库信息：

GET /health/live：进程存活。
GET /health/ready：启动迁移和 WAL 初始化已经完成。

需要 Bearer 令牌：

GET /api/v1/health：完整 SQLite、外键、观察记录和 FTS5 检查。
GET /api/v1/stats：数据库规模与最近批次。
GET /api/v1/imports?limit=20：最近导入批次。
GET /api/v1/search?q=<关键词>&field=any&page=1&page_size=50：按用户分页搜索。
POST /api/v1/query-text：用 JSON 正文提交查询词，返回适合消息转发的限长纯文本。
POST /api/v1/imports/json：直接提交标准 JSON v1 对象。

HTTP 响应不包含服务端数据库路径。完整健康检查可能遍历 FTS5 内容，只用于运维诊断；容器探针使用轻量的 /health/ready。

导入示例

$headers = @{
    Authorization = "Bearer $env:SOCIAL_DATABASE_API_TOKEN"
}
Invoke-RestMethod `
    -Method Post `
    -Uri http://127.0.0.1:8000/api/v1/imports/json `
    -Headers $headers `
    -ContentType "application/json" `
    -InFile data/input/batch.json

推荐每次采集提供不重复的 batch_id。相同 producer + batch_id 和相同内容再次提交返回 200 且 duplicate=true；相同身份对应不同内容返回 409。没有 batch_id 时，服务使用与 JSON 键顺序和空白无关的规范化 SHA-256 去重。新批次成功创建返回 201。

消息转发查询示例

query-text 避免把查询词放入 URL 或访问日志，固定搜索所有字段，默认返回十个用户的编号短列表；末尾数字选择全局第几条结果，--page 选择列表页。它适合由 LAS 等可信内部路由调用，不代替路由侧的用户权限检查。请求中的 sd查 或 社交查询 命令前缀会在搜索前移除，因此 LAS 可以直接转发完整 QQ 文本。

QQ 命令与 JSON q 内容对应如下（CloudOps 将命令转成 sd查 … 经 LAS 转发）：

QQ 命令	含义
`/sd query 小明`	第 1–10 条：序号、昵称/名片、QQ、群摘要
`/sd query 小明 --page 2`	第 11–20 条
`/sd query 小明 13`	查看全部匹配结果中的第 13 条，不是第 13 页
`/sd query "小明 2"`	将末尾数字作为关键词的一部分
`/sd query "小明 2" 3`	查看关键词“小明 2”的第 3 条

编号与已有搜索一致，按 QQ/user_id 文本升序排列；每次重新查询，不保存会话结果集。数据库增量更新后编号可能变化，详情中的 QQ 号用于确认对象。纯数字 QQ 号本身仍可直接搜索。英文双引号支持 JSON 转义；复杂关键词可照着回复中的命令复制。页码与序号必须是正整数，不能在同一条命令里混用。解析后的关键词仍限 128 字符，含引号、转义和导航参数的 q 最多 1024 字符。

列表和详情均不显示“最近记录时间”，但不会删除数据库里的时间字段；完整 GET /api/v1/search JSON 不变。详情最多展开五个群，每条回复仍限 3000 字符，超长字段显示省略号。无匹配时不回显关键词；编号/页码越界时提示总数。

$body = @{q = "昵称或 QQ 号"} | ConvertTo-Json -Compress
Invoke-WebRequest `
    -Method Post `
    -Uri http://127.0.0.1:8000/api/v1/query-text `
    -Headers $headers `
    -ContentType "application/json" `
    -Body $body

其他常见状态码：

400：JSON 格式或批次契约错误。
401：令牌缺失或错误。
403：生产反向代理拒绝当前来源地址（应用本身认证失败仍返回 401）。
413：请求体超过配置限制。
415：请求不是 JSON 媒体类型。
422：查询参数或搜索字段错误。
503：数据库不可用或完整健康检查未通过。

运行边界

导入请求在接收过程中累计计算大小，超过配置限制时立即终止；JSON 解码和数据库合并在线程池执行，不阻塞异步服务循环，也不保存上传副本。
进程内写锁串行处理批次；读取可以由 FastAPI 线程池并发执行。
SQLite 使用 WAL、30 秒忙等待和单 worker。长导入仍是同步请求，调用方应设置合理超时并使用同一 batch_id 安全重试。
默认访问日志关闭，因为标准 Uvicorn 访问日志会包含搜索查询参数。
Bearer 令牌不替代 HTTPS。公网部署必须通过反向代理提供 TLS，并限制直接访问容器端口。

服务可以短期同时接受当前令牌和 SOCIAL_DATABASE_PREVIOUS_API_TOKEN，用于先切服务、再切 AstrBot、最后撤销旧值的无停机轮换。旧令牌不应长期保留；完整部署与轮换顺序见 production-deployment.md。

FilesExpand file tree

http-api.md

Latest commit

History