X Xora API

概览与通用约定 #

Xora 服务端为数码社区客户端提供接口,覆盖登录、信息流、话题板块、帖子、评论、搜索、用户、私信、通知、应用库、设备库,以及一组 WebView 页面。

项值
Base URLhttps://api.xoar.top
协议HTTPS(TLS 1.2 / 1.3)。HTTP 请求接口直通,网页 GET 会 301 到 HTTPS
方法全部 POST,用 action 字段区分操作
Content-Typeapplication/x-www-form-urlencoded; charset=UTF-8;仅 /api/app_upload.php 为 multipart/form-data
返回JSON(UTF-8),业务成功 HTTP 200 + code:0
时间格式YYYY-MM-DD HH:MM:SS;私信气泡时间 HH:MM
健康检查GET https://api.xoar.top/healthz

请求形态

所有业务接口通过 action 分派,其余字段为参数:

POST /api/post.php
Content-Type: application/x-www-form-urlencoded

action=like&post_id=p1&like=1

返回结构

成功时业务字段直接平铺在顶层,并带 code:0、msg:"ok":

{ "code": 0, "msg": "ok", "post_id": "p1", "likes": 343 }

失败时 HTTP 4xx,返回 code + msg:

{ "code": 1004, "msg": "内容不存在" }

分页

请求带 page(从 1 开始)与 per_page(默认 20,上限 100),返回:

{
  "items": [ ... ],
  "pagination": { "has_next": true, "page": 1, "total": 137 }
}

信息流额外支持游标分页:带 timestamp=<上一页最后一条 created_at 的 Unix 秒>,只返回更早的数据。

匿名访问

信息流、板块、帖子详情、评论列表、搜索、用户资料、应用库、设备库列表均可匿名调用,此时 liked、collected、is_followed、is_following 一律为 false。

图片

接口返回的 avatar_url、cover、images、icon 都是完整 URL,客户端直接加载,无需拼接域名。

类型路径说明
封面 / 头图/static/cover.svg?t=<标题>服务端动态生成,可平滑替换为对象存储 CDN
头像/static/avatar.svg?u=<昵称>同上
上传产物/uploads/apps/<app_id>.apkAPK 与图标

快速开始 #

1. 发送邮箱验证码

POST/api/user/email.phpaction=login_account_by_email
curl -X POST https://api.xoar.top/api/user/email.php \
  -d 'action=login_account_by_email' \
  -d 'email=xora001@163.com'

# {"code":0,"msg":"ok"}

2. 校验验证码并登录

POST/api/user/email.phpaction=verify_login_email
curl -X POST https://api.xoar.top/api/user/email.php \
  -d 'action=verify_login_email' \
  -d 'email=xora001@163.com' -d 'code=123456'

# {"code":0,"token":"40ae4c8c...","user_id":"10001","username":"舟行客",
#  "avatar_url":"https://...","sgin":"675e6b...","newly_registered":false}

3. 调用业务接口

curl -X POST https://api.xoar.top/api/feed.php \
  -d 'action=feed' -d 'feed_type=推荐' -d 'per_page=20' \
  -H 'Authorization: Bearer <token>'

错误码 #

codeHTTP含义客户端处理
0200成功正常解析
401401token 失效或缺失清本地 token,跳登录
403403被限制(私信受限 / 评论已关闭 / 黑名单)弹提示,读 reason
429429请求过频(验证码 60 秒 1 次)倒计时后再试
1001400参数错误提示用户
1002400账号不存在引导注册
1003400验证码错误或过期停留在输码页
1004400内容不存在(帖子/评论/板块/应用/设备)返回上一页
1005400无权限(非作者 / 非楼主)隐藏操作按钮

鉴权与 token #

登录成功返回三个关键字段,客户端本地保存:

字段说明
token请求凭证,90 天有效;每次请求放在 Authorization: Bearer <token>
user_id用户 ID(字符串形式的数字)
sgin原包签名字段,WebView 页面(绑定手机 / 登录设备 / 黑名单 / 注销 / 等级进度)用它当 token
服务端也接受把 token 或 sgin 放在表单参数里传,方便 WebView 与老客户端。

令牌记录在数据库的 tokens 表,按设备保存 device_id、android_id、ip、last_active,可在「登录设备管理」页面按设备踢下线。

