SSPanel（mod_mu）

设置 panel_type = "sspanel" 后，katana 节点通过 mod_mu API 从 SSPanel 获取节点描述和用户列表，这与 XrayR 使用的是同一套节点 API。katana 定期轮询面板，按面板的描述构建监听器，并回传每个用户的流量和审计命中记录。

以下情况请阅读本页：让 katana 对接 SSPanel、把 SSPanel 节点从 XrayR 迁移过来，或者节点无法启动且日志中提到某个面板字段。配置文件的整体结构见 配置文件；本页只介绍 SSPanel 特有的部分。

概览

属性	katana 中的 SSPanel
panel_type	"sspanel"，不区分大小写
认证	[node.api].key，同时作为 key 和 muKey 查询参数发送
节点类型	V2ray（VMess 或 VLESS）、Trojan、Hysteria 2。Shadowsocks 会被拒绝。
节点描述	SSPanel 2021.11 及以上版本使用 custom_config（除非设置了 disable_custom_config = true），否则使用旧版 server 字符串
限速	来自面板的节点限速和每个用户的限速，或者一个本地覆盖值
审计	面板的审计规则，外加可选的本地规则文件；命中记录上报到 detectlog
未实现	在线 IP 上报（aliveip）和节点状态上报

最小示例

这个节点提供 VMess 服务。端口、传输层以及是否启用 TLS 由面板决定；证书始终来自本地文件。使用下文所示的 custom_config 时，节点在 443 端口上提供基于 WebSocket 和 TLS 的 VMess。

/etc/katana/config.toml

# A katana node for SSPanel (mod_mu): one V2ray node that serves VMess over
# TLS. The panel supplies the port, the transport and the user list; the
# certificate is always local. Replace the panel key and certificate paths.

[log]
level = "info"

[[node]]
panel_type = "sspanel"

[node.api]
host = "https://panel.example.com"
node_id = 1
key = "replace-with-the-panel-key"   # sent as both `key` and `muKey`
node_type = "V2ray"                  # V2ray serves VMess unless the panel enables VLESS
timeout = 10                         # seconds per panel request; 0 means 5
speed_limit = 0                      # Mbps; 0 keeps the panel's own limits
rule_list_path = "/etc/katana/rules.txt"
disable_custom_config = false        # read custom_config on SSPanel 2021.11 and later

[node.controller]
listen_ip = "0.0.0.0"
update_periodic = 60                 # seconds between panel polls

[node.controller.cert]
mode = "file"
cert_file = "/etc/katana/fullchain.pem"
key_file = "/etc/katana/privkey.pem"

1. 在 SSPanel 中创建节点。 类型选择 V2ray，并填写它的 custom_config（见下文 custom_config）。记下面板分配的节点 ID，以及面板配置中的 muKey。

2. 编写配置。 将面板 URL 填入 host，节点 ID 填入 node_id，muKey 填入 key。让 cert_file 和 key_file 指向与客户端所连接域名匹配的证书。

3. 检查配置。 --test 会构建面板客户端和路由器，但不会连接面板：

   katana --test -c /etc/katana/config.toml

   Configuration OK

   --test 不会拉取节点信息，因此无法判断面板给出的描述 katana 能否提供服务。例如，Shadowsocks 节点可以通过 --test，要到 katana 启动时才会被拒绝。唯一的例外是 Hysteria 2 节点：--test 还会检查它本地的 [node.hysteria] 设置和证书。

4. 启动 katana，并留意监听器日志：

   INFO katana::manager::node: node 1: listening on 0.0.0.0:443

设置

所有 SSPanel 设置都位于 [node.api] 中。对解析器而言，所有键都是可选的，但缺少 host、node_id、key 或 node_type 的节点无法连接面板或无法启动。未知的键会报错，因此像 mu_key 这样的拼写错误会让 --test 失败。

