Xboard 与 V2board（UniProxy）

设置 panel_type = "newv2board" 后，katana 节点从实现了 UniProxy 节点 API（位于 /api/v1/server/UniProxy/ 下）的面板获取节点描述和用户列表。这套 API 源自 Xboard 和 V2board，本页介绍的也正是这两个面板。katana 定期轮询面板，按面板的描述构建监听器，并回传每个用户的流量。

以下情况请阅读本页：让 katana 对接这类面板、把节点从其他节点程序迁移过来，或者节点无法启动、需要弄清 katana 向面板请求了什么。配置文件的整体结构见 配置文件；本页只介绍 UniProxy 特有的部分。

概览

属性	katana 中的 UniProxy
panel_type	"newv2board"，或其别名 "v2board"，不区分大小写
认证	[node.api].key，在每个请求中作为 token 查询参数发送
节点类型	VMess、VLESS、Trojan、Shadowsocks、Hysteria 2
节点描述	GET …/UniProxy/config，支持 ETag 缓存
用户	GET …/UniProxy/user，支持 ETag 缓存
流量	POST …/UniProxy/push，每个有流量的用户一行
审计	面板中动作为 block 的路由，外加可选的本地规则文件。命中记录不上报。
轮询间隔	[node.controller].update_periodic，默认 60 秒。面板自身的间隔设置会被忽略。
未实现	在线用户和 IP（alive、alivelist）、节点状态（status）、/api/v2/server/ 路由

在面板中设置节点

节点的形态由面板决定：协议、端口、传输层以及是否启用 TLS。与本机相关的一切由 katana 决定：绑定哪个地址、证书、路由和出站。

1. 创建节点。 选择协议（VMess、VLESS、Trojan、Shadowsocks 或 Hysteria），然后按客户端的连接方式设置端口、传输层和 TLS。katana 能提供哪些选项，见 面板设置与 katana 实际提供的服务。面板中的证书设置无需改动；katana 不会读取它们。

2. 为节点分配用户。 把节点关联到应当能使用它的用户组（或套餐）。对于不属于任何组的节点，Xboard 返回空的用户列表，而用户列表为空时 katana 不会绑定任何端口。

3. 记下节点 ID。 即面板为该节点显示的编号。Xboard 同时按这个 ID 和 katana 发送的节点类型查找节点，因此如果 node_type 与节点协议不符，即使 ID 正确也会得到 Server does not exist。

4. 记下服务端通讯密钥。 这是面板级别的密钥，节点程序用它进行认证，位于面板的节点设置或服务端设置中。katana 中对应的键是 key。

5. 获取证书，证书需匹配客户端所连接的域名；节点使用 TLS 或者是 Hysteria 节点时需要。katana 从本地文件读取证书，从不从面板获取。

最小示例

这份配置从 Xboard 面板提供一个 VMess 节点。端口、传输层和 TLS 都以面板为准；只有面板启用了 TLS 时才会用到证书。

/etc/katana/config.toml

[log]
level = "info"

[[node]]
panel_type = "NewV2board"

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

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

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

启动 katana 之前先检查配置：

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

Configuration OK

--test 会构建面板客户端和路由器，但不会连接面板。它无法判断节点 ID、密钥或节点类型是否与面板一致，也无法判断面板描述的节点 katana 能否提供服务。本地部分的检查有一个例外，即 Hysteria 2 节点：--test 会检查它的 [node.hysteria] 块并读取其证书。

katana 启动且面板正常响应后，节点会输出：

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

各协议的节点配置

不同协议之间唯一需要改动的是 node_type，此外 VLESS 需要 enable_vless，Hysteria 2 需要一个 [node.hysteria] 块。每个标签页单独展示一个 [[node]] 条目。

VMess

[[node]]
panel_type = "NewV2board"

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

# 仅当面板为该节点启用 TLS 时需要。
[node.controller.cert]
mode = "file"
cert_file = "/etc/katana/cert/fullchain.pem"
key_file = "/etc/katana/cert/privkey.pem"