登录 #

邮箱验证码:发码

POST/api/user/email.phpaction=login_account_by_email
参数必填说明
email是已绑定账号的邮箱

成功 {"code":0,"msg":"ok"};账号不存在 1002(「请输入已绑定账号的邮箱」);60 秒内重复请求 429。

服务端未配置 SMTP 且开启调试时,响应会附带 dev_code 便于联调。

邮箱验证码:校验登录

POST/api/user/email.phpaction=verify_login_email
参数必填说明
email是邮箱
code是6 位数字验证码,10 分钟有效、一次性
{
  "code": 0,
  "token": "40ae4c8c163f2837e41a97e9ab5d9eab2920947247b2847fbdcba69c782a67c8",
  "user_id": "10001",
  "username": "舟行客",
  "avatar_url": "https://api.xoar.top/static/avatar.svg?u=%E8%88%9F%E8%A1%8C%E5%AE%A2",
  "sgin": "675e6ba035c151abcdf7bac713265848",
  "newly_registered": false
}

图形验证码

POST/api/user/email.phpaction=captcha
{ "code": 0, "captcha_id": "bf963b7696c6d10be4590e8f",
  "img": "data:image/png;base64,iVBORw0KGgo..." }

img 可直接放进 ImageView;captcha_id 5 分钟有效,供风控校验,当前登录流程不强制。

账号密码登录 / 注册

POST/api/user/v2/login.phpusername + password
POST/api/user/v2/register.phpusername + password(+email)
参数说明
username用户名(注册至少 2 位)
password密码(注册至少 6 位)
device_id / android_id / platform设备信息,用于登录设备管理,可空
sign保留字段,当前不校验(可配置为 MD5(参数按 key 排序拼接 + salt))

返回结构与验证码登录一致。演示账号密码统一为 123456。

扫码登录

POST/api/user/qr_login.phpaction=poll / confirm

第一步:新建二维码(不传 qr_token)

{
  "code": 0,
  "qr_token": "22e6f45dab6f60f7430cc4e261d3e6f8",
  "status": "pending",
  "expires_in": 120,
  "scan_url": "https://api.xoar.top/web/qr_login/?qr_token=22e6f45dab6f60f7430cc4e261d3e6f8"
}

把 scan_url 生成二维码。

第二步:已登录端确认(需登录态)

POST /api/user/qr_login.php
action=confirm&qr_token=22e6f45dab6f60f7430cc4e261d3e6f8
# {"code":0,"status":"confirmed"}

第三步:网页端轮询 action=poll&qr_token=<qr_token>,status 为 pending → confirmed(同时返回 token/user_id/username/avatar_url/sgin)或 expired(120 秒过期)。

首页信息流 #

POST/api/feed.phpaction=feed
参数默认说明
feed_type推荐推荐 / 关注 / 应用集 / 应用 / 视频 / 快讯 / 热榜 / 问答 / 精选 / 话题
timestamp—游标分页,上一页最后一条的 Unix 秒
page / per_page1 / 20页码分页
is_personalizedtrue个性化开关(当前按时间与热度混合)
blocked_keywords—逗号分隔的屏蔽词,服务端过滤标题与正文
sortdefaultdefault / latest / hot

feed_type=关注 需登录,按「关注的板块 + 关注的用户」聚合,并返回 followed_top。

{
  "code": 0,
  "items": [
    {
      "post_id": "p1",
      "title": "小米 15 Ultra 上手两周:这次影像真的能打",
      "content": "上手两周,夜景样张提升明显……",
      "cover": "https://api.xoar.top/static/cover.svg?t=...",
      "type": "post",
      "category": "default",
      "author": { "user_id": "20001", "username": "数码老王",
                  "avatar_url": "https://...", "verification_level": 3 },
      "board_id": "b1",
      "board_name": "小米 15 Ultra",
      "created_at": "2026-11-19 11:12:36",
      "likes": 342,
      "comment_count": 56,
      "collect_count": 88,
      "view_count": 12400,
      "liked": false,
      "collected": false,
      "allow_comment": true,
      "is_pinned": false
    }
  ],
  "followed_top": [
    { "board_id": "b1", "name": "小米 15 Ultra", "cover": "https://..." }
  ],
  "pagination": { "has_next": true, "page": 1, "total": 16 }
}

