AnyBot/docs/install.md

# 安裝細節

一般使用請用 README 的一行安裝（`install.sh`），它會做完下面所有步驟。這份文件說明它做了什麼，以及想自己一步一步來時怎麼做。

## install.sh 做了什麼

| 步驟 | 桌面 App（`app`） | 手腳（`hands`） | 伺服器（`server`） |
|---|---|---|---|
| 1. 系統套件 | 編譯工具、ALSA、視窗和聲音、通知、剪貼簿、ffmpeg、中文字型 | 編譯工具、ALSA、虛擬螢幕（Xvfb）、視窗管理員、輔助使用服務 | curl、git |
| 2. 工具 | Rust（rustup，裝在 `~/.cargo`） | Rust | Docker（官方 get.docker.com）和 docker compose |
| 3. 原始碼 | 下載到 `~/AnyBot`（已存在就更新） | 同左 | 同左 |
| 4. 安裝 | 編譯，放到 `~/Applications`（Mac）或 `~/.local/bin`（Linux） | 編譯、放到 `~/.local/bin`，帶網址和配對碼時接著執行 `anybot setup` | 執行 `deploy/server/setup.sh`：問網域、帳號、密碼，用 Docker 建置並啟動 |

- 系統套件會依發行版挑對的名字（例如 Ubuntu 24.04 的 `libasound2` 叫 `libasound2t64`；沒有的名字會跳過）。支援 apt（Debian、Ubuntu、Mint、Raspberry Pi OS…）、dnf / yum（Fedora、RHEL、Rocky、Alma、Amazon Linux）、pacman（Arch、Manjaro）、zypper（openSUSE）、apk（Alpine）、xbps（Void）。NixOS 和 Gentoo 看 `sh install.sh --print` 的 notes。
- 架構：macOS arm64、x86_64；Linux x86_64、aarch64、armv7、riscv64（glibc 或 musl）；Windows x64、arm64。
- 有終端機會先問要裝桌面、手腳、伺服器或只裝工具，裝完再引導第一次設定（API 金鑰或配對碼）。沒有終端機（代理程式）不要問：`ANYBOT_NONINTERACTIVE=1`，見 [install/AGENT.md](../install/AGENT.md)。`sh install.sh --print` 印出這台適不適合、以及每種模式的一行指令。
- 已經有 Rust 但版本低於 1.95：有 rustup 就更新；是系統套件裝的就另外用 rustup 裝新版。
- 記憶體小的機器會自動減少同時編譯的數量（每 2 GB 一個）。
- 不帶參數時自己判斷：Mac 和有桌面的 Linux 裝桌面 App，沒有桌面的 Linux 裝手腳。

環境變數：`ANYBOT_DIR`（原始碼放哪，預設 `~/AnyBot`）、`ANYBOT_BRANCH`（預設 `main`）。

## 自己一步一步來

### 需要準備

| 平台 | 需要 |
|---|---|
| 全部 | Rust **1.95 以上**（用 rustup 安裝；apt 裝的通常太舊）、git、make |
| macOS 12 以後 | Xcode Command Line Tools（`xcode-select --install`） |
| Linux | `build-essential pkg-config libasound2-dev`；執行用的套件見下面 |
| Windows 10/11（x64、arm64） | `install.ps1`（或 `install.cmd`）。需要 Git，以及 Visual Studio Build Tools 的 C++（沒有的話腳本會用 winget 裝）。伺服器請改在 Linux 上架 |

`make deps` 會把這些都裝好（等於 `./install.sh deps`）。`make doctor` 檢查還缺什麼。

### 步驟

```sh
git clone https://code.30cm.net/daniel.w/AnyBot.git
cd AnyBot
make deps       # 系統套件和 Rust（Linux 會問 sudo 密碼）；Mac：Xcode 工具和 Rust
make            # 建置 AnyBot 和帳號伺服器（第一次約 5–15 分鐘）
make install
```

`make install` 做的事：

- **macOS**：做出 `AnyBot.app`（含圖示），放到 `~/Applications/`。沒有 Apple 開發者簽章，第一次打開請按右鍵 › 打開。想放到別的地方：`make install APPDIR=/Applications`。
- **Linux**：程式放在 `~/.local/bin/anybot`，選單項目和圖示放在 `~/.local/share/`。不需要 root。