VLESS

[[node]]
panel_type = "NewV2board"

[node.api]
host = "https://panel.example.com"
node_id = 2
key = "replace-with-the-panel-key"
node_type = "vless"
enable_vless = true      # 不设置的话，katana 提供的是 VMess

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

Trojan

[[node]]
panel_type = "NewV2board"

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

# Trojan 始终运行在 TLS 之上。
[node.controller.cert]
mode = "file"
cert_file = "/etc/katana/cert/fullchain.pem"
key_file = "/etc/katana/cert/privkey.pem"

Shadowsocks

[[node]]
panel_type = "NewV2board"

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

# 无需证书：Shadowsocks 没有 TLS 层。

Hysteria 2

[[node]]
panel_type = "NewV2board"

[node.api]
host = "https://panel.example.com"
node_id = 5
key = "replace-with-the-panel-key"
node_type = "hysteria2"   # 不要写 "hy2"：见下文

# 每个 Hysteria 2 节点都需要证书：它的 TLS 是 QUIC 的一部分。
[node.controller.cert]
mode = "file"
cert_file = "/etc/katana/cert/fullchain.pem"
key_file = "/etc/katana/cert/privkey.pem"

# port = 0（默认值）表示端口和混淆由面板提供。
[node.hysteria]
udp = true

面板不描述的 Hysteria 2 监听器设置，例如 UDP 中继、凭据格式和伪装页面，见 Hysteria 2 节点。

设置

下面是对接 UniProxy 面板时需要关注的 [[node]] 键。panel_type 直接位于 [[node]] 中；其余键位于 [node.api]，除非键名前标明了其他表。完整的节点键列表见 配置文件。

键	类型	默认值	对接 UniProxy 面板时
panel_type	string	""	"newv2board" 或 "v2board"，不区分大小写。其他值会报错 unknown panel_type "…"。
host	string	""	面板基础 URL，包含协议头。katana 会去掉末尾的 / 并追加 /api/v1/server/UniProxy/…，因此 https://example.com/panel 这样的基础路径会被保留。--test 不检查此项。
node_id	u32	0	节点的数字 ID，作为 node_id 查询参数发送。
key	string	""	服务端通讯密钥，作为 token 查询参数发送。
node_type	string (enum)	""	要提供哪种协议，以及向面板请求哪种节点类型。可接受的值（不区分大小写）：v2ray、vmess、vless、trojan、shadowsocks、hysteria2、hysteria、hy2。其他值会报错 unknown node_type "…"。见 node_type。
enable_vless	bool	false	对 V2ray 系节点：提供 VLESS 而不是 VMess，向面板请求 node_type=vless，并从 network_settings 读取传输层设置。对其他节点类型无效。
timeout	u64	0	单个面板请求的总超时，单位为秒。0 表示 5 秒。
speed_limit	float	0.0	单位 Mbps。大于 0 的值会用这个值替换面板下发给每个用户的限速。见 限速。
rule_list_path	string	""	本地审计正则表达式文件，与面板下发的规则合并使用。见 审计规则。
vless_flow	string	""	对接此面板时无效。流控取自面板的 flow 字段。
device_limit	integer	0	无效。katana 不执行设备数限制。
disable_custom_config	bool	false	无效。仅用于 SSPanel。
[node.controller] update_periodic	u64	60	两次轮询之间的秒数。拉取节点信息、拉取用户、刷新规则和上报流量共用同一个定时器。小于 1 的值按 1 处理。
[node.controller] disable_get_rule	bool	false	设为 true 时 katana 不加载审计规则，面板规则和本地文件规则都不加载。如果通过热重载开启此项，之前已加载的规则仍会生效，直到 katana 重启或某次热重载替换了该节点。
[node.controller] disable_upload_traffic	bool	false	设为 true 时停止流量上报。离开节点的用户的计数会被丢弃。当前用户的计数器继续累计，因此通过热重载重新开启上报后，也会上报他们在此期间产生的流量。
[node.hysteria] port	u16	0	仅用于 Hysteria 2。0 表示向面板请求节点信息。非零端口表示在本地描述节点，此时 katana 从不调用 config 接口。

