NARIX - NASA Adaptive RESP2/3 Infrastructure eXchange（NASA 自适应 RESP2/3 基础设施交换层）

NARIX 是使用 Rust 编写的高性能 RESP2/RESP3 多 KV 代理与托管复制 HA 控制面。它的核心差异不在转发：数据面之外，NARIX 直接承担主从拓扑的探测、fencing、切换、互斥协调与持久化编排——这些是业务直连或普通代理都拿不到的能力。一个进程可以运行多个相互隔离的代理监听器；每个 proxies[] 项拥有独立的连接限制、连接池、只读策略、指标和运行状态。

NARIX 当前提供五种数据面模式：

standalone：固定单后端透明代理。
sentinel：按 Redis Sentinel 客户端协议发现并校验当前主节点，切主后更新本地连接资源。
cluster：标准槽位 Cluster 的单入口代理，负责拓扑加载、槽位路由、MOVED/ASK 和跨节点聚合。
cluster-node-proxy：为标准槽位 Cluster 的每个节点提供一对一代理地址，并改写集群拓扑和重定向地址。
replication-ha：按 backend_profile 加载产品适配器，执行主从探测、保护、fencing 和协同切换；除 Kvrocks 外还可动态编排持久化责任。

为什么是 NARIX：托管复制 HA 架构

如果只需要转发 RESP，业务直连后端确实更短。NARIX 的价值在 replication-ha：把每个业务都要重复解决、又极难做对的主从高可用问题，收敛成一个经过固定版本验证的控制面。

        业务客户端（普通 Redis 客户端，零 SDK 改造）
                          │ 稳定接入地址
             ┌────────────▼────────────┐
             │        NARIX 数据面      │ 只路由到唯一已验证主节点
             │   保护模式 fail-closed    │ 切主后主动关闭旧代长连接
             └────────────┬────────────┘
                          │
             ┌────────────┼────────────┐
             ▼            ▼            ▼
          master ◄─── replica      replica
             ▲                         │
             └─────────────────────────┘
          全部副本直连当前主节点；级联漂移会被自动修复

   NARIX HA 控制面对全部节点持续探测并执行：
   候选延迟门禁 · 故障确认后先断路 · fencing/切换 · 级联副本修复
   动态持久化编排（单节点由主节点承担快照；多节点责任在副本间交接并验证）
   多实例互斥：local-file / Redis 租约 / 内置 2 节点与多数派协调集群

与业务直连或 Sentinel 客户端方案对比：

关注点	业务直连 / Sentinel 客户端	NARIX replication-ha
切主时的业务侧	每个业务都要实现 Sentinel 协议、拓扑刷新和重试	客户端零改造；NARIX 收敛路由并主动关闭旧主长连接，旧响应不外泄
双主与数据回退	无 fencing，脑裂窗口靠运气	故障确认后先关闭路由；强隔离可在提升前 fencing；候选按复制证据 fail-closed 门禁
多个接入点并存	各实例独立判断，可能同时切换	local-file/Redis 租约或内置协调集群保证同一时刻只有一个执行者，失权即断路
不确定状态	客户端继续写向可能的旧主	保护模式：无法证明安全就拒绝新连接并给出明确原因，绝不乱路由
持久化对业务的抖动	master fork 快照直接打在业务路径上	快照责任编排到副本并验证交接；多副本时保留零快照热备专职接管
拓扑漂移	级联副本、错误上游长期无人发现	自动把漂移副本修复为直连当前主节点，失败退避并保持保护
多种 KV	每种产品一套接入与切换脚本	Redis/Valkey/Redict/KeyDB/Kvrocks/Dragonfly 六产品统一模式、接口与指标；产品切换语义差异由适配器吸收
配置变更	逐实例改配置、滚动重启	五种模式统一走事务热更新；集群部署可由一个成员发起多数派一致发布，安全预提交不成立时拒绝并保留旧配置

