从 XrayR 或 V2bX 迁移

katana 与 XrayR、V2bX 使用相同的面板 API，因此迁移节点时面板一侧无需任何改动：节点 ID、密钥、用户和客户端订阅都保持不变。变化的是节点上的文件。XrayR 的 YAML（以及 V2bX 的 JSON）变成一个 TOML 文件，路由和出站所用的 Xray JSON 文件变成该文件中的表，另有少数 XrayR 功能没有对应项。

如果你目前在运行 XrayR 或 V2bX，本页就是为你准备的。它把每个 XrayR 键映射到对应的 katana 键，并排展示一个完整节点，改写 route.json 和 custom_outbound.json，并列出 katana 会忽略或拒绝的内容，确保没有任何行为在不知不觉中改变。V2bX 在接近末尾处有单独的一节。

迁移前后的文件

XrayR 把一个节点分散在多个文件中，katana 只读取一个文件。

flowchart LR
  subgraph X["XrayR"]
    Y["config.yml：Log 和 Nodes"]
    R["route.json"]
    O["custom_outbound.json"]
    D["dns.json"]
    I["custom_inbound.json"]
  end
  subgraph K["katana：一个 config.toml"]
    L["[log]"]
    N["每个 Nodes 条目对应一个 [[node]]"]
    NR["每个节点内的 [node.route]"]
    OB["[[outbound]]，共享"]
    DNS["[dns]，共享"]
  end
  Gone["无对应项"]
  Y --> L
  Y --> N
  R --> NR
  O --> OB
  D --> DNS
  I --> Gone

下文的一切都由以下四点差异决定。

• 键名使用 snake_case，且解析严格。 ApiHost 变为 host，NodeID 变为 node_id。每个表都拒绝不认识的键，因此残留的 XrayR 键会以 unknown field 让 katana 停止，而不是被忽略。
• 路由按节点配置。 XrayR 把同一个 route.json 应用于所有节点。在 katana 中，每个 [[node]] 都有自己的 [node.route]；出站和 DNS 仍是共享的。
• 路由和出站使用 katana 自己的语法，而不是 Xray JSON。匹配条件更少，并且只要规则中任一匹配条件命中，该规则就匹配。
• 证书来自文件。 katana 没有 ACME 客户端。CertMode: dns、http 和 tls 会被拒绝。

迁移一个节点

1. 收集 XrayR 用到的内容。 记下 Nodes 下的每个条目，以及 RouteConfigPath、OutboundConfigPath、DnsConfigPath 或 InboundConfigPath 是否指向某个文件。检查每个节点的 CertMode。

2. 把证书放到文件中。 如果 XrayR 通过 ACME 获取证书（CertMode: dns、http 或 tls），请自行选择并配置一个 ACME 客户端，例如 certbot 或 acme.sh，并记下完整证书链和私钥的路径，两者均为 PEM 格式。在新客户端接管续期之前，可以让 katana 指向 XrayR 已获取文件的副本：XrayR 把它们保存在其配置目录（通常是 /etc/XrayR）下的 cert/certificates/<domain>.crt 和 <domain>.key。

3. 编写 /etc/katana/config.toml。 按下面的表格改写每个节点。在每个需要路由的节点中写入 [node.route]，并在顶层写一次出站。

4. 检查文件。

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

   它会输出 Configuration OK，或输出 configuration error: 及其后的第一个问题。--test 不会联系面板，并且除 Hysteria 2 节点外不会读取证书文件，因此面板下发内容或证书本身的问题要到节点启动时才会暴露。

5. 切换服务。 先停止 XrayR：两者都要绑定节点端口，无法同时运行。然后启动 katana，留意每个节点的监听日志行：

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

   如果看到的是 node 1: node_info failed: …; retrying in 1s 或 node 1: initial start failed: …; retrying in 1s，; retrying 之前的文字会说明原因，节点会自行重试；参见常见错误。用户列表为空的节点不会绑定任何端口，也不会写出监听日志行，直到 update_periodic 秒后某次轮询返回了用户。

无法启动的节点会持续重试

XrayR 的 HTTP 客户端会对每个面板请求最多重试三次。katana 每个请求只发送一次，转而重试整个节点的启动过程。如果首次请求节点设置或用户列表失败，或者监听器未能构建，该节点会以 ERROR 级别记录 node 1: <reason>; retrying in <N>s 并再次尝试，而 katana 的其余部分继续运行。第一次等待 1 秒，此后每失败一次等待时间翻倍，上限为 60 秒与该节点 update_periodic 中较小的一个。因此，切换期间面板短暂不可达，或者 XrayR 尚未释放端口，都只会让节点晚一些启动。原因出在你的文件中时不会自行消失：修正后保存文件，节点会立即重试。节点启动失败时列出了所有相关日志行。

部署介绍了如何把 katana 安装为服务。