键	类型	默认值	在 SSPanel 上的含义
host	string	""	面板的基础 URL，需包含协议头，例如 "https://panel.example.com"。katana 会去掉末尾的 / 再拼接 /mod_mu/…，因此部署在子路径下的面板也能正常使用。
node_id	integer	0	SSPanel 中的节点 ID。它会出现在节点信息路径中，也会作为 node_id 查询参数发送。
key	string	""	面板的 muKey。katana 会发送两次，分别作为 key 和 muKey 查询参数，与 XrayR 的做法相同。
node_type	string（枚举）	""	V2ray（别名 vmess、vless）、Trojan、Hysteria2（别名 hysteria、hy2），或 Shadowsocks（SSPanel 节点会拒绝该类型）。不区分大小写。其他任何值，包括空值，都会以 unknown node_type 失败。别名 vless 本身并不会启用 VLESS；见 enable_vless。
enable_vless	bool	false	在 V2ray 节点上提供 VLESS 而不是 VMess。它与面板自身的 enable_vless 共同生效：任意一方开启即启用 VLESS。
vless_flow	string	""	仅在节点来自旧版 server 字符串时读取。任何非空值都会被拒绝，因为 katana 没有实现 XTLS 流控（flow）。
timeout	integer	0	每个面板请求允许的秒数，从建立连接到读完响应体。0 表示 5 秒。
speed_limit	float	0	本地的每用户限速，单位 Mbps。大于 0 的值会替换面板下发的所有限速。见 限速。
device_limit	integer	0	为兼容 XrayR 而接受，但会被忽略。
rule_list_path	string	""	本地审计规则文件，每行一个正则表达式。katana 无法读取的文件会记录日志，并视为没有规则。见 审计规则。
disable_custom_config	bool	false	始终读取旧版 server 字符串，即使面板版本为 2021.11 或更高。

[node.controller] 下的键适用于所有面板类型：update_periodic 设置轮询间隔，disable_get_rule 关闭审计规则，disable_upload_traffic 停止流量上报。详见 配置文件。

katana 向面板发起的请求

katana 会调用五个 mod_mu 接口。每个请求的查询字符串中都带有 key 和 muKey；涉及节点用户的请求还会带上 node_id。

请求	查询参数	请求体	ETag	时机
GET /mod_mu/nodes/<node_id>/info	key、muKey		是	启动时，之后每次轮询
GET /mod_mu/users	key、muKey、node_id		是	启动时，之后每次轮询
GET /mod_mu/func/detect_rules	key、muKey		是	节点启动后，之后每次轮询；设置了 disable_get_rule = true 时除外
POST /mod_mu/users/traffic	key、muKey、node_id	{"data":[{"user_id","u","d"}]}		每次有流量需要上报的轮询，以及节点停止时再上报一次；设置了 disable_upload_traffic = true 时除外
POST /mod_mu/users/detectlog	key、muKey、node_id	{"data":[{"list_id","user_id"}]}		每次有面板规则命中需要上报的轮询，以及节点停止时再上报一次

每隔 update_periodic 秒（默认 60 秒）进行一次轮询，依次发出以下请求：

sequenceDiagram
    participant K as katana 节点
    participant P as SSPanel
    K->>P: GET /mod_mu/nodes/1/info
    P-->>K: 节点描述，或 304
    K->>P: GET /mod_mu/users
    P-->>K: 用户列表，或 304
    Note over K: 如有变化，重建监听器或刷新用户
    K->>P: GET /mod_mu/func/detect_rules
    P-->>K: 审计规则，或 304
    K->>P: POST /mod_mu/users/traffic
    K->>P: POST /mod_mu/users/detectlog

响应封装

SSPanel 的每个响应都包在一层封装中：{"ret": 1, "data": …}。只有当 ret 恰好为 1 时，katana 才接受 GET 响应；缺少 ret 视为 0。其他情况都是错误，错误信息中会注明接口：

node 1: node_info failed: /mod_mu/nodes/1/info: panel returned ret=0; retrying in 1s

对于两个 POST 请求，响应体不是 JSON（例如空响应体）时，katana 视为成功。如果是 ret 不为 1 的 JSON 对象，包括完全没有 ret 的对象，则视为失败。

