neko 开发者指南本地开发环境搭建、热重载工作流与 Monorepo 代码结构解析【免费下载链接】nekoA self hosted virtual browser that runs in docker and uses WebRTC.项目地址: https://gitcode.com/GitHub_Trending/ne/nekoneko 是一款自托管的虚拟浏览器以 Docker WebRTC 为核心将真实浏览器会话流式传输给多个用户。本文围绕仓库中的开发者指南webpage/docs/developer-guide/README.md展开系统讲解从零搭建本地开发环境所需的系统依赖、前后端分离式热重载工作流以及整个 Monorepo 的目录划分与构建链路。读完本文你将掌握后端跑在 Docker、前端本地热重载、改动即时生效的开发循环并理解server、client、runtime、apps、utils、webpage六大目录各自承担的职责。本文面向开发者聚焦 开发者指南、本地开发 与 仓库结构 三份文档的核心内容并结合仓库内的实际脚本与配置进行源码级印证。依赖清单从系统包到开发环境原文档明确标注Work in Progress但其中列出的依赖是理解整个项目技术栈的第一把钥匙。neko 的运行时链路是Xorg 提供显示服务 → PulseAudio 提供音频 → GStreamer 负责视频采集与编码 → Go 服务端负责 WebRTC 信令与媒体转发 → Vue/TypeScript 前端负责交互界面因此本地开发需要以下系统级依赖。Node.js 与 npm前端构建前端代码位于 client/使用 Vue 2 TypeScript构建工具为 Vue CLI见 client/package.json 中的serve、build脚本。开发机上需要 Node.js 与 npm若不想污染本机环境仓库提供了基于 Docker 的 npm 包装脚本见下文前端开发一节日常开发甚至无需本机安装 Node。Go服务端构建服务端位于 server/由 Go 编写server/go.mod并通过 server/pkg/gst/gst.go 等 cgo 文件调用 C 库因此依赖 X11 与 GStreamer 的开发头文件。GStreamer视频处理服务端通过 GStreamer pipeline 完成屏幕采集、编码VP8/H.264与推流。开发机需安装以下包sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \ gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \ gstreamer1.0-pulseaudio;注意libgstreamer1.0-dev与libgstreamer-plugins-base1.0-dev是 cgo 编译所必需的头文件而gstreamer1.0-pulseaudio负责将音频送入 PulseAudio 回环。这与 server/Dockerfile 中apt-get install的libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev完全一致只是 Docker 构建镜像还额外包含了libgtk-3-dev。X.orgX11 显示服务器服务端通过 X11 协议操作真实桌面需要 X11 头文件与 Xorg 本体sudo apt-get install libx11-dev libxrandr-dev libxtst-dev libxcvt-dev xorg;libx11-devX11 核心协议头文件libxrandr-dev屏幕分辨率动态调整xrandr对应 server/internal/desktop/xorg.go 中的桌面管理逻辑libxtst-devXTEST 扩展用于注入键盘/鼠标事件对应 server/pkg/xinput/ 与 server/internal/desktop/xinput.golibxcvt-devCVT 模型线计算用于生成虚拟显示器的分辨率模式xorgX 服务器本体。PulseAudio音频支持sudo apt-get install pulseaudio;音频通过 PulseAudio 服务端与 runtime/default.pa 配置加载 loopback 模块将应用声音回环给 GStreamer 采集。其他依赖sudo apt-get install xdotool xclip libgtk-3-0 libgtk-3-dev libopus0 libvpx6;xdotool/xclip桌面辅助工具xclip服务于剪贴板读写对应 server/internal/desktop/clipboard.golibgtk-3-0/libgtk-3-devGTK3 运行时与头文件用于文件选择对话框server/internal/desktop/filechooserdialog.golibopus0Opus 音频编解码库WebRTC 音频libvpx6VP8 视频编解码库WebRTC 视频对应 server/dev/runtime/config.yml 中默认的vp8enc编码器。仓库结构总览Monorepo 六大目录仓库结构文档 明确该项目采用Monorepo单仓库多模块结构共六个顶层目录各司其职目录语言/技术职责server/Go后端WebRTC 信令、媒体流转发、成员/会话管理、桌面控制client/TypeScript Vue 2前端浏览器中的交互界面视频流、聊天、控制面板runtime/Shell 配置运行时环境Xorg、PulseAudio、字体、图标主题apps/Dockerfile随镜像分发的应用程序Firefox、Chrome、KDE、VLC 等utils/Go / C构建工具与 Xorg 依赖补丁Dockerfile 生成器、自研驱动webpage/TypeScript Docusaurus项目官网与本文档所在的技术文档站server/Go 后端server/cmd/neko 服务端的子命令如serveserver/cmd/serve.go、pluginsserver/cmd/plugins.go与根命令 server/cmd/root.goserver/dev/本地开发脚本build、start、rebuild等详见下文server/internal/内部包包括apiREST/WS 接口、captureGStreamer 采集、desktopX11 桌面、webrtcPion WebRTC 封装、websocketWS 消息处理与plugins聊天、文件传输、openinapp 三大插件等server/pkg/可被其他项目复用的公共包如auth、gst、types、xevent、xinput、xorgserver/plugins/将被编译进服务端二进制/插件的源码目录当前为空插件源码位于server/internal/plugins/。client/Vue 前端client/dev/本地开发脚本serve、npm、execclient/public/静态资源图标、index.html、键盘布局、表情符号数据client/src/源码包括components/视频、聊天、设置、成员列表等 Vue 组件、store/Vuex 状态、neko/与后端协议对应的 base/data/events/messages 封装、locale/16 种语言的 i18nclient/tools/代码生成工具如根据 emoji 数据生成类型定义。runtime/运行时环境runtime/fontconfig/字体配置文件构建时复制到镜像的/etc/fonts/conf.d/runtime/fonts/ 与 runtime/icon-theme/空目录占位用于在运行时镜像中加入自定义字体与图标主题runtime/intel/ 与 runtime/nvidia/Intel / NVIDIA 专属 flavor 的运行时文件如 NVIDIA 的 entrypoint.shruntime/widevine-installer/来自 AsahiLinux 的 Widevine 安装脚本用于播放 DRM 内容。apps/随镜像分发的应用apps/ 下的每个应用目录firefox、google-chrome、chromium、kde、vlc、remmina 等都包含Dockerfile基于构建脚本传入的BASE_IMAGE扩展出应用镜像Dockerfile.flavor如Dockerfile.nvidia带硬件加速优化的变体supervisord.confsupervisord 进程管理配置运行期会被放置在应用镜像的/etc/neko/supervisord/app-name.conf。utils/构建工具与 Xorg 依赖utils/docker/main.goDockerfile 生成器通过拼接多个 Dockerfile 构建基础镜像对应server/dev/build调用的根目录build脚本utils/xorg-deps/自研或打过补丁的 Xorg 驱动包括xf86-input-neko输入驱动与xf86-video-dummy虚拟显示驱动 v0.3.8 randr 补丁。webpage/文档与官网webpage/docs/全部技术文档本文所属的 developer-guide 即位于此处webpage/scripts/用于生成配置文档与 OpenAPI 文档的辅助脚本webpage/src/Docusaurus 站点源码首页组件、CSSwebpage/static/站点静态资源图标、图片webpage/versioned_docs/ 与 webpage/versioned_sidebars/Docusaurus 为 v2 版本生成的版本化文档。本地开发后端进 Docker前端热重载本地开发文档 给出了 neko 推荐的开发模式后端跑在 Docker 容器中前端在本机以热重载方式运行。这样每次修改源码都不必重新构建整个 Docker 镜像唯一的先决条件是安装 Docker。首先克隆仓库并进入根目录git clone https://github.com/m1k1o/neko.git cd neko后端开发server/dev所有后端开发脚本都位于 server/dev/包括build、start、rebuild、exec、go、fmt、lint。首次构建镜像以下命令只需执行一次或在重大依赖变更后重跑cd server/dev ./buildbuild脚本实际做了三件事对应 server/dev/build基于 server/Dockerfile 构建neko_server:src镜像Go 1.25-trixie含 cgo 所需的 X11 / GStreamer / GTK3 头文件并把仓库源码与构建入口./build一并 COPY 进去调用仓库根目录的build脚本生成基础镜像neko_server:base该脚本由 utils/docker/ 的 Dockerfile 生成器驱动基于 server/dev/runtime/Dockerfile 构建最终开发镜像neko_server:app并将BASE_IMAGE指向neko_server:base。启动后端容器cd server/dev ./startstart脚本会先检查neko_server:app镜像是否存在不存在则自动执行./build。随后以如下参数启动名为neko_server_dev的前台容器见 server/dev/start端口映射3000 → 8080HTTP/WS API另映射52100端口的 TCP/UDP 作为 WebRTC 的 mux 端口环境变量NEKO_WEBRTC_UDPMUX、NEKO_WEBRTC_TCPMUX 52100、NEKO_WEBRTC_NAT1TO1自动探测本机局域网 IP用于 NAT 穿透、NEKO_SESSION_FILE/home/neko/sessions.txt、NEKO_DEBUG1挂载配置server/dev/runtime/config.yml→ 容器内/etc/neko/neko.yml运行时参数--shm-size2G、--security-opt seccompunconfinedWebRTC/浏览器所需。NEKO_PORT与NEKO_MUX可用环境变量覆盖默认值3000/52100。GPU 加速变体start脚本接受一个可选参数以启用硬件加速./start nvidia ./start intelnvidia追加--gpus all并使用config.nvidia.yml作为配置见 server/dev/runtime/config.nvidia.ymlintel追加--device /dev/dri暴露 Intel GPU 设备节点注意脚本中 Intel 配置仍为 TODO暂沿用默认config.yml。热更新后端live rebuild修改 Go 源码后无需重启 Docker只需在另一个终端执行cd server/dev ./rebuildserver/dev/rebuild 的执行流程每一步都有明确依据在neko_server:src镜像中执行./build编译出新的服务端二进制与插件编译环境与宿主机解耦保证 cgo 依赖一致删除运行容器内的旧插件docker exec neko_server_dev rm -rf /etc/neko/plugins用docker cp将新二进制覆盖到容器/usr/bin/neko若存在bin/plugins目录则一并复制到/etc/neko/plugins通过supervisorctl -c /etc/neko/supervisord.conf restart neko仅重启 neko 进程。整个过程不会重建 Docker 镜像因此通常几秒内即可完成一次迭代。开发辅助脚本补充server/dev/execdocker exec -it neko_server_dev /bin/bash进入运行中容器server/dev/go在neko_server:src中执行任意go命令并将go.mod/go.sum回拷到宿主机、commit 镜像server/dev/fmtgo fmt ./...server/dev/lint自动下载 golangci-lint v1.31.0 后运行静态检查。前端开发client/dev前端开发脚本位于 client/dev/包含serve、npm、exec。安装依赖首次运行./serve会自动安装依赖也可手动强制安装cd client/dev ./serve -i或者使用仓库提供的 Docker npm 包装脚本cd client/dev ./npm installclient/dev/npm 的本质是在node:18-bullseye-slim镜像中以当前用户身份、挂载client/为工作区执行npm $从而把依赖安装与宿主机 Node 环境彻底隔离。启动热重载开发服务器cd client/dev ./serveclient/dev/serve 的行为若client/node_modules不存在或传入了-i先在容器中执行npm install随后在node:18-bullseye-slim容器中运行npm run serve -- --port 3001并以VUE_APP_SERVER_PORT3000可用环境变量覆盖告知前端 API 地址宿主机端口3001映射进容器服务以--user $(id -u):$(id -g)运行避免容器内文件属主错乱。npm run serve实际执行的是 client/package.json 中的vue-cli-service serve --mode development即 Vue CLI 开发服务器具备 HMR模块热替换client/src/下任何文件保存后浏览器即时刷新无需手动重载页面。服务地址后端Docker 容器http://localhost:3000前端热重载http://localhost:3001典型开发工作流将前后端开发脚本组合起来就得到文档推荐的三终端工作流终端 1—— 启动后端cd server/dev ./start终端 2—— 启动前端cd client/dev ./serve浏览器打开http://localhost:3001Vue 开发服务器会把 API 请求代理到http://localhost:3000修改前端文件 → 浏览器自动更新修改后端文件 → 在终端 3执行cd server/dev ./rebuild应用变更开发配置速查config.yml 关键参数server/dev/runtime/config.yml 是开发模式下的后端配置挂载为容器内/etc/neko/neko.yml也是理解服务端各模块行为的窗口。以下为其核心片段与含义capture: video: codec: vp8 # 视频编码器默认 vp8enc ids: [ hq, lq ] # 可选的清晰度档位legacy 档不列入避免被带宽估计器计入 pipelines: hq: # 高清档目标码率约 3072*650 bps25fps fps: 25 gst_encoder: vp8enc gst_params: target-bitrate: round(3072 * 650) cpu-used: 4 end-usage: cbr # 恒定码率 threads: 4 deadline: 1 keyframe-max-dist: 25 min-quantizer: 4 max-quantizer: 20 lq: # 低清档目标码率约 1024*650 bps fps: 25 gst_encoder: vp8enc gst_params: target-bitrate: round(1024 * 650) # ... 其余参数与 hq 相同 screencast: enabled: true # 开启录屏功能 server: pprof: true # 开启 pprof 性能分析 desktop: screen: 1920x108060 # 虚拟屏幕分辨率 member: provider: multiuser # 成员提供者multiuser默认 multiuser: admin_password: admin # 管理员密码 user_password: neko # 普通用户密码 session: merciful_reconnect: true # 允许 WebSocket 断线重连可能有会话劫持风险 implicit_hosting: false inactive_cursors: true # 显示非活动光标 api_token: neko123 # REST API 令牌 cookie: enabled: false # 关闭 cookie改用 Bearer 认证注意token 会暴露给 JS secure: false webrtc: icelite: true # ICE-lite 模式后端不主动做连接检查 iceservers: backend: # icelite 开启时后端 STUN/TURN 会被忽略 - urls: [ stun:stun.l.google.com:19302 ] frontend: - urls: [ stun:stun.l.google.com:19305 ] # username: foo # credential: bar说明config.yml中还注释了 H.264/x264enc 的 pipeline 示例、object/file 成员提供者示例以及带宽估计器estimator的完整参数组开发时按需取消注释即可启用。常见问题与调优提示./rebuild报找不到镜像rebuild、go、fmt、lint都依赖neko_server:src镜像需先执行./build生成见各脚本开头的镜像检查逻辑。容器内修改后 go.mod/go.sum 变化通过 server/dev/go 执行 go 命令后脚本会把go.mod、go.sum回拷到宿主机并docker commit保存改动避免依赖变更丢失。端口冲突默认占用3000后端、3001前端与52100WebRTC mux TCP/UDP可用NEKO_PORT、NEKO_MUX、VUE_APP_SERVER_PORT调整。NAT 穿透start会依次尝试ipconfig getifaddr、hostname -I、hostname -i探测本机 IP 写入NEKO_WEBRTC_NAT1TO1多网卡环境下建议显式设置该环境变量。小结neko 的本地开发链路可以概括为一条清晰的依赖链与两个开发循环系统依赖Node/Go/GStreamer/Xorg/PulseAudio支撑起 Monorepo 中的六大目录后端通过server/dev的build → start → rebuild脚本实现容器内编译、容器内热替换前端通过client/dev的serve实现 HMR 即时预览。本文所述脚本与配置均可在仓库中直接查看进一步深入可阅读 开发指南、本地开发文档 与 仓库结构文档或直接进入 server/dev/ 与 client/dev/ 阅读脚本源码。【免费下载链接】nekoA self hosted virtual browser that runs in docker and uses WebRTC.项目地址: https://gitcode.com/GitHub_Trending/ne/neko创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考