node_type

node_type 有两个作用：一是决定 katana 提供哪种协议，二是转为小写后作为 node_type 查询参数，供面板查找节点。唯一的例外是设置了 enable_vless = true 的 V2ray 系节点：此时无论你写的是什么，katana 都发送 vless。

node_type（不区分大小写）	enable_vless	katana 提供	发送给面板	Xboard
v2ray	false	VMess	v2ray	接受，作为 vmess 的别名
vmess	false	VMess	vmess	接受
v2ray、vmess 或 vless	true	VLESS	vless	接受
vless	false	VMess	vless	接受，但协议不一致
trojan	忽略	Trojan	trojan	接受
shadowsocks	忽略	Shadowsocks	shadowsocks	接受
hysteria2	忽略	Hysteria 2	hysteria2	接受，作为 hysteria 的别名
hysteria	忽略	Hysteria 2	hysteria	接受
hy2	忽略	Hysteria 2	hy2	拒绝：Invalid node type specified

只设置 node_type = "vless" 提供的是 VMess

面板能找到这个 VLESS 节点，但 katana 在上面构建的是 VMess 服务端，所有 VLESS 客户端都会认证失败。VLESS 节点请设置 enable_vless = true。此时 node_type 可以是 vless、vmess 或 v2ray；三种情况下 katana 都请求 vless。

使用 hysteria2，不要用 hy2

katana 接受 hy2，--test 也能通过，但 katana 会把它原样发送给面板。Xboard 不认识这个名称，对每个请求都返回错误，节点会一直重试，却始终无法启动。hysteria2 和 hysteria 都可以正常使用。

katana 向面板发起的请求

katana 调用三个接口，都位于 host 之下。每个请求（包括 POST）都带有相同的三个查询参数：

参数	值
node_id	[node.api].node_id
node_type	小写后的 node_type，或者 vless（见 node_type）
token	[node.api].key

调用	时机	katana 读取的响应
GET /api/v1/server/UniProxy/config	启动时以及每次轮询。对于设置了本地 [node.hysteria].port 的 Hysteria 2 节点则跳过。	描述节点的 JSON 对象，没有外层封装。见 katana 读取的字段。
GET /api/v1/server/UniProxy/user	启动时以及每次轮询	{"users": [{"id": …, "uuid": "…", "speed_limit": …}, …]}
POST /api/v1/server/UniProxy/push	每次轮询，前提是有用户产生了流量	只看 HTTP 状态码，忽略响应体。

sequenceDiagram
    participant K as katana 节点
    participant P as 面板
    K->>P: GET config
    P-->>K: 节点描述和路由
    K->>P: GET user
    P-->>K: 用户列表
    Note over K: 绑定监听器，加载审计规则
    loop 每 update_periodic 秒
        K->>P: GET config (If-None-Match)
        P-->>K: 200 带新描述，或 304
        K->>P: GET user (If-None-Match)
        P-->>K: 200 带新列表，或 304
        Note over K: 同步状态，刷新审计规则
        K->>P: POST push
    end

ETag 与 304

katana 为每个接口各保存一个 ETag：config 一个，user 一个。当完整响应带有 ETag 头时，katana 会保存它，并在下次请求同一接口时作为 If-None-Match 发回。内容没有变化时 Xboard 返回 304 Not Modified，katana 随即沿用上次应用的节点描述或用户列表，不做任何解析。没有 ETag 头的响应不会改变已保存的标签。

面板一返回 200，katana 就会保存标签，然后才解析响应体。如果运行中的节点收到一份被 katana 拒绝的响应，例如用户列表无法解析，或节点没有端口，下一次轮询仍会带上新标签，Xboard 返回 304，katana 则保留上次应用的状态，且不会再次记录这个错误。以下三种情况下，katana 会重新读取这份被拒绝的响应：