HTTP 状态码大于等于 400 也是错误，网络故障和超时同样如此。由于 URL 中包含面板密钥，katana 在记录这些错误之前会去掉 URL，因此日志中只会出现请求方法和路径，不包括状态码或具体原因：

node 1: node_info failed: GET /mod_mu/nodes/1/info; retrying in 1s

ETag

对三个 GET 接口中的每一个，katana 都会记住面板上次发送的 ETag 响应头，并在下一次请求时通过 If-None-Match 带回。HTTP 304 Not Modified 响应表示“没有变化”：katana 保留已有的节点描述、用户列表或规则集，不做任何处理。不发送 ETag 的面板每次都会返回完整响应。

如果某次轮询中的 GET 请求失败，katana 会记录一条警告并保留上一次应用的状态，因此面板故障不会让正在运行的节点停止服务。

以下两种情况下请求不带 ETag，因此面板会返回完整响应：

• 首次启动。 每次尝试启动节点之前，katana 都会清空 ETag，然后拉取节点信息和用户列表。某次尝试失败时，katana 记录 node <node_id>: …; retrying in <N>s 并再次尝试；见 节点无法启动时。
• 修改配置文件中的 [node.api]。 katana 会构建一个新的面板客户端，其中没有任何 ETag。见 在 katana 运行时修改设置。

katana 如何读取节点

SSPanel 描述节点的方式有两种：SSPanel 2021.11 引入的 JSON 对象 custom_config，或者更早的以分号分隔的 server 字符串。katana 根据节点信息响应中的 version 字段和 disable_custom_config 选择其中一种：

flowchart TB
    A{"node_type 是 Shadowsocks？"} -->|是| R1["拒绝"]
    A -->|否| B{"disable_custom_config = true？"}
    B -->|是| L["旧版 server 字符串"]
    B -->|否| C{"面板版本为 2021.11 或更高？"}
    C -->|否| L
    C -->|是| CC["custom_config"]
    L --> D{"node_type 是 Hysteria2？"}
    D -->|是| R2["拒绝"]
    D -->|否| OK["V2ray 或 Trojan 节点"]

katana 按点号分隔的数字逐段比较版本号，并忽略所有非数字字符。2021.11、2021.11.0 和 2023.3 都会选择 custom_config；2021.10 以及空的或缺失的 version 会选择旧版字符串。

两种情况下都会读取响应中的 node_speedlimit（见 限速）。

custom_config

katana 从 custom_config 中读取以下键。其他键一律忽略，缺失的键视为空。

键	JSON 类型	适用于	含义
offset_port_node	string	全部	katana 监听的端口，例如 "443"。必须是内容为 1 到 65535 之间数字的 JSON 字符串。
network	string	V2ray、Trojan	传输层，不区分大小写：tcp（或 raw，或空值）、ws（或 websocket）、grpc（或 gun）。
security	string	V2ray	小写的 tls 或 xtls 会在监听器上启用 TLS。其他任何值，包括空值，都表示不启用 TLS。
enable_vless	string	V2ray	"1" 表示提供 VLESS 而不是 VMess。
flow	string	V2ray、Trojan	必须为空。任何流控（flow）都会被拒绝。
host	string	V2ray、Trojan	ws 节点的 WebSocket Host。
path	string	V2ray、Trojan	ws 节点的 WebSocket 路径。为空表示 /。
servicename	string	V2ray、Trojan	grpc 节点的 gRPC 服务名。
enable_reality	bool	V2ray、Trojan	必须为 false。REALITY 会被拒绝。
header	object	V2ray、Trojan	会被读取，但 katana 不支持 TCP header 伪装。
obfs	string	Hysteria 2	"salamander"，或为空表示不混淆。
obfs-password	string	Hysteria 2	Salamander 密码，至少 4 字节。

Trojan 节点无论 security 取何值都始终启用 TLS。Hysteria 2 节点只读取 offset_port_node、obfs 和 obfs-password；它的 QUIC 监听器没有可选的传输层。method 和 server_key 会被读取，但只对 Shadowsocks 有意义，而 SSPanel 节点不提供 Shadowsocks。

在 SSPanel 中，一个在 443 端口上基于 WebSocket 和 TLS 的 VMess 节点如下所示：

