macOS × Ubuntu 24.04
Sunshine＋Moonlight 實作指南

把 MAC_LAN_IP 換成實際 Mac 區網 IP。先檢視規則；不要重設或關閉防火牆，也不要對一台原本未啟用 UFW 的遠端主機直接啟用它。

sudo ufw status numbered
MAC_IP="MAC_LAN_IP"
# 替換上方值後才執行：
sudo ufw allow from "$MAC_IP" to any port 47984,47989,48010 proto tcp
sudo ufw allow from "$MAC_IP" to any port 47998,47999,48000,48002,48010 proto udp

Tailscale 的 netfilter 與 tailnet grants/ACL 是另一層；不要只加 UFW 就認定已限制全部 tailnet 流量。回復時只刪掉本次新增的規則。

# Agent Action：macOS 遠端操作 Ubuntu 24.04

查證日期：2026-10-16（Asia/Taipei）。這是獨立執行規格；不需要先讀原始對話。

## 目標與背景

為一台 Ubuntu 24.04 Desktop 主機部署 Sunshine，讓 Mac 使用 Moonlight 操作現有桌面。先完成同一區網的 1080p / 60 FPS / SDR 串流，再視需求加入 Tailscale 跨網路存取。若主要用途為 Coding Agent，保留 SSH 作為任務執行及故障復原通道，Moonlight 用來查看 GUI。

使用者尚未提供 GPU 型號、Ubuntu IP、登入帳號、Mac 型號、macOS 版本或是否無螢幕。能從獲授權的目標環境讀取就先盤點；不得把 Agent 所在的雲端工作容器當成使用者的 Ubuntu 主機。沒有目標連線時，完成安裝計畫與待執行腳本並標記 blocked，請使用者提供目標連線方式，不得宣稱已部署。

基準假設：單一使用者、Ubuntu 已可正常登入圖形桌面、有可用顯示輸出，初次配對時有人能在主機確認授權。若必須從「重開機後未登入、無人看守、無螢幕」狀態啟動，先改寫登入／顯示方案，不能把一般桌面流程當作已解決。

## 選定工具與版本

下表發布日期採官方 UTC 日期；查證日期採 Asia/Taipei。

| 元件 | 查證基準 | 執行原則 |
|---|---|---|
| Ubuntu | 24.04 Desktop | 保留現有 OS；不為串流升級發行版 |
| Sunshine | v2026.914.233613，2026-09-15 發布 | 官方原生 DEB，按 amd64 / arm64 選檔 |
| Moonlight PC / Qt | v6.2.0，2026-10-04 發布 | 官方 macOS Universal DMG |
| Tailscale | GitHub stable v1.104.1，2026-10-07 發布 | 跨網路需要時安裝；記錄兩端實際版本，平台發布可能不同步 |
| GPU 驅動 | 不預設版本 | 按實際 GPU、Ubuntu 套件與 Sunshine 日誌確認；nvidia-smi 成功不等於 NVENC 驗收成功 |

執行前重新查閱官方 stable release 和安全公告。若已有較新穩定版，核對 Ubuntu 24.04 資產、遷移說明與 checksum 後使用，並更新 versions.md；不要把下方舊 checksum 套用於新檔。不要自動降級較新的既有安裝。不要使用 nightly、beta、來源不明 fork。Sunshine 此基準已修補 GHSA-fp6g-27w5-489j。

## 依序執行

1. **盤點與備份**
   - 讀目標專案／機器適用的管理規範，確認 Ubuntu 與 Mac 各自的執行位置與權限。
   - 在 Ubuntu 圖形使用者的 terminal 收集 OS、架構、GPU、驅動、Wayland/X11、顯示輸出、目前網路與防火牆。SSH 會話的 XDG_SESSION_TYPE 不代表圖形桌面的類型，需用 loginctl 找到實際圖形會話。
   - Mac 收集 `sw_vers`、`uname -m`、現有 Moonlight/Tailscale 版本。
   - 若已安裝 Sunshine，確認來源、版本、systemd user unit、設定目錄與擷取後端；備份設定和必要的服務覆寫。備份含配對金鑰，限制權限，不放進公開報告或 Git。
   - 只回報缺少什麼，不安裝整套桌面、不改顯示管理員、不在未知 GPU 上盲裝 NVIDIA 驅動。

2. **安裝 Sunshine**
   - 預設使用官方 DEB。確認目標有 curl、CA 憑證和 apt；缺少才安裝必要工具。
   - 下方為本報告基準版本的可重現安裝區塊；執行前先確認沒有更新版已裝在主機上。