同一节点的对照

下面这个 XrayR 节点从 Xboard 或 V2board 面板提供 VLESS 服务，证书来自文件，并使用本地审计列表。其下的 katana 文件实现相同的功能。

XrayR config.yml

/etc/XrayR/config.yml

Log:
  Level: warning
  AccessPath:
  ErrorPath:
Nodes:
  - PanelType: "NewV2board"
    ApiConfig:
      ApiHost: "https://panel.example.com"
      ApiKey: "replace-with-the-panel-key"
      NodeID: 1
      NodeType: V2ray
      Timeout: 30
      EnableVless: true
      VlessFlow: ""
      SpeedLimit: 0
      DeviceLimit: 0
      RuleListPath: /etc/XrayR/rulelist
    ControllerConfig:
      ListenIP: 0.0.0.0
      SendIP: 0.0.0.0
      UpdatePeriodic: 60
      EnableDNS: false
      DNSType: AsIs
      EnableProxyProtocol: false
      EnableFallback: false
      CertConfig:
        CertMode: file
        CertDomain: "proxy.example.com"
        CertFile: /etc/XrayR/cert/proxy.example.com.cert
        KeyFile: /etc/XrayR/cert/proxy.example.com.key

katana config.toml

/etc/katana/config.toml

[log]
level = "warn"                        # 对应 XrayR 的 "warning"

[[node]]
panel_type = "NewV2board"

[node.api]
host = "https://panel.example.com"
node_id = 1
key = "replace-with-the-panel-key"
node_type = "V2ray"
enable_vless = true
timeout = 30
rule_list_path = "/etc/katana/rulelist"

[node.controller]
listen_ip = "0.0.0.0"
update_periodic = 60

[node.controller.cert]
mode = "file"
cert_file = "/etc/katana/proxy.example.com.cert"
key_file = "/etc/katana/proxy.example.com.key"

其他键的去向：

• VlessFlow: ""、SpeedLimit: 0 和 DeviceLimit: 0 都是默认值，因此 katana 文件中省略了它们。send_ip 可以写，但不起任何作用。
• EnableDNS、DNSType、EnableProxyProtocol、EnableFallback 和 CertDomain 没有对应的 katana 键，写上会导致解析失败。
• AccessPath 和 ErrorPath 没有对应项：katana 把日志写到标准输出。

在 YAML 中，节点的设置嵌套在它的列表条目之下。在 TOML 中，[node.api]、[node.controller] 和 [node.controller.cert] 归属于在它们上方最近写出的那个 [[node]]，因此请把每个节点的表放在一起，紧跟在它的 [[node]] 行之后。第二个节点以另一个 [[node]] 开始。

PanelType

katana 支持两种面板 API。panel_type 比较时不区分大小写。

XrayR PanelType	katana panel_type	API
NewV2board	"NewV2board"	UniProxy（Xboard、V2board）
V2board	"V2board"，是 "NewV2board" 的别名	UniProxy
SSpanel	"SSpanel"	mod_mu
PMpanel、Proxypanel、V2RaySocks、GoV2Panel、BunPanel	不支持	无

不支持的值或缺失该值时，--test 会以 unknown panel_type "pmpanel" 失败，其中的值以小写显示。启动时，katana 会为该节点记录同样的消息，跳过它并运行其他节点；只有所有节点都以这种方式失败时才会退出。面板页面 Xboard 和 V2board 与 SSPanel 列出了 katana 从各面板读取的字段。

NodeType

XrayR NodeType	katana node_type	提供的服务
V2ray	"V2ray"	VMess；设置 enable_vless = true 时为 VLESS
Vmess	"V2ray"（也接受 "vmess"）	VMess
Vless	"V2ray" 并设置 enable_vless = true	不带 flow 的 VLESS。XrayR 仅凭 NodeType: Vless 就提供 VLESS；katana 需要 enable_vless。在 UniProxy 面板上，enable_vless 还会让 katana 从 network_settings 而不是 networkSettings 读取传输层设置；参见新版 Xboard 上基于 WebSocket 或 gRPC 的 VLESS。
Trojan	"Trojan"	Trojan；与 XrayR 相同，每个用户的密码就是其 UUID
Shadowsocks	"Shadowsocks"	AEAD 加密方式或 Shadowsocks 2022，仅 TCP，不支持插件。仅限 UniProxy 面板；SSPanel 节点会以 sspanel: Shadowsocks node type is not supported 失败
Shadowsocks-Plugin	不支持	以 unknown node_type "Shadowsocks-Plugin" 失败
无	"Hysteria2"	基于 QUIC 的 Hysteria 2；参见 Hysteria 2

node_type = "vless" 提供的是 VMess