控制面的工程保证同样是架构的一部分：切代与删除存在后端副作用屏障（旧运行代退休后，任何在途操作——包括管理接口持有的句柄——都无法再改写后端）；协调动作令牌在每个外部步骤前复验；HA 观察、切换结果与持久化所有权全部进入协调状态机。这些细节见运维指南与后端逐版本认证手册。

托管复制 HA 的持久化拓扑

HA 的价值不止于"主挂了自动切"。启用 ha.persistence.enabled: true（Kvrocks 除外）后，NARIX 还会编排"谁来承担持久化"：单节点部署由主节点承担快照；多节点稳态把责任交给合格副本，让主节点不被快照 I/O 拖累，并始终保留至少一个可验证的持久化副本。

推荐生产稳态是 1 主 + 1 热备 + 至少 1 快照节点（至少 3 个健康节点）。业务只发往当前主节点，其余节点都直接跟随主节点：

                       业务读写
                          │
                          ▼
              ┌────────────────────────┐
              │   当前主节点 (master)    │  稳态关闭周期快照，不被快照 I/O 拖累
              └────────────┬───────────┘
                           │ 全部副本直连主节点（级联漂移会被自动修复）
           ┌───────────────┼────────────────┐
           ▼               ▼                ▼
     热备 hot-standby   快照节点 1        快照节点 N
     关周期快照         执行周期快照       执行周期快照
     专职故障接管        承担持久化责任     承担持久化责任

三个角色由运行时根据节点实际主从状态、复制延迟和稳定时间动态选择，nodes 只是候选清单——不能把某个地址永久钉成主节点或热备。运行时按当前健康从节点数量在三种拓扑间自动切换：

健康主	合格从	拓扑（状态接口 `topology`）	说明
单节点配置：1	0	`single-master-snapshot`	只有配置本来就只有一个节点时，主节点承担快照。
多节点配置：1	0	`none` / `protected`	多节点拓扑失去全部合格副本时不把持久化责任偷渡回主节点；按 `fail_closed` 保持保护并等待副本恢复。
1	1	`single-replica-snapshot`	自动取消独立热备，唯一从节点既做快照 owner 又是故障切换候选；快照 I/O 与接管职责落在同一节点，属可用性降级。
1	≥2	`hot-standby-replica-snapshots`	选 1 个稳定低延迟从节点做无快照热备（专职接管），其余从节点全部承担快照。这是推荐稳态。

节点数建议：3 个是满足"1 主 + 1 热备 + 1 快照"的最低数量；若要求任意 1 个节点故障后仍保留这三个角色，建议至少 4 个节点（1 主 + 1 热备 + 2 快照）。主节点故障后原热备优先晋升；只有 3 个节点时，在故障节点恢复或补充新节点前会暂时退化为"1 主 + 1 快照从节点"。

安全约束：启用严格持久化策略后，启动阶段会保持保护，直到首次 owner 与后端配置完成验证。交接严格按“启用新 owner → 验证 checkpoint → 停用全部旧 owner → 提交协调结果 → 发布本地拓扑”执行，任一步失败都不会把新拓扑标记为已验证；产品适配器内部每条配置写和验证轮询都会复验动作权威，多配置中途失败会在权威仍有效时恢复调用前配置。已发布拓扑也会持续与后端真实配置复核，外部 CONFIG/cron 漂移不会被本地缓存掩盖；proxy-cluster 提交的证据覆盖完整 owner 与复制链路，而不是只记录首个 owner。已知旧 owner 缺席时不能假定其已经停用，持久化无法安全收敛且 fail_closed: true 时进入保护模式而非静默失去持久化。Kvrocks 是例外——每个节点自管 RocksDB/WAL，必须 ha.persistence.enabled: false，NARIX 只收敛主从拓扑、不分配热备或快照角色。

已验证的 KV

当前固定版本支持结论如下。每项结论只适用于表中版本与已执行形态，不外推到其他版本、托管服务或未执行拓扑。