custom_config

{
  "offset_port_node": "443",
  "network": "ws",
  "security": "tls",
  "host": "proxy.example.com",
  "path": "/ws"
}

header 未实现

如果 custom_config 要求使用 TCP header，例如 {"type": "http"}，katana 仍会启动节点，但以不带 HTTP 伪装的普通 TCP 运行。期望收到伪造 HTTP 头的客户端将无法连接。请从节点中删除 header，或将其类型保持为 none。

如果面板版本为 2021.11 或更高，但节点没有 custom_config，katana 不会回退到 server 字符串，而是以 custom_config is empty, disable custom config 停止。要么填写 custom_config，要么设置 disable_custom_config = true，让 katana 读取旧版字符串。

旧版 server 字符串

当面板版本早于 2021.11，或者设置了 disable_custom_config = true 时，katana 读取 server 字段。不同节点类型的字段格式各不相同。

V2ray

proxy.example.com;443;0;ws;tls;path=/ws|host=proxy.example.com

该字符串按 ; 分割，至少需要六个部分：

部分	含义
1	地址。katana 忽略此项。
2	katana 监听的端口。
3	alterId。katana 忽略此项。
4 和 5	各自为 tls、传输层名称（tcp、ws、grpc）或空值，顺序不限。tls 启用 TLS。
6	以 | 分隔的 key=value 对：path、host、servicename 和 headerType。path 本身可以包含 =。

headerType 与 custom_config 中的 header 有相同的限制：katana 会读取它，但提供的是普通 TCP。VLESS 只能通过 [node.api] 中的 enable_vless 开启，流控也只能来自 vless_flow。

Trojan

proxy.example.com;port=443#8443|host=proxy.example.com|grpc=1|servicename=trojan

项	含义
port=443	端口。后面没有内部端口时，katana 监听此端口。
#8443	可选的内部端口。存在时，katana 监听此端口，并忽略 # 之前的端口。
grpc	只要存在 grpc 项，无论其值为何，节点都使用 gRPC。没有该项时节点使用 TCP。
servicename	gRPC 服务名。
host	会被读取，但对 TCP 或 gRPC 监听器没有作用。

旧版 Trojan 节点始终启用 TLS，且不能使用 WebSocket；如需 WebSocket，请使用 custom_config。

旧版字符串无法描述 Hysteria 2 节点。katana 会以 sspanel: a hysteria2 node needs custom_config; the legacy server string cannot describe one 拒绝这类节点。

节点类型

node_type	协议	传输层	TLS	说明
V2ray	VMess，启用后为 VLESS	TCP、WebSocket、gRPC	取决于 security，或旧版字符串中的 tls	不支持 VLESS 流控，不支持 REALITY
Trojan	Trojan	TCP、WebSocket、gRPC（旧版：TCP、gRPC）	始终启用	每个用户的密码是其 UUID
Hysteria2	基于 QUIC 的 Hysteria 2	无	始终启用	仅支持 custom_config，或本地描述
Shadowsocks				拒绝：sspanel: Shadowsocks node type is not supported

每个启用 TLS 的节点都需要在 [node.controller.cert] 下设置 mode = "file"，并配置 cert_file 和 key_file。katana 从不从面板获取证书，并且会拒绝 ACME 模式 dns、http 和 tls。各协议运行后支持哪些功能，见 协议。

SSPanel 上的 Hysteria 2

SSPanel 本身没有 Hysteria 2 节点类型。katana 根据自身配置中的 node_type 决定协议，而不是面板显示的类型，因此你可以用 SSPanel 提供的任意类型创建节点，再为它填写包含上述键的 custom_config。描述节点的方式有两种：

• 由面板描述。 将 [node.hysteria].port 保持为 0。katana 从 offset_port_node 读取端口，从 obfs 和 obfs-password 读取混淆设置。面板版本必须为 2021.11 或更高，且 disable_custom_config 必须为 false。
• 本地描述。 设置 [node.hysteria].port。此时 katana 从不拉取节点信息，端口和混淆设置都取自 [node.hysteria]。它仍然会从 SSPanel 拉取用户、上报流量并读取审计规则。