```bash
(
  set -eu
  . /etc/os-release
  if [ "$ID" != ubuntu ] || [ "$VERSION_ID" != 24.04 ]; then
    echo '此段只適用 Ubuntu 24.04，請改用對應發行版套件。' >&2
    exit 1
  fi
  SUN_ARCH="$(dpkg --print-architecture)"
  case "$SUN_ARCH" in
    amd64) SUN_SHA='c38e9c705f650f8705f61702717e99bec34044c5028fcb8f23a08fe041292c21' ;;
    arm64) SUN_SHA='5751c22cf0b9253b459d7f42103f1c422594363a5881e21bd1ce845218226888' ;;
    *) echo "未涵蓋的架構：$SUN_ARCH" >&2; exit 1 ;;
  esac
  SUN_WORK="$(mktemp -d)"
  cd "$SUN_WORK"
  curl --fail --location --proto '=https' --tlsv1.2 \
    -o sunshine.deb \
    "https://github.com/LizardByte/Sunshine/releases/download/v2026.914.233613/sunshine_2026.914.233613-1%2Bubuntu24.04_${SUN_ARCH}.deb"
  printf '%s  sunshine.deb\n' "$SUN_SHA" | sha256sum --check -
  sudo apt update
  sudo apt install ./sunshine.deb
)
```

   - 使用 `dpkg-query -W sunshine` 記錄版本。安裝官方編譯套件通常不需要另裝 CUDA Toolkit；有 GPU 問題時按實際日誌查證。

3. **圖形會話、服務與擷取**
   - 以 Ubuntu 桌面使用者啟動 user service：

```bash
systemctl --user start app-dev.lizardbyte.app.Sunshine
systemctl --user status app-dev.lizardbyte.app.Sunshine --no-pager
journalctl --user -u app-dev.lizardbyte.app.Sunshine -b -n 100 --no-pager
```

   - GNOME Wayland 先觀察自動選擇結果；需要時在 Web UI 指定 XDG Portal 擷取，並在主機確認 Remote Desktop／螢幕分享授權。`portal` 為擷取後端；`nvenc` / `vaapi` / `vulkan` 為編碼後端，不可混淆。
   - 初始編碼讓程式自動選擇；若選到 software 或發生相容問題，再按 GPU 試 NVENC 或 VAAPI。不要因 Vulkan 較新就強制啟用。
   - 確認實際日誌為硬體編碼。服務 active 只證明程序存在，不代表可用串流。
   - 不以 root 長期執行 Sunshine，不做 `chmod 666 /dev/uinput`，不照抄舊教學向程式額外加 cap_sys_admin。輸入故障先查套件 udev 規則；只有證據顯示必要才按官方文件修復權限並記錄變更。

4. **Mac 安裝與 LAN 配對**
   - 下載官方 v6.2.0 的 macOS Universal DMG，將 Moonlight.app 放入 Applications。已有 Homebrew 可使用 cask，但必須核對實際安裝版及當前 macOS 要求。
   - 在 Ubuntu 開 `https://localhost:47990` 設定獨立管理帳密。若以 Mac 管理，使用已存在的 SSH 通道轉送到 Ubuntu 的 localhost；Mac 自己的 localhost 並不等於 Ubuntu。
   - Moonlight 手動加入 Ubuntu 的 LAN IP；Moonlight 顯示 PIN，再到 Sunshine Web UI 的 PIN 頁輸入。不要將管理密碼或配對狀態檔寫入交付成果。
   - 用 Desktop 項目測試；若沒有，建立不帶啟動命令的 Desktop 應用以串流現有桌面。
   - 起始值：1920×1080、60 FPS、H.264、20 Mbps、SDR，先保留其他預設。這是測試起點，不是官方最佳值。
   - 測試鼠標、英文與繁體中文輸入、捲動、音訊；記錄主機端輸入法與 Mac 快捷鍵的差異。

5. **網路與 Tailscale（需要跨網路時）**
   - 先讓 LAN 驗收通過。兩端安裝官方 Tailscale，加入同一個已授權 tailnet；登入、MFA、系統網路擴充允許由使用者完成。
   - Ubuntu 使用官方 Linux 安裝方式；Mac 使用官方 macOS 安裝包。記錄版本及 Ubuntu Tailscale IPv4。
   - Moonlight 手動加入 Ubuntu 的 Tailscale IP。用 `tailscale ping <對端名稱或IP>`、`tailscale status` 確認最後是 direct、peer-relay 或 DERP relay；初始數包經 DERP 不等於一直走中繼。
   - 不啟用 Tailscale Funnel，不開啟 Sunshine UPnP，不把管理介面／串流埠轉送到公網；保持既有防火牆運作。
   - 如果連線遭擋，先檢查 tailnet grants/ACL、作業系統防火牆與服務位址。按現行官方埠表、只對必要來源新增最小規則。不得重寫整份 tailnet policy，也不要假設 UFW 規則能覆蓋所有 Tailscale netfilter 行為。
   - 若要從 Mac 管理 Sunshine，優先用既有 SSH 的 localhost port forwarding；不要為了管理 UI 把 origin_web_ui_allowed 改成 wan。