后端与固定版本	`backend_profile`	已验证范围
Redis 8.2.2	`redis`	全量原生命令；standalone、Cluster、cluster-node-proxy、Sentinel、replication-ha 计划切换与 RDB/AOF 动态持久化
Valkey 9.1.1	`valkey`	全量原生命令；standalone、Cluster、cluster-node-proxy、Sentinel、replication-ha 计划切换与 RDB/AOF 动态持久化
Dragonfly 1.39.0	`dragonfly`	308 项原生命令；standalone、复制、replication-ha 切换与动态快照责任编排
Apache Kvrocks 2.16.0	`kvrocks`	全量原生命令；standalone、官方 Cluster/Controller、replication-ha 主从切换；各节点保持 RocksDB/WAL 持久化
Microsoft Garnet 1.1.9	`garnet`	336 项原生可执行命令；standalone、ACL、Lua、Vector、多数据库及 Cluster 适用门禁
KeyDB 6.3.4	`keydb`	236 项原生命令；standalone、认证、Cluster 命令面、真实槽位路由、replication-ha 计划切换与 RDB/AOF 动态持久化
Redict 7.3.6	`redict`	392 项原生命令；standalone、认证、Cluster、Sentinel、replication-ha 计划切换与 RDB/AOF 动态持久化
Pika 3.5.6	`pika`	190 项原生外部命令；standalone、认证、主从、Pika/Codis 槽接口及生命周期
Tendis 2.8.0	`tendis`	225 项运行时命令零未执行；standalone、主从、官方 Cluster、真实槽迁移和 cluster-node-proxy

Tendis 的 225 项结果中，204 项为成功语义，17 项为内部复制/迁移角色命令，2 项为后端原生缺陷，1 项为显式客户端边界，1 项为官方 TODO 桩；遗留 NARIX 缺陷为 0。

配置层的模式准入如下：

模式	可用 `backend_profile`
`standalone`	`redis`、`valkey`、`dragonfly`、`kvrocks`、`garnet`、`keydb`、`redict`、`pika`、`tendis`
`sentinel`	`redis`、`valkey`、`redict`
`cluster`	`redis`、`valkey`、`kvrocks`、`garnet`、`keydb`、`redict`、`tendis`
`cluster-node-proxy`	`redis`、`valkey`、`kvrocks`、`garnet`、`keydb`、`redict`、`tendis`
`replication-ha`	`redis`、`valkey`、`dragonfly`、`redict`、`kvrocks`、`keydb`

注意：

Pika/Codis 槽接口不是标准 Redis Cluster 协议，因此 Pika 使用 standalone 透明接入，不能配置为 cluster 或 cluster-node-proxy。
sentinel 只消费 Sentinel 已提交的主节点拓扑，不发起选主、REPLICAOF、fencing 或 Sentinel 配置修改。
六个托管复制产品统一使用 mode: replication-ha，由 backend_profile 选择适配器，不存在产品专属模式入口。
Kvrocks 的 replication-ha 只管理主从拓扑，必须设置 ha.persistence.enabled: false；Redis、Valkey、Redict、KeyDB 和 Dragonfly 可使用产品原生动态持久化。
云托管 RESP 服务的 TLS、ACL、网络和故障转移必须在目标服务上独立认证，本地容器结果不能替代。
命令分类、路由策略和模式限制见 command-matrix.md；固定版本、已验证形态和已知边界以本节表格为准。

构建与启动

需要稳定版 Rust 工具链。发布构建使用锁定依赖：

cargo build --release --locked

使用外部配置启动：

RUST_LOG=narix=info target/release/narix --config=/etc/narix/narix.yml

也可以通过环境变量指定：

NARIX_CONFIG=/etc/narix/narix.yml target/release/narix

--config 优先于 NARIX_CONFIG。进程会在打开业务监听前完成配置解析、强类型校验、代理名称去重和监听地址冲突检查；失败时直接退出。

最小可运行配置

以下配置只保留启动和基本运维所需字段。示例密码和 token 必须在部署前替换；后端需要 ACL 或密码时再增加 username、password。

standalone

固定单后端的透明代理。业务侧看到的仍是一个普通 RESP 端点，NARIX 在中间补齐直连拿不到的治理能力：