任何面板都无法表达的设置，例如如何读取凭据、UDP 中继和伪装页面，始终来自 [node.hysteria]。详见 Hysteria 2 节点。

用户

katana 读取用户列表中每一项的三个字段：

字段	用途
id	流量和审计上报中携带的用户 ID。必填。
uuid	凭据：VMess 或 VLESS 的 ID、Trojan 密码，或 Hysteria 2 凭据。必填。
node_speedlimit	该用户的限速，单位 Mbps。

passwd、port 和 method 会被读取但不会使用，因为它们只对 Shadowsocks 有意义。如果某一项缺少 id 或 uuid，整个列表都会解析失败（parse sspanel user list），katana 会保留之前的列表。首次启动时没有之前的列表，因此启动会以 user_list failed: parse sspanel user list 失败，katana 会重试。在 V2ray 节点上，uuid 不是合法 UUID 的用户会被跳过，并记录一条警告，其中只包含用户 ID，从不包含该值本身：

WARN katana::manager: skipping user 8: uuid is not a valid UUID

当面板返回空的用户列表时，katana 会关闭该节点的监听器，直到有用户重新出现。已经统计的流量仍会上报。

限速

SSPanel 下发两种限速，单位都是 Mbps：节点信息中的 node_speedlimit，以及每个用户的 node_speedlimit。katana 将 Mbps 乘以 125 000 换算为字节每秒，并把 0 或负值视为不限速。

节点限速	用户限速	每个用户得到的限速
0	0	不限速
0	U	U
N	0	N
N	U	N 和 U 中较小的一个

节点限速分别作用于每个用户，而不是节点总带宽的上限。

在 [node.api] 中将 speed_limit 设为大于 0 的值，会用这个数值替换面板下发的两种限速，因此节点上的每个用户都恰好得到这一限速。本地描述的 Hysteria 2 节点只从 speed_limit 获取节点限速，因为 katana 不会拉取它的节点信息。

面板修改限速后，katana 会在下一次轮询时应用，无需重启监听器，也不会断开用户的连接。已经打开的流保持旧速率；修改之后打开的流使用新速率。在配置文件中修改 speed_limit 也以同样的方式立即生效。令牌桶如何执行限速，见 限速。

审计规则

katana 按以下顺序，从两个来源构建每个节点的规则列表：

1. rule_list_path 指向的本地文件：每行一个正则表达式，跳过空行和以 # 开头的行。所有本地规则的 ID 都是 -1。
2. 面板的 detect_rules：由 {"id": …, "regex": …} 对象组成的列表。正则表达式无法编译的规则会记录日志并被跳过。

katana 将每个流的目标主机（域名或 IP 地址，不含端口）按顺序与规则进行匹配。除非表达式用 ^ 和 $ 锚定，否则规则只要匹配主机的任意部分即算命中。第一条命中的规则会拒绝该流（对于 UDP，katana 丢弃该数据报），并记录用户 ID 与规则 ID 组成的一对；每一对在每次轮询中只记录一次。每次轮询结束时，katana 将记录的各对以 list_id 和 user_id 的形式上报到 /mod_mu/users/detectlog，且只上报 ID 大于等于 0 的规则。因此本地规则会阻断连接，但永远不会出现在 SSPanel 的审计日志中。没有 id 的面板规则 ID 为 0。

注意

只有当面板对 detect_rules 返回完整响应时，katana 才会读取本地文件。304 或错误会让规则列表（包括本地规则）保持原样，因此在面板发送 ETag 的情况下，对本地文件的修改要等到面板规则发生变化或节点重启后才会生效。如果对配置文件的修改改动了 [node.api]，例如修改了 rule_list_path 本身，节点会获得一个新的面板客户端：它会完整拉取 detect_rules，并重新读取本地文件。设置 disable_get_rule = true 时，katana 从不请求 detect_rules，因此也从不读取本地文件：节点没有任何审计规则。detectlog 上报失败不会重试，这些命中记录会被丢弃。

更详细的匹配规则见 审计。