• 该内容在面板中发生变化；
• 修改配置中的 [node.api] 让节点获得了新的面板客户端，新客户端不持有任何标签，会完整读取两个接口；
• katana 重启，或某次热重载替换了该节点。

节点启动期间，每次尝试都会丢弃已保存的标签，重新向面板请求，因此启动时被拒绝的响应会在每次重试时重新读取。

启动、轮询与失败处理

• 启动。 katana 先拉取节点描述，再拉取用户列表，然后绑定监听器。第一次轮询发生在节点启动完成后一个完整的 update_periodic 周期之后。

• 启动失败。 启动过程中的任何失败都会重试：面板无法访问或拒绝请求、响应无法解析、面板描述了 katana 拒绝的功能，或者端口仍被占用。节点以 ERROR 级别记录失败原因，随后写出距下一次尝试的等待时间：

  ERROR katana::manager::node: node 1: node_info failed: GET /api/v1/server/UniProxy/config; retrying in 1s

  等待时间从 1 秒开始，每次失败后翻倍，上限为 60 秒与 update_periodic 中的较小者。每次尝试都从节点描述重新开始，不带 ETag。在配置文件中保存对该节点设置的修改，会立即开始下一次尝试。在某次尝试成功之前，节点不绑定任何端口。

• 必须拿到用户列表。 节点在读取到用户列表之前不会启动完成：拉取用户失败或无法解析，与其他失败一样算作一次失败的尝试，记录为 user_list failed 并重试。空列表是可以接受的：节点照常启动，在用户出现之前不绑定任何端口。

• 之后的拉取失败。 katana 记录一条警告，并保留上次应用的描述或用户列表。单次轮询内不会重试；下一次定时轮询就是重试。

• 用户列表为空。 katana 关闭监听器，在用户重新出现之前不绑定任何端口。

失败的 HTTP 请求在日志中不包含 URL，因为 URL 中带有密钥。日志只写出接口名称，例如 GET /api/v1/server/UniProxy/config。

katana 读取的字段

katana 只从 config 响应中读取以下字段。它不会拒绝未知字段，因此面板可以附带任何其他字段。

字段	节点类型	katana 的用途
server_port	全部	监听端口。为 0 或缺失时报错 newV2board: server port must be > 0。
network	VMess、VLESS	传输层：tcp 或 raw、ws 或 websocket、grpc 或 gun。为空表示 TCP。见 传输层。
networkSettings	VMess	path（WebSocket）、headers.Host（WebSocket）、serviceName（gRPC）、header（TCP）
network_settings	VLESS	相同的字段，仅在 enable_vless = true 时读取
tls	VMess、VLESS	0 明文，1 TLS，2 REALITY（拒绝）
flow	VLESS	必须为空。任何流控都会被拒绝。
host、server_name	Trojan、Hysteria 2	会被记录，变化时会重建监听器。它们不影响 katana 提供的服务；域名由本地证书决定。
cipher、server_key	Shadowsocks	加密方式，以及 Shadowsocks 2022 的服务端 PSK
obfs	Shadowsocks	必须为空、plain 或 none。Xboard 不会为 Shadowsocks 发送此字段。
obfs、obfs-password	Hysteria 2	Salamander 混淆。obfs 必须为 salamander 或空；obfs 为空时 obfs-password 也必须为空。
routes[].match、routes[].action	全部	审计规则。见 审计规则。

katana 从 user 响应中读取每个用户的 id（上报流量时使用的 uid）、uuid（凭据）和 speed_limit（Mbps）。

以下字段即使面板发送了，katana 也会忽略：