与 XrayR 一样，VLESS 的开关是 enable_vless。对于 UniProxy 面板，katana 把 node_type 转为小写后发送给面板，并且只有在 enable_vless = true 时才把 "V2ray" 变成 vless。如果写 node_type = "vless" 而没有 enable_vless，katana 会向面板请求 VLESS 节点，然后在其上提供 VMess，导致所有 VLESS 客户端都无法连接。请写 node_type = "V2ray" 和 enable_vless = true。

协议详细介绍了每种协议。

ApiConfig 对应 [node.api]

XrayR 键	katana 键	说明
ApiHost	host	面板的基础 URL，带协议前缀。末尾的 / 会被去掉。
ApiKey	key	对 UniProxy 面板以 token 发送，对 SSPanel 以 key 和 muKey 发送。
NodeID	node_id	32 位无符号整数。
NodeType	node_type	参见 NodeType。
Timeout	timeout	单个面板请求的秒数。0 或不设置表示 5 秒，与 XrayR 相同。XrayR 会把失败的请求重试三次；katana 只发送一次。失败的轮询会在下一次轮询时重试；首次启动失败则在等待后重试，等待时间从 1 秒开始并逐次翻倍，上限为 60 秒或 update_periodic。
EnableVless	enable_vless	含义相同。
VlessFlow	vless_flow	请留空；katana 没有 XTLS flow。UniProxy 节点会忽略本地值。在回退到旧式 server 字符串的 SSPanel 节点上，非空值会让节点以 node requests kernel-unsupported feature: VLESS XTLS flow 被拒绝。XrayR 的示例文件设置了 xtls-rprx-vision，所以请检查这一项。
SpeedLimit	speed_limit	单位为 Mbps。大于 0 时，它会取代每个用户在面板上的限速，与 XrayR 相同。参见限速。
DeviceLimit	device_limit	接受但忽略。katana 不实施设备数限制。
RuleListPath	rule_list_path	文件格式相同：每行一个正则表达式。katana 还会跳过空行和以 # 开头的行，并对无法编译的行记录日志后跳过。规则所匹配的字符串有所变化：XrayR 匹配的是 tcp:example.com:443，katana 只匹配主机名 example.com。依赖 tcp: 前缀或端口的规则（例如 :25$）在 katana 中永远不会匹配。参见审计规则。
DisableCustomConfig	disable_custom_config	仅 SSPanel。含义相同。

ControllerConfig 对应 [node.controller]

XrayR 键	katana 键	说明
ListenIP	listen_ip	默认 "0.0.0.0"。
SendIP	send_ip	接受但忽略。出站连接从操作系统选择的地址发出。
UpdatePeriodic	update_periodic	单位为秒，默认 60，最小 1。同一个定时器驱动节点轮询、用户轮询、审计规则和流量上报。
DisableUploadTraffic	disable_upload_traffic	含义相同。
DisableGetRule	disable_get_rule	含义相同；它还会让 katana 停止读取 rule_list_path。
DisableSniffing	disable_sniffing	开关相同，效果不同。XrayR 会用嗅探到的名称替换目标地址。katana 对以 IP 为目标的流读取 TLS SNI 或 HTTP Host 头，仅用于匹配 domain_suffix 和 geosite 规则，仍然拨号到该 IP。参见路由。
CertConfig	[node.controller.cert]	参见下一节。
EnableDNS、DNSType	无	使用顶层的 [dns] 段，以及出站上的 address_family（参见出站）。
EnableProxyProtocol	无	katana 不接受 PROXY protocol。不要在节点前面放置会发送它的组件。
EnableFallback、FallBackConfigs	无	katana 没有回落（fallback）。
DisableIVCheck	无
AutoSpeedLimitConfig	无	限速只来自面板和 speed_limit。
GlobalDeviceLimitConfig	无	没有设备数限制，也没有 Redis。
EnableREALITY、REALITYConfigs、DisableLocalREALITYConfig	无	katana 不提供 REALITY。开启了 REALITY 的面板节点会在启动时以 node requests kernel-unsupported feature: REALITY 被拒绝。

把任何标为“无”的键照搬过来都会导致解析错误，例如：

configuration error: config parse error: TOML parse error at line 18, column 1
   |
18 | enable_dns = true
   | ^^^^^^^^^^
unknown field `enable_dns`, expected one of `listen_ip`, `send_ip`, `update_periodic`, `disable_upload_traffic`, `disable_get_rule`, `disable_sniffing`, `cert`

CertConfig 对应 [node.controller.cert]

XrayR 键	katana 键	说明
CertMode	mode	"none"（默认）或 "file"，用小写书写。"dns"、"http" 和 "tls" 会被拒绝。
CertFile	cert_file	PEM 证书，完整证书链。
KeyFile	key_file	PEM 私钥。
RejectUnknownSni	reject_unknown_sni	只能为 false。设为 true 会让节点以 node requests kernel-unsupported feature: cert.reject_unknown_sni 被拒绝。
CertDomain、Provider、Email、DNSEnv	无	ACME 设置。请删除它们，否则会导致解析错误。

