先搞清楚:你需要 Bridge 吗?播放、分组、逐房音量、语音、收藏与资料库浏览、播报后自动恢复——这些纯 Wi-Fi 都能用,不需要 Bridge。只有当你想要「任意歌名的云端搜索」和「长期常驻的复杂自动化」时,本地 Bridge 才派上用场。如果暂时用不上,大可跳过这篇。先搞清楚:你需要 Bridge 嗎?播放、分組、逐房音量、語音、收藏與資料庫瀏覽、播報後自動恢復——這些純 Wi-Fi 都能使用,不需要 Bridge。只有當你想要「任意歌名的雲端搜尋」和「長期常駐的複雜自動化」時,本地 Bridge 才派上用場。如果暫時用不上,大可跳過這篇。First: do you even need the Bridge? Playback, grouping, per-room volume, voice, favorites and library browsing, announce-then-restore — all work on Wi-Fi alone, no Bridge required. The local Bridge only matters when you want "search any song from the cloud" and "always-on complex automation". If that's not you yet, feel free to skip this.
开始前你需要開始前你需要Before you start
- 一台常开、装了 Docker 的机器:NAS(群晖、威联通)、Unraid、迷你主机或旧电脑都行,和 Sonos 在同一个本地网络一台常開、裝了 Docker 的機器:NAS(群暉、威聯通)、Unraid、迷你主機或舊電腦皆可,和 Sonos 在同一個本地網絡An always-on machine with Docker: a NAS (Synology, QNAP), Unraid, mini-PC or an old computer — on the same local network as your Sonos
- ZoneFoundry iPhone app,已经能正常看到并控制你的 Sonos 房间ZoneFoundry iPhone app,已能正常看到並控制你的 Sonos 房間The ZoneFoundry iPhone app, already seeing and controlling your Sonos rooms
步骤步驟Steps
从哪里装？三条路装出来的是同一个 Bridge，差别只在「模板新不新」：
· 直接 Docker 命令（下面这条）—— 永远是最新镜像，推荐。
· 飞牛 fnOS 应用中心—— 我们持续更新，装完即是新版。
· Unraid App Store（Community Applications）—— 目前上架的是较早的模板版本，暂时没有跟进更新；用它装完之后，容器本身仍会通过 iOS app 的「升级」按钮拉到最新镜像，所以不影响使用。從哪裡安裝？三條路裝出來的是同一個 Bridge，差別只在「模板新不新」：
· 直接 Docker 指令（下面這條）—— 永遠是最新映像，推薦。
· 飛牛 fnOS 應用中心—— 我們持續更新，裝完即是新版。
· Unraid App Store（Community Applications）—— 目前上架的是較早的模板版本，暫時沒有跟進更新；用它安裝之後，容器本身仍會透過 iOS app 的「升級」按鈕拉到最新映像，所以不影響使用。Where to install from? All three routes give you the same Bridge — they only differ in how fresh the template is:
· The plain Docker command below — always the latest image. Recommended.
· fnOS app store — we keep this one current, so a fresh install is a fresh version.
· Unraid Community Applications — the listed template is an older revision that we haven't refreshed lately. It still works: once installed, the container itself pulls the newest image whenever you tap "Apply Update" in the iOS app.
用 Docker 跑起 Bridge 容器用 Docker 跑起 Bridge 容器Run the Bridge container with Docker
Bridge 要用 host 网络模式(它靠本地网络发现你的 Sonos 音箱),并挂一个目录存配置。在你的机器上跑:Bridge 需要用 host 網絡模式(它靠本地網絡發現你的 Sonos 音箱),並掛載一個目錄存放設定。在你的機器上執行:The Bridge needs host network mode (it discovers your Sonos speakers over the local network) and a folder to store its config. On your machine, run:
docker run -d \
--name zonefoundry-bridge \
--network host \
--restart unless-stopped \
--cap-drop ALL \
-e ZF_RELAY_URL=wss://relay.zonefoundry.dev/ws \
-e ZF_PAIR_CODE=<iOS app 里的 6 位配对码> \
-v /path/to/zf-bridge:/app/data \
-v /var/run/docker.sock:/var/run/docker.sock \
zonefoundry/bridge:latest把 /path/to/zf-bridge 换成你机器上真实的目录。三个要点:① 容器里的数据路径是 /app/data（配对凭证存这里，重启后不用再配对）；② 容器以非 root 用户 10001 运行，所以宿主目录要先 chown -R 10001:10001 /path/to/zf-bridge，否则起不来；③ 挂 docker.sock 是为了让 iOS app 里的「升级」按钮能直接拉新镜像 —— 不想要一键升级的话，把这行删掉，改成日后手动 docker pull 即可。把 /path/to/zf-bridge 換成你機器上真實的目錄。三個要點:① 容器裡的資料路徑是 /app/data（配對憑證存在這裡，重啟後不用再配對）；② 容器以非 root 用戶 10001 執行，所以主機目錄要先 chown -R 10001:10001 /path/to/zf-bridge，否則起不來；③ 掛 docker.sock 是為了讓 iOS app 裡的「升級」按鈕能直接拉新映像 —— 不想要一鍵升級的話，把這行刪掉，日後手動 docker pull 即可。Replace /path/to/zf-bridge with a real folder on your machine. Three things to get right: (1) the in-container data path is /app/data — pairing credentials live there, so you only pair once; (2) the container runs as non-root user 10001, so chown -R 10001:10001 /path/to/zf-bridge on the host first or it won't start; (3) mounting docker.sock is what lets the "Apply Update" button in the iOS app pull a new image for you — drop that line if you'd rather docker pull manually.
用 Unraid / 群晖 / 飞牛的图形界面装？照同样几项设即可:host 网络、映射 /app/data、填 ZF_RELAY_URL 和配对码。Unraid 还要在 Extra Parameters 加 --group-add 281（Unraid 的 docker 组 GID），一键升级才有权限调用 docker。用 Unraid / 群暉 / 飛牛的圖形介面安裝？照同樣幾項設定即可:host 網絡、映射 /app/data、填 ZF_RELAY_URL 和配對碼。Unraid 還要在 Extra Parameters 加 --group-add 281（Unraid 的 docker 群組 GID），一鍵升級才有權限呼叫 docker。Installing through the Unraid / Synology / fnOS UI? Mirror the same settings: host network, a mapped /app/data volume, plus ZF_RELAY_URL and your pair code. On Unraid also add --group-add 281 (Unraid's docker group GID) under Extra Parameters, so one-tap updates have permission to talk to Docker.
/app/data 卷、relay 地址。（此图为 Unraid 英文界面，各平台后台语言跟你自己的设定。）Unraid 的容器設定頁。群暉／飛牛的介面不同，但要填的東西一樣：host 網絡、/app/data 卷、relay 位址。（此圖為 Unraid 英文介面，各平台後台語言跟你自己的設定。）Unraid's container setup page. Synology and fnOS look different but need the same things: host network, an /app/data volume, and the relay URL.在 app 里连上这台 Bridge在 app 裡連接這台 BridgeConnect the app to this Bridge
容器跑起来后,打开 ZoneFoundry,到「设置 → 桥接」。同一网络下 app 通常会自动发现这台 Bridge;没自动出来就手动填它的本地 IP。连上后,状态会显示「已连接」。容器跑起來後,打開 ZoneFoundry,前往「設定 → 橋接」。同一網絡下 app 通常會自動發現這台 Bridge;沒有自動出現就手動填入它的本地 IP。連接後,狀態會顯示「已連接」。Once the container is up, open ZoneFoundry and go to Settings → Bridge. On the same network the app usually finds it automatically; if not, enter its local IP by hand. Once linked, the status shows "Connected".
确认 Bridge 带来的那几项已经生效確認 Bridge 帶來的那幾項已經生效Check what the Bridge added
先说清楚:播放控制、多房间、音乐搜索、语音助手、场景、广播这些,本来就不用 Bridge,装之前装之后都一样。Bridge 真正带来的是这三件:① 房间进 Apple「家庭」——变成可开关的配件，Siri 和家庭自动化都能驱动;② 到家／离家自动触发场景;③ Apple Music 的电台与推荐架、Plex 个人资料库。另外日常操作会更快，因为指令走本地直连而不绕云。哪天关掉 Bridge，上面这三件会暂停，其余功能照常。先說清楚:播放控制、多房間、音樂搜尋、語音助手、場景、廣播這些,本來就不用 Bridge,裝之前裝之後都一樣。Bridge 真正帶來的是這三件:① 房間進 Apple「家庭」——變成可開關的配件，Siri 和家庭自動化都能驅動;② 到家／離家自動觸發場景;③ Apple Music 的電台與推薦架、Plex 個人資料庫。另外日常操作會更快，因為指令走本地直連而不繞雲。哪天關掉 Bridge，上面這三件會暫停，其餘功能照常。To be clear first: playback, multi-room, music search, the voice assistant, scenes and announcements never needed the Bridge — they work the same before and after. What the Bridge actually adds is three things: (1) your rooms appear in Apple Home as switchable accessories that Siri and Home automations can drive; (2) arrive/leave triggers for scenes; (3) Apple Music radio & recommendation shelves and your Plex library. Everything also gets faster, since commands go direct over your LAN instead of through the cloud. Turn the Bridge off and only those three pause — the rest keeps working.
连不上?先确认三件事:① 容器是用 --network host 跑的(桥接网络发现不到 Sonos);② Bridge 机器和 Sonos、你的 iPhone 在同一个局域网、同一网段;③ 机器防火墙没挡住本地发现。三样齐了,自动发现基本都能成。連不上?先確認三件事:① 容器是用 --network host 跑的(橋接網絡發現不到 Sonos);② Bridge 機器和 Sonos、你的 iPhone 在同一個區域網、同一網段;③ 機器防火牆沒有擋住本地發現。三樣齊全,自動發現基本都能成功。Can't connect? Check three things: ① the container runs with --network host (bridge networking can't discover Sonos); ② the Bridge machine, your Sonos and your iPhone are on the same LAN and subnet; ③ the machine's firewall isn't blocking local discovery. With all three in place, auto-discovery almost always works.
不想登云，也有得用不想登雲，也有得用You do not have to sign in to the cloud
ZoneFoundry 支持局域网直连控制，不依赖 Sonos 云账号；想用云端功能再登也不迟。Bridge 是可选增强，不是入场券。ZoneFoundry 支援區域網絡直連控制，不依賴 Sonos 雲端帳戶；想用雲端功能再登入也不遲。Bridge 是可選增強，並非入場券。ZoneFoundry can control Sonos directly over your local network without a Sonos cloud account. Sign in later if you want the cloud features. The Bridge is an optional upgrade, not an entry ticket.