2026/8/21 16:18:17
FEATURED · 精选文章 
neko-rooms 配置完全参考30 环境变量逐个拆解【免费下载链接】neko-roomsSelfhosted collaborative browser - room management for n.eko项目地址: https://gitcode.com/gh_mirrors/ne/neko-rooms想用 Docker 快速搭建一个自托管的协作浏览器Selfhosted Collaborative Browserneko-rooms 无疑是目前最省心的选择它把 n.eko 的房间创建、生命周期管理、HTTPS 反代全部做成了开箱即用的图形界面。但很多人卡在了配置这一步——neko-rooms 环境变量多达 30 余个命名规则、默认值、废弃项让人一头雾水。本文把所有 neko-rooms 环境变量按功能分组逐个拆解从基础运行到存储挂载、Traefik 集成配齐默认值和避坑要点读完你就能自己写出一份生产级配置。neko-rooms 是什么neko-rooms 是 n.eko 的「房间管理服务」用户在网页上点几下就能创建/销毁共享浏览器房间每个房间分配独立的浏览器容器Firefox、Chromium、Edge 等镜像再通过 WebRTC 把画面和操作共享给多个访客。管理员在一个 Web 面板里就能查看所有房间的状态、最大连接数、镜像和运行时长。一、neko-rooms 环境变量的命名规则neko-rooms 使用 Viper 读取配置规则非常统一环境变量统一加前缀NEKO_ROOMS_代码里的点号.会被替换为下划线_例如代码中的instance.name对应的环境变量就是NEKO_ROOMS_INSTANCE_NAME。也就是说下面所有变量你只要遵循「前缀 全大写 下划线」规则就能准确对号入座。配置加载逻辑见 cmd/root.go。二、最常用的三个基础变量调试与日志环境变量默认值作用NEKO_ROOMS_DEBUGfalse开启 debug 日志排查问题时首选NEKO_ROOMS_LOGSfalse把日志写入文件Linux 下为/var/log/neko_rooms/含自动轮转NEKO_ROOMS_CONFIG空指定配置文件路径加载自定义 yaml生产环境建议至少开启NEKO_ROOMS_LOGStrue出问题时能拿到完整日志文件。相关定义见 internal/config/root.go。三、服务端核心配置绑定地址、HTTPS 与反向代理环境变量默认值作用NEKO_ROOMS_BIND127.0.0.1:8080服务监听地址容器部署时改端口用NEKO_ROOMS_CERT空SSL 证书路径启用后走 HTTPSNEKO_ROOMS_KEY空SSL 私钥路径NEKO_ROOMS_PROXYfalse信任反向代理的请求头Nginx/Traefik 后面必开NEKO_ROOMS_CORSfalse开启跨域支持NEKO_ROOMS_PPROFfalse开启/debug/pprof性能分析接口NEKO_ROOMS_METRICSfalse开启/metrics监控指标接口关键提醒只要你在 Nginx 或 Traefik 后面务必设置NEKO_ROOMS_PROXYtrue否则客户端拿到的 IP/端口可能是错的。以上配置见 internal/config/server.go。管理后台认证Admin环境变量默认值作用NEKO_ROOMS_ADMIN_USERNAMEadmin管理后台用户名NEKO_ROOMS_ADMIN_PASSWORD空管理后台密码强烈建议设置NEKO_ROOMS_ADMIN_STATIC空自定义前端静态文件目录NEKO_ROOMS_ADMIN_PATH_PREFIX/管理界面与 API 的访问路径前缀NEKO_ROOMS_ADMIN_PROXY_AUTH空代理认证 URL仅当返回 200 时放行四、房间核心配置镜像、端口与连接方式这是 neko-rooms 环境变量中最关键的一组直接决定房间能否被顺利访问。环境变量默认值作用NEKO_ROOMS_MUXfalse开启 mux 多路复用每个房间只需 1 个 TCP 1 个 UDP 端口强烈推荐NEKO_ROOMS_EPR59000-59999ICE UDP 端口池范围按房间数规划NEKO_ROOMS_NAT1TO1空服务器对外 IP1:1 NAT 外部地址客户端可达的 IPNEKO_ROOMS_NEKO_IMAGES12 个官方镜像允许使用的 neko 镜像白名单NEKO_ROOMS_NEKO_PRIVILEGED_IMAGES空允许以特权模式运行的镜像白名单NEKO_ROOMS_PATH_PREFIX/房间路径前缀例如/room/NEKO_ROOMS_WAIT_ENABLEDtrue房间启动时是否显示等待页NEKO_ROOMS_STOP_TIMEOUT10停止房间的超时秒数超时后 SIGKILL0立即杀-1无限等NEKO_ROOMS_LABELS空给每个房间追加的自定义 Docker labelNAT1TO1 与 EPR最常见的两个坑NEKO_ROOMS_NAT1TO1必须填客户端能访问到的服务器公网 IP否则 WebRTC 协商会把内网地址发给访客导致「连接超时」。不填时会自动探测公网 IP但 NAT 环境下必须手动指定。NEKO_ROOMS_EPR的端口需要全部放行UDP。例如 2 个房间、每房 5 人文档建议范围59000-59009就够相关说明见 docs/README.md。开启 mux 的好处默认情况下每个连接都要分配独立端口而NEKO_ROOMS_MUXtrue让所有数据流复用同一个 TCP/UDP 端口对能极大减少需要放行的端口数量是生产部署的首选方案。五、存储与挂载让房间数据持久化房间容器默认是临时的重启即丢。neko-rooms 通过以下 neko-rooms 环境变量实现持久化存储环境变量默认值作用NEKO_ROOMS_STORAGE_ENABLEDtrue是否启用存储NEKO_ROOMS_STORAGE_INTERNAL/data容器内的数据目录必须绝对路径NEKO_ROOMS_STORAGE_EXTERNAL空宿主机上的数据目录必须绝对路径NEKO_ROOMS_MOUNTS_WHITELIST空允许挂载的宿主机路径白名单空格分隔多个注意storage.internal和storage.external必须同时配置且都是绝对路径否则存储会被自动禁用。启用后rooms/房间名/存放房间私有数据templates/用于存放可复用的模板文件比如浏览器 policies 配置。详细配置示例见 docs/storage.md。安全提示白名单挂载/等于把所有文件暴露给房间强烈不建议这么做按需白名单如/home /media即可。六、实例与 Traefik 集成配置如果你用 Traefik 做反向代理这组 neko-rooms 环境变量直接决定域名路由是否生效环境变量默认值作用NEKO_ROOMS_INSTANCE_NAMEneko-rooms实例唯一名称同主机多实例时必须区分NEKO_ROOMS_INSTANCE_URL空实例外部 URL用于拼接房间地址NEKO_ROOMS_INSTANCE_NETWORK空实例与房间通信的 Docker 网络NEKO_ROOMS_TRAEFIK_ENABLEDtrue是否启用 Traefik 标签NEKO_ROOMS_TRAEFIK_DOMAIN空托管域名子域名用*.domain.tldNEKO_ROOMS_TRAEFIK_ENTRYPOINTweb-secureTraefik 路由入口NEKO_ROOMS_TRAEFIK_CERTRESOLVER空证书解析器配置后自动走 HTTPSNEKO_ROOMS_TRAEFIK_NETWORKtraefik已废弃请改用INSTANCE_NETWORKNEKO_ROOMS_TRAEFIK_PORT空已废弃请改用INSTANCE_URL两个重要的地址拼接规则当INSTANCE_URL为空时系统会按http(s)://{traefik_domain}/自动生成域名以*.开头时房间地址变成房间名.domain.tld子域名模式否则拼在路径后面如domain.tld/room/房间名/。INSTANCE_NAME的格式要求很严必须符合 Docker 容器命名规范填错了进程会直接 Panic相关校验逻辑见 internal/config/room.go。七、一份可直接跑的最小配置示例不需要 Traefik、只想本机快速体验时参考官方 docker-compose.yml 精简后的配置services: neko-rooms: image: m1k1o/neko-rooms:latest restart: unless-stopped environment: - NEKO_ROOMS_MUXtrue - NEKO_ROOMS_EPR59000-59049 - NEKO_ROOMS_NAT1TO1你的服务器公网IP - NEKO_ROOMS_INSTANCE_URLhttp://你的域名:8080/ - NEKO_ROOMS_INSTANCE_NETWORKneko-rooms-net - NEKO_ROOMS_TRAEFIK_ENABLEDfalse - NEKO_ROOMS_PATH_PREFIX/room/ - NEKO_ROOMS_ADMIN_PASSWORD请改成强密码 ports: - 8080:8080 volumes: - /var/run/docker.sock:/var/run/docker.sock注意提前docker pull需要的 neko 镜像如m1k1o/neko:firefox否则创建房间会报No such image。自定义房间标签比如暴露 3000 端口的写法见 docs/lables.md。八、常见问题速查房间加载但一直「connection timeout」大概率是 UDP 端口没放行检查NEKO_ROOMS_EPR范围内的端口是否全部开放并确认NEKO_ROOMS_NAT1TO1填的是公网 IP。报错「Mounts cannot be specified because storage is disabled」说明NEKO_ROOMS_STORAGE_EXTERNAL没配或路径不是绝对路径按第五节补全即可。改了变量不生效检查命名是否用了NEKO_ROOMS_前缀、点号是否换成下划线比如NEKO_ROOMS_ADMIN_PATH_PREFIX对应代码里的admin.path_prefix。掌握了这 30 个 neko-rooms 环境变量无论是本机调试、Traefik 全自动 HTTPS还是多实例大规模部署你都能从容应对。建议把本文收藏部署时逐项对照一次配对不再返工。【免费下载链接】neko-roomsSelfhosted collaborative browser - room management for n.eko项目地址: https://gitcode.com/gh_mirrors/ne/neko-rooms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
neko-rooms 配置完全参考：30+ 环境变量逐个拆解
neko-rooms 配置完全参考30 环境变量逐个拆解【免费下载链接】neko-roomsSelfhosted collaborative browser - room management for n.eko项目地址: https://gitcode.com/gh_mirrors/ne/neko-rooms想用 Docker 快速搭建一个自托管的协作浏览器Selfhosted Collaborative Browserneko-rooms 无疑是目前最省心的选择它把 n.eko 的房间创建、生命周期管理、HTTPS 反代全部做成了开箱即用的图形界面。但很多人卡在了配置这一步——neko-rooms 环境变量多达 30 余个命名规则、默认值、废弃项让人一头雾水。本文把所有 neko-rooms 环境变量按功能分组逐个拆解从基础运行到存储挂载、Traefik 集成配齐默认值和避坑要点读完你就能自己写出一份生产级配置。neko-rooms 是什么neko-rooms 是 n.eko 的「房间管理服务」用户在网页上点几下就能创建/销毁共享浏览器房间每个房间分配独立的浏览器容器Firefox、Chromium、Edge 等镜像再通过 WebRTC 把画面和操作共享给多个访客。管理员在一个 Web 面板里就能查看所有房间的状态、最大连接数、镜像和运行时长。一、neko-rooms 环境变量的命名规则neko-rooms 使用 Viper 读取配置规则非常统一环境变量统一加前缀NEKO_ROOMS_代码里的点号.会被替换为下划线_例如代码中的instance.name对应的环境变量就是NEKO_ROOMS_INSTANCE_NAME。也就是说下面所有变量你只要遵循「前缀 全大写 下划线」规则就能准确对号入座。配置加载逻辑见 cmd/root.go。二、最常用的三个基础变量调试与日志环境变量默认值作用NEKO_ROOMS_DEBUGfalse开启 debug 日志排查问题时首选NEKO_ROOMS_LOGSfalse把日志写入文件Linux 下为/var/log/neko_rooms/含自动轮转NEKO_ROOMS_CONFIG空指定配置文件路径加载自定义 yaml生产环境建议至少开启NEKO_ROOMS_LOGStrue出问题时能拿到完整日志文件。相关定义见 internal/config/root.go。三、服务端核心配置绑定地址、HTTPS 与反向代理环境变量默认值作用NEKO_ROOMS_BIND127.0.0.1:8080服务监听地址容器部署时改端口用NEKO_ROOMS_CERT空SSL 证书路径启用后走 HTTPSNEKO_ROOMS_KEY空SSL 私钥路径NEKO_ROOMS_PROXYfalse信任反向代理的请求头Nginx/Traefik 后面必开NEKO_ROOMS_CORSfalse开启跨域支持NEKO_ROOMS_PPROFfalse开启/debug/pprof性能分析接口NEKO_ROOMS_METRICSfalse开启/metrics监控指标接口关键提醒只要你在 Nginx 或 Traefik 后面务必设置NEKO_ROOMS_PROXYtrue否则客户端拿到的 IP/端口可能是错的。以上配置见 internal/config/server.go。管理后台认证Admin环境变量默认值作用NEKO_ROOMS_ADMIN_USERNAMEadmin管理后台用户名NEKO_ROOMS_ADMIN_PASSWORD空管理后台密码强烈建议设置NEKO_ROOMS_ADMIN_STATIC空自定义前端静态文件目录NEKO_ROOMS_ADMIN_PATH_PREFIX/管理界面与 API 的访问路径前缀NEKO_ROOMS_ADMIN_PROXY_AUTH空代理认证 URL仅当返回 200 时放行四、房间核心配置镜像、端口与连接方式这是 neko-rooms 环境变量中最关键的一组直接决定房间能否被顺利访问。环境变量默认值作用NEKO_ROOMS_MUXfalse开启 mux 多路复用每个房间只需 1 个 TCP 1 个 UDP 端口强烈推荐NEKO_ROOMS_EPR59000-59999ICE UDP 端口池范围按房间数规划NEKO_ROOMS_NAT1TO1空服务器对外 IP1:1 NAT 外部地址客户端可达的 IPNEKO_ROOMS_NEKO_IMAGES12 个官方镜像允许使用的 neko 镜像白名单NEKO_ROOMS_NEKO_PRIVILEGED_IMAGES空允许以特权模式运行的镜像白名单NEKO_ROOMS_PATH_PREFIX/房间路径前缀例如/room/NEKO_ROOMS_WAIT_ENABLEDtrue房间启动时是否显示等待页NEKO_ROOMS_STOP_TIMEOUT10停止房间的超时秒数超时后 SIGKILL0立即杀-1无限等NEKO_ROOMS_LABELS空给每个房间追加的自定义 Docker labelNAT1TO1 与 EPR最常见的两个坑NEKO_ROOMS_NAT1TO1必须填客户端能访问到的服务器公网 IP否则 WebRTC 协商会把内网地址发给访客导致「连接超时」。不填时会自动探测公网 IP但 NAT 环境下必须手动指定。NEKO_ROOMS_EPR的端口需要全部放行UDP。例如 2 个房间、每房 5 人文档建议范围59000-59009就够相关说明见 docs/README.md。开启 mux 的好处默认情况下每个连接都要分配独立端口而NEKO_ROOMS_MUXtrue让所有数据流复用同一个 TCP/UDP 端口对能极大减少需要放行的端口数量是生产部署的首选方案。五、存储与挂载让房间数据持久化房间容器默认是临时的重启即丢。neko-rooms 通过以下 neko-rooms 环境变量实现持久化存储环境变量默认值作用NEKO_ROOMS_STORAGE_ENABLEDtrue是否启用存储NEKO_ROOMS_STORAGE_INTERNAL/data容器内的数据目录必须绝对路径NEKO_ROOMS_STORAGE_EXTERNAL空宿主机上的数据目录必须绝对路径NEKO_ROOMS_MOUNTS_WHITELIST空允许挂载的宿主机路径白名单空格分隔多个注意storage.internal和storage.external必须同时配置且都是绝对路径否则存储会被自动禁用。启用后rooms/房间名/存放房间私有数据templates/用于存放可复用的模板文件比如浏览器 policies 配置。详细配置示例见 docs/storage.md。安全提示白名单挂载/等于把所有文件暴露给房间强烈不建议这么做按需白名单如/home /media即可。六、实例与 Traefik 集成配置如果你用 Traefik 做反向代理这组 neko-rooms 环境变量直接决定域名路由是否生效环境变量默认值作用NEKO_ROOMS_INSTANCE_NAMEneko-rooms实例唯一名称同主机多实例时必须区分NEKO_ROOMS_INSTANCE_URL空实例外部 URL用于拼接房间地址NEKO_ROOMS_INSTANCE_NETWORK空实例与房间通信的 Docker 网络NEKO_ROOMS_TRAEFIK_ENABLEDtrue是否启用 Traefik 标签NEKO_ROOMS_TRAEFIK_DOMAIN空托管域名子域名用*.domain.tldNEKO_ROOMS_TRAEFIK_ENTRYPOINTweb-secureTraefik 路由入口NEKO_ROOMS_TRAEFIK_CERTRESOLVER空证书解析器配置后自动走 HTTPSNEKO_ROOMS_TRAEFIK_NETWORKtraefik已废弃请改用INSTANCE_NETWORKNEKO_ROOMS_TRAEFIK_PORT空已废弃请改用INSTANCE_URL两个重要的地址拼接规则当INSTANCE_URL为空时系统会按http(s)://{traefik_domain}/自动生成域名以*.开头时房间地址变成房间名.domain.tld子域名模式否则拼在路径后面如domain.tld/room/房间名/。INSTANCE_NAME的格式要求很严必须符合 Docker 容器命名规范填错了进程会直接 Panic相关校验逻辑见 internal/config/room.go。七、一份可直接跑的最小配置示例不需要 Traefik、只想本机快速体验时参考官方 docker-compose.yml 精简后的配置services: neko-rooms: image: m1k1o/neko-rooms:latest restart: unless-stopped environment: - NEKO_ROOMS_MUXtrue - NEKO_ROOMS_EPR59000-59049 - NEKO_ROOMS_NAT1TO1你的服务器公网IP - NEKO_ROOMS_INSTANCE_URLhttp://你的域名:8080/ - NEKO_ROOMS_INSTANCE_NETWORKneko-rooms-net - NEKO_ROOMS_TRAEFIK_ENABLEDfalse - NEKO_ROOMS_PATH_PREFIX/room/ - NEKO_ROOMS_ADMIN_PASSWORD请改成强密码 ports: - 8080:8080 volumes: - /var/run/docker.sock:/var/run/docker.sock注意提前docker pull需要的 neko 镜像如m1k1o/neko:firefox否则创建房间会报No such image。自定义房间标签比如暴露 3000 端口的写法见 docs/lables.md。八、常见问题速查房间加载但一直「connection timeout」大概率是 UDP 端口没放行检查NEKO_ROOMS_EPR范围内的端口是否全部开放并确认NEKO_ROOMS_NAT1TO1填的是公网 IP。报错「Mounts cannot be specified because storage is disabled」说明NEKO_ROOMS_STORAGE_EXTERNAL没配或路径不是绝对路径按第五节补全即可。改了变量不生效检查命名是否用了NEKO_ROOMS_前缀、点号是否换成下划线比如NEKO_ROOMS_ADMIN_PATH_PREFIX对应代码里的admin.path_prefix。掌握了这 30 个 neko-rooms 环境变量无论是本机调试、Traefik 全自动 HTTPS还是多实例大规模部署你都能从容应对。建议把本文收藏部署时逐项对照一次配对不再返工。【免费下载链接】neko-roomsSelfhosted collaborative browser - room management for n.eko项目地址: https://gitcode.com/gh_mirrors/ne/neko-rooms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