流量上报

每次轮询时，katana 会上报每个用户自上次成功上报以来传输的字节数：

{"data": [{"user_id": 7, "u": 1048576, "d": 52428800}]}

u 是上传量，d 是下载量，单位都是字节。没有流量的用户不会出现在上报中，没有任何内容需要上报时 katana 不发送请求。如果请求失败，这些字节会保留下来，随下一次上报一起发送，因此面板故障只会推迟流量计费，而不会丢失数据。流量计费的细节见 流量上报。

katana 不调用的接口

XrayR 还会调用另外两个 mod_mu 接口，katana 没有实现：

接口	XrayR 的用途	在 katana 中
POST /mod_mu/users/aliveip	在线用户 IP	不调用。SSPanel 不会显示 katana 节点的在线 IP，device_limit 也不起作用。
POST /mod_mu/nodes/<node_id>/info	节点负载和运行时长，用于 2023.2 之前的面板	不调用。面板不会显示 katana 节点的负载。

在 katana 运行时修改设置

katana 会监视自己的配置文件。对于 SSPanel 节点，修改分为以下几类：

修改内容	结果
panel_type（仅改大小写的除外）、host、node_id 或 key	这些键标识面板上的节点，因此 katana 停止节点，并用新的面板客户端重新启动它。ETag 会被清空，因此接下来的请求都会得到完整响应。
node_type、enable_vless、vless_flow、timeout、speed_limit、rule_list_path 或 disable_custom_config	就地生效。节点构建新的面板客户端，并立即重新完整读取节点信息和用户列表。修改 enable_vless 总会重建监听器。对于其他键，只有当新的描述改变了协议或传输层时，katana 才会重建监听器（这会断开该节点的连接）；否则会像普通轮询一样应用新的用户和限速。
listen_ip、证书设置、disable_sniffing、[node.hysteria] 或 [node.route]	katana 重建监听器，这会断开该节点的连接。
update_periodic、disable_get_rule 或 disable_upload_traffic	从下一次轮询开始生效，不影响监听器。

在应用一次修改之前，katana 会为每个设置发生变化的节点构建新的面板客户端。只要有一个构建失败，例如 node_type 拼写错误，katana 就不会应用这次修改中的任何内容，并记录 reload: node <node>: <error>; keeping current config，其中 <node> 由面板类型、host 和节点 ID 组成，例如 sspanel@https://panel.example.com#1。所有节点都保持原来的状态继续运行。

如果修改到达时某个节点仍在重试首次启动，这次修改会被保存下来，节点会立即用新设置再次尝试。

热重载的一般说明见 热重载。

常见错误

以下是 SSPanel 节点无法启动时 katana 记录的消息。大多数出现在 node <node_id>: node_info failed: 或 node <node_id>: initial start failed: 之后，并以 ; retrying in <N>s 结尾。运行中的节点在后续轮询中遇到这些问题时，同样的消息会出现在 node <node_id>: node_info: 或 node <node_id>: rebuild failed: 之后。