CertMode: none 不再关闭 TLS

在 XrayR 中，即使面板声明节点使用 TLS，CertMode: none 也会让节点不带 TLS 提供服务。katana 则采用 fail closed（出错即拒绝）：面板描述为使用 TLS 的节点，以及所有 Trojan 节点，都需要 mode = "file"，否则会在启动时以 TLS node requires cert.mode = "file" 被拒绝。Hysteria 2 节点同样需要它，缺少时 --test 会以 hysteria2 node requires cert.mode = "file" 失败。如果你原先依靠 none 把 TLS 交给前置代理处理，请同时在面板中关闭该节点的 TLS，使客户端与节点保持一致。

对大多数节点，--test 不会拦下 ACME 模式

只有在面板声明节点使用 TLS 之后才需要证书，因此 --test 只对 Hysteria 2 节点检查 [node.controller.cert]。对其他所有节点，mode = "dns" 能通过 --test，但节点在启动时会被拒绝，无论它是否使用 TLS：

ERROR katana::manager::node: node 1: initial start failed: node requests kernel-unsupported feature: ACME cert mode "dns"; retrying in 1s

节点会以逐渐增长的间隔持续重试，你修正文件后它就会启动。保存修正后的文件会让它立即重试，无需重启。在此期间其他节点继续运行。

顶层设置

XrayR 键	katana	说明
Log.Level	[log].level	一个 tracing 过滤器。error、info 和 debug 可直接沿用。XrayR 的 warning 请写成 warn，none 请写成 off：katana 会把不认识的词当作 target 名称，因此 level = "warning" 会隐藏所有日志行。参见 [log] 段。
Log.AccessPath、Log.ErrorPath	无	katana 把日志写到标准输出，不写访问日志。
DnsConfigPath	[dns]	整个进程共用一个解析器：系统解析器（默认），或者指向单个服务器的普通 DNS、DNS over TLS 或 DNS over HTTPS。Xray dns.json 的功能，例如按域名指定服务器和 hosts，没有对应项。
RouteConfigPath	每个节点中的 [node.route]	参见路由与出站。
OutboundConfigPath	[[outbound]]	参见出站。
InboundConfigPath	无	katana 只提供面板所描述的节点。
ConnectionConfig	无	超时是固定的。客户端有 10 秒完成 TLS、WebSocket 或 gRPC 握手，之后再有 10 秒发送完整的代理请求。被中继的流如果在两个方向上 300 秒都没有传输任何数据，就会被关闭；XrayR 的 ConnIdle 默认值为 30。
Nodes	[[node]]，可重复	每个列表条目对应一个 [[node]] 块。

路由与出站

XrayR 把 route.json 和 custom_outbound.json 交给 Xray 处理。katana 有自己的路由，用 TOML 配置，匹配条件也更少。下面的示例是改写后的 XrayR 示例路由。

custom_outbound.json

/etc/XrayR/custom_outbound.json

[
  { "tag": "IPv4_out", "protocol": "freedom", "settings": {} },
  { "tag": "IPv6_out", "protocol": "freedom", "settings": { "domainStrategy": "UseIPv6" } },
  {
    "tag": "socks5-egress",
    "protocol": "socks",
    "settings": { "servers": [{ "address": "127.0.0.1", "port": 1080 }] }
  },
  { "protocol": "blackhole", "tag": "block" }
]

route.json

/etc/XrayR/route.json

{
  "domainStrategy": "IPOnDemand",
  "rules": [
    { "type": "field", "outboundTag": "block", "ip": ["geoip:private"] },
    { "type": "field", "outboundTag": "block", "protocol": ["bittorrent"] },
    { "type": "field", "outboundTag": "socks5-egress", "domain": ["geosite:openai"] },
    { "type": "field", "outboundTag": "IPv6_out", "domain": ["geosite:netflix"] },
    { "type": "field", "outboundTag": "IPv4_out", "network": "udp,tcp" }
  ]
}

katana config.toml

/etc/katana/config.toml

# IPv4_out 和 block 无需条目：不带 domainStrategy 的 freedom 就是
# 内置的 "direct"，而 "block" 是内置的。
[[outbound]]
tag = "ipv6-out"
protocol = "direct"
address_family = "ipv6_only"          # 对应 Xray 的 UseIPv6

[[outbound]]
tag = "socks5-egress"
protocol = "socks"
server = "127.0.0.1"
port = 1080

[[node]]
panel_type = "NewV2board"

[node.api]
host = "https://panel.example.com"
node_id = 1
key = "replace-with-the-panel-key"
node_type = "V2ray"

[node.route]
default = "direct"                    # 兜底的 IPv4_out 规则
geoip = "/etc/katana/geoip.dat"
geosite = "/etc/katana/geosite.dat"