话题板块 #

板块详情

POST/api/topic.phpaction=board_detail&board_id=b1
{
  "code": 0,
  "board": {
    "board_id": "b1",
    "name": "小米 15 Ultra",
    "cover": "https://...",
    "description": "小米年度影像旗舰讨论区",
    "rules": "理性讨论,禁止人身攻击。",
    "follower_count": 12800,
    "post_count": 3421,
    "heat": 986.4,
    "download_count": 520000,
    "launch_date": "2025-02-27",
    "is_followed": true,
    "is_board_owner": false,
    "rating_enabled": true,
    "rating_summary": { "score_10": 8.7, "average_star": 4.35, "rating_count": 3 },
    "qa_enabled": true,
    "news_mode_enabled": false,
    "is_digital_topic": true,
    "rating_owner_only_enabled": false,
    "has_owner_ratings": true,
    "tab_config": [
      { "key": "default", "label": "讨论" },
      { "key": "parameters", "label": "参数" },
      { "key": "rules", "label": "规则" },
      { "key": "news", "label": "快讯" }
    ],
    "spec_tabs": [],
    "detailed_specs": [
      { "label": "处理器", "value": "骁龙 8 至尊版" },
      { "label": "屏幕", "value": "6.73 英寸 2K 120Hz" },
      { "label": "影像", "value": "1 英寸主摄 + 2 亿潜望" },
      { "label": "电池", "value": "6000mAh 90W" }
    ],
    "digital_sections": [],
    "rating_trend": []
  }
}

板块帖子列表

POST/api/topic.phpaction=board_posts
参数说明
board_id板块 ID,必填
categorydefault / parameters / rules / news
sortlatest(最新)/ reply(回复最多)/ owner(机主评价)
page / per_page分页

返回结构与信息流一致(items + pagination)。

关注 / 取关板块

POST/api/topic.phpaction=board_info
POST /api/topic.php
action=board_info&board_id=b1&follow=1     # 1 关注,0 取关,不传只查状态
# {"code":0,"board_id":"b1","is_followed":true}

评分

POST/api/topic.phpaction=rate
参数说明
board_id板块 ID
score1–10 整数,必填
dimensionsJSON 字符串,如 {"battery":9,"camera":9}
{ "code": 0, "score_10": 8.7, "average_star": 4.35,
  "rating_count": 4, "has_owner_ratings": true, "my_score": "9" }

同一用户重复评分会覆盖上一次。

帖子 #

详情

POST/api/post.phpaction=detail&post_id=p1
{
  "code": 0,
  "post_id": "p1",
  "title": "小米 15 Ultra 上手两周:这次影像真的能打",
  "content": "完整正文……",
  "cover": "https://...",
  "type": "post",
  "category": "default",
  "created_at": "2026-11-19 11:12:36",
  "likes": 342,
  "comment_count": 56,
  "collect_count": 88,
  "view_count": 12401,
  "allow_comment": true,
  "is_pinned": false,
  "author": { "user_id": "20001", "username": "数码老王",
              "avatar_url": "https://...", "verification_level": 3 },
  "board": { "board_id": "b1", "name": "小米 15 Ultra" },
  "images": [ "https://...", "https://..." ],
  "liked": false,
  "collected": false,
  "vote": { "id": "v1", "options": [ { "id": "o1", "text": "值得升级", "count": 268 } ] }
}

每次调用详情会让 view_count +1;vote 仅投票帖返回。

点赞 / 收藏

POST/api/post.phpaction=like / action=collect
POST /api/post.php
action=like&post_id=p1&like=1          # like=0 取消
# {"code":0,"likes":343,"liked":true}

POST /api/post.php
action=collect&post_id=p1&collect=1    # collect=0 取消
# {"code":0,"collect_count":89,"collected":true}

删除 / 置顶 / 关闭评论(作者本人)

POST/api/post.phpaction=delete / pin / close_comment
action=delete&post_id=p1
action=pin&post_id=p1&pin=1
action=close_comment&post_id=p1        # 切换开关,返回当前 allow_comment

非作者调用返回 1005 无权限。

发帖