字段	后果
base_config（push_interval、pull_interval）	katana 每 update_periodic 秒轮询和上报一次。
tls_settings、cert_config	证书始终来自 [node.controller.cert]。面板中的服务器名称、REALITY 密钥和证书模式都不生效。
multiplex	katana 没有实现此设置在客户端开启的 smux、yamux 或 h2mux 多路复用。请保持关闭。Xray 的 Mux.Cool 无需任何设置即可使用。
decryption（VLESS encryption）	VLESS 客户端必须使用 encryption = "none"。
up_mbps、down_mbps（Hysteria）	katana 没有实现 Brutal 拥塞控制。请改用限速。
device_limit（用户）	不执行设备数限制。
plugin、plugin_opts（Shadowsocks）	katana 只提供不带插件的普通 Shadowsocks。
network（Trojan）	Trojan 始终通过带 TLS 的 TCP 提供。
version（Hysteria）	katana 始终提供 Hysteria 2。
listen_ip、protocol、custom_outbounds、custom_routes	katana 绑定 [node.controller].listen_ip，并使用 [node.route] 和 [[outbound]] 进行路由。

面板设置与 katana 实际提供的服务

下表按照 Xboard 的节点表单排列。标为拒绝的行表示监听器构建失败，日志会写出该功能的名称，在面板设置修改之前节点不会监听。标为忽略的行表示 katana 照常提供服务，但按被忽略的设置配置的客户端将无法连接。

VMess 和 VLESS

面板设置	katana 提供
传输方式 TCP	TCP
传输方式 TCP，带 HTTP 头部伪装	普通 TCP。头部设置被忽略。
传输方式 WebSocket	在 path（默认 /）上提供 WebSocket。如果设置了 headers.Host，只接受请求该主机名的请求。
传输方式 gRPC	使用面板 serviceName 的 gRPC。启用 TLS 时提供 ALPN h2。
传输方式 HTTPUpgrade	拒绝：node requests kernel-unsupported feature: httpupgrade transport
传输方式 XHTTP 或 SplitHTTP	拒绝：node requests kernel-unsupported feature: splithttp transport
其他任何传输方式	拒绝：node requests kernel-unsupported feature: transport "…"
开启 TLS	使用本地证书的 TLS。需要 [node.controller.cert] mode = "file"。
REALITY	拒绝：node requests kernel-unsupported feature: REALITY
VLESS 流控，例如 xtls-rprx-vision	拒绝：node requests kernel-unsupported feature: VLESS XTLS flow
VLESS encryption	忽略
多路复用（smux、yamux、h2mux）	忽略。使用它的客户端会连接失败；请保持关闭。Xray 的 Mux.Cool 不受影响，照常可用。

用户使用 UUID 认证。VMess 只运行在 AEAD 模式下，alterId 为 0。

当前版本 Xboard 下基于 WebSocket 或 gRPC 的 VLESS

katana 从 network_settings 字段读取 VLESS 节点的传输层设置。而当前版本的 Xboard 对所有协议都把这些设置放在 networkSettings 下发送，因此 katana 读不到 VLESS 节点的任何设置。结果是：

• WebSocket 在 / 上提供，不检查 Host，无论面板向客户端展示的路径是什么。
• gRPC 使用空的服务名提供。
• 基于 TCP 的 VLESS（无论是否启用 TLS）不受影响。

对接这样的面板时，请通过 TCP 加 TLS 提供 VLESS，或者在面板中把 WebSocket 路径设为 /，让客户端请求的路径与 katana 提供的一致。把 VLESS 设置放在 network_settings 下发送的面板，行为与上文描述一致。VMess 节点读取的是 networkSettings，不受影响。

Trojan

面板设置	katana 提供
TLS	带 TLS 的 TCP，使用本地证书
传输方式 WebSocket 或 gRPC	仍然是带 TLS 的 TCP。传输方式被忽略。
REALITY	使用本地证书的普通 TLS。REALITY 被忽略。
多路复用（smux、yamux、h2mux）	忽略。使用它的客户端会连接失败；请保持关闭。

Trojan 密码就是用户的 UUID。

Shadowsocks

