C++ priority_queue 与 pair 自定义排序：三种写法及方向详解
2026/9/13 14:24:06
Neko V2 到 V3 迁移完全指南：Legacy 兼容模式、配置映射与 API 变更
【免费下载链接】nekoA self hosted virtual browser that runs in docker and uses WebRTC.项目地址: https://gitcode.com/GitHub_Trending/ne/neko
Neko 是一个运行在 Docker 中、基于 WebRTC 的自托管虚拟浏览器/桌面流媒体服务器。从 V2 升级到 V3 时，配置结构从"扁平的单一大块"演进为"分模块、可插拔"的组织方式，同时服务端内置了一层legacy 兼容模式，让旧版 V2 客户端与旧配置可以无缝过渡。本文以仓库文档 webpage/docs/migration-from-v2/README.md 为核心骨架，结合 server/cmd/root.go、server/internal/config 等源码，系统讲解兼容模式的启用机制、V2→V3 全量配置映射表、遗留 HTTP/WebSocket API 的行为差异，以及迁移后需要注意的已知限制，帮助你平滑完成升级并理解底层实现原理。
兼容模式：V2 配置如何自动启用 legacy 模式
Neko V3 默认处于兼容模式（compatibility mode）：只要检测到任何一个 V2 配置项被设置，就会自动开启 legacy 模式。这种设计的目的是让新用户不再暴露在 V2 API 之下，同时让仍在使用旧配置的存量用户保持原有行为，实现 V2 → V3 的平滑过渡。
从 server/cmd/root.go 与 server/internal/config/root.go 的实现可以看到 legacy 模式的实际判定逻辑：
// root.go init() if viper.GetBool("legacy") || !viper.IsSet("legacy") { rootConfig.SetV2() }// Root.SetV2() 的关键逻辑 enableLegacy := false if viper.IsSet("logs") { if viper.GetBool("logs") { logs := filepath.Join(".", "logs") if runtime.GOOS == "linux" { logs = "/var/log/neko" } s.LogDir = logs } else { s.LogDir = "" } log.Warn().Msg("you are using v2 configuration 'NEKO_LOGS' which is deprecated, please use 'NEKO_LOG_DIR=/path/to/logs' instead") enableLegacy = true } // 只要发现任意 V2 配置被使用，就自动把 legacy 置为 true if !viper.IsSet("legacy") && enableLegacy { viper.Set("legacy", true) }也就是说，legacy 模式的启用遵循以下规则：
- 显式开启：设置
NEKO_LEGACY=true（或命令行--legacy=true），无论是否使用了 V2 配置项都会强制开启； - 显式关闭：设置
NEKO_LEGACY=false，即使存在 V2 配置项也会被忽略（不推荐，见下文警告）； - 自动判定：未显式设置时，只要检测到任意一个 V2 配置项（如
NEKO_LOGS、NEKO_CERT、NEKO_BIND等），legacy 模式自动开启，并在日志中输出形如legacy configuration is enabled because at least one V2 configuration was used...的告警提示你尽快迁移。
# 显式开启 legacy 模式 NEKO_LEGACY=true # 显式关闭 legacy 模式（仅当使用兼容 V3 的新客户端时） NEKO_LEGACY=false:::warning 重要警告 legacy 模式目前仍被官方内置客户端使用。官方文档明确建议：可以逐步迁移到新的配置项，但不要关闭 legacy 模式，除非你正在使用兼容 V3 的新客户端（例如demodesk/neko-client）。一旦新客户端正式发布，legacy 模式将从服务端自动移除。 :::
另一个值得注意的规则是优先级：如果同时设置了 V3 和 V2 配置项，V2 配置项优先生效（例如同时设置NEKO_BIND与NEKO_SERVER_BIND时，NEKO_BIND会被采用），这是为了保证 legacy 模式按预期工作、不破坏现有配置。每个SetV2()方法内部也都逐个检查viper.IsSet(...)并输出对应的 deprecation 告警，方便你定位仍在使用的旧配置。
Docker 镜像变更：多架构与新的主分发渠道
V2 时代 Neko 主要发布在 Docker Hub 的m1k1o/neko仓库。V3 之后：
- 主分发渠道迁移到 GitHub Container Registry：
ghcr.io/m1k1o/neko（Docker Hub 上的m1k1o/neko仍保留可用）； - ARM 镜像不再使用独立 flavor 标签：V2 时代你需要使用
m1k1o/neko:arm-firefox或ghcr.io/m1k1o/neko/arm-firefox这类专门标签；V3 起 ARM 与 amd64 合并为多架构镜像（multi-arch），直接使用与 amd64 相同的标签即可，例如ghcr.io/m1k1o/neko/firefox； - V2 镜像中提供的全部应用（Firefox、Chromium、Brave、VLC 等）在 V3 镜像中同样可用，完整列表见 webpage/docs/installation/docker-images.md。
仓库根目录的 docker-compose.yaml 展示的就是 V3 风格的编排示例：
services: neko: image: "ghcr.io/m1k1o/neko/firefox:latest" restart: "unless-stopped" shm_size: "2gb" ports: - "8080:8080" - "52000-52100:52000-52100/udp" environment: NEKO_DESKTOP_SCREEN: 1920x1080@30 NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin NEKO_WEBRTC_EPR: 52000-52100 NEKO_WEBRTC_ICELITE: 1 # NEKO_NAT1TO1: <IP_ADDRESS>配置迁移：V2 → V3 全量映射表
V3 的配置相比 V2 做了模块化拆分：不再是单一的扁平命名空间，而是按职责划分为server、session、capture、desktop、member、webrtc等区块。映射表之外的每个 V2 配置项在源码中都对应一个InitV2（注册 flag）与SetV2（读取并映射）方法，下面按模块逐一说明。
服务端基础配置（Server）
对应源码：server/internal/config/server.go
| V2 配置 | V3 配置 | 说明 |
|---|---|---|
NEKO_LOGS=true | NEKO_LOG_DIR=/var/log/neko | V3 允许指定日志目录；在 Linux 上NEKO_LOGS=true等价于把日志写入/var/log/neko，并支持neko-latest.log自动轮转（见 server/cmd/root.go） |
NEKO_CERT | NEKO_SERVER_CERT | SSL 证书路径，默认空 |
NEKO_KEY | NEKO_SERVER_KEY | SSL 私钥路径，默认空 |
NEKO_BIND | NEKO_SERVER_BIND | 监听地址/端口/socket，V3 默认127.0.0.1:8080 |
NEKO_PROXY | NEKO_SERVER_PROXY | 是否信任反向代理头，默认false |
NEKO_STATIC | NEKO_SERVER_STATIC | 需要静态托管的 neko 客户端文件路径 |
NEKO_PATH_PREFIX | NEKO_SERVER_PATH_PREFIX | HTTP 请求路径前缀，V3 默认/ |
NEKO_CORS | NEKO_SERVER_CORS | 允许的跨域来源列表；V3 中为空则禁用 CORS，含*则允许所有来源（会输出生产环境告警） |
补充说明：V3 中NEKO_SERVER_CORS是字符串列表类型，*通配符会被归一化为["*"]；NEKO_SERVER_PATH_PREFIX会被path.Join("/", path.Clean(...))规范化，保证以/开头。
会话与权限（Session）
对应源码：server/internal/config/session.go
| V2 配置 | V3 配置 | 说明 |
|---|---|---|
NEKO_LOCKS | NEKO_SESSION_LOCKED_CONTROLS和NEKO_SESSION_LOCKED_LOGINS | V3 将控制锁与登录锁拆分为两个独立开关；V2 的NEKO_LOCKS=control,login会被分别映射为true |
NEKO_IMPLICIT_CONTROL | NEKO_SESSION_IMPLICIT_HOSTING | 是否允许隐式接管控制，V3 默认true |
NEKO_CONTROL_PROTECTION | NEKO_SESSION_CONTROL_PROTECTION | 控制保护：仅在房间内至少有一名管理员时，普通用户才能获得控制权，默认false |
NEKO_HEARTBEAT_INTERVAL | NEKO_SESSION_HEARTBEAT_INTERVAL | 心跳间隔（秒），V2 默认 120，V3 默认 10 |
WebRTC 视频（Video）
对应源码：server/internal/config/capture.go 与 server/internal/config/capture_pipeline.go
| V2 配置 | V3 配置 | 说明 |
|---|---|---|
NEKO_DISPLAY | NEKO_CAPTURE_VIDEO_DISPLAY和NEKO_DESKTOP_DISPLAY | 若两者想保持一致，推荐直接使用DISPLAY环境变量；V3 中NEKO_CAPTURE_VIDEO_DISPLAY未设置时会自动回退到DISPLAY环境变量 |
NEKO_VIDEO_CODEC | NEKO_CAPTURE_VIDEO_CODEC | 视频编码器，V3 默认vp8，支持 vp8/vp9/h264/av1 |
NEKO_AV1=truedeprecated | NEKO_CAPTURE_VIDEO_CODEC=av1 | 旧布尔开关已废弃 |
NEKO_H264=truedeprecated | NEKO_CAPTURE_VIDEO_CODEC=h264 | 旧布尔开关已废弃 |
NEKO_VP8=truedeprecated | NEKO_CAPTURE_VIDEO_CODEC=vp8 | 旧布尔开关已废弃 |
NEKO_VP9=truedeprecated | NEKO_CAPTURE_VIDEO_CODEC=vp9 | 旧布尔开关已废弃 |
NEKO_VIDEO | NEKO_CAPTURE_VIDEO_PIPELINE | V3 支持多条视频管道（NEKO_CAPTURE_VIDEO_PIPELINES为 JSON 映射，NEKO_CAPTURE_VIDEO_PIPELINE为单条快捷方式） |
NEKO_VIDEO_BITRATE | 已移除 | 改用自定义 pipeline 实现，参考 webpage/docs/configuration/capture.md |
NEKO_HWENC | 已移除 | 改用自定义 pipeline 实现 |
NEKO_MAX_FPS | 已移除 | 改用自定义 pipeline 实现 |
关于已移除项的实现细节：V3 之所以移除NEKO_VIDEO_BITRATE、NEKO_HWENC、NEKO_MAX_FPS，是因为引入多视频管道后，码率/帧率/硬件编码都应由 GStreamer pipeline 参数直接表达。源码 server/internal/config/capture_pipeline.go 保留了NewVideoPipeline函数用于在 legacy 模式下"翻译"这些旧参数——例如hwenc=none|vaapi|nvenc分别对应 CPU、VAAPI、NVENC 编码路径，默认帧率 25fps，并用ximagesrc display-name=%s show-pointer=true use-damage=false作为视频源。也就是说，即使你暂时不迁移，legacy 层也会把这些旧参数还原成等价的 V3 pipeline。
游标（cursor）限制：V2 没有客户端侧游标支持，鼠标指针始终被编码进视频流；V3 中游标与视频流分离传输。因此使用 legacy 配置时，服务端会创建两条视频管道——一条带游标（供 V2 客户端）、一条不带游标（供 V3 客户端）。在 server/internal/config/capture.go 的Set()中可以看到：legacy 模式下默认管道会额外生成一个"legacy"管道（强制show-pointer=true），且该管道不加入VideoIDs，从而不会被带宽估算器计入。如果你不希望这种双流行为，请优先迁移到新配置。
WebRTC 音频（Audio）
| V2 配置 | V3 配置 | 说明 |
|---|---|---|
NEKO_DEVICE | NEKO_CAPTURE_AUDIO_DEVICE | PulseAudio 采集设备，V3 默认audio_output.monitor |
NEKO_AUDIO_CODEC | NEKO_CAPTURE_AUDIO_CODEC | 音频编码器，V3 默认opus |
NEKO_G722=truedeprecated | NEKO_CAPTURE_AUDIO_CODEC=g722 | 旧布尔开关已废弃 |
NEKO_OPUS=truedeprecated | NEKO_CAPTURE_AUDIO_CODEC=opus | 旧布尔开关已废弃 |
NEKO_PCMA=truedeprecated | NEKO_CAPTURE_AUDIO_CODEC=pcma | 旧布尔开关已废弃 |
NEKO_PCMU=truedeprecated | NEKO_CAPTURE_AUDIO_CODEC=pcmu | 旧布尔开关已废弃 |
NEKO_AUDIO | NEKO_CAPTURE_AUDIO_PIPELINE | GStreamer 音频管道 |
NEKO_AUDIO_BITRATE | 已移除 | 改用自定义 pipeline 实现 |
legacy 模式下，旧音频参数由 server/internal/config/capture_pipeline.go 中的audioSrc = "pulsesrc device=%s ! audio/x-raw,channels=2 ! audioconvert ! "模板与NewAudioPipeline组合还原为等价管道。
广播（Broadcast）
| V2 配置 | V3 配置 | 说明 |
|---|---|---|
NEKO_BROADCAST_PIPELINE | NEKO_CAPTURE_BROADCAST_PIPELINE | 自定义广播 GStreamer 管道，支持{hostname}、{url}、{device}、{display}占位符替换（见 server/internal/config/capture_pipeline.go） |
NEKO_BROADCAST_URL | NEKO_CAPTURE_BROADCAST_URL | 广播默认目标 URL；设置后管理员可在 GUI 中修改/关闭 |
NEKO_BROADCAST_AUTOSTART | NEKO_CAPTURE_BROADCAST_AUTOSTART | 是否在 neko 启动且配置了 URL 时自动开始广播；V2 默认false，V3 默认true |
桌面（Desktop）
| V2 配置 | V3 配置 | 说明 |
|---|---|---|
NEKO_SCREEN | NEKO_DESKTOP_SCREEN | 默认屏幕分辨率与帧率，V3 格式如1920x1080@30 |
认证（Authentication）
| V2 配置 | V3 配置 | 说明 |
|---|---|---|
NEKO_PASSWORD | NEKO_MEMBER_MULTIUSER_USER_PASSWORD，且需NEKO_MEMBER_PROVIDER=multiuser | 普通用户密码 |
NEKO_PASSWORD_ADMIN | NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD，且需NEKO_MEMBER_PROVIDER=multiuser | 管理员密码 |
要让 legacy 认证正常工作，必须配置 multiuser 成员提供者（NEKO_MEMBER_PROVIDER=multiuser），详见 webpage/docs/configuration/authentication.md。
:::warning 限制 V2 客户端可能无法兼容除multiuser之外的任何其他认证提供者。 :::
WebRTC 网络（WebRTC）
对应源码：server/internal/config/webrtc.go
| V2 配置 | V3 配置 | 说明 |
|---|---|---|
NEKO_NAT1TO1 | NEKO_WEBRTC_NAT1TO1 | 1:1 (D)NAT 外部 IP 及候选类型列表 |
NEKO_TCPMUX | NEKO_WEBRTC_TCPMUX | 所有 peer 共用的单一 TCP mux 端口 |
NEKO_UDPMUX | NEKO_WEBRTC_UDPMUX | 所有 peer 共用的单一 UDP mux 端口，取代 EPR |
NEKO_ICELITE | NEKO_WEBRTC_ICELITE | ICE Lite 模式，默认false |
NEKO_ICESERVERS或NEKO_ICESERVER | NEKO_WEBRTC_ICESERVERS_FRONTEND和NEKO_WEBRTC_ICESERVERS_BACKEND | V3 支持前端/后端使用不同的 ICE 服务器 |
NEKO_IPFETCH | NEKO_WEBRTC_IP_RETRIEVAL_URL | 当未配置 NAT1TO1 时，从该 URL 自动获取公网 IP；V3 默认https://checkip.amazonaws.com |
NEKO_EPR | NEKO_WEBRTC_EPR | ICE UDP 连接可分配的临时端口范围 |
完整的 V2 配置参考（legacy 支持项全集）
以下是 Neko V2 中所有在 V3 启用 legacy 后仍然有效的配置项完整列表，其默认值与类型定义来自迁移文档所引用的 webpage/docs/migration-from-v2/help.json：
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
NEKO_LEGACY | boolean | true | 是否启用 legacy 模式 |
NEKO_LOGS | boolean | false | 是否将日志保存到文件 |
NEKO_CERT | string | — | 用于保护 neko 服务器的 SSL 证书路径 |
NEKO_KEY | string | — | 用于保护 neko 服务器的 SSL 私钥路径 |
NEKO_BIND | string | — | neko 服务监听地址/端口/socket |
NEKO_PROXY | boolean | false | 是否启用反向代理模式 |
NEKO_STATIC | string | — | 需要托管的 neko 客户端文件路径 |
NEKO_PATH_PREFIX | string | — | HTTP 请求路径前缀 |
NEKO_CORS | strings | — | 允许的 CORS 来源列表 |
NEKO_LOCKS | strings | — | 启动时锁定的资源（control、login） |
NEKO_IMPLICIT_CONTROL | boolean | false | 启用后成员可隐式获得控制 |
NEKO_CONTROL_PROTECTION | boolean | false | 控制保护：仅当房间内至少一名管理员时才可获得控制 |
NEKO_HEARTBEAT_INTERVAL | int | 120 | 心跳间隔（秒） |
NEKO_FILE_TRANSFER_ENABLED | boolean | false | 是否启用文件传输 |
NEKO_FILE_TRANSFER_PATH | string | — | 文件传输使用的路径 |
NEKO_DISPLAY | string | — | 要采集的 X Display |
NEKO_VIDEO_CODEC | string | — | 使用的视频编码器 |
NEKO_AV1 | boolean | false | 废弃：改用video_codec |
NEKO_H264 | boolean | false | 废弃：改用video_codec |
NEKO_VP8 | boolean | false | 废弃：改用video_codec |
NEKO_VP9 | boolean | false | 废弃：改用video_codec |
NEKO_VIDEO | string | — | 用于流媒体传输的视频编码参数 |
NEKO_VIDEO_BITRATE | int | — | 视频码率（kbit/s） |
NEKO_HWENC | string | — | 使用硬件加速编码 |
NEKO_MAX_FPS | int | — | WebRTC 最大 FPS，0 表示无上限 |
NEKO_DEVICE | string | — | 要采集的音频设备 |
NEKO_AUDIO_CODEC | string | — | 使用的音频编码器 |
NEKO_G722 | boolean | false | 废弃：改用audio_codec |
NEKO_OPUS | boolean | false | 废弃：改用audio_codec |
NEKO_PCMA | boolean | false | 废弃：改用audio_codec |
NEKO_PCMU | boolean | false | 废弃：改用audio_codec |
NEKO_AUDIO | string | — | 用于流媒体传输的音频编码参数 |
NEKO_AUDIO_BITRATE | int | — | 音频码率（kbit/s） |
NEKO_BROADCAST_PIPELINE | string | — | 广播用自定义 gst 管道，{hostname}{url}{device}{display}会被替换 |
NEKO_BROADCAST_URL | string | — | 广播流默认 URL，管理员稍后可在 GUI 中关闭/修改 |
NEKO_BROADCAST_AUTOSTART | boolean | false | 当 neko 启动且设置了 broadcast_url 时自动开始广播 |
NEKO_SCREEN | string | — | 默认屏幕分辨率与帧率 |
NEKO_PASSWORD | string | — | 连接流的密码 |
NEKO_PASSWORD_ADMIN | string | — | 连接流的管理员密码 |
NEKO_NAT1TO1 | strings | — | 1:1 (D)NAT 外部 IP 地址及候选类型列表 |
NEKO_TCPMUX | int | — | 所有 peer 共用的单一 TCP mux 端口 |
NEKO_UDPMUX | int | — | 所有 peer 共用的单一 UDP mux 端口 |
NEKO_ICELITE | boolean | false | ICE agent 是否为 lite agent |
NEKO_ICESERVER | strings | — | ICEAgent 建立连接可用的单个 STUN/TURN 服务器描述 |
NEKO_ICESERVERS | string | — | ICEAgent 建立连接可用的单个 STUN/TURN 服务器描述 |
NEKO_IPFETCH | string | — | 未配置 nat1to1 时，从给定 URL 自动获取 IP |
NEKO_EPR | string | — | 限制 ICE UDP 连接可分配的临时端口池 |
完整的新版 V3 配置参考见 webpage/docs/configuration/README.md。
文件传输的迁移
NEKO_FILE_TRANSFER_ENABLED/NEKO_FILE_TRANSFER_PATH的对应 V3 配置为：
| V2 配置 | V3 配置 |
|---|---|
NEKO_FILE_TRANSFER_ENABLED | NEKO_FILETRANSFER_ENABLED |
NEKO_FILE_TRANSFER_PATH | NEKO_FILETRANSFER_DIR |
V3 中文件传输的完整能力由File Transfer 插件承载（见 server/internal/plugins/filetransfer/plugin.go 与 webpage/docs/configuration/plugins.md），包括上传、下载、拖拽（drop）等能力，配置项也更细化。
API 迁移：legacy API 兼容层如何工作
启用 legacy 后，V3 服务端会通过一个专门的**兼容层（legacy API）**让 V2 客户端连接 V3。它默认开启，后续版本中将被移除。兼容层挂载入口在 server/internal/http/manager.go：legacy 模式开启时调用legacy.New(serverAddr, pathPrefix).Route(router)注册/ws、/stats、/screenshot.jpg、/file、/health等旧端点；若使用 HTTPS（配置了 Cert/Key），还会额外在本机随机端口启动一个 HTTP 代理来承载 legacy 转发（见 server/internal/http/manager.go）。
认证：从?pwd=到?usr=&pwd=
V2 只有一个认证提供者，即 V3 中被称为multiuser的提供者。V2 的 API 仅凭密码（?pwd=查询串）判断用户是否为管理员。
V3 的认证方式不同（见 server/internal/api/sessions/handler.go 与 webpage/docs/api/README.mdx），因此 legacy API 新增了?usr=查询串来指定用户名：
- 密码仍然通过
?pwd=提供； ?usr=是可选的，未提供时 API 会生成随机用户名；- 只有
multiuser（或noauth）提供者支持不指定?usr=。
在 server/internal/http/legacy/session.go 的create()中可以看到，legacy 会话本质上就是调用 V3 的/api/login获取 token，随后所有请求都携带Authorization: Bearer <token>转发到 V3 后端 API。
:::warning 会话生命周期限制 legacy API 的每一次请求都会基于?usr=&pwd=创建一个新的用户会话，请求完成后会话即被销毁。因此 HTTP API 请求的会话是短生命周期的；而 WebSocket API 请求的会话会一直存活到 WebSocket 连接关闭。 :::
WebSocket 消息：/ws与/api/ws
WebSocket 消息属于内部协议（非面向用户的 API），因此没有专门的迁移指南。启用 legacy 时：
- V2 客户端连接
/ws端点，由兼容层以 V2 协议处理； - V3 原生 API 位于
/api/ws端点（server/internal/http/manager.go）。
兼容层的/ws实现（server/internal/http/legacy/handler.go）本质上是一个协议翻译代理：先将 HTTP 连接升级为 WebSocket，然后向本地 V3 后端ws://<serverAddr>/api/ws?token=...发起拨号，再在两条连接之间双向复制消息，并在复制过程中调用wsToClient/wsToBackend完成新旧消息格式的互转。V2 与 V3 的心跳差异：V2 每60 秒发送一次 WebSocket ping，V3 每10 秒发送一次，并额外使用心跳机制（heartbeat）验证连接是否仍然存活（对应NEKO_SESSION_HEARTBEAT_INTERVAL，默认 10 秒）。
WebRTC API：字节序与数据通道方向
WebRTC API 同样是内部协议，没有迁移指南，但有两个底层行为变化值得注意：
- 字节序变更：控制消息从 Little Endian 改为Big Endian，便于客户端侧操作；
- 数据通道方向反转：V2 由客户端创建新数据通道，V3 改为由服务端创建新数据通道。legacy 模式下，服务端只是监听来自客户端的新数据通道，并用 legacy API handler 接受它，同时用 legacy 通道覆盖已有的 V3 数据通道。
HTTP API：从受限到强大
V2 的 HTTP API 非常有限，V3 的 API 更强大、更灵活（完整文档见 webpage/docs/api/README.mdx）。以下是 legacy 层保留的旧端点及其 V3 对应关系：
GET/health
迁移至 V3 的 Health 端点（服务健康检查）。服务运行正常时返回200 OK。legacy 实现中直接写入true（见 server/internal/http/legacy/handler.go）。
GET/stats
迁移至 V3 的 Stats 端点（服务端统计）与 List Sessions 端点（会话列表）。legacy 实现内部会并行请求/api/sessions、/api/stats、/api/room/settings三个 V3 端点再聚合（见 server/internal/http/legacy/handler.go）。返回 JSON 结构如下：
{ // 当前活跃连接数 "connections": 0, // 当前持会话者（无人时为空） "host": "<session_id>", // 当前已连接用户列表 "members": [ { "session_id": "<session_id>", "displayname": "Name", "admin": true, "muted": false, } ], // 被封禁 IP 及其封禁者 session_id "banned": { "<ip>": "<session_id>" }, // 被锁定资源及其锁定者 session_id "locked": { "<resource>": "<session_id>" }, // 服务器启动时间 "server_started_at": "2021-01-01T00:00:00Z", // 最后一位管理员/普通用户离开会话的时间 "last_admin_left_at": "2021-01-01T00:00:00Z", "last_user_left_at": "2021-01-01T00:00:00Z", // 是否启用了控制保护或隐式控制 "control_protection": false, "implicit_control": false, }注意：该端点要求调用者是管理员（!s.isAdmin时返回401），其中host直接取 V3 stats 的HostId，locked由房间设置转换而来，banned目前尚未实现（源码中标记为TODO: stats.Banned, not implemented yet）。
GET/screenshot.jpg
迁移至 V3 的 Screenshot 端点（截屏）。返回桌面截图的 JPEG 图片，legacy 实现转发到/api/room/screen/shot.jpg并透传quality查询参数（server/internal/http/legacy/handler.go）。
GET/POST/DELETE/file
V2 的文件传输功能整体迁移到了File Transfer 插件（见 server/internal/plugins/filetransfer）。legacy 层将其映射到 V3 的/api/filetransfer端点，支持下载（GET）、上传（POST）与删除（DELETE），通过filename查询参数指定文件（server/internal/http/legacy/handler.go）。
迁移后的已知限制（Limitations）
锁与静音状态不持久化
V2 中，锁（locks）和静音用户通过一个简单 map 记录"谁设置的锁、锁了什么"。V3 中锁被实现为设置项（setting options），不再存储加锁用户的session_id。因此：
- 如果客户端刷新页面或重连，锁信息会丢失；
- 设置锁的用户在界面上会显示为
Somebody（匿名"某人"）。
会话列表中的 "Somebody"
使用 legacy API 配合 V2 客户端时，API 调用顺序与预期不同：客户端会先获取会话列表、再注册用户，因此拉取会话列表时当前session_id尚不可知，当前用户会以Somebody出现在会话列表中。这是顺序问题导致的显示限制，并非数据错误。
V3 暂无原生 pipeline 生成器
V3 目前没有原生支持 pipeline 自动生成，用户若想自定义视频/音频管道，需要手动编写完整 pipeline。V2 内置了简单的视频码率、FPS、音频码率与硬件编码设置支持；由于 V3 引入多视频管道，这一自动生成特性已被移除。好消息是 legacy 模式会在后台把旧参数翻译成等价管道（见上文"WebRTC 视频"一节），但这只是过渡手段，长期应直接编写 V3 的 GStreamer 管道配置。
迁移建议与检查清单
基于上述映射表与源码行为，推荐按以下步骤完成 V2 → V3 迁移：
- 先保持 legacy 模式运行：用原有 V2 配置直接启动 V3 镜像，观察启动日志中出现的 deprecation 告警，逐条记录仍在使用的 V2 配置项；
- 按模块替换配置：依照本文的映射表，将
NEKO_CERT→NEKO_SERVER_CERT、NEKO_BIND→NEKO_SERVER_BIND等基础项逐一迁移到 V3 命名空间，把NEKO_PASSWORD/NEKO_PASSWORD_ADMIN迁移为NEKO_MEMBER_PROVIDER=multiuser下的用户/管理员密码； - 处理已移除项：
NEKO_VIDEO_BITRATE、NEKO_HWENC、NEKO_MAX_FPS、NEKO_AUDIO_BITRATE已移除，需改写为自定义 GStreamer pipeline（参考 webpage/docs/configuration/capture.md 中的 pipeline 示例）； - 确认认证提供者：legacy 认证依赖
multiuser，且旧版客户端仅兼容该提供者；若升级了兼容 V3 的新客户端，可再考虑切换提供者； - 验证 API 行为：升级客户端后检查
/stats、/screenshot.jpg、文件传输等端点是否符合预期，注意锁信息与Somebody显示属于已知限制； - 最终关闭 legacy：确认新客户端（如
demodesk/neko-client）可用后，设置NEKO_LEGACY=false彻底切换到纯 V3 模式——届时旧/ws等 legacy 端点将不再注册。
以上迁移路径与兼容层行为均可通过 server/internal/config（配置映射）、server/internal/http/legacy（API 兼容层）、server/internal/http/manager.go（路由注册）等源码逐一验证，确保升级过程可控、可回退。
【免费下载链接】nekoA self hosted virtual browser that runs in docker and uses WebRTC.项目地址: https://gitcode.com/GitHub_Trending/ne/neko
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考