[[node.route.rule]]
outbound = "block"
geoip = ["private"]

# bittorrent 规则没有对应项：katana 不识别 BitTorrent。

[[node.route.rule]]
outbound = "socks5-egress"
geosite = ["openai"]

[[node.route.rule]]
outbound = "ipv6-out"
geosite = ["netflix"]

第二个节点如果要以同样的方式路由，需要有自己的一份 [node.route] 表及其规则。[[outbound]] 条目只需定义一次，所有节点都可以使用。

出站

Xray 出站	katana [[outbound]]
freedom	内置的 direct（别名 freedom）。如需不同的地址策略，用新的 tag 声明 protocol = "direct"（或 "freedom"）并设置 address_family。
带 domainStrategy 的 freedom	address_family：UseIPv4 变为 "ipv4_only"，UseIPv6 变为 "ipv6_only"，UseIPv4v6 变为 "prefer_ipv4"，UseIPv6v4 变为 "prefer_ipv6"。"auto"（默认）按解析器返回的顺序尝试每个解析出的地址。要改变未匹配流量的策略，请用新的 tag 声明出站，并让 [node.route].default 指向它。
blackhole	内置的 block（别名 blackhole）。删除对应的 JSON 条目。
socks	protocol = "socks"，带 server、port，以及可选的 username 和 password。
http	protocol = "http"。
vmess、vless	protocol = "vmess" 或 "vless"，server、port 和 uuid 取自 vnext。VMess 的 security 接受 auto、aes-128-gcm 和 chacha20-poly1305，katana 把 auto 视为 aes-128-gcm；none 和 zero 会以 unsupported vmess security "none" 失败。VLESS 不支持 flow。
shadowsocks	protocol = "shadowsocks"，带 method 和 password；2022-blake3-… 方法会选用 Shadowsocks 2022。仅 TCP：路由到它的 UDP 流会失败。
wireguard	protocol = "wireguard"，单个 peer：secretKey 变为 private_key，address 变为 local_address，peer 的 publicKey、preSharedKey、endpoint 和 keepAlive 分别变为 public_key、pre_shared_key、server 与 port、keepalive。mtu 和 reserved 保持原名。
trojan 及其他	不支持：unknown outbound protocol "trojan"。
streamSettings、mux、sendThrough	不支持。除 WireGuard 外，所有代理出站都通过明文 TCP 连接上游。

direct、freedom、block 和 blackhole 这几个 tag 是保留的。把 XrayR 的 block blackhole 照搬过来会以 duplicate/reserved outbound tag block 失败；换用其他 tag 则会以 outbound needs a non-empty server and non-zero port (got "":0) 失败，因为 blackhole 在 katana 中不是出站协议。tag 按原样精确比较，因此如果出站已改名而规则仍引用 IPv6_out，会以 route references unknown outbound tag: IPv6_out 失败。出站记录了所有出站键。

规则

Xray 规则中同时写了 domain 和 port 时，两者都要满足才匹配。katana 规则只要任一匹配条件命中就匹配：同一条规则中的 domain_suffix = ["example.com"] 和 port = ["443"] 会把 example.com 的所有流量以及所有 443 端口的流量都发往该规则的出站。请拆分这样的规则，或者接受更宽的匹配范围。

Xray 规则字段	katana [[node.route.rule]]
outboundTag	outbound。必填。
domain，"domain:example.com"	domain_suffix = ["example.com"]：该域名及其子域名。去掉 domain: 前缀：katana 按字面理解字符串，因此 "domain:example.com" 能通过 --test，但永远不会匹配。
domain，"geosite:cn"	geosite = ["cn"]，并把 [node.route].geosite 设为该文件。支持 "cn@ads" 形式的属性。不要带 geosite: 前缀；geosite = ["geosite:cn"] 会以 geosite code not found: geosite:cn 失败。
domain，"full:…"	没有精确匹配。最接近的是 domain_suffix，但它也会匹配子域名。
domain，"regexp:…"、"keyword:…" 或不带前缀的字符串	没有对应项。Xray 中不带前缀的字符串可以匹配名称中的任意位置；domain_suffix 不行。
ip，CIDR 或地址	cidr = ["10.0.0.0/8"]；单个地址表示一台主机。主机位必须为零：Xray 接受 10.0.0.1/8，katana 则以 invalid cidr "10.0.0.1/8": host part of address was not zero 失败。
ip，"geoip:cn" 或 "geoip:!cn"	geoip = ["cn"] 或 geoip = ["!cn"]，并把 [node.route].geoip 设为该文件。
port，"53,443,1000-2000"	port = ["53", "443", "1000-2000"]：每个字符串一个端口或一个范围，并且必须是字符串。"53,443" 会以 invalid port spec: "53,443" 失败，port = [443] 会以 invalid type: integer `443`, expected a string 失败。
network、source、sourcePort、user、inboundTag、protocol、attrs、balancerTag	没有对应项。
domainStrategy	没有对应项。参见下面的警告。
balancers	没有对应项。