面板加密方式	katana 提供
aes-128-gcm、aes-256-gcm、chacha20-ietf-poly1305、xchacha20-ietf-poly1305	Shadowsocks AEAD。每个用户的密码就是其 UUID。
2022-blake3-aes-128-gcm、2022-blake3-aes-256-gcm	所有用户共用一个端口的 Shadowsocks 2022。面板的 server_key 是服务端 PSK，每个用户的 PSK 是其 UUID 文本的前 16 或 32 个字符，与 Xboard 为客户端订阅生成 PSK 的方式相同。
2022-blake3-chacha20-poly1305	失败：Xboard 不会为这种加密方式发送 server_key，katana 会报错 shadowsocks-2022: PSK too short (0 < 32)。请改用 AES 变体。
其他任何加密方式	拒绝：node requests kernel-unsupported feature: shadowsocks cipher "…"
插件	忽略

katana 只通过 TCP 提供 Shadowsocks，不会为 Shadowsocks 打开 UDP 端口。

Hysteria

面板设置	katana 提供
版本 2	在 UDP server_port 上提供 Hysteria 2，使用本地证书
版本 1	不支持。katana 在该端口上提供的是 Hysteria 2，Hysteria 1 客户端无法使用；而且版本 1 的混淆密码会让节点报错 unknown obfs。
开启混淆，类型为 Salamander	使用面板密码的 Salamander。密码短于 4 字节时报错 obfs_password must be at least 4 bytes for salamander。
关闭混淆，但仍填着密码	报错 obfs_password is set but obfs is not; did you mean obfs = "salamander"?。即使混淆已关闭，Xboard 仍会发送已保存的密码，因此关闭混淆时请同时清空密码字段。
上行和下行带宽	忽略
TLS 服务器名称、允许不安全连接	忽略；域名由证书决定

用户使用 UUID 认证。设置 [node.hysteria] credential = "user_pass" 时，用户名为 <uuid>@v2board.user，密码为 UUID。其余 Hysteria 设置见 Hysteria 2 节点。

用户

user 响应中的每个条目对应一个账户：

响应字段	katana 的用途
id	上报流量时使用的 uid
uuid	凭据：VMess 或 VLESS 的 ID、Trojan 密码、Shadowsocks 密码，或 Hysteria 2 的认证字符串
speed_limit	用户的限速，单位 Mbps。0 表示不限速。

用户从列表中消失后（例如被面板封禁，或者套餐到期、流量用尽），在第一次拿到新列表的轮询时，其已打开的连接会被断开。在 VMess 或 VLESS 节点上，uuid 不是合法 UUID 的用户会被跳过，katana 记录 skipping user <id>: uuid is not a valid UUID；其他用户照常服务。

speed_limit 必须是数字

katana 要求每个用户的 speed_limit 都是整数。只要有一个用户的 speed_limit 为 null，katana 就会以 parse UniProxy user response 拒绝整个响应，正在启动的节点不会启动完成，而是重试（见 启动、轮询与失败处理）。运行中的节点继续使用上次应用的列表；由于已保存的标签（见 ETag 与 304），这个错误只记录一次，在面板中的列表发生变化之前不会再次读取。Xboard 用 NULL 表示“不限速”，购买了不限速套餐的用户也会得到 NULL，因此这些用户在响应中都是 null。请为每个套餐和每个现有用户设置明确的限速；0 表示不限速。

限速

katana 将 Mbps 乘以 125 000 换算为字节每秒，并对每个用户在该节点上的所有连接合并执行限速。面板为每个用户提供一个限速值，没有节点级限速。

[node.api] speed_limit	每个用户的实际限速
0（默认）或更小	面板中该用户的 speed_limit。其中 0 表示不限速。
大于 0	所有用户都使用此值，无论面板如何设置

用户在面板中的限速变化会在下一次轮询时生效，不会断开连接：已有连接保持旧限速，该次轮询之后新建的连接使用新限速。限速的执行方式见 限速。

审计规则

Xboard 的路由规则同时充当 katana 的审计规则。当面板中为节点分配了路由时，config 响应会以 routes 字段下发它们，katana 会把每条 action 为 block 的路由转换为一条规则：

• 该路由的各个 match 条目用 | 连接成一个正则表达式；
• 在每个连接的目标主机中以非锚定方式搜索该表达式；目标主机指客户端请求的域名或 IP 地址，不含端口；
• 第一条匹配的规则会拒绝该连接；发往匹配目标的 UDP 数据包会被丢弃。

