Neko 本地开发环境搭建Docker 后端 Vue 前端热重载工作流【免费下载链接】nekoA self hosted virtual browser that runs in docker and uses WebRTC.项目地址: https://gitcode.com/GitHub_Trending/ne/nekoNeko 是一个基于 Docker 与 WebRTC 的虚拟浏览器self-hosted virtual browser项目后端由 Go 编写前端为 Vue 2 单页应用。本文基于仓库 webpage/docs/developer-guide/development.md 编写完整介绍 Neko 推荐的本地开发方式后端跑在 Docker 容器里、前端在本机或同一容器镜像以热重载方式运行让你修改代码后无需重新构建整个 Docker 镜像即可看到效果。读完本文你将掌握server/dev与client/dev两套开发脚本的完整用法、首次构建与增量热替换的底层原理以及一整套“三终端并行”的高效开发工作流。开发架构为什么后端与前端要分开跑Neko 的开发链路涉及两个核心部分后端Go GStreamer WebRTC负责 X11 桌面捕获、编码、信令与 WebSocket 通信。如果每次改一行 Go 代码都要重新docker build整个镜像开发迭代会非常缓慢。前端Vue 2负责界面与交互。Vue 自带 dev server 与 HMRHot Module Replacement非常适合本地热加载。因此 Neko 官方推荐的开发策略是后端编译产物动态注入运行中的容器前端借助 Vue 的 hot reload 实时刷新。文档明确指出The fastest way to contribute to Neko is to run the backend in Docker and the frontend locally with hot reload. No need to rebuild the whole Docker image on every change.最快的贡献方式是后端跑 Docker、前端本地热重载无需每次改动都重建整个镜像。这种方式唯一的硬性前置条件是安装 Docker其中列出了 node.js/npm、go、gstreamer、X.org、pulseaudio 等可选的原生依赖清单对项目整体布局不熟悉的话可先阅读 webpage/docs/developer-guide/repository-structure.md。开始前先克隆仓库git clone https://gitcode.com/GitHub_Trending/ne/neko.git cd neko后端开发server/dev后端所有开发脚本都集中在server/dev/目录由start、build、rebuild、exec、go、fmt、lint等一组 shell 脚本组成。它们分工明确构建镜像、启动服务、热替换二进制、进入容器调试、执行 Go 工具链。首次构建一条命令生成三层镜像首次开发或依赖发生重大变更后需要构建所需的 Docker 镜像cd server/dev ./build从 server/dev/build 的源码可以看到这一步实际上依次构建了三个镜像neko_server:src以 server/Dockerfile 构建的源码构建镜像内置 Go 工具链rebuild/go/fmt/lint等脚本都以它为执行环境neko_server:base调用仓库根目录的 build 模板脚本../../build -y -b neko_server:base -f $1生成的基础运行镜像neko_server:app以 server/dev/runtime/Dockerfile 构建的应用镜像基于 base 镜像额外安装了 xfce4 桌面与 Firefox并拷贝 server/dev/runtime/supervisord.conf 作为 XFCE 的 supervisord 程序配置。只有首次或依赖变化时才需要执行./build日常开发中启动与热替换都不再触发全量构建。另外./build会读取当前 git 的短 commit 与分支名git rev-parse作为构建信息建议在干净的工作区状态下手动执行。启动后端默认端口 3000cd server/dev ./start./start会把 Neko 后端以 Docker 方式启动映射到本机 3000 端口容器名为neko_server_dev并以前台模式保持运行docker run --rm -it。它包含几处值得注意的自动化逻辑见 server/dev/start镜像自检若本地不存在neko_server:app镜像会自动先执行./build端口与环境变量NEKO_PORT默认3000映射到容器内 8080NEKO_MUX默认52100同时映射 TCP/UDP用于 WebRTC 复用端口可通过环境变量覆盖NAT 地址自动探测NEKO_WEBRTC_NAT1TO1依次尝试ifconfig网卡地址、hostname -I首个地址、hostname -i自动确定本机公网/局域网 IP供 WebRTC 候选地址使用配置注入以只读卷方式挂载开发配置 server/dev/runtime/config.yml 到容器内/etc/neko/neko.yml并开启NEKO_DEBUG1调试日志运行参数--shm-size2G保证共享内存足够编码使用--security-opt seccompunconfined放行沙箱限制便于运行浏览器等应用。该开发配置中默认开启server.pprof便于性能剖析、capture.screencast.enabled、member.provider: multiuseradmin 密码admin、user 密码neko、session.api_token: neko123以及 WebRTC 的icelite: true与 STUN 服务器清单捕获流水线默认使用 VP8 编码vp8enc并配置了hq/lq两档分辨率档位供带宽估算与自适应切换使用。这些参数在开发容器内即真实生效可放心用于联调。启用 GPU 加速nvidia / intel 参数./start支持通过第一个参数启用 GPU 加速./start nvidia # 附加 --gpus all使用 config.nvidia.yml ./start intel # 附加 --device /dev/dri透传 Intel 核显设备从 server/dev/start 的逻辑看nvidia会追加--gpus all并加载 server/dev/runtime/config.nvidia.ymlintel会追加--device /dev/dri透传显卡设备脚本中注释表明 Intel 专用配置仍在 TODO 状态因此 Intel 场景当前仍使用默认 config.yml。不传参数则使用默认软件编码路径。需要说明的是GPU 加速依赖宿主机具备 NVIDIA 驱动/容器运行时或 Intel 核显设备属于可选开发项。应用后端修改./rebuild 热替换不重启容器这是整个开发流程的核心亮点。编辑完 Go 源码后在另一个新终端执行cd server/dev ./rebuild./rebuild见 server/dev/rebuild的工作机制可以拆解为四步编译在neko_server:src容器内以挂载的源码执行./build产出新的服务端二进制bin/neko与插件二进制清理旧插件docker exec neko_server_dev rm -rf /etc/neko/plugins移除容器内旧插件热替换二进制用docker cp把新编译的bin/neko覆盖到运行容器/usr/bin/neko若存在bin/plugins则一并拷贝到/etc/neko/plugins仅重启 neko 进程docker exec neko_server_dev supervisorctl -c /etc/neko/supervisord.conf restart neko通知 supervisord 只重启 neko 服务整个 Docker 镜像与容器本身完全不动。由于rebuild使用了set -e编译或拷贝任一步失败都会立即中止保证不会把损坏的二进制热替换进运行中的容器。文档特别强调the full Docker image is never rebuilt——镜像永不重建这正是它能做到秒级迭代的原因。辅助脚本exec / go / fmt / lintserver/dev还提供了四个与容器交互的辅助脚本脚本用途实现要点server/dev/exec进入运行中的neko_server_dev容器 shell便于排查运行态问题docker exec -it neko_server_dev /bin/bashserver/dev/go在neko_server:src内执行任意go子命令如./go test ./...运行后回拷go.mod/go.sum并docker commit固化依赖变更server/dev/fmt统一代码格式go fmt ./...server/dev/lint运行 golangci-lintv1.31.0静态检查缺失时自动下载安装到./bin/golangci-lint其中go脚本对依赖管理尤其重要你在容器里执行./go get或./go mod tidy后容器内更新过的go.mod/go.sum会被拷回宿主机源码目录并通过docker commit固化到neko_server:src镜像中实现“依赖变更不出容器、改动自动落盘”。前端开发client/dev前端开发脚本集中在client/dev/包括serve、npm、exec。它们统一使用node:18-bullseye-slim镜像在容器内执行 npm宿主机无需安装 Node.js。安装依赖依赖会在首次运行./serve时自动安装。如果需要手动安装或强制重装cd client/dev ./serve -i-i标志会触发安装流程见 client/dev/serve当node_modules不存在或传入-i时以容器方式执行npm install将client/目录挂载为/app。也可以直接使用仓库提供的 npm 包装脚本cd client/dev ./npm installnpm 脚本本质上是docker run ... --entrypointnpm ... node:18-bullseye-slim $因此./npm run build、./npm run lint等任意 npm 子命令都可以按同样方式执行。启动热重载开发服务器cd client/dev ./serve./serve启动 Vue dev server监听3001 端口并把 API 请求代理到后端3000 端口通过VUE_APP_SERVER_PORT环境变量指定后端地址默认3000。任何保存到client/src/下的改动都会即时反映到浏览器无需手动刷新页面。两个服务在本机分别监听服务地址后端Docker 容器http://localhost:3000前端热重载http://localhost:3001注意./serve通过--user $(id -u):$(id -g)以当前用户身份运行容器避免 npm 产生的node_modules文件归属混乱若你在终端里直接执行的是client/dev/exec则会得到一个挂载了client/目录的交互式容器 shell适合执行一次性脚本。典型开发工作流三终端并行将文档推荐的流程整理如下这也是 Neko 贡献者最常用的日常循环终端 1——启动后端cd server/dev ./start终端 2——启动前端cd client/dev ./serve浏览器打开http://localhost:3001修改前端文件client/src/下任意 .vue/.ts 文件→ 浏览器自动热更新修改后端文件server/下任意 .go 文件→ 在终端 3执行cd server/dev ./rebuild应用改动排障与注意事项以下要点大多可以从上述脚本源码直接推导帮助你在实际开发中少踩坑容器名冲突neko_server_dev是固定容器名若上次启动未正常退出或忘记加--rm再次./start会因容器名冲突失败可先docker rm -f neko_server_dev清理再启动。镜像缺失自愈./start与./rebuild/go/fmt/lint都会检查对应镜像是否存在——前者会自动触发./build后者会提示先执行./build。端口占用3000后端、3001前端、52100WebRTC muxTCP/UDP均被占用时可通过NEKO_PORT、NEKO_MUX环境变量改写前端代理地址由VUE_APP_SERVER_PORT控制需保持一致。WebRTC 无法连接./start自动探测的NEKO_WEBRTC_NAT1TO1在多网卡/云主机场景下可能取到错误网卡可显式export NEKO_WEBRTC_NAT1TO1实际公网IP后重启容器。前端代理不通先确认后端容器在前台正常运行./start是前台模式日志会直接输出到终端再确认VUE_APP_SERVER_PORT与后端NEKO_PORT一致。浏览器被 seccomp 拦截./start已附加--security-opt seccompunconfined这是为了容纳 Chromium/Firefox 等浏览器的沙箱调用请勿在开发容器上再收紧该选项。掌握这套“后端容器化 前端热重载 三终端并行”的开发模式后从克隆仓库到完成一次前后端联调改动全程不需要在宿主机安装任何语言工具链也不需要反复重建 Docker 镜像——这正是 Neko 为贡献者准备的零摩擦开发体验。【免费下载链接】nekoA self hosted virtual browser that runs in docker and uses WebRTC.项目地址: https://gitcode.com/GitHub_Trending/ne/neko创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考