IP 规则从不解析域名

katana 的路由方式相当于 Xray 的 domainStrategy: "AsIs"。cidr 和 geoip 规则只匹配目标为 IP 地址的流；以名称为目标的流永远不会匹配它们，katana 也不会为此解析该名称。在 XrayR 的 IPOnDemand 下，geoip:private 规则还会拦截解析到私有地址的名称；在 katana 中，它只拦截以 IP 为目标的请求。反过来，域名匹配条件还会尝试从 TLS SNI 或 HTTP Host 头嗅探到的名称，因此也能作用于以 IP 为目标的流。

• 地理数据文件与 XrayR 使用的是同样的 v2ray 格式 geoip.dat 和 geosite.dat，可以直接复制。katana 不会在默认目录中查找它们；请把 [node.route].geoip 和 geosite 设为绝对路径。使用了其中之一却没有设置路径的规则会以 a geoip matcher is used but no geoip file is configured 失败。
• 规则按顺序应用，第一条匹配的规则生效，与 Xray 相同。没有匹配时，流走 [node.route].default，未设置时为 direct。
• 面板以 block 动作发布的路由在 katana 中是审计规则而不是路由，与 XrayR 相同；参见审计规则。以 dns 动作发布的路由（XrayR 会把它们变成 DNS 服务器）会被忽略。

路由介绍了所有路由键。

katana 忽略或拒绝的设置

XrayR 的设置分为四类。第一类会让 --test 失败；第二类和第三类能通过 --test，但会让节点无法启动；最后一类没有影响。

类别	键和值	结果
不存在的键	EnableDNS、DNSType、EnableProxyProtocol、EnableFallback、FallBackConfigs、DisableIVCheck、AutoSpeedLimitConfig、GlobalDeviceLimitConfig、EnableREALITY、REALITYConfigs、DisableLocalREALITYConfig、CertDomain、Provider、Email、DNSEnv、AccessPath、ErrorPath、ConnectionConfig、各 *ConfigPath 键，以及任何 PascalCase 名称	解析错误，unknown field。--test 失败，katana 不会启动。
节点启动时因你的文件被拒绝	mode = "dns"、"http" 或 "tls"；reject_unknown_sni = true；TLS 节点上的 mode = "none"；使用旧式 server 字符串的 SSPanel 节点上非空的 vless_flow	节点记录 initial start failed: …; retrying in <N>s 并持续重试。修正并保存文件后它就会启动，保存也会让它立即重试。其他节点继续运行。对于 Hysteria 2 节点，--test 也会检查证书设置。
因面板描述的内容被拒绝	REALITY；XTLS flow；TCP、WebSocket 和 gRPC 以外的任何传输层，例如 httpupgrade、xhttp 或 h2；Shadowsocks 插件，例如 obfs: http；在 SSPanel 上使用 node_type = "Shadowsocks"	节点记录 initial start failed: node requests kernel-unsupported feature: …，后两种情况则记录 node_info failed: …，其后跟着 ; retrying in <N>s，并持续重试。在面板中修改该节点，或修改文件中的 node_type 之后，它会在下一次尝试时启动。
接受但忽略	send_ip、device_limit；UniProxy 节点上的 vless_flow，以及从 custom_config 读取的 SSPanel 节点上的 vless_flow	不起作用。

从 V2bX 迁移

V2bX 总是与 UniProxy 面板通信，因此每个 V2bX 节点都对应一个 panel_type = "NewV2board" 的 katana 节点。V2bX 没有 PanelType 键，而 katana 也没有默认值：省略 panel_type 会以 unknown panel_type "" 失败。

节点键

V2bX 接受平铺的节点键，也接受拆分到 ApiConfig 和 Options 中的写法；两种写法的映射相同。