POST/api/post.phpaction=publish
参数必填说明
board_id是目标板块
title / content二选一标题与正文
images否逗号分隔的图片 URL,第一张作封面
cover否单独指定封面,不传则取 images[0] 或自动生成
category否default / rating / qa / article / vote / wallpaper / video
scheduled_at否定时发布时间 YYYY-MM-DD HH:MM:SS,为空立即发布
vote_options否category=vote 时的选项 JSON 数组
POST /api/post.php
action=publish&board_id=b1&title=标题&content=正文&category=default
# {"code":0,"post_id":"p09b129eb7a1d"}

评论 #

POST/api/comment.phpaction=list / create / like / delete
操作请求返回
列表action=list&post_id=p1&page=1&per_page=20items + pagination
发表action=create&post_id=p1&content=...&reply_to=c1{"code":0,"comment":{...}}
点赞action=like&comment_id=c1(再调一次取消){"likes":43,"liked":true}
删除action=delete&comment_id=c1(作者本人){"comment_id":"c1"}
{
  "id": "c1",
  "content": "夜景确实提升明显,暗部噪点少了很多。",
  "created_at": "2026-11-19 11:12:36",
  "likes": 42,
  "liked": false,
  "user": { "user_id": "20002", "username": "极客小林",
            "avatar_url": "https://...", "verification_level": 1 },
  "is_author": false,
  "is_pinned": false,
  "reply_to": ""
}

帖子关闭评论后发表返回 403 该内容已关闭评论。

用户 #

资料

POST/api/user/profile.phpaction=profile&user_id=10001
{
  "code": 0,
  "user_id": "10001",
  "username": "舟行客",
  "avatar_url": "https://...",
  "signature": "探索科技新大陆",
  "community_no": "YZ10001",
  "gender": "男",
  "verification_level": 2,
  "follower_count": 1280,
  "following_count": 30,
  "level": 3,
  "is_banned": false,
  "is_following": false,
  "is_mutual": false,
  "is_blocked": false,
  "post_count": 2
}

不传 user_id 时取当前登录用户。

用户内容列表

POST/api/user/profile.phpaction=posts
参数说明
user_id目标用户,不传取自己
tabhome / dynamic / article / favorite / review / qa
page / per_page分页

编辑资料

POST/api/user/profile.phpaction=update
action=update&username=新昵称&signature=签名&avatar_url=https://...&gender=男
# {"code":0,"user":{ ... }}

关注 / 粉丝 / 黑名单

POST/api/user/follow.phpaction=follow / list / block
操作请求
关注action=follow&user_id=20001&follow=1(follow=0 取关)
粉丝 / 关注action=list&type=followers 或 type=following&page=1
黑名单action=block&user_id=20001(block=0 解除)
# 关注返回
{"code":0,"user_id":"20001","is_following":true,"is_mutual":false}

# 列表项
{"user_id":"20001","username":"数码老王","avatar_url":"https://...","verification_level":3}

私信 #

POST/api/chat.phpaction=conversations / get_history / send

会话列表

POST /api/chat.php
action=conversations&page=1

{ "code": 0, "items": [
  { "conversation_id": "cv_10001_20001", "peer_user_id": "20001",
    "username": "数码老王", "avatar_url": "https://...", "verification_level": 3,
    "last_message": "好,那我明天再问详细参数", "last_time": "2026-11-19 13:38:33",
    "unread": 0, "last_message_sequence": 5 } ] }

历史消息

POST /api/chat.php
action=get_history&peer_user_id=20001&before_seq=0&limit=30

{ "code": 0,
  "data": [
    { "message_id": "m1", "from_me": false, "content": "在吗?想问你之前那个长焦微距的样张",
      "created_at": "13:00", "sequence": 1 },
    { "message_id": "m2", "from_me": true, "content": "在的,你说",
      "created_at": "13:02", "sequence": 2 }
  ],
  "dm_ban": false, "reason": "" }

默认返回最新 30 条并按时间正序排列;把当前窗口最小 sequence 作为 before_seq 可继续往前翻页。

发送

POST /api/chat.php
action=send&peer_user_id=20001&content=你好

{ "code": 0, "message": { "message_id": "m348c5aa10ef0", "from_me": true,
  "content": "你好", "created_at": "13:47", "sequence": 6 } }

被限制时 HTTP 403:

{ "code": 403, "msg": "私信权限已被限制",
  "reason": "含违规引流内容", "dm_ban": true }

通知 #