全命令类别透明透传，前端 pipeline 严格保序；前端是 pipeline 时到后端同样保持 pipeline。
Pub/Sub、阻塞命令、事务和连接绑定命令自动进入 DedicatedTunnel，独享连接并受活跃上限、排队容量与获取超时约束，慢消费者不会拖垮普通请求的连接池。
auth_mode: terminate 前端认证由 NARIX 终止、后端独立认证，业务侧不再持有后端密码；backend-inject 兼容旧内网免认证接入。
read_only: true 时写命令与全部脚本执行入口按失败关闭原则拒绝，只读查询保持可用。
每个代理项独立的连接上限、队列、帧/批大小与超时预算，以及独立指标；NARIX 到后端支持受 CA/SNI 校验的 RESP TLS 与可选 mTLS。
九个后端产品全部准入（见上方模式准入表）；Pika/Codis 等非标准槽位产品也经由该模式透明接入。

下面以 Redis 为例。接入其他已验证 KV 时，替换 backend_profile、host 和 port：

admin: # 管理端 HTTP 服务配置。
  enabled: true # 启用健康、状态和指标接口。
  listen: 127.0.0.1:18080 # 管理端监听地址。
  token: "replace-with-a-long-random-admin-token" # 管理 API 令牌，部署前必须替换。

proxies: # 业务代理项列表。
  - name: redis-primary # 代理项唯一名称。
    backend_profile: redis # 后端产品能力档案。
    mode: standalone # 固定单后端模式。
    listen_host: 0.0.0.0 # 业务 listener 绑定地址。
    listen: 7001 # 客户端连接 NARIX 的端口。
    host: 127.0.0.1 # 固定后端主机。
    port: 6379 # 固定后端端口。
    frontend_password: "replace-with-a-long-random-client-password" # 客户端连接 NARIX 使用的密码。
    auth_mode: terminate # NARIX 终止前端认证并独立认证后端。

完整配置：docs/configuration/standalone.yml

sentinel

面向已有 Redis Sentinel 体系的动态单主代理。业务客户端不需要实现 Sentinel 协议，只连 NARIX 一个稳定地址：

按 Sentinel 客户端协议查询已提交的当前主节点，并校验候选节点角色确实为 master 后才路由，不盲信 Sentinel 应答。
订阅 +switch-master 事件即时感知切主，另有周期刷新兜底；切主后更新本地连接资源并执行安全路由，无法确认安全主节点时拒绝新连接而不是乱路由。
定位是 Sentinel 拓扑的消费者：不发起选主、不执行 REPLICAOF、不做 fencing、不修改 Sentinel 配置——需要 NARIX 亲自管理主从时应使用 replication-ha。
Sentinel 控制连接与业务数据连接的认证、TLS 完全独立配置，互不复用。
当前准入 redis、valkey、redict。

业务客户端只连接 NARIX；NARIX 查询 Sentinel、校验候选节点为 master，再把业务请求发送到当前主节点：

admin: # 管理端 HTTP 服务配置。
  enabled: true # 启用健康、状态和指标接口。
  listen: 127.0.0.1:18080 # 管理端监听地址。
  token: "replace-with-a-long-random-admin-token" # 管理 API 令牌，部署前必须替换。

proxies: # 业务代理项列表。
  - name: redis-sentinel # 代理项唯一名称。
    backend_profile: redis # Sentinel 模式当前准入 redis、valkey、redict。
    mode: sentinel # Sentinel 动态单主模式。
    listen_host: 0.0.0.0 # 业务 listener 绑定地址。
    listen: 7001 # 客户端连接 NARIX 的端口。
    sentinel_master_name: mymaster # Sentinel 监控的服务名称。
    sentinel_nodes: 192.0.2.11:26379,192.0.2.12:26379,192.0.2.13:26379 # Sentinel 控制节点。
    frontend_password: "replace-with-a-long-random-client-password" # 客户端连接 NARIX 使用的密码。
    auth_mode: terminate # NARIX 分别处理前端、Sentinel 和数据节点认证。

完整配置：docs/configuration/sentinel.yml