6. **調校、重連與重啟**
   - 先保存 1080p60 基準，再一次只改一個項目：解析度、碼率、codec、幀率。測量真實工作負載，尤其是 AI 運算同時占用 GPU 時。
   - 使用 Moonlight 統計畫面記錄 FPS、網路掉幀、解碼時間與 jitter（有顯示才記）；這些數值不是完整的點擊到畫面端到端延遲。
   - 通過後才啟用 `systemctl --user enable app-dev.lizardbyte.app.Sunshine`。避免另跑手動 sunshine 造成雙程序。
   - 需重啟測試時先確認使用者工作已保存且有登入／救援路徑。分開測「重啟服務後重連」、「重新登入後可用」、「主機重開機後未登入可用」；最後一項預設不在基準承諾內。
   - 不把 enable 或 loginctl enable-linger 當成建立圖形桌面；不自動啟用 autologin、停用鎖屏或改 GRUB。

## 驗收標準

- [ ] 記錄目標 OS、CPU 架構、GPU/驅動、Mac 型號及兩端版本。
- [ ] LAN 能配對，Desktop 有畫面、鼠標鍵盤可用，中文輸入與音訊完成檢查。
- [ ] 日誌確認使用硬體編碼；若僅 software，標為未通過目標效能驗收。
- [ ] 1080p60 連續操作 10 分鐘，無黑畫面、無需重啟救援、無持續掉幀；記錄實際統計及網路條件。10 分鐘與以下數字是本任務工程門檻，不是官方效能承諾：流暢動態測試時 FPS 接近設定值、網路掉幀以低於 1% 為目標；無對應計數器則寫未量測。
- [ ] 斷線後重新連線成功；服務重啟後成功；登入及螢幕狀態的限制寫清楚。
- [ ] 跨網路若納入範圍，從不同網路測試，記錄 direct / peer-relay / relay。經中繼可標功能通過，但效能需另驗收。
- [ ] 無公網端口轉送、UPnP/Funnel；保留現有 SSH／救援通道；配置變更可回復。

## 必須交付

1. `environment.md`：實際環境與缺少條件，避免敏感 IP/帳號進入公開版。
2. `versions.md`：版本、官方下載 URL、SHA-256、查證日期。
3. `setup-log.md`：已執行步驟、改動檔案、服務狀態；禁止記錄密碼、金鑰、授權 token。
4. `validation.md`：逐項 pass/fail/blocked/not-tested、實測值、測試日期與會話狀態。不可把沒測的項目寫成成功。
5. `rollback.md`：只撤回本次變更；停止／停用此次服務、恢復設定與新增規則，不移除原已存在的軟體或既有 tailnet 設定。不降級到已知受影響版本。

可直接執行已授權的盤點、安裝及可回復修正；只有會中斷工作、變更核心登入／安全方式或需要使用者完成互動時才暫停，並說明具體原因。這份規格授權的是遠端桌面設定，不包含購買硬體、修改帳號權限或全面升級 OS。

## 官方與查證來源

- 原文：https://university.tenten.co/t/macos-ubuntu-24-04-sunshine-moonlight/2613
- Sunshine 固定版本：https://github.com/LizardByte/Sunshine/releases/tag/v2026.914.233613
- 資產及雜湊：https://api.github.com/repos/LizardByte/Sunshine/releases/tags/v2026.914.233613
- Sunshine 安裝：https://docs.lizardbyte.dev/projects/sunshine/latest/md_docs_2getting__started.html
- Sunshine 排錯：https://docs.lizardbyte.dev/projects/sunshine/latest/md_docs_2troubleshooting.html
- Linux 安全修正：https://github.com/LizardByte/Sunshine/security/advisories/GHSA-fp6g-27w5-489j
- Moonlight：https://github.com/moonlight-stream/moonlight-qt/releases/tag/v6.2.0
- Moonlight 配對與埠表：https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide
- Tailscale：https://tailscale.com/download/linux 及 https://tailscale.com/docs/install/mac
- Tailscale 連線類型：https://tailscale.com/docs/reference/connection-types
- Remote SSH：https://code.visualstudio.com/docs/remote/ssh