POST/api/notification.phpaction=list
参数说明
types逗号分隔:like_post / reply_post / follow / system,不传返回全部
page / per_page分页
{
  "code": 0,
  "items": [
    {
      "id": "n1",
      "type": "like_post",
      "text": "赞了你的帖子",
      "actor": { "user_id": "20001", "username": "数码老王", "avatar_url": "https://..." },
      "target_id": "p1",
      "target_title": "小米 15 Ultra 上手两周:这次影像真的能打",
      "created_at": "2026-11-19 13:36:33",
      "unread": true
    }
  ],
  "pagination": { "has_next": false, "page": 1, "total": 5 }
}

系统通知(type=system)没有 actor 字段。

应用库 #

榜单 / 详情

POST/api/app.phpaction=list&rank=good / detail&app_id=a1
参数说明
actionlist / detail
rankgood(好评)/ new(最新)/ hot(热门)
app_id详情时必填
{ "app_id": "a1", "name": "舟行客", "icon": "https://...",
  "summary": "数码社区客户端,看帖、发帖、私信一站式",
  "version_name": "3.2.0", "version_code": 320,
  "download_count": 152000, "rating": 4.7, "tags": ["社区", "数码"] }

上传应用

POST/api/app_upload.phpmultipart,需登录
字段说明
apkAPK 文件(必填)
icon图标图片
name应用名(必填)
summary一句话简介
version_name / version_code版本号,如 1.0.1 / 2
tags逗号分隔或 JSON 数组
curl -X POST https://api.xoar.top/api/app_upload.php \
  -H 'Authorization: Bearer <token>' \
  -F 'name=测试应用' -F 'summary=上传测试' \
  -F 'version_name=1.0.1' -F 'version_code=2' \
  -F 'apk=@app-release.apk' -F 'icon=@icon.png'

# {"code":0,"app_id":"ab3fff...","icon":"https://.../uploads/apps/ab3fff....png",
#  "apk_url":"https://.../uploads/apps/ab3fff....apk"}

更新检查

POST/api/app_update.phpapp_id + version_code
POST /api/app_update.php
app_id=a1&version_code=1

# 有新版本
{"code":0,"has_update":true,"version_code":320,"version_name":"3.2.0",
 "download_url":"https://.../uploads/apps/a1.apk","apk_url":"https://.../uploads/apps/a1.apk"}

# 已是最新
{"code":0,"has_update":false,"version_code":320,"version_name":"3.2.0"}

设备库 #

POST/api/equipment.phpaction=my_equipment / add / update / delete
操作请求
我的设备action=my_equipment&user_id=10001(不传取自己)
添加action=add&brand=小米&model=小米 15 Ultra&image=&owned_at=2025-03-02&note=主力机&rating_stars=5
修改action=update&equipment_id=e1&note=备用机&rating_stars=4
删除action=delete&equipment_id=e1
{ "code": 0, "items": [
  { "equipment_id": "e1", "brand": "小米", "model": "小米 15 Ultra",
    "image": "https://...", "owned_at": "2025-03-02",
    "owner_name": "舟行客", "note": "主力机", "rating_stars": 5 } ] }

image 留空时服务端自动生成封面图。

Web 页面(WebView 直接加载) #

用途路径参数
用户协议/web/user_agreement—
隐私政策/web/privacy_policy—
个人信息收集清单/web/personal_information_collection—
举报/web/report_post/target_type=post|user|comment、target_id
绑定手机/web/phone_binding/token(或 sgin)
登录设备管理/web/login_devices/token
黑名单管理/web/blocked_users/token
注销账号/web/account_deletion/token
等级进度/web/level_progress/sgin
下载页/web/download/uid
扫码确认/web/qr_login/qr_token
外链标题抓取/web/post/link_titles.phpurls=https://a.com,https://b.com
curl -X POST https://api.xoar.top/web/post/link_titles.php \
  -d 'urls=https://example.com,https://www.apple.com'
# {"code":0,"titles":{"https://example.com":"Example Domain"}}

页面全部移动端自适应、全站 HTTPS,可直接塞进 WebView,无需放行混合内容。

客户端接入示例 #

Kotlin + OkHttp(表单请求封装)