cluster

标准槽位 Cluster 的单入口代理：业务客户端把 NARIX 当普通单机 Redis 使用，不需要 Cluster 客户端能力。

NARIX 负责拓扑加载与周期刷新、按 key 槽位路由、吸收 MOVED/ASK 重定向；跨槽多 key 命令按槽拆分、并发执行并聚合结果，pipeline 响应严格保序。
适合让不支持 Cluster 协议的旧客户端、框架或语言栈接入集群，也适合把集群拓扑变化对业务完全屏蔽。
共享后端通道固定使用 RESP2；HELLO 3 明确返回 NOPROTO，不虚假宣称 RESP3。会话状态类命令（如 RESET）在单入口语义下无法安全映射到具体节点时明确拒绝。
配置热更新预检会刷新拓扑并校验 16384 个槽位完整且无冲突后才发布。
当前准入 redis、valkey、kvrocks、garnet、keydb、redict、tendis。

nodes 是标准槽位 Cluster 的 seed 列表：

admin: # 管理端 HTTP 服务配置。
  enabled: true # 启用健康、状态和指标接口。
  listen: 127.0.0.1:18080 # 管理端监听地址。
  token: "replace-with-a-long-random-admin-token" # 管理 API 令牌，部署前必须替换。

proxies: # 业务代理项列表。
  - name: redis-cluster # 代理项唯一名称。
    backend_profile: redis # 标准槽位后端能力档案。
    mode: cluster # Cluster 单入口模式。
    listen_host: 0.0.0.0 # 业务 listener 绑定地址。
    listen: 7001 # Cluster Client 连接 NARIX 的端口。
    nodes: 192.0.2.11:6379,192.0.2.12:6379,192.0.2.13:6379 # 逗号分隔的 Cluster seed，使用文档专用地址。
    frontend_password: "replace-with-a-long-random-client-password" # 客户端连接 NARIX 使用的密码。
    auth_mode: terminate # NARIX 终止前端认证并独立认证后端。

完整配置：docs/configuration/cluster.yml

cluster-node-proxy

保留 Cluster Client 语义的节点级代理：业务继续使用标准 Cluster 客户端，但每个真实节点都经由一个 NARIX listener 暴露。

改写 CLUSTER SLOTS、CLUSTER NODES、MOVED 和 ASK 中的节点地址为公布地址，客户端拿到的永远是可达的代理地址。
aliases 用于归一化后端可能返回的主机名、容器名或内网地址，防止重定向泄漏业务不可达的原始地址。
适合客户端位于 NAT/防火墙之外、或需要为每个集群节点独立做连接治理与指标的场景；terminate 模式下同样由 NARIX 终止前端认证。
槽位迁移、MOVED/ASK 与节点故障语义与直连集群一致，由客户端按 Cluster 协议处理。
当前准入 redis、valkey、kvrocks、garnet、keydb、redict、tendis。

每个真实 Cluster 节点必须有唯一的代理监听端口；advertise_host/advertise_port 是返回给 Cluster Client 的可达地址：

admin: # 管理端 HTTP 服务配置。
  enabled: true # 启用健康、状态和指标接口。
  listen: 127.0.0.1:18080 # 管理端监听地址。
  token: "replace-with-a-long-random-admin-token" # 管理 API 令牌，部署前必须替换。

proxies: # 业务代理项列表。
  - name: redis-cluster-nodes # 代理项唯一名称。
    backend_profile: redis # 标准槽位后端能力档案。
    mode: cluster-node-proxy # Cluster 节点一对一代理模式。
    listen_host: 0.0.0.0 # 子 listener 默认绑定地址。
    cluster_node_advertise_host: narix.example.internal # 返回给 Cluster Client 的统一可达主机。
    frontend_password: "replace-with-a-long-random-client-password" # 客户端连接节点代理使用的密码。
    auth_mode: terminate # NARIX 终止前端认证并独立认证后端。
    node_proxies: # 真实节点与代理 listener 的映射表。
      - backend: 192.0.2.11:6379 # 第一个真实 Cluster 节点，示例使用文档专用地址。
        listen: 17001 # 第一个节点代理监听端口。
        advertise_port: 17001 # 返回给 Cluster Client 的第一个代理端口。
      - backend: 192.0.2.12:6379 # 第二个真实 Cluster 节点。
        listen: 17002 # 第二个节点代理监听端口。
        advertise_port: 17002 # 返回给 Cluster Client 的第二个代理端口。
      - backend: 192.0.2.13:6379 # 第三个真实 Cluster 节点。
        listen: 17003 # 第三个节点代理监听端口。
        advertise_port: 17003 # 返回给 Cluster Client 的第三个代理端口。