V2bX 键	katana 键	说明
ApiHost	[node.api].host	V2bX 默认为 http://127.0.0.1；katana 没有默认值。
ApiKey	[node.api].key
NodeID	[node.api].node_id
NodeType	[node.api].node_type	参见下一张表。
Timeout	[node.api].timeout	V2bX 默认 30 秒，katana 默认 5 秒。
RuleListPath	[node.api].rule_list_path
ListenIP	[node.controller].listen_ip
SendIP	[node.controller].send_ip	接受但忽略。
CertConfig	[node.controller.cert]	与 XrayR 相同。V2bX 的 CertMode: "self" 没有对应项：TLS 节点需要 mode = "file"。
LimitConfig.SpeedLimit	[node.api].speed_limit	规则不同：参见下面的警告。
EnableSniff、DisableSniffing	[node.controller].disable_sniffing	注意 sing-box 核心的 EnableSniff 含义相反。katana 从不覆盖目标地址，因此 SniffOverrideDestination 没有对应项。
Hysteria2ConfigPath	[node.hysteria]	凭据格式、UDP 中继和伪装页面。参见 Hysteria 2。
Log.Level	[log].level	V2bX 的 debug、info、warn 和 error 可原样沿用。Log.Output 没有对应项；katana 把日志写到标准输出。核心自身的 Log 设置同样没有对应项。
Core、CoreName、Cores	无	katana 只有一个内置内核。
ApiSendIP、Include、Name	无
LimitConfig.DeviceLimit、ConnLimit、EnableRealtime、EnableIpRecorder、EnableDynamicSpeedLimit	无	没有设备数、连接数或动态限制。
DeviceOnlineMinTraffic、ReportMinTraffic	无	katana 上报所有流量非零的用户。
EnableProxyProtocol、EnableFallback、FallBackConfigs、EnableTFO、EnableUot、DisableIVCheck	无
EnableDNS、DNSType、DomainStrategy	无	使用 [dns]，以及 direct 出站上的 address_family。

Xray 核心的 RouteConfigPath 和 OutboundConfigPath 文件与上文 XrayR 的改写方式完全相同。sing-box 核心的 OriginalPath 配置需要手动改写为 [[outbound]] 和 [node.route]。

面板路由的解读方式也不同。V2bX 会把 block 路由中的 protocol:bittorrent 条目变成协议规则，并去掉其他条目的 regexp: 前缀。katana 与 XrayR 一样，把 block 路由的各条目合并为一个针对所请求主机的正则表达式，因此带有这两种前缀之一的条目永远不会匹配。以 dns 动作发布的路由会被忽略。

LimitConfig.SpeedLimit 在 katana 中是覆盖值

在 V2bX 中，本地 SpeedLimit 与用户在面板上的限速会合并：取两者中较小的非零值。katana 的 speed_limit 大于 0 时会取代每个用户在面板上的限速，与 XrayR 的行为一致，因此套餐限速低于节点值的用户会得到节点值。要保持 V2bX 的行为，请把 speed_limit 保留为 0，并在面板中设置限速。

节点类型

V2bX NodeType	katana node_type
vmess	"V2ray"
vless	"V2ray" 并设置 enable_vless = true。只写 "vless" 提供的是 VMess；参见 NodeType。
trojan	"Trojan"
shadowsocks	"Shadowsocks"
hysteria2	"Hysteria2"
hysteria	不支持。katana 只提供 Hysteria 2；它的 "hysteria" 是 "Hysteria2" 的别名。
tuic、anytls	不支持：unknown node_type "tuic"。

对照

V2bX config.json

/etc/V2bX/config.json

{
  "Log": { "Level": "info", "Output": "" },
  "Cores": [{ "Type": "xray", "Log": { "Level": "error" } }],
  "Nodes": [
    {
      "Core": "xray",
      "ApiHost": "https://panel.example.com",
      "ApiKey": "replace-with-the-panel-key",
      "NodeID": 1,
      "NodeType": "vless",
      "Timeout": 30,
      "ListenIP": "0.0.0.0",
      "SendIP": "0.0.0.0",
      "EnableProxyProtocol": false,
      "EnableDNS": false,
      "LimitConfig": { "SpeedLimit": 0, "DeviceLimit": 0 },
      "CertConfig": {
        "CertMode": "file",
        "CertFile": "/etc/V2bX/fullchain.cer",
        "KeyFile": "/etc/V2bX/cert.key"
      }
    }
  ]
}

katana config.toml

/etc/katana/config.toml

[log]
level = "info"

[[node]]
panel_type = "NewV2board"             # V2bX 总是使用 UniProxy

[node.api]
host = "https://panel.example.com"
node_id = 1
key = "replace-with-the-panel-key"
node_type = "V2ray"                   # 对应 V2bX 的 "vless"
enable_vless = true
timeout = 30

[node.controller]
listen_ip = "0.0.0.0"
update_periodic = 60                  # 不读取面板的推送和拉取间隔

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

V2bX 从面板的 base_config 获取轮询和上报间隔。katana 会忽略这些值，两者都使用 update_periodic（默认 60 秒）；请把它设为你原来使用的间隔。

客户端与面板的变化

