配置参考

基础

配置是一个 TOML 文件，默认名为 nostrfy.toml。用 init 创建它：

nostrfy --config nostrfy.toml init

校验它（建议每次启动前都执行）：

nostrfy --config nostrfy.toml check

每个命令都接受 --config <path>（默认 nostrfy.toml）。

通用语法：

[section]
key = "string"
key = 8080
key = [1, 2]
key = true

配置段

每个键都是可选的；缺少的键使用其默认值。

[relay] 段 — 中继身份

键详情

• private_key — 中继自身的密钥，用于签署中继生成的事件：NIP-29 群组元数据（39000-39005）和 NIP-43 角色/成员事件。用 nostrfy genkey 生成；请保密。它只在启动时读取一次，因此更改它需要重启。
• public_url — 用于校验客户端发来的带 URL 标签：NIP-42 AUTH、NIP-62 消除和 NIP-98 管理认证。为空时，中继回退到 host:port，而绑定 0.0.0.0 或 127.0.0.1 时它永远不会匹配真实客户端 URL（会记录警告）。务必设置它。
• enabled_nips 与 disabled_nips — 白名单优先：当 enabled_nips 非空时，只公布其中的 NIP，disabled_nips 被忽略。两者都需要重启。
• reject_ephemeral — 类型 20000-29999 被拒绝，但 NIP 要求转发的豁免类型仍会转发：22242、27235、28934/28935/28936、24133、23194/23195、24242 和 21059。SIGHUP 时生效。
• enabled_git — 可选的 NIP-34：接受类型 1617-1633 和 30617/30618 并公布 NIP-34。默认关闭，因为补丁负载可能很大。SIGHUP 时生效。

[server] 段 — 服务器设置

键详情

• host — 0.0.0.0 绑定所有 IPv4 接口；127.0.0.1 仅本机。
• port — 1-65535；80 端口需要 root。这一个端口同时提供 WebSocket 中继、NIP-11 文档、REST API 和 NIP-86 RPC。
• api_host — 将 REST API 专用于单个主机名，使 API 和中继可以在反向代理后共享一个端口。启动时固定 — 需要重启。
• ws_paths — root 只提供 /，inbox-outbox 只提供 /inbox 和 /outbox，all 两者都提供。启动时固定 — 需要重启。
• trusted_proxies — 只列出代理自身的地址（同主机上 nginx/Caddy 用回环地址，云端用负载均衡器的源网段）。设置后，客户端 IP 从最后一个不受信任的 X-Forwarded-For 条目推导，用于按 IP 的上限、速率限制、blockip 和日志。切勿添加客户端能直接访问的地址 — 它们可以伪造该头并绕过按 IP 限制。启动时固定 — 需要重启。

[rpc] 段 — NIP-86 管理

NIP-86 RPC 挂载在中继的公共 POST / 路由上 — 没有单独的管理端口。旧指南中 management_token 和 admin_pubkey 有时出现在 [server] 下；那些写法是这些 [rpc] 键的遗留别名。

[limits] 段 — 限制与保护

连接与消息

订阅与查询

事件

遗留别名：limits.require_pow、limits.new_pubkey_min_age_secs 和 limits.max_indexed_words 仍被接受为 relay.require_pow、relay.new_pubkey_min_age_secs 和 database.max_indexed_words 的别名。

REST API

实时扇出

[database] 段 — 数据库

键详情

• map_size — 内存映射的下限：映射始终至少以该大小打开。
• max_map_size — 上限，以稀疏虚拟预留方式打开：物理磁盘只随实际写入的数据增长。当遇到 database map is full 时提高它。
• search_index = false — 搜索仍然可用（针对内容的全词匹配）但扫描会更慢；在微型 VPS 上它可将数据库减半。小型实例推荐。
• disabled_fsync — 以持久性换取吞吐量：写入提交到操作系统页缓存，断电可能丢失最近的写入。

[daemon] 段 — 守护进程

路径相对于配置文件所在目录解析，因此守护进程更改工作目录后它们仍然有效。

[access] 段 — 访问控制

公钥白名单/黑名单不是配置键 — 它们位于中继数据库（LMDB）中并在运行时管理：

nostrfy relay allow npub1...
nostrfy relay deny npub1...
nostrfy relay list

• restrict_relay = true — 只有白名单中的公钥可以发布，而读取对所有人保持开放（任何客户端仍可订阅和获取）。
• 被拒绝的公钥在发布时始终被拒绝，读取时也永远不会被提供。
• method_grants — 非管理员公钥的 NIP-86 方法授权（公钥 → 方法名，例如允许版主使用 banevent 和 listbannedevents）。首次运行时从配置播种，之后在运行时用 NIP-86 assignmethod/unassignmethod 管理（用 listmethodassignees 查看）。只有审核和读取方法可被授权 — 权限、角色、邀请码和中继身份管理保持仅管理员，且被封禁的公钥即使有授权也会被拒绝。参见管理 API。

[blossom] 段 — Blossom 文件服务器

运行时重载（SIGHUP）

编辑文件并发送 kill -HUP $(cat nostrfy.pid) 会无需重启重载配置。大多数设置立即生效；少数在启动时固定：

[access] 不会由重载应用 — 列表在启动时播种一次，之后通过 NIP-86 在运行时管理。当需要重启的设置发生变化时日志会警告，少数启动时捕获的设置不会被重载检查。