完整配置：docs/configuration/cluster-node-proxy.yml

replication-ha

托管复制 HA 的唯一模式入口，架构与对比见上文《为什么是 NARIX：托管复制 HA 架构》。配置层面的要点：

backend_profile 选择产品适配器，当前放行六个固定版本产品；产品切换语义差异（Redis 系 FAILOVER TO、Dragonfly 先升后降、Kvrocks CLIENT PAUSE+SLAVEOF）由适配器吸收，管理接口统一为 /ha/*。
ha 块是后端无关的控制面配置：探测周期与独立探测超时、故障判定阈值、复制延迟门禁、auto_failover 开关、fencing 模式、协调器（none/local-file/redis/proxy-cluster）。coordinator.mode 省略时自动解析：组了内置协调集群（coordination.enabled=true）自动为 proxy-cluster（集群里只有 leader 切主，其余节点只观察）；单实例自动为 none（进程内串行）。组集群时显式配非 proxy-cluster 会被启动校验拒绝，从源头堵死多实例各自切主的双主风险。
产品持久化参数放在 ha.persistence.<product> 子块；Kvrocks 必须 ha.persistence.enabled: false。
自动故障转移默认开启（ha.auto_failover: true）：主节点达到连续失败阈值后先关闭路由，再经过协调、fencing 和候选门禁恢复服务。默认 fencing.mode: manual 是无需脚本的软隔离，允许旧主恢复到被降级之间存在短暂双写风险；生产零脑裂目标必须使用经真实基础设施演练的 external-command。
人工拓扑动作不是绕过安全门禁的后门：failover/switchover/promote/replicaof/fence 与自动切主使用同一协调权威；人工 promote 也必须先 fencing 旧主。产品适配器在每条角色/复制写命令及等待确认期间持续复验租约或动作令牌，切主结果成功提交后才发布本地新主路由。
观察者模式（ha.observer: true）：控制面只探测和跟随，绝不发送后端控制命令，手动拓扑接口一并拒绝；切路由需要证据：旧主降级证词立即跟随，旧主永久死亡时按“确认宕机 + 接管者连续稳定”的受限通道自动恢复；证据不足与双主期间进入保护。observer 不限制业务命令，旁路只读端点必须同时配置 read_only: true。
运维全套接口：GET /ha/topology|master|replicas，POST /ha/failover|switchover，POST /ha/node/{node}/promote|replicaof/{master}|fence。

这是以 Dragonfly 为例的单实例自动切换最小配置，适合本地验证或能接受软隔离风险的单控制面部署。nodes 中每项格式为 客户端地址@复制地址；接入其他已验证产品时替换 backend_profile 和节点地址，并使用下方对应全量 YAML 的产品持久化块：

admin: # 管理端 HTTP 服务配置。
  enabled: true # 启用健康、HA 状态和指标接口。
  listen: 127.0.0.1:18080 # 管理端监听地址。
  token: "replace-with-a-long-random-admin-token" # 管理 API 令牌，部署前必须替换。

proxies: # 托管复制 HA 业务代理项列表。
  - name: replication-ha-dragonfly # 代理项唯一名称。
    backend_profile: dragonfly # 选择 Dragonfly 的 replication-ha 适配器。
    mode: replication-ha # 托管复制 HA 的唯一模式入口。
    listen_host: 0.0.0.0 # 业务 listener 绑定地址。
    listen: 7001 # 客户端连接该托管复制代理的端口。
    nodes: 198.51.100.11:6379@198.51.100.11:6379,198.51.100.12:6379@198.51.100.12:6379 # 节点清单，每项为客户端地址@复制地址，使用文档专用地址。
    frontend_password: "replace-with-a-long-random-client-password" # 客户端连接 NARIX 使用的密码。
    auth_mode: terminate # NARIX 终止前端认证并独立认证后端。
    ha: # 后端无关的 HA 控制面配置。
      auto_failover: true # 默认即 true：确认主故障后先保护路由，再自动选择并提升候选。
      fencing: # 旧主隔离策略。
        mode: manual # 默认软隔离：切主后靠 REPLICAOF 把旧主降级为副本；零脚本，但存在短暂双写风险。
      coordinator: # 单实例用默认 none（进程内串行化）；多实例部署必须改 proxy-cluster/redis 防双主。
        mode: none

上面几乎全是默认值——auto_failover、fencing.mode、coordinator.mode 都可省略。默认值解决的是单进程动作串行和自动恢复，不承诺零脑裂。生产强隔离把 fencing.mode 改为 external-command 并配置隔离程序；跨机器多实例改用 proxy-cluster 或独立 Redis 协调器，完整模板见下方。

完整单节点配置：docs/configuration/replication-ha-dragonfly.yml

内置协调集群生产模板：docs/configuration/replication-ha-dragonfly-proxy-cluster.yml

其他产品完整配置：

生产自动切换必须同时配置可靠的 external-command fencing 和与部署范围匹配的互斥机制：单实例可使用进程内锁，但必须保证没有进程重叠；跨进程/跨机器部署使用 proxy-cluster 或独立 Redis。跨机器新部署优先使用至少三个成员的内置多数派协调；local-file 只协调同机进程。

运维检查

健康和就绪端点不要求 token：

curl -fsS http://127.0.0.1:18080/health
curl -fsS http://127.0.0.1:18080/ready

状态与指标接口需要管理 token：

curl -fsS \
  -H 'Authorization: Bearer replace-with-a-long-random-admin-token' \
  http://127.0.0.1:18080/status

curl -fsS \
  -H 'Authorization: Bearer replace-with-a-long-random-admin-token' \
  http://127.0.0.1:18080/metrics

负载均衡健康检查应使用 /ready，不要使用只表示进程存活的 /health。管理端还接受 X-Admin-Token: <token>。

业务冒烟：

redis-cli -h 127.0.0.1 -p 7001 \
  -a replace-with-a-long-random-client-password PING

配置入口

配置加载优先级从低到高：

zcf/application.yml
同目录 application-${NARIX_PROFILE}.yml
--config 或 NARIX_CONFIG 指定的外部文件
外部文件同目录的 ${name}-${NARIX_PROFILE}.yml
NARIX_ 字段环境变量
${...} 配置占位符解析

支持 YAML、JSON 和 TOML。文件显式写出 proxies[] 或 node_proxies[] 时，该数组表示完整期望集合：同 name 或 backend 的条目继承低优先级文件中未覆盖的字段，未出现在高优先级数组中的条目会被删除；省略整个数组才表示全部继承。环境变量仍按身份或下标定向覆盖，不删除其他数组项。

默认开启配置热更新。修改外部配置后，NARIX 会在连续两次读取到相同有效摘要时尝试发布；也可以显式校验或发布。涉及 HA 拓扑、持久化责任或未确认多主证据时，发布仍须通过旧运行代的安全预提交，失败会保留原配置和原运行代：

curl -fsS \
  -H 'Authorization: Bearer replace-with-a-long-random-admin-token' \
  -X POST http://127.0.0.1:18080/config/validate

curl -fsS \
  -H 'Authorization: Bearer replace-with-a-long-random-admin-token' \
  -X POST http://127.0.0.1:18080/config/reload

单节点部署直接切换代理运行代。启用进程级协调集群后，只需在任意一个 NARIX 成员修改并提交一次；请求会转交领导节点，以多数派预检和共识提交同步到其他成员。落后成员在追平已提交 revision 前不开放数据面，本地旧文件不能覆盖集群新版本。

更多配置：

指标与 Grafana

GET /metrics 暴露进程 CPU、RSS、线程、文件描述符、前后端连接、命令、pipeline、DedicatedTunnel、Cluster、Sentinel 和托管复制 HA 指标。仓库内置的监控文件：

文件	用途
`dashboards/prometheus.yml`	单个 NARIX 进程抓取模板
`dashboards/prometheus-cluster.yml`	多个 NARIX 节点逐节点抓取模板
`dashboards/grafana-datasource.yml`	Grafana Prometheus 数据源
`dashboards/grafana-dashboard-provider.yml`	Grafana dashboard provider
`dashboards/narix-overview.json`	支持集群、节点和代理筛选的 NARIX 仪表盘

NARIX 集群中每个进程都独立暴露管理端，Prometheus 必须逐节点抓取，不能只抓负载均衡地址。集群内各任务的 environment 和 narix_cluster 标签保持一致，narix_node 必须唯一。详细部署与告警处理见运维指南。

生产约束

生产业务入口建议使用 auth_mode: terminate，不要无认证暴露代理端口。
管理端默认要求 token；allow_unauthenticated: true 只用于本地测试或可信隔离网络。
业务 RESP 入口不原生终止 TLS；跨不可信网络时应由受信四层入口、隧道或服务网格终止 TLS。
NARIX 到业务数据节点支持受 CA/SNI 校验的 RESP TLS；Sentinel 控制连接可独立启用 TLS，两套证书和 ACL 互不复用。
coordination.tls 只保护 NARIX 成员间的 gRPC 控制端口，不能替代业务入口加密。
replication-ha 达到主故障阈值、观察到未确认新主或双主时会关闭路由；负载均衡必须按 /ready 摘挂。
生产自动故障转移必须具备可靠 fencing 和与部署范围匹配的协调门禁；不能把不可确认的旧主直接视为已隔离。
ha.persistence.enabled: true 是持久化责任编排，不是零数据丢失 WAL；异步复制仍有 RPO 窗口。
Kvrocks 必须保持 ha.persistence.enabled: false，各节点自己的 RocksDB/WAL、备份和磁盘可靠性由部署侧负责。
按文件描述符、后端 maxclients、业务 pipeline 和内存预算设置连接、队列与帧上限。
cluster-node-proxy 的别名应覆盖可能出现在 CLUSTER SLOTS、CLUSTER NODES、MOVED 和 ASK 中的后端地址。

验证

cargo fmt --all -- --check
cargo check --locked --all-targets
cargo clippy --all-targets --locked -- -D warnings
RUSTDOCFLAGS='-D warnings -D missing_docs' cargo doc --locked --no-deps
cargo test --locked --all-targets

许可证

本项目采用 Apache License 2.0，详见 LICENSE。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
dashboards		dashboards
docs		docs
proto		proto
src		src
zcf		zcf
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
build.rs		build.rs
command-matrix.md		command-matrix.md

Navigation Menu

Repository navigation

About

Repository files navigation

NARIX - NASA Adaptive RESP2/3 Infrastructure eXchange（NASA 自适应 RESP2/3 基础设施交换层）

为什么是 NARIX：托管复制 HA 架构

托管复制 HA 的持久化拓扑

已验证的 KV

构建与启动

最小可运行配置

standalone

sentinel

cluster

cluster-node-proxy

replication-ha

运维检查

配置入口

指标与 Grafana

生产约束

验证

更多文档

许可证

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

NARIX - NASA Adaptive RESP2/3 Infrastructure eXchange（NASA 自适应 RESP2/3 基础设施交换层）

为什么是 NARIX：托管复制 HA 架构

托管复制 HA 的持久化拓扑

已验证的 KV

构建与启动

最小可运行配置

standalone

sentinel

cluster

cluster-node-proxy

replication-ha

运维检查

配置入口

指标与 Grafana

生产约束

验证

更多文档

许可证

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages