RetroShare 0.6.7 API 使用详解

目标：面向服务器运维，系统讲解 RetroShare 0.6.7 headless 服务的 JSON API 管理面——端口与调用约定、鉴权矩阵、账号引导、好友互信端到端流程与各功能域常用方法。全部路径、参数与响应均在 Ubuntu 22.04 双节点环境实测（含一次跨节点互信全流程）。环境准备见《Ubuntu 22.04 安装 RetroShare 0.6.7 指南》。

一、API 概览与运行环境

1.1 开启方式与监听地址

JSON API 由 retroshare-service 的两个参数控制：-J <端口> 开启（缺省 9092），-P <地址> 指定绑定地址（缺省 127.0.0.1）。本文所有实测基于 systemd unit 的启动参数：

/usr/bin/retroshare-service -c /var/lib/retroshare -s -J 9092 -P 127.0.0.1

若需跨机访问 API（例如集中运维面板），把 -P 改为 0.0.0.0 并务必配合防火墙/反向代理加固（见第六节）。实测 -P 0.0.0.0 时，同网段另一台机器可直接 curl http://<节点IP>:9092/rsLoginHelper/getLocations 拿到节点信息——公开引导端点不区分来源。

1.2 调用约定

统一约定如下（全部实测验证）：

• 路径规则：/rs<域名>/<方法名>，如 /rsPeers/getFriendList；
• 方法：绝大多数为 POST，请求体为 JSON（空参数传 {}）；唯一的常用 GET 特例是 /rsJsonApi/version（POST 亦可）；
• 响应：JSON，服务端以 4 空格缩进的格式化输出返回；
• 参数名：与 C++ 接口签名一致（如 sslId、invite、opMode），大小写敏感；
• 出错不抛 HTTP 5xx：参数被忽略时常见"空响应"或业务字段 retval:false，需要结合状态码与响应体判断。

验证 API 存活的健康检查（免鉴权）：

curl -s http://127.0.0.1:9092/rsJsonApi/version

实测回显：

{
    "major": 0,
    "minor": 6,
    "mini": 7,
    "extra": "---OBS",
    "human": "0.6.7---OBS"
}

二、鉴权机制

2.1 三类端点与实测矩阵

把 0.6.7 的端点按访问控制分为三类（每行都实测过）：

2.2 Basic 令牌

受保护端点使用标准 HTTP Basic 认证，凭据格式为 用户名:口令（用户名中不允许出现冒号），令牌在账号创建时通过 createLocationV2 的 apiUser/apiPass 字段一并授权（见第三节），落盘于账号目录 config/jsonapi.cfg。

调用示例（两种写法等价，实测均 200）：

# 写法一：curl 原生 -u
curl -s -u admin:q1w2e3r4 -X POST http://127.0.0.1:9092/rsPeers/getFriendList

# 写法二：手工构造 Authorization 头
AUTH=$(echo -n "admin:q1w2e3r4" | base64)
curl -s -X POST -H "Content-Type: application/json" \
  -H "Authorization: Basic $AUTH" -d '{}' http://127.0.0.1:9092/rsPeers/getFriendList

实测回显（新节点无好友时）：

{"sslIds":[],"retval":true}

已授权令牌可通过 /rsJsonApi/getAuthorizedTokens 查询（实测 200）：

$ curl -s -u admin:q1w2e3r4 -X POST -d '{}' http://127.0.0.1:9092/rsJsonApi/getAuthorizedTokens
{
    "tokens": [
        {
            "token": "admin",
            "type": "STR"
        }
    ]
}

2.3 状态码语义（实测）

⚠️ 重启后 409 的完整说明（含 attemptLogin 实测结论）见 6.3 节。

三、节点引导：创建账号并授权令牌

全新数据目录（无任何账号）时，retroshare-service 已启动但未登录。此时唯一入口是免鉴权的 createLocationV2：一次调用同时创建 PGP 身份 + 节点位置 + API 令牌，并自动登录。

curl -s -X POST http://127.0.0.1:9092/rsLoginHelper/createLocationV2 \
  -H "Content-Type: application/json" \
  -d '{"locationName":"node1","pgpName":"admin","password":"q1w2e3r4","apiUser":"admin","apiPass":"q1w2e3r4"}'

实测回显：

{
    "locationId": "1bb68f6a9122a6066f8501f81d172920",
    "pgpId": "15A46E459B7F315A",
    "retval": {
        "errorNumber": 0,
        "errorCategory": "generic",
        "errorMessage": "Success"
    }
}

字段说明：locationName 为节点/位置显示名（一台机器一个位置），pgpName 为 PGP 个人身份名（跨位置复用），password 为 PGP 口令（备份/恢复凭据），apiUser/apiPass 即第二节的管理令牌。创建后用 getLocations（公开）核对：

{
    "locations": [
        {
            "mLocationId": "1bb68f6a9122a6066f8501f81d172920",
            "mPgpId": "15A46E459B7F315A",
            "mLocationName": "node1",
            "mPgpName": "admin"
        }
    ]
}

⚠️ 0.6.7 还有旧版 createLocation（嵌套 location 对象参数），实测提交后无响应且不建账（服务端日志报 409 "before RetroShare login"），不要使用；一律走 V2。

四、好友网络：证书互信端到端流程

RetroShare 没有中心注册概念，好友关系完全靠交换节点证书建立。本章用两个真实节点（node1 与 node2）完整走通：取证书 → 对方接受 → 双方互信 → 在线直连。API 层只有两步。

4.1 获取本节点证书

curl -s -u admin:q1w2e3r4 -X POST -d '{}' \
  http://127.0.0.1:9092/rsPeers/getRetroshareInvite | python3 -c 'import sys,json; print(json.load(sys.stdin)["retval"])'

retval 字段是一段可文本传输的证书串（内含节点 SSL 公钥、PGP 身份签名、外部 IP 与监听端口，实测单份约 600+ 字节，形如 AQcAgs0Aq ... 开头的 Base 系编码块），把它原样发给朋友即可。

4.2 对端接受证书

朋友节点调用 acceptInvite，请求体为 {"invite":"<证书串>"}：

curl -s -u friend:q1w2e3r4 -X POST -H "Content-Type: application/json" \
  -d '{"invite":"AQcAgs0Aq...(完整证书串)"}' \
  http://127.0.0.1:9092/rsPeers/acceptInvite

实测：接受方 getFriendList 立刻出现对方 sslIds；而发起方仍看不到对方——信任必须反向再来一遍（把你的证书发给对方、对方同样 acceptInvite）。第二次 acceptInvite 完成后，双方目录里互有对方。

4.3 连接建立与状态确认

证书互换后节点会经 DHT/直连地址互相发现并建链（实测同网段秒级握手）。用 getPeerDetails 确认连接态：

curl -s -u admin:q1w2e3r4 -X POST -H "Content-Type: application/json" \
  -d '{"sslId":"<对方sslId>"}' http://127.0.0.1:9092/rsPeers/getPeerDetails

实测关键字段（双方互信后）：

常见问题：若 acceptInvite 返回 retval:false，多半是证书串被截断或混入了换行转义；若长期 state 停在 1（仅 FRIEND 不在线），检查两侧 DHT 端口（UDP）与自动分配的 TCP 端口是否被防火墙拦截。

五、常用功能域方法速查

以下方法均在 0.6.7 双节点环境逐一 POST 实测（带有效令牌）。

5.1 实测方法矩阵

新节点的 GXS 域响应为空表（实测 {"retval": []} 形态），属正常现象——论坛/频道/圈子内容需要先创建或订阅（对应 createForum、createChannel 等方法，命名同域）。

5.2 rsConfig：运行模式

getOperatingMode 返回当前模式（实测新节点默认值）：

{
    "mOperatingMode": 1
}

模式取值对应源码 RsOpMode 枚举（0.6.7 权威定义）：1=FULL（全功能）、2=NOTURTLE（关闭 Turtle 匿名路由）、3=GAMING（低带宽模式）、4=MINIMAL（最小化）。setOperatingMode 的整数参数名为 opMode（另有 opModeStr 字符串重载）。getMaxDataRates 实测默认上下行均为 10000（内部 KB/s 单位，与 GUI 限速设置同源）。

5.3 rsFiles：共享目录

getSharedDirectories 返回默认共享（新节点自带 Downloads 目录共享）：

{
    "dirs": [
        {
            "filename": "Downloads",
            "virtualname": "",
            "shareflags": 128,
            "parent_groups": [],
            "parent_min_age": 0
        }
    ],
    "retval": true
}

shareflags 为共享权限位掩码（128=好友可见）；parent_groups 用于把共享限定到指定圈子。getDownloadDirectory 返回下载落盘目录（对应账号目录下 Downloads/）。

5.4 身份与 GXS 域

rsIdentity/getIdentitiesSummaries 列出节点可用的匿名身份（新节点为空数组 []；创建伪名走同域 createIdentity）。论坛/频道/圈子三个 Summaries 方法是各自域的"列表入口"，返回结构一致（元数据数组），可先列出再按 mGroupId 拉内容。

5.5 方法名差异与 404 坑（实测）

网络流传的教程路径与 0.6.7 实际存在出入，以下均在 0.6.7 实测返回 404，遇到时按括号内实测可用的入口替代：

💡 技术拓展：JSON API 的方法名由 C++ 类名与方法签名自动注册生成，属"接口即文档"的生成式 API——同一功能在不同版本中可能因签名重构而改名，这也是老教程 404 的根源。排查方法是先 grep -r "rsMail" libretroshare/src/jsonapi 看注册点，或直接对照官方 Wiki 的 JSON API 页面（按版本过滤）。

六、安全与运维实践

6.1 网络边界

• 生产环境保持 -P 127.0.0.1，通过反向代理（加 TLS 与额外认证）暴露给运维网；本组件无 Web UI 自带证书能力；
• 公开引导端点（version/getLocations/createLocationV2）永久免鉴权：绝不可把 9092 裸露公网，否则任何人都能在你的节点上创建账号（实测 -P 0.0.0.0 时跨机 createLocationV2 可用）；
• P2P 通讯端口（TCP+UDP，自动分配）与 API 端口分离，防火墙只需放行前者。

6.2 危险端点警示

/rsControl/rsGlobalShutDown 带有效令牌调用即立即关停核心（实测返回 200 后进程正常退出，systemd 场景会被 Restart=on-failure 拉起，手工实例需重新启动）。写巡检脚本时严禁"试探性"调用该端点——200 就意味着你的服务已经停了。同类需谨慎的还有 /rsJsonApi/restart 与 /rsFiles/getFileData（源码标注均需鉴权）。

6.3 服务重启后的登录现实（实测）

节点进程重启后不会自动登录（创建时的自动登录只在首建生效）：

• isLoggedIn 返回 false；受保护接口一律 409，服务端日志反复记 "blocked ... before RetroShare login"；
• /rsLoginHelper/attemptLogin 实测以 account 取 sslId/PGP Id/位置名/名@身份 多种格式传参，均返回 {"retval": 255}，未能解锁；
• 可用路径：交互式终端用 retroshare-service -U <账户名> 按提示输口令登录（systemd 常驻无 TTY 不适用）；生产实践是保持服务常驻（systemd Restart=on-failure），避免主动重启；数据目录有完整备份时，也可恢复目录后重建引导。

6.4 令牌管理

• 令牌明文落盘于 LOC06_*/config/jsonapi.cfg，目录权限应收紧为运行用户可读；
• getAuthorizedTokens 可随时核对当前生效令牌（见 2.2）；
• 多套令牌可并存，便于按用途轮换与吊销（吊销走 GUI 或授权配置文件调整）。

七、参考链接

• 组件总览：《RetroShare 介绍与选型指南》
• 安装与服务化：《Ubuntu 22.04 安装 RetroShare 0.6.7 指南》
• 官方 JSON API 文档：https://retroshare.readthedocs.io
• GitHub 仓库：https://github.com/RetroShare/RetroShare