Mac 家用伺服器

把一台 Mac 變成全家人的網路中心：用 Tailscale 連回家、擋廣告、家用雲端硬碟， 再加一個手機用的控制台，用按鈕就能管理每個人能用什麼、能用多久——不用寫程式、不用改路由器。

介面是繁體中文，為 iPhone 設計（也支援電腦、深色模式）。 給家人看的使用教學：https://hitachi513.github.io/home-guide/

功能

需要準備

• 一台一直開著、插著電的 Mac（macOS 13 以上，Apple 晶片或 Intel 都可以）
• 一顆外接硬碟（用來當雲端，選用）
• Tailscale 帳號（免費），在 Tailscale 後台打開 MagicDNS 和 HTTPS 憑證 （裝完後還要把 Global nameserver 設成這台 Mac，擋廣告才會生效，安裝程式最後會告訴你怎麼做）
• 選用：Homebrew（只有 Shadowrocket 功能需要）

安裝

git clone https://github.com/Hitachi513/mac-homeserver ~/homeserver
bash ~/homeserver/install.sh

安裝程式會問你幾個問題（控制台擁有者是哪個 Tailscale 帳號、哪顆是雲端硬碟、要不要開 Shadowrocket）， 然後自動：

1. 下載 AdGuard Home 並完成初始設定（只聽本機，管理密碼隨機產生）
2. 安裝 Python 套件（cryptography、cbor2）
3. 設定開機自動啟動的背景服務
4. 用 tailscale serve 發布控制台（只有你的 Tailscale 連得到），用 Funnel 發布成員網頁

裝完之後照畫面上的「接下來」做：iPhone 打開控制台設定密碼、給 Python「完整取用磁碟」權限、 連結 Tailscale API（成員權限才能自動套用），最後建議執行防火牆加固：

sudo bash ~/homeserver/security/harden.sh

所有個人設定都在 ~/homeserver/config.json（範例：config.example.json）。 想在控制台同時管理 GitHub 上的回報，在 config.json 加上 "github_repo": "你的帳號/你的repo"（需要先用 gh auth login 登入）。 移除：bash ~/homeserver/uninstall.sh（資料會保留）。

架構

iPhone ──Tailscale──▶ tailscale serve :443  ──▶ 控制台   127.0.0.1:8088（只信任 Tailscale 傳來的身分）
                      tailscale serve :3443 ──▶ AdGuard  127.0.0.1:3000
網路上任何人 ─Funnel─▶ :8443 /p/<秘密網址>   ──▶ 成員網頁 127.0.0.1:8090（不信任任何身分標頭）
                      :8443 /（選用）       ──▶ Xray     127.0.0.1:10080（Shadowrocket）

• 只用 Python 標準函式庫寫的伺服器（另外只需要 cryptography 和 cbor2），沒有資料庫，資料都是 JSON 檔（權限 600）
• 成員權限會即時轉成 Tailscale ACL（透過 Tailscale API），到期、時段、時數用完都會自動收回

安全

請先讀 SECURITY.md。重點：

• 控制台只接受由 Tailscale 轉進來的連線（會檢查連線來自哪個程式），本機其他程式無法冒用身分
• 對網路公開的只有成員網頁（128 位元隨機網址＋限速＋自動封鎖）和選用的 Shadowrocket 入口
• 控制台裡的「設定 → 安全」可以隨時看安全分數，並對自己跑一次攻擊測試

回報問題／建議

需要 GitHub 帳號（免費）。表單是中文的，照著填就好。詳細說明請看 CONTRIBUTING.md。

回報前請先：

1. 到 Issues 搜尋看看，是不是有人回報過了（有的話在下面留言 +1 並補充你的情況）
2. 更新到最新版再試一次：cd ~/homeserver && git pull，然後重新啟動控制台
3. 把個人資料遮掉：Tailscale 網址（xxx.ts.net）、IP、成員名字、密碼、專屬網址都不要貼上來

附上這些，會修得比較快：

# 版本
cd ~/homeserver && git describe --tags
# macOS 版本和晶片
sw_vers -productVersion; uname -m
# 控制台最後 50 行記錄（貼上前請先檢查有沒有個人資料）
tail -n 50 ~/homeserver/dashboard/panel.log

⚠️ 法律注意

Shadowrocket 功能本質上是代理伺服器。在部分國家或地區，架設或使用這類服務可能違法。 這個功能預設關閉，請先確認你所在地的法律，使用責任由你自行負擔。

授權

MIT（第三方元件見 THIRD_PARTY_NOTICES.md）。AdGuard Home（GPL-3.0）、Xray-core（MPL-2.0）、noVNC（MPL-2.0）、websockify（LGPL-3.0） 不包含在這個專案裡，由安裝程式從官方來源下載，各自依原本的授權使用。

git clone https://github.com/Hitachi513/mac-homeserver ~/homeserver
bash ~/homeserver/install.sh