其他动作（direct、dns、proxy）的路由会被忽略。路由请使用 [node.route]。

例如，action 为 block、match 为 ["(^|\\.)example\\.org$", "^torrent\\."] 的路由会拒绝 example.org、www.example.org，以及任何以 torrent. 开头的主机，例如 torrent.example.com。

使用普通正则表达式

katana 按原样使用每个 match 条目，不会去掉 regexp:、domain: 或 protocol: 之类的前缀，因此 regexp:example\.org 这样的条目会查找这段字面文本，什么也匹配不到。不是合法正则表达式的条目会让 katana 记录 invalid block rule […]，并跳过整条路由。

katana 不需要额外请求来获取规则：每次轮询时，它都会根据最近一次 config 响应，并结合 rule_list_path 中的规则重新构建规则。如果面板不再下发 routes，面板规则会在下一次完整的 config 响应时消失。UniProxy 没有上报审计命中的接口，因此 katana 拒绝连接后不会向面板报告任何内容。本地规则文件和匹配细节见 审计规则。

流量上报

每次轮询时，katana 会提交每个用户自上次成功上报以来产生的流量：

{"1001": [52428800, 1073741824], "1002": [0, 4096]}

每个键是用户 id 的字符串形式，每个值是以字节为单位的 [upload, download]。上行是用户发送的数据，下行是用户接收的数据。katana 统计的是与目标之间中继的字节数，因此不包含协议和 TLS 的开销。

• 没有流量的用户不会出现在上报中。所有用户都没有流量时，katana 不发送任何请求。
• katana 只检查 HTTP 状态码。成功时，它精确扣除已上报的字节数，因此请求进行期间统计到的流量会计入下一次上报。
• 失败时，katana 记录 report traffic 并保留计数；下一次轮询会把它们与新流量一起上报。如果面板实际上已经处理了上报，但 katana 没有收到响应（例如请求超时），这部分字节会被再次上报。
• katana 停止时，以及热重载移除或替换某个节点时，该节点会最后上报一次流量。
• 设置 disable_upload_traffic = true 时，katana 不提交任何内容。计数的处理方式见 设置。

Xboard 根据上报请求得出节点的在线用户数和最后上报时间，在线用户数会保留一小时。没有流量的节点不会发送上报，因此面板会显示它在线，但没有最近的上报记录。计数器的详细说明见 流量上报。

katana 不调用的接口

接口	面板因此缺少的信息
POST /api/v1/server/UniProxy/alive、GET …/alivelist	每个用户的在线 IP。对接 katana 时，面板无法执行设备数限制。
POST /api/v1/server/UniProxy/status	节点的 CPU、内存和磁盘负载
/api/v2/server/…	katana 只使用 V1 路由
ShadowsocksTidalab、TrojanTidalab	katana 只使用 UniProxy

每次 katana 拉取用户列表时，Xboard 都会将节点标记为已签到，因此只要 katana 在轮询，节点就会显示为在线。

在 katana 运行时修改设置

katana 会监视配置文件，大多数修改无需重启即可生效；完整列表见 热重载。对于此面板：

• 修改 panel_type（仅改大小写除外）、host、node_id 或 key 会替换该节点。任何改变 katana 向面板请求的节点类型的修改也是如此：node_type（仅改大小写除外），或 v2ray、vmess 节点上的 enable_vless。Xboard 同时按 ID 和类型查找节点，因此这些修改都会指向面板中的另一个节点。旧节点停止运行，断开其连接，并最后上报一次流量；随后 katana 从面板启动一个全新的节点，使用它自己的流量计数器。
• 修改其他任何 [node.api] 键，例如 timeout、speed_limit 或 rule_list_path，会立即生效。katana 用新值构建新的面板客户端，完整读取节点及其用户，并像处理一次轮询的结果那样应用：除非节点的协议或传输层发生变化，连接都会保留。
• 对于请求的节点类型保持不变的节点，例如 node_type = "vless" 的节点，修改 enable_vless 会重建监听器，并断开该节点的连接。
• 导致节点无法构建的修改，例如未知的 node_type，会被整体拒绝。katana 记录 reload: node …: unknown node_type "…"; keeping current config，所有节点都保持原样继续运行。
• 面板中的修改在 katana 一侧无需任何操作，katana 会在下一次轮询时获取：新的端口、传输层或 TLS 设置会重建监听器，并断开该节点的连接；用户列表的变化则就地应用。