object Api {
    const val BASE = "https://api.xoar.top"
    private val client = OkHttpClient.Builder()
        .connectTimeout(10, TimeUnit.SECONDS)
        .readTimeout(20, TimeUnit.SECONDS)
        .build()

    fun post(path: String, params: Map<String, String>, token: String? = null): String {
        val body = params.entries.joinToString("&") {
            "${URLEncoder.encode(it.key, "UTF-8")}=${URLEncoder.encode(it.value, "UTF-8")}"
        }.toRequestBody("application/x-www-form-urlencoded; charset=UTF-8".toMediaType())

        val req = Request.Builder().url(BASE + path).post(body)
            .header("X-Sailboat-Skip-Active-Auth", "1")
            .apply { token?.let { header("Authorization", "Bearer $it") } }
            .build()

        client.newCall(req).execute().use { resp ->
            val text = resp.body?.string().orEmpty()
            if (!resp.isSuccessful) throw ApiException(resp.code, text)
            return text
        }
    }
}

// 发码
Api.post("/api/user/email.php", mapOf(
    "action" to "login_account_by_email",
    "email"  to "xora001@163.com"
))

// 校验登录
val json = Api.post("/api/user/email.php", mapOf(
    "action" to "verify_login_email",
    "email"  to "xora001@163.com",
    "code"   to code
))

curl 全流程

BASE=https://api.xoar.top

# 1. 发码
curl -s -X POST $BASE/api/user/email.php \
  -d 'action=login_account_by_email&email=xora001@163.com'

# 2. 登录,取出 token
TOKEN=$(curl -s -X POST $BASE/api/user/email.php \
  -d 'action=verify_login_email&email=xora001@163.com&code=123456' \
  | python3 -c 'import json,sys;print(json.load(sys.stdin)["token"])')

# 3. 信息流
curl -s -X POST $BASE/api/feed.php \
  -d 'action=feed&feed_type=推荐&per_page=10' \
  -H "Authorization: Bearer $TOKEN"

# 4. 点赞
curl -s -X POST $BASE/api/post.php \
  -d 'action=like&post_id=p1&like=1' \
  -H "Authorization: Bearer $TOKEN"

联调账号 #

账号邮箱密码说明
舟行客(10001)xora001@163.com123456主测试号,已有设备 / 通知 / 私信
数码老王(20001)laowang@example.com123456内容较多的作者号
极客小林(20002)xiaolin@example.com123456—
摄影阿May(20003)may@example.com123456—
音频控老陈(20004)laochen@example.com123456—

演示数据规模

对象数量备注
板块5小米 15 Ultra / iPhone 17 Pro / WH-1000XM6 / 摄影器材 / 智能家居
帖子16含置顶、投票帖、机主评价、快讯、问答
评论8含楼中楼
通知5点赞 / 回复 / 关注 / 系统
私信1 会话 5 条10001 ↔ 20001
应用 / 设备5 / 3榜单与详情可直接看

运维与自检 #

项值
服务管理systemctl status|restart|stop xoar-api
监听地址127.0.0.1:8080
代码目录/www/wwwroot/api.xoar.top
配置文件/www/wwwroot/api.xoar.top/config.json
应用日志/www/wwwlogs/api.xoar.top.server.log
访问日志/www/wwwlogs/api.xoar.top.log
数据库MySQL 5.7 · 库 xoar_api · 账号 xoar_api@127.0.0.1
证书/www/server/panel/vhost/cert/api.xoar.top/

重新编译发布

cd /www/wwwroot/api.xoar.top
PATH=$PATH:/usr/local/go/bin go build -o bin/api-server .
systemctl restart xoar-api

三条自检命令

curl -s https://api.xoar.top/healthz
curl -s -X POST https://api.xoar.top/api/feed.php -d 'action=feed&per_page=1' | head -c 200
systemctl is-active xoar-api nginx mysql
图片当前由服务端生成的 SVG 承载;要切对象存储,只需改 config.json 的 site_url 与上传落盘逻辑,接口字段不变。

更新日志 #

日期内容
2026-11-19v1.0:接口全量上线(登录 / 信息流 / 板块 / 帖子 / 评论 / 搜索 / 用户 / 私信 / 通知 / 应用库 / 设备库 / Web 页面);HTTPS 证书覆盖 xoar.top 与 api.xoar.top;80 端口网页 301、接口 POST 直通