方面	使用 katana 后
客户端配置	VMess、不带 flow 的 VLESS、Trojan、Shadowsocks 和 Hysteria 2 保持不变。凭据仍来自面板上用户的 UUID。
Shadowsocks UDP	不提供。katana 不会为 Shadowsocks 节点绑定 UDP socket。
UniProxy 面板上的 Trojan	通过 TCP 加 TLS 提供，与 XrayR 相同。不读取面板上该节点的传输层设置。
Hysteria 2 认证	默认情况下客户端密码就是用户的 UUID，与 V2bX 相同。[node.hysteria].credential = "user_pass" 会切换为 user:pass 形式。
在线用户和设备数	不上报。面板不会显示该节点的在线用户或 IP。
节点状态	不上报：面板中没有 CPU、内存或磁盘数据。
审计规则	匹配客户端所请求的目标地址，从不匹配嗅探到的名称。XrayR 会用嗅探到的名称覆盖目标地址，因此匹配的是该名称。
审计命中	对于面板自身的规则，会上报给 SSPanel。UniProxy 没有对应的接口，因此 UniProxy 面板收不到命中记录；相应的流仍会被拒绝。
限速	按用户限速，来自面板，并可被本地值覆盖；对每个用户的所有连接统一执行一个预算。参见限速。
编辑配置文件	XrayR 在文件变化时会重启所有节点。katana 只把每处变化应用到相关的节点，包括对 [node.api] 的修改，无需重启。如果修改让该块指向面板上的另一个节点（panel_type、host、node_id、key，以及在 Xboard 和 V2board 上 katana 请求的节点类型），该节点会被替换。如果新文件无法解析，或其中某个出站或节点无法构建，katana 会保留正在运行的配置。参见节点身份与热重载和热重载。

用户限速为 null 会让用户列表失效

XrayR 和 V2bX 把 speed_limit 为 null 的用户视为不限速。katana 则会以 parse UniProxy user response 拒绝整个 UniProxy 用户响应。正在运行的节点会继续服务上一次应用的列表。正在启动的节点则无法完成启动：它会记录 node 1: user_list failed: parse UniProxy user response; retrying in 1s，并持续重试，直到面板发送有效的列表。Xboard 会把套餐的限速复制给每个购买该套餐的用户，套餐未设限速时发送 null。切换之前，请为每个套餐设置明确的限速，也为已持有无限速套餐的每个用户设置；0 表示不限速。详情参见 Xboard 和 V2board。

常见错误

节点启动失败时的日志行以 ; retrying in <N>s 结尾，下表省略了这一部分。

消息	原因和解决方法
unknown field `PanelType`, expected one of `panel_type`, …	使用了 XrayR 的键名。请改用上面表格中的 snake_case 名称。
unknown field `enable_dns`, …（或 cert_domain、enable_proxy_protocol、access_path …）	katana 没有这项设置。删除该键。
unknown panel_type "pmpanel"（或 ""）	katana 不支持该面板，或者省略了 panel_type。
unknown node_type "Shadowsocks-Plugin"	katana 不提供该节点类型。
duplicate/reserved outbound tag block	某个 [[outbound]] 重新定义了内置 tag。删除它并使用内置出站。
outbound needs a non-empty server and non-zero port (got "":0)	由 Xray 的 blackhole 改写而来的 [[outbound]]，或者缺少 server 和 port 的代理出站。请使用内置的 block。
unknown outbound protocol "trojan"	katana 没有该出站协议。
outbound ipv6-out invalid address_family "UseIPv6"	使用了 Xray 的名称。请改用 ipv4_only、ipv6_only、prefer_ipv4、prefer_ipv6 或 auto。
route references unknown outbound tag: IPv6_out	规则引用了未定义的出站，常见于改名之后。
invalid port spec: "53,443"	拆分列表：port = ["53", "443"]。
geosite code not found: geosite:netflix	去掉 geosite: 前缀。
a geoip matcher is used but no geoip file is configured	把 [node.route].geoip 设为 .dat 文件。geosite 同理。
node 1: initial start failed: node requests kernel-unsupported feature: ACME cert mode "dns"	改用带证书文件的 mode = "file"，然后保存文件。
node 1: initial start failed: TLS node requires cert.mode = "file"	面板描述的是 TLS 节点，而文件中是 mode = "none"。
node 1: hysteria2 node requires cert.mode = "file"	Hysteria 2 节点没有设置 mode = "file"。这一项由 --test 报告。
node 1: initial start failed: node requests kernel-unsupported feature: VLESS XTLS flow	在面板中清除 flow；对于 SSPanel，还要清除文件中的 vless_flow。
node 1: node_info failed: newV2board: shadowsocks obfs "http" is not supported	在面板中移除该 Shadowsocks 节点的插件。
完全没有日志输出	使用了 level = "warning" 或 "none"。请改用 warn 或 off。

故障排查介绍了与迁移无关的其他错误。

相关页面

配置文件katana TOML 文件中的每个键，包括类型和默认值。

快速开始对接面板，启动第一个 katana 节点。

路由按节点配置的路由表，支持域名、CIDR、端口、GeoIP 和 GeoSite 规则。

出站所有节点共享的上游代理和 WireGuard 隧道。

Xboard 和 V2boardUniProxy API：katana 请求什么、读取什么。

SSPanelmod_mu API、custom_config 以及旧式 server 字符串。