常见错误

前两条消息是 --test 输出的内容。启动时同样的错误会显示为 node 1: unknown panel_type "xboard"，katana 会跳过该节点；如果没有剩余可用节点，katana 以 no nodes could be started 退出。

node_info failed、user_list failed 和 initial start failed 这几类消息来自正在启动的节点。katana 以 ERROR 级别记录它们，末尾带有 ; retrying in <N>s，节点会自行重试，因此只需修正原因：节点会在下一次尝试时启动。

消息	原因	解决方法
configuration error: unknown panel_type "xboard"	panel_type 写成了面板产品名	Xboard 和 V2board 都使用 panel_type = "newv2board"。
configuration error: unknown node_type "…"	katana 不认识的 node_type	使用 node_type 中列出的值之一。
node 1: node_info failed: GET /api/v1/server/UniProxy/config	请求失败：面板无法访问，或者面板拒绝了密钥、节点 ID 或节点类型	按下文方法自己请求一次面板。
node 1: node_info failed: parse UniProxy config response	响应不是 katana 预期的 JSON，例如 host 指向了错误的站点而返回了 HTML 页面	检查 host。它应是面板的基础 URL，不含 /api/…。
node 1: node_info failed: newV2board: server port must be > 0	面板中该节点没有设置端口	在面板中设置端口。
node 1: node_info failed: newV2board: shadowsocks obfs "…" is not supported	面板要求 Shadowsocks 混淆	在面板中关闭混淆。
node 1: initial start failed: node requests kernel-unsupported feature: …	面板描述了 katana 拒绝的功能	在面板中修改节点；见 面板设置与 katana 实际提供的服务。
node 1: initial start failed: TLS node requires cert.mode = "file"	面板启用了 TLS，但节点没有证书	添加 [node.controller.cert]，并设置 mode = "file"、cert_file 和 key_file。
node 1: initial start failed: obfs_password is set but obfs is not; …	Hysteria 节点在面板中关闭了混淆，但仍保存着混淆密码	在面板中清空密码。
启动时 node 1: user_list failed: parse UniProxy user response; retrying in …，之后 node 1: user_list: parse UniProxy user response	某个用户条目的类型不符合预期，通常是 speed_limit 为 null	见 用户。
node 1: rebuild failed: …	面板的修改要求了 katana 无法提供的内容	节点保持停止服务，并在每次轮询时重试。请在面板中修正设置。
node 1: report traffic: POST UniProxy push	流量上报失败	如果只是暂时的，无需处理：计数会保留，并随下一次上报发送。

当日志中只写出接口名称时，可以用配置中的值直接请求面板。密钥会留在 shell 历史记录中，事后请清除：

curl -sS "https://panel.example.com/api/v1/server/UniProxy/config?node_id=1&node_type=vmess&token=replace-with-the-panel-key"

Xboard 对错误的密钥返回 Invalid token，对未知的节点类型返回 Invalid node type specified，对该类型下不存在的节点 ID 返回 Server does not exist。正常的节点会返回一个包含 server_port 的 JSON 对象。

相关页面

katana 快速上手安装 katana 并启动第一个面板节点。

配置文件katana 的全部配置键，包括本页未涉及的部分。

协议katana 为每种节点类型提供的服务，与面板无关。

Hysteria 2 节点本地描述和面板描述的 Hysteria 2 节点、凭据与伪装。

SSPanel（mod_mu）katana 支持的另一种面板。

故障排查诊断无法启动或不转发流量的节点。