不想安裝、只想試：`make run`。

## Linux 的系統套件

`make deps` 依發行版（apt、dnf、pacman、zypper）安裝這些。除了第一行，全部都是選用的，缺了 App 會說明少了什麼：

| 套件 | 用途 |
|---|---|
| libasound2（Ubuntu 24.04 起叫 libasound2t64）、libxkbcommon-x11-0、libgl1、xdg-utils | 視窗和聲音（必要） |
| libnotify-bin | 通知 |
| libsecret-tools | 保險庫存在系統鑰匙圈 |
| espeak-ng | 唸出回覆 |
| zenity | 選檔案的視窗 |
| xclip / wl-clipboard | 貼上圖片；GNOME/KDE Wayland 上打中文 |
| ffmpeg | 影片、語音、示範錄影 |
| docker.io | Bot 自己的電腦 |
| fonts-noto-cjk | 更多中文字形（內建的粉圓體已經夠用） |

沒有螢幕的 Linux（只當手腳或大腦）：只需要 `libasound2`；要讓 Bot 看得到畫面，還要虛擬螢幕（Xvfb）、視窗管理員和輔助使用服務。`./install.sh hands` 會一起裝好（自己來：`make hands`）。

## 更新

再執行一次安裝的那一行就好。自己建置的話：

```sh
git pull
make install
```

你的 Bot、聊天和設定不在程式裡，更新不會動到它們。

## 移除

```sh
make uninstall
```

只移除程式。要連資料一起刪，刪掉資料資料夾：

| 平台 | 資料在哪 |
|---|---|
| macOS | `~/Library/Application Support/AnyBot/` |
| Linux | `~/.local/share/AnyBot/` |
| Windows | `%APPDATA%\AnyBot\` |

設成開機自動執行的（`anybot setup` 裝的）也要停掉：Linux 執行 `systemctl --user disable --now anybot`。

## 其他執行方式

| 指令 | 用途 |
|---|---|
| `make serve`（`anybot --serve`） | 不開視窗：Bot、例行任務、訊息管道一直運作，用手機操作 |
| `make setup`（`anybot setup`） | 把這台接到你的 AnyBot（大腦或手腳），見 [multi-device.md](multi-device.md) |
| `make relay-run` | 在這台跑帳號伺服器（測試用，埠 8080） |
| `make server` | 在伺服器上用 Docker 架帳號伺服器、大腦和 HTTPS |
| `ANYBOT_DATA_DIR=/某個資料夾 anybot` | 用另一份資料（測試、同一台跑兩份） |

## 常見問題

**Mac 說「無法打開，因為無法驗證開發者」**
按右鍵 › 打開，再按一次「打開」。只有第一次需要。

**Mac 上 Bot 看不到螢幕、不能點擊**
系統設定 › 隱私權與安全性：「螢幕錄製」和「輔助使用」要打開 AnyBot。App 的 設定 › 電腦 有按鈕直接開到那一頁。

**Linux 啟動時說找不到 libasound.so.2**
`sudo apt-get install libasound2t64`（Ubuntu 24.04 以後）或 `libasound2`（更早的版本）。

**編譯時找不到 alsa 或 pkg-config**
Linux 少了編譯用的套件：`make deps`，或 `sudo apt-get install build-essential pkg-config libasound2-dev`。

**`make: cargo: No such file or directory` 或「找不到 Rust」**
還沒裝 Rust：`make deps`。剛裝好但終端機找不到：`. "$HOME/.cargo/env"`，或開一個新的終端機。

**`requires rustc 1.95` 或「Rust 太舊」**
`rustup update stable`。如果 rustc 是 apt 裝的，先 `sudo apt-get remove rustc cargo`，再 `make deps`。

**編譯到一半 `Killed`、`signal: 9`、或整台卡住**
記憶體不夠（常見於 1–2 GB 的 VPS）。加 2 GB swap 再試：

```sh
sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab   # 重開機後也保留
```

**第一次 `make` 很久**
要下載並編譯所有套件，第一次需要 5–15 分鐘，之後只會重編有改的部分。