侧边栏壁纸
博主头像
Beibingの小窝

  • 累计撰写 11 篇文章
  • 累计创建 36 个标签
  • 累计收到 2 条评论

目 录CONTENT

文章目录
教程

Astra星链-开发者接入指南

本文章具有时效性，依照本文章参考及开发前请先核对是否符合当前的状态及要求！2026-8-30

总览

欢迎来到 AstraHub 开发者接入指南。

我们诚挚邀请来自各个独立博客生态的开发者一起共建这张星链：

  - WordPress / WooCommerce 插件作者
  - Halo 插件 / 主题作者
  - Hugo / Hexo / Jekyll / Astro 等静态站点的构建钩子作者
  - Typecho / Z-BlogPHP / EMLOG 等老牌 PHP 博客系统的扩展作者
  - Ghost / Mastodon / 自建 CMS 的运营者
  - 用 Go / Rust / Node.js / Python / PHP / Java 等任何语言写自定义脚本的开发者

只要你的平台后端能发出 HTTPS 请求并计算 HMAC-SHA256，就能接入 AstraHub。本文档描述的是 Hub 服务端 API，不要求使用 Halo 插件，也不要求把密钥暴露给浏览器。

——

AstraHub 是一个面向独立博客生态的星链协作系统。它不是单纯的友链展示页，而是把博客之间原本分散、孤立的友链关系、节点身份和公开动态组织成一个可联动、可检索、可探索的博客关系网络。