消息	原因	解决方法
unknown panel_type "…"	panel_type 拼写错误。--test 会报告此错误。	使用 "sspanel"。
unknown node_type "…"	node_type 为空或拼写错误。--test 会报告此错误。	使用 V2ray、Trojan 或 Hysteria2。
no nodes could be started	启动时，没有任何一个 [[node]] 能构建出面板客户端（例如由于上面两个错误）或路由器，因此 katana 退出。	修复此前记录的错误；--test 会显示第一个错误。
/mod_mu/nodes/1/info: panel returned ret=0	面板拒绝了请求，通常是因为 key 或 node_id 错误。	检查 SSPanel 中的 muKey 和节点 ID。
GET /mod_mu/nodes/1/info	网络故障、超时或 HTTP 错误状态码。	检查 host、面板是否可达，以及面板自身的日志。
parse /mod_mu/nodes/1/info	面板返回的内容不是 JSON 封装，例如一个 HTML 页面。	检查 host 是否指向面板本身，包括可能存在的子路径。
sspanel: Shadowsocks node type is not supported	node_type = "Shadowsocks"。	改用其他类型提供该节点，或使用支持 Shadowsocks 节点的面板。
custom_config is empty, disable custom config	面板版本为 2021.11 或更高，且节点没有 custom_config。	填写 custom_config，或设置 disable_custom_config = true。
invalid offset_port_node ""	offset_port_node 缺失或不是端口号。	将其设为字符串，例如 "443"。
parse sspanel custom_config	custom_config 中某个键的 JSON 类型错误，例如 offset_port_node 写成了数字。	字符串类型的键写成字符串，enable_reality 写成布尔值。
no server info in response	katana 读取旧版字符串，但节点的 server 字段为空。	填写 server，或在 SSPanel 2021.11 及以上版本中使用 custom_config。
malformed legacy v2ray server string: "…"	旧版字符串中以 ; 分隔的部分少于六个。	补齐缺少的部分，即使它们为空。
invalid legacy port "…"	旧版 V2ray 字符串的第二部分不是端口号。	在第二部分填写监听端口。
invalid legacy trojan port ""	旧版 Trojan 字符串中没有 port=。	添加 port=443，或用 port=443#8443 指定内部端口。
sspanel: a hysteria2 node needs custom_config; the legacy server string cannot describe one	Hysteria 2 节点位于旧版面板上，或设置了 disable_custom_config = true。	使用 custom_config，或用 [node.hysteria].port 在本地描述节点。
node requests kernel-unsupported feature: VLESS XTLS flow	custom_config 中的 flow 或 vless_flow 不为空。	清空流控设置。
node requests kernel-unsupported feature: REALITY	enable_reality 为 true。	为该节点关闭 REALITY。
node requests kernel-unsupported feature: transport "…"	network 指定了 katana 不支持的传输层，例如 h2 或 kcp。httpupgrade 和 splithttp 会产生这条消息的另一种变体。	使用 tcp、ws 或 grpc。
TLS node requires cert.mode = "file"	节点启用了 TLS，但没有配置本地证书。Hysteria 2 节点记录的是 hysteria2 node requires cert.mode = "file"。	设置 mode = "file"，并配置 cert_file 和 key_file。
TLS node requires cert.cert_file and cert.key_file	设置了 mode = "file"，但其中一个路径为空。	同时设置 cert_file 和 key_file。
panel returned port 0	节点的端口为 0。启动时这一行为 node 1: panel returned port 0; retrying in …。运行中的节点则记录 node 1: refreshed port is 0, keeping the last one，保留原来的端口，并照常应用用户列表。	在 SSPanel 中设置一个真实端口。

更多诊断方法见 故障排查。

节点无法启动时

如果节点首次启动失败，无论是无法拉取节点信息或用户列表，还是无法构建监听器，都会记录错误并再次尝试。第一次重试等待 1 秒，之后每失败一次，等待时间翻倍，最长 60 秒；如果 update_periodic 更短，则以 update_periodic 为上限。每次尝试都会清空 ETag，并完整读取节点信息和用户列表：

ERROR katana::manager::node: node 1: node_info failed: GET /mod_mu/nodes/1/info; retrying in 1s
ERROR katana::manager::node: node 1: initial start failed: TLS node requires cert.mode = "file"; retrying in 2s

用户列表拉取失败时，会以同样的方式记录 user_list failed: …。请在面板或配置文件中修复原因。修改配置文件会让节点立即再次尝试；如果是在面板中修复，节点会在下一次尝试时生效。

节点启动之后，轮询失败只会记录一条警告，节点继续按最后已知的状态提供服务。如果面板之后给出的节点描述 katana 无法构建，katana 会记录 rebuild failed，节点停止监听，katana 会在每次轮询时重试，直到描述可以构建为止。

相关页面

Xboard 与 V2boardkatana 支持的另一类面板，通过 UniProxy API 对接。

节点一个 katana 进程如何运行多个节点并分别轮询各自的面板。

Hysteria 2 节点任何面板上的 Hysteria 2 节点都需要的本地设置。

从 XrayR 迁移XrayR 的 SSPanel 设置如何对应到 katana 的配置文件。