RetroShare 0.6.7 配置参数详解

目标：一站式说清 RetroShare 0.6.7 headless 服务的全部配置面——retroshare-service 命令行参数全集、systemd 服务单元、账号目录下的落盘配置文件，以及通过 JSON API 动态读写的运行参数。所有参数、路径与实测值均在 Ubuntu 22.04 节点验证。安装与服务化前置步骤见《Ubuntu 22.04 安装 RetroShare 0.6.7 指南》，API 调用细节见《RetroShare 0.6.7 API 使用详解》。

一、配置体系总览

与多数"一个主配置文件"的软件不同，RetroShare 的配置分散在三个层面，理解分层是排查一切配置问题的前提：

三层的联动关系：命令行参数决定"以哪个数据目录、哪个端口起服务"；核心启动后加载账号目录中的落盘配置；运行期通过 JSON API 修改的参数会即时生效并在适当时机回写（落盘配置文件出现 tmp/sGn 副本与 .sgn 签名是正常现象，属配置系统的原子写与签名机制）。

二、命令行参数全集

2.1 --help 实测原文

retroshare-service --help 在 0.6.7-1 上的实测输出（原文照录，含缺省值说明）：

Options:
 -s,--stderr          stderr instead of logfile.
 -u,--udp             Only listen to UDP.
 -c,--base-dir        Set base and default directory.
 -l,--log-file        Log filename.
 -d,--debug-level     debug level. Defaults to 5.
 -i,--ip-address      Forced IP address. Defaults to 127.0.0.1.
 -o,--opmode          Operating mode Full|NoTurtle|Gaming|Minimal. Defaults to =.
 -p,--port            Set the listenning port. Defaults to 0.
 -t,--tor             Path to Tor executable.
 -U,--user-id         Select account and ask for password. Use "-U list" to print accounts.
 -J,--jsonApiPort     Enable JSON API. Defaults to 9092.
 -P,--jsonApiBindAddress JSON API Bind address. Defaults to 127.0.0.1.
 -h,--help            Display this Help.
 -v,--version         Display version string.

RetroShare version: 0.6.7
libretroshare version: 0.6.7---OBS

2.2 参数分组说明

💡 技术拓展：服务监听端口的常见策略有两种——固定端口与自动分配。固定端口便于防火墙精确放行与端口转发（家用 NAT 场景必须固定才能稳定被连）；自动分配避免端口冲突但要求 UPnP 或 DHT 辅助发现。RetroShare 默认自动分配（-p 0），P2P 双向可达性由 DHT 发现兜底；服务器有公网 IP 时建议固定端口简化防火墙规则。

三、systemd 服务单元

deb 包不附带 unit（需自建，原因与完整步骤见《Ubuntu 22.04 安装 RetroShare 0.6.7 指南》第五节），推荐形态与逐项解读：

[Unit]
Description=RetroShare headless service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/retroshare-service -c /var/lib/retroshare -s -J 9092 -P 127.0.0.1
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

• After/Wants=network-online.target：P2P 服务需要网络就绪后再起，避免启动初期 DHT 初始化失败；
• Type=simple：主进程即服务进程，不 fork；
• -s：日志入 journald，journalctl -u retroshare-service 直接可查（实测日志含 JSON API 拦截、DHT 等运行信息）；
• Restart=on-failure + RestartSec=5：异常退出自动拉起；注意第六节的关停端点会触发它；
• 单元内未配置内存限制：实测常驻内存仅 5.2MB（峰值 10.5MB），无调优必要。

四、落盘数据目录与配置文件

4.1 目录结构实测

账号初始化完成后，-c 指定目录下的实测结构：

/var/lib/retroshare/
├── default_cert_06.txt          # 默认账号 location id（实测 33 字节文本）
├── extensions6/                 # 插件目录
├── pgp/                         # PGP 身份密钥环
└── LOC06_<32位hex>/             # 每个账号位置一个目录（目录名即前缀+location id）
    ├── bdboot.txt               # DHT 引导节点缓存
    ├── bdfilter.txt             # DHT 过滤规则
    ├── config/                  # 服务配置文件族（见 4.2）
    ├── Downloads/               # 下载完成目录（默认共享目录）
    ├── file_sharing/            # 共享目录索引/哈希数据库
    ├── gxs/                     # 论坛/频道/圈子等 GXS 分布式数据库
    ├── keys/                    # 身份与节点密钥（见 4.2）
    └── lock                     # 运行实例锁

4.2 关键文件与目录

运维要点：整机迁移/备份只需停服后整体拷贝 -c 目录（default_cert_06.txt、pgp/、LOC06_*/ 一个不落）；config/ 下的文件由核心的配置系统管理，手工编辑易与签名机制冲突，应通过 JSON API 修改。

五、运行参数（JSON API 动态读写）

5.1 运行模式：getOperatingMode / setOperatingMode

$ curl -s -u admin:q1w2e3r4 -X POST -d '{}' http://127.0.0.1:9092/rsConfig/getOperatingMode
{
    "mOperatingMode": 1
}

实测新节点默认 1=FULL。取值对应 0.6.7 源码 RsOpMode 枚举：

运行期设置走 rsConfig/setOperatingMode（整数参数名 opMode，另有 opModeStr 字符串重载）；启动期预设走命令行 -o。两处同源，API 修改会回写配置。

5.2 带宽限速：getMaxDataRates

$ curl -s -u admin:q1w2e3r4 -X POST -d '{}' http://127.0.0.1:9092/rsConfig/getMaxDataRates

实测默认上下行均为 10000（内部单位 KB/s，与 GUI 限速设置同源）。对应设置方法为同域 setMaxDataRates；服务器大带宽场景可按需上调，弱网下调。

5.3 共享目录与下载目录

$ curl -s -u admin:q1w2e3r4 -X POST -d '{}' http://127.0.0.1:9092/rsFiles/getSharedDirectories
{
    "dirs": [
        {
            "filename": "Downloads",
            "virtualname": "",
            "shareflags": 128,
            "parent_groups": [],
            "parent_min_age": 0
        }
    ],
    "retval": true
}

• 新节点默认把 Downloads/ 以 shareflags=128（好友可见）共享；
• shareflags 是权限位掩码（128=对好友可见），配合 parent_groups 可把共享收窄到指定圈子（Circle）；
• 下载落盘目录用 rsFiles/getDownloadDirectory 查询（实测返回账号目录下的 Downloads）；
• 增删共享对应 rsFiles 域的 addSharedDirectory/removeSharedDirectory 系方法，修改即时生效并回写 config/。

5.4 JSON API 自身参数

-J/-P 只在启动参数层；运行期可查询令牌清单（rsJsonApi/getAuthorizedTokens，实测见《RetroShare 0.6.7 API 使用详解》2.2 节）。修改绑定/端口需改 unit 后 systemctl daemon-reload && systemctl restart retroshare-service。

六、生产参数建议

按场景给出推荐组合（均在实测环境验证过对应能力）：

七、常见配置问题

Q1：监听端口每次启动都变？ 默认 -p 0 由系统自动分配（实测先后出现 1946、17812、37660）。需要稳定端口的场景在 unit 的 ExecStart 中显式加 -p 7812（TCP）并放行对应 UDP（DHT 用）。

Q2：命令行 -o 与 API setOperatingMode 冲突？ 不冲突：启动时 -o 决定初始值，运行期 API 修改即时生效并回写；重启后以回写值+-o 的最终结果为准。要"每次启动都固定模式"就写死在 -o，别依赖运行期修改。

Q3：config/jsonapi.cfg 一直不存在？ 该文件在首次授权 API 令牌后才生成（实测对照：从未授权令牌的节点无此文件）。若用 createLocationV2 引导且传了 apiUser/apiPass，创建成功即落盘。

Q4：执行 -U list 卡住？ 账号目录锁（LOC06_*/lock）被运行中的服务持有，-U 系列参数必须停服后执行：systemctl stop retroshare-service → 执行 → 再启动（实测复现与解除流程）。

Q5：改了 config/ 下的 cfg 文件没生效/被改回？ 配置由核心管理并周期回写（含 tmp/sGn 副本与 .sgn 签名），手工编辑会被覆盖或因签名校验失效。统一走 JSON API（rsConfig/rsFiles 域）修改。

Q6：数据怎么备份/迁移？ 停服 → 拷贝整个 -c 目录（含 default_cert_06.txt、pgp/、全部 LOC06_*/）→ 目标机同参数起服务。PGP 口令（createLocationV2 的 password）务必另行妥善保存——密钥文件依赖它加解密。

八、参考链接

• 组件总览：《RetroShare 介绍与选型指南》
• 安装与服务化：《Ubuntu 22.04 安装 RetroShare 0.6.7 指南》
• API 调用详解：《RetroShare 0.6.7 API 使用详解》
• GitHub 仓库（源码枚举权威来源）：https://github.com/RetroShare/RetroShare