接入价值：

  - 连接：把原本分散的独立博客连接起来，形成真实可见的博客关系网络。每一条友链都成为图谱中的一条边，被全网共同读取、共同放大。
  - 发现：沿着"朋友的朋友"快速触达更多与你气质相近的博主与圈层。从图谱、标签和节点关系中发现你想要的博客与创作者，不再一个个手动翻友链页。
  - 曝光：加入生态的人越多，每个博客都会获得更高的可见度——出现在更多关系链、动态流和检索结果中。
  - 圈层归属：系统会根据站点信息、内容主题与标签，把博客自动归入对应星团（圈层）。同圈层的博主彼此可见、相互发现。
  - 关系图谱：交互式星链图谱把站点之间的友链与圈层关系可视化展现。一眼看清谁在你的圈层里、谁处在网络枢纽位置、哪些节点之间存在高频连接。
  - 友链交换新范式：在 AstraHub 看到心仪的博客，直接发起友链申请，对方在自己后台一键审核通过，双向友链同步生效，整个换链过程不超过 1 分钟。
  - 跨站协作：基于 friend-invitations 协议（v1）跨站发起友链邀请、批量解析关系，配合 WebSocket 实时事件做即时通知。
  - 全网检索：聚合后的全网友链信号流（/v1/planet/feed）、友链星球（/v1/planet/links）、节点聚类（/v1/planet/clusters）、RSS 深空（/v1/planet/rss-deep-space/*）等查询能力，可接入自身后台、主题或客户端。
  - 迁移无忧：换服务器、换域名后，通过 boarding-restore 邮箱验证码恢复站点身份，原有的友链关系与圈层归属全部保留。

接入参考：

  - 入门思考与生态背景：
    https://www.aobp.cn/archives/AstraHub
    《AstraHub 星链插件 · 一篇写给独立博客生态的使用与思考》

接入流程：

  1. 注册：用一次性邀请码（X-BP-Invitation-Code）换取永久 siteId + apiKey
  2. 上报：由你的服务端采集本地友链、RSS、文章/页面数据，再主动调用 /v1/site-link-edges/push 与 /v1/graph/push 推送给 Hub
  3. 查询：由你的服务端用签名请求查询聚合后的星系数据，再回传给自己的后台、主题或客户端。友链星球、星链资讯和关系图都走签名 GET
  4. 协作：通过 friend-invitations 跨站发起友链邀请、relations/sites/batch 批量解析关系
  5. 实时：用 WebSocket 订阅 friend_invitation_* / site_link_edges_pushed / graph_pushed 等事件做即时通知

数据格式协议版本：bp.site-links.v1、bp.graph.v1、friend-invitations v1。

本文档展示的请求 / 响应为协议示例；实际接入请使用自己注册后得到的真实 siteId + apiKey，在接入方服务端生成签名并调用 Hub。

鉴权与签名

所有写操作（POST 上报）和私有读操作（GET 查询）必须带 4 个签名头：

  X-BP-Site-Id      注册时返回的 siteId
  X-BP-Timestamp    Unix 秒级时间戳（UTC）
  X-BP-Nonce        单次随机串，建议 UUID 去横线
  X-BP-Signature    HMAC-SHA256 签名（小写 hex）

签名算法（与 internal/security/signature.go 1:1 对齐）：
  canonical = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256_HEX(BODY)
  signature = HMAC-SHA256(apiKey, canonical)

要点：
  - METHOD 必须大写，PATH 不含 query string
  - GET 等无 body 时对空字符串计算 SHA-256
  - signature 输出全小写 hex，nonce 禁止复用
  - 时间窗 ±5 分钟（AllowedClockSkew），nonce 缓存 900 秒（MaxNonceCacheSeconds）

密钥轮转：调用 POST /v1/sites/credentials/rotate（带签名）即可滚动更新 apiKey；新旧 key 都被允许签验，给客户端足够时间无中断切换。

POST/v1/sites/credentials/rotate签名

轮转 API Key

滚动生成新的 apiKey；旧 key 在下一次轮转前仍然有效。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/sites/credentials/rotate

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

POST/v1/ws-token签名

申请 WebSocket Token

换取一个 2 分钟有效的短期 token，用于 wss://.../v1/ws?access_token=<token> 升级。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/ws-token

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

站点注册与恢复

POST/v1/sites/register

注册站点

用一次性邀请码换取永久 siteId + apiKey。apiKey 仅在响应中明文返回一次，必须立即持久化。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/sites/register

请求头

Accept: application/json
Content-Type: application/json
X-BP-Invitation-Code: <your_invitation_code>

请求体

{
  "name": "示例博客",
  "url": "https://example.com",
  "description": "我的博客简介",
  "rssUrl": "https://example.com/rss.xml",
  "avatarUrl": "https://example.com/avatar.png",
  "contactEmail": "owner@example.com",
  "nodeName": "示例节点",
  "category": "技术",
  "nodeAvatar": "https://example.com/owner-avatar.png"
}

POST/v1/sites/invitations/apply

申请邀请码

自助接口；管理员审核后通过运营渠道下发邀请码。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/sites/invitations/apply

请求头

Accept: application/json
Content-Type: application/json

请求体

{
  "contactEmail": "owner@example.com",
  "siteUrl": "https://example.com"
}

POST/v1/sites/boarding/send-code

发送登舱验证码

当客户端遗失 apiKey 时使用：向站点登记的 contactEmail 发送 6 位验证码。配合 /v1/sites/boarding/restore 取回 siteId + apiKey。

冷却时间内重复请求会返回 429 + RATE_LIMITED。验证码 10 分钟有效，最多输错 5 次。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/sites/boarding/send-code

请求头

Accept: application/json
Content-Type: application/json

请求体

{
  "contactEmail": "owner@example.com"
}

POST/v1/sites/boarding/restore

恢复站点接入

验证码 + contactEmail 校验通过后，Hub 滚动出新的 apiKey 一次性返回；旧的 apiKey 立即失效。

apiKey 仅在本次响应中明文返回一次，客户端必须立即落库；nodeName 与 category 字段当前同源（站点的 category）。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/sites/boarding/restore

请求头

Accept: application/json
Content-Type: application/json

请求体

{
  "contactEmail": "owner@example.com",
  "code": "123456"
}

数据上报

POST/v1/site-link-edges/push签名

友链快照上报

由接入方自己的服务端读取本地友链数据并全量上报给 Hub。Hub 按 (siteId, targetUrl) 做增量 diff，自动计算 added / updated / removed。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/site-link-edges/push

请求头

Accept: application/json
Content-Type: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

请求体

{
  "version": "bp.site-links.v1",
  "snapshotAt": "2026-05-30T12:00:00.000Z",
  "source": {
    "platform": "custom",
    "plugin": "my-plugin",
    "pluginVersion": "0.1.0",
    "siteId": "site_AbCdEf12345",
    "siteName": "示例博客",
    "siteUrl": "https://example.com"
  },
  "edges": [
    {
      "targetUrl": "https://friend1.example.org",
      "title": "好友 A 的博客",
      "description": "纯粹的写作之地",
      "logo": "https://friend1.example.org/avatar.png",
      "rssUrl": "https://friend1.example.org/rss.xml",
      "isActive": true,
      "firstSeenAt": "2025-08-01T00:00:00Z",
      "lastSeenAt": "2026-05-30T11:55:00Z",
      "updatedAt": "2026-05-30T11:55:00Z"
    }
  ]
}

POST/v1/graph/push签名

内容图谱推送

由接入方自己的服务端采集文章、页面、RSS 源、站内链接、提及与话题后推送给 Hub，用于构建跨站知识图谱。consent.granted 必须为 true，否则整批被拒。

Hub 始终只使用 bp.graph.v1。新版插件会附带 pushId 与单调 sequence；旧版 v1 插件缺少这些字段时由 Hub 在同一处理链路中生成内部身份。重复上报返回幂等成功，旧快照不会覆盖新数据。成功响应表示接收节点已同步完成当前持久化链路。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/graph/push

请求头

Accept: application/json
Content-Type: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

请求体

{
  "version": "bp.graph.v1",
  "pushId": "gpush_0123456789abcdef0123456789abcdef",
  "sequence": 1786078400001,
  "source": {
    "platform": "custom",
    "plugin": "my-plugin",
    "pluginVersion": "0.1.0",
    "siteId": "site_AbCdEf12345",
    "siteName": "示例博客",
    "siteUrl": "https://example.com",
    "nodeName": "示例节点",
    "category": "技术",
    "nodeAvatar": "https://example.com/owner-avatar.png",
    "siteRssUrl": "https://example.com/rss.xml",
    "syncReason": "post.updated",
    "owner": "owner@example.com",

数据查询

GET/v1/planet/feed签名

探索页友链信号流

聚合后的全网友链信号流，分页返回。排序：MentionCount desc → UpdatedAt desc → URL asc（稳定确定性）。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/planet/feed?page=1&size=20&tag=

Query / 路径参数说明

?page=1&size=20&tag=

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/planet/clusters签名

节点聚类

把全网友链按节点 / 主题聚类后返回。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/planet/clusters?page=1&size=200&search=

Query / 路径参数说明

?page=1&size=200&search=

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/planet/node-stats签名

节点统计

节点维度的站点数、最近活跃时间、同步成功次数。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/planet/node-stats

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/planet/broadcasts签名

全网广播

全网最近的事件流（新加入站点、关系变更、内容同步等）。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/planet/broadcasts?limit=120&hours=48

Query / 路径参数说明

?limit=120&hours=48

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/planet/links签名

聚合友链浏览（observer-aware）

当前签名站点视角下的全网聚合友链清单，游标分页。每条 item 直接挂载 relationKind / targetRegistered / targetSupportsInvitation / targetInvitationState / outboxInvitationActive 等关系与邀请字段，第三方平台无需再调 site-relations/batch 拼装。Hub 在服务端把关系卡片（mutual → one_way_out → one_way_in → 可发起邀请 → outbox-only → 普通）按 relationRankOf 统一排序置顶，单游标分两阶段（关系阶段 → 普通阶段）连续分页，前端无需本地重排或拼接。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/planet/links?size=24&tag=&cursor=

Query / 路径参数说明

?size=24&tag=&cursor=

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/sites/lookup签名

URL 反查 siteId

用站点主页 URL 反查 Hub 中的 siteId / nodeId / nodeName。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/sites/lookup?url=https://example.com

Query / 路径参数说明

?url=https://example.com

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

POST/v1/sites/lookup-batch签名

URL 批量反查

一次提交最多 64 个 URL，批量反查注册状态。每条记录字段与单查 LookupResponse 完全一致，含 invitationState / matchedBy。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/sites/lookup-batch

请求头

Accept: application/json
Content-Type: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

请求体

{
  "urls": [
    "https://friend1.example.org",
    "https://friend2.example.net"
  ]
}

POST/v1/relations/sites/batch签名

批量站点关系解析

观察者站点（请求侧）批量查询自己与目标 URL 的友链关系：mine.added / theirs.added → relationKind（mutual / one_way_out / one_way_in / none / unknown / self）。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/relations/sites/batch

请求头

Accept: application/json
Content-Type: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

请求体

{
  "targetUrls": [
    "https://friend1.example.org",
    "https://friend2.example.net"
  ]
}

GET/v1/planet/rss-deep-space签名

RSS 深空检索

检索 Hub 已索引的 RSS 内容。支持按关键词、分页、排序。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/planet/rss-deep-space?q=&page=1&size=20&sort=latest

Query / 路径参数说明

?q=&page=1&size=20&sort=latest

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/planet/rss-deep-space/browse签名

RSS 深空浏览（游标分页）

mode=browse 的游标版：返回 cursor / nextCursor 而非 page，适合资讯流无限滚动。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/planet/rss-deep-space/browse?size=24&cursor=

Query / 路径参数说明

?size=24&cursor=

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/planet/rss-deep-space/discover签名

RSS 站点发现

游标分页：按站点维度返回（每个站点的最新文章 + 文章总数 + 标签），适合做 RSS 源站发现页。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/planet/rss-deep-space/discover?size=24&cursor=

Query / 路径参数说明

?size=24&cursor=

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/planet/rss-deep-space/search签名

RSS 全文搜索

mode=search 的游标版：q 必填。命中后按 publishedAt desc 返回。响应结构与 rss-browse 完全一致。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/planet/rss-deep-space/search?q=测试&size=24&cursor=

Query / 路径参数说明

?q=测试&size=24&cursor=

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

图谱接口

GET/v1/graph/overview签名

图谱概览

全网图谱概览：summary 节点 / 站点 / 内容 / 关系数；metrics 共享信号；topNodes 头部节点列表。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/graph/overview

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/graph/nodes签名

节点列表

分页拉取所有节点（支持排序）。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/graph/nodes?page=1&size=20

Query / 路径参数说明

?page=1&size=20

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/graph/nodes/{nodeId}签名

节点详情

指定 nodeId 的节点详情（主站、活跃站点、关系、指标）。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/graph/nodes/{nodeId}

Query / 路径参数说明

路径参数 {nodeId} 替换为节点列表里的 summary.nodeId

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

GET/v1/graph/sites/{siteId}/relations签名

站点关系（推荐 + 一阶）

返回站点的关系列表：直接互引（mentions_site）、共享链接（shared_link）、同 cluster、共享 topic / group 等。适合用于关系图推荐关系和一阶关系展示。

relations[].relationType 取值：mentions_site / shared_link_interest / same_cluster / shared_group / shared_topic / recommended_site / recommended_node。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/graph/sites/{siteId}/relations?page=1&size=40

Query / 路径参数说明

?page=1&size=40

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

友链邀请

friend-invitations 协议：

  - 协议版本：v1（响应头 X-BP-Friend-Invitation-Protocol-Version: v1）
  - 流程：发起方 POST /v1/friend-invitations → 接收方在 /inbox 看到 → 接收方 POST /{id}/review → 发起方 POST /{id}/ack 回执 → 任意一方可 /cancel 或 /delete
  - 幂等：CreateRequest.idempotencyKey 推荐填写（同 idempotencyKey + fromSiteId 24h 内只创建一次）
  - 链接组：linkGroupName 表示对方期望被加到哪个友链分组，审核时可改写为最终落地分组（reviewLinkGroupName）

所有 friend-invitations 接口都返回 protocolVersion + invitation，发起方按 invitation.deliveryStatus 决定是否触发 ack。

POST/v1/friend-invitations签名

发起友链邀请

由发起方（A 站）签名调用。Hub 写入 invitation 后通过 WebSocket 实时推送给被邀方（B 站）。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/friend-invitations

请求头

Accept: application/json
Content-Type: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

请求体

{
  "toSiteId": "site_FriendA001",
  "message": "希望与你交换友链 :)",
  "linkGroupName": "技术朋友",
  "idempotencyKey": "5f3a2e0b-9c1d-4f7e-8a52-c1b9f30e72a4"
}

POST/v1/friend-invitations/{inviteId}/review签名

审核邀请（被邀方）

被邀方对 inviteId 做出 approved / rejected 决定。可选 linkGroupName 改写最终落地分组；reason 在拒绝场景必填。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/friend-invitations/{inviteId}/review

Query / 路径参数说明

路径参数 {inviteId} 替换为收件箱里某条 invitation.inviteId

请求头

Accept: application/json
Content-Type: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

请求体

{
  "approved": true,
  "reason": "",
  "linkGroupName": "我的好友"
}

POST/v1/friend-invitations/{inviteId}/ack签名

回执（发起方）

发起方在落地侧（友链页）操作完成后回写：lastError 留空表示成功，否则给出错误描述。Hub 据此终止重试链路。

请求体可以为空（{} 或缺省），Hub 会按 lastError 为空处理。失败重试请上报具体 error 字符串。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/friend-invitations/{inviteId}/ack

Query / 路径参数说明

路径参数 {inviteId} 替换为发件箱里某条 invitation.inviteId

请求头

Accept: application/json
Content-Type: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

请求体

{
  "lastError": ""
}

POST/v1/friend-invitations/{inviteId}/cancel签名

取消邀请（发起方）

发起方主动撤回未审核的邀请。已审核（approved/rejected）的不可取消。

请求体一律为空（不传或 {}）。Hub 仅校验 path 上的 inviteId 与 X-BP-Site-Id 归属。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/friend-invitations/{inviteId}/cancel

Query / 路径参数说明

路径参数 {inviteId} 替换为发件箱里某条 invitation.inviteId

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

POST/v1/friend-invitations/{inviteId}/delete签名写入数据

删除邀请记录

发起方或被邀方都可调用，删除自己一侧的邀请记录（软删，对端仍可见）。常用于清理列表。

请求体一律为空。删除是软删除（仅对调用方不可见），对端仍能查看。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/friend-invitations/{inviteId}/delete

Query / 路径参数说明

路径参数 {inviteId} 替换为收件箱或发件箱里的 invitation.inviteId

请求头

Accept: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

POST/v1/friend-relations/{peerSiteId}/remove签名写入数据

删除互链关系

删除当前站点与 peerSiteId 的 Hub 互链关系，并触发实时广播；用于“双方都移除/后台删除星球关系”场景。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/friend-relations/{peerSiteId}/remove

Query / 路径参数说明

路径参数 {peerSiteId} 替换为对方已注册站点的 siteId

请求头

Accept: application/json
Content-Type: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

请求体

{
  "reason": "站点主动移除友链"
}

POST/v1/friend-follows/{peerSiteId}/remove签名写入数据

只删除我方关注

仅移除当前站点对 peerSiteId 的单向关注/边，不要求对方同步删除。用于“我不再关注该站点，但不强制对端变更”的场景。

请求示例响应示例cURL 模板

请求 URL

https://astra.aobp.cn/v1/friend-follows/{peerSiteId}/remove

Query / 路径参数说明

路径参数 {peerSiteId} 替换为对方已注册站点的 siteId

请求头

Accept: application/json
Content-Type: application/json
X-BP-Site-Id: <your_site_id>
X-BP-Timestamp: <unix_seconds>
X-BP-Nonce: <random_nonce>
X-BP-Signature: <hmac_sha256_hex>

请求体

{
  "reason": "站点主动移除单向关注"
}

实时事件

WebSocket 鉴权流程：

  1. 调用 POST /v1/ws-token（带签名，body 为空）→ 拿到 token + expiresAt
  2. 用 token 升级：wss://astra.aobp.cn/v1/ws?access_token=<token>
     （可选）携带 lastEventId 用于断线回放

token TTL 为 2 分钟（websocketTokenTTL），且是一次性的；每次重连都需要重新申请。

真实推送的事件类型（来自服务端 publishRealtime 调用）：

  site_registered / site_restored / site_deleted
  site_link_edges_pushed / site_relation_updated
  friend_link_deleted
  friend_link_submission_created / friend_link_submission_approved / friend_link_submission_rejected / friend_link_submission_deleted
  friend_invitation_created / friend_invitation_reviewed / friend_invitation_acked / friend_invitation_cancelled / friend_invitation_deleted
  graph_pushed / graph_task_status / graph_manual_updated
  system_log / admin_login / admin_logout

错误码

错误响应格式（internal/app/apperror/common.go::Error）：

  {
    "error": {
      "code": "AUTH_INVALID_SIGNATURE",
      "message": "invalid signature"
    }
  }

鉴权类（internal/app/sitecredentialruntime/manager.go）：
  401 AUTH_MISSING_HEADERS       缺签名头
  401 AUTH_UNKNOWN_SITE          siteId 不存在
  401 AUTH_INVALID_TIMESTAMP     时间戳格式错误
  401 AUTH_EXPIRED               时间戳超出 ±5min 窗口
  401 AUTH_REPLAY                nonce 已被使用
  401 AUTH_INVALID_SIGNATURE     签名不匹配
  401 AUTH_FAILED                WebSocket token 无效
  403 SITE_BLOCKED               站点被运营封禁
  429 RATE_LIMITED               触发分钟级限流

注册类（internal/app/siteregistrationruntime/manager.go）：
  400 INVALID_INPUT              字段校验失败
  401 INVITATION_INVALID         邀请码不存在
  409 INVITATION_ALREADY_USED    邀请码已使用
  409 INVITATION_NOT_ALLOCATED   邀请码未分配
  403 INVITATION_EMAIL_MISMATCH  邀请码邮箱与 contactEmail 不一致
  409 SITE_URL_CONFLICT          URL 已被其他邮箱注册
  409 SITE_ALREADY_REGISTERED    contactEmail 已注册
  409 SITE_EXISTS                站点已存在
  500 INVITATION_MARK_USED_FAILED 站点已建但邀请码标记失败

登舱恢复类（internal/app/boardingcoderuntime）：
  400 INVALID_INPUT              邮箱或验证码格式错误
  404 SITE_NOT_FOUND             contactEmail 未关联任何站点
  401 BOARDING_CODE_INVALID      验证码错误或已过期
  409 BOARDING_CODE_LOCKED       验证码错误次数超限
  429 RATE_LIMITED               冷却时间内重复发码

friend-invitations 类（internal/app/friendinvitationruntime）：
  400 FRIEND_INVITATION_INVALID_JSON      请求体非法
  400 FRIEND_INVITATION_INVALID_INPUT     字段校验失败（toSiteId 必填等）
  404 FRIEND_INVITATION_NOT_FOUND         inviteId 不存在
  403 FRIEND_INVITATION_FORBIDDEN         不是该邀请的发起方/被邀方
  409 FRIEND_INVITATION_ALREADY_REVIEWED  已审核，不可重复审核
  409 FRIEND_INVITATION_ALREADY_CANCELLED 已取消，不可再操作
  409 FRIEND_INVITATION_DUPLICATE         相同 idempotencyKey 已存在

通用：
  400 INVALID_JSON               JSON 解析失败
  400 INVALID_BODY               请求体超过 1 MiB
  404 SITE_NOT_FOUND             目标 siteId 不存在
  500 INTERNAL_ERROR / INTERNAL_PANIC
  503 WEBSOCKET_UNAVAILABLE

重试策略：
  - 可重试：429、502、503、504、INTERNAL_ERROR
  - 不可重试：所有 4xx（除 429）；签名错误一律不主动重试

注：

Astra有N+1个站点，在api中请按照实际可用性选择

https://astra.aobp.cn/
https://astra.zzrbk.xyz/
https://astra.fryfries13.cn/
https://astra.rinty.xyz/
https://astra.lygalaxy.cn/

1
教程 技术创新 全网可见 生态连接 图谱关系 资源发现 独立博客 便捷创作 技术变革 服务器运维 高级设置 数据分析 维护页面 Halo插件 APItoken获取
版权归属： Beibing
本文链接： https://blog.zzrbk.xyz/archives/astra-openbox-on
许可协议： 本文使用《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》协议授权

评论区

播放音乐