# Gateway

## 什麼是 Gateway？

Gateway 是 Neotask 的核心, , 一個管理所有代理程式工作階段、訊息頻道、工具執行和裝置連接的長期執行服務。所有事情都透過 Gateway 流轉。

它是一個 WebSocket 伺服器，監聽來自用戶端（桌面應用程式、行動應用程式、網頁儀表板）的連接，並管理整個 AI 助理的生命週期。

## 架構

### 元件

- **WebSocket 伺服器**, 接受用戶端連接（預設連接埠 18789）
- **HTTP 伺服器**, 提供控制 UI、畫布主機和健康端點
- **頻道轉接器**, 維護與訊息平台的連接（WhatsApp、Telegram、Discord 等）
- **工作階段管理器**, 持久化並管理代理程式對話狀態
- **Cron 排程器**, 執行排程工作和心跳喚醒
- **外掛執行期**, 載入和管理外掛生命週期
- **瀏覽器服務**, 控制 Chromium 實例進行網頁自動化

### 綁定模式

| 模式 | 說明 |
|------|------|
| **Loopback** | 預設。只能從 localhost（127.0.0.1）存取 |
| **LAN** | 可在本機網路上存取。透過 Bonjour/mDNS 自動探索 |
| **Tailnet** | 透過 Tailscale VPN 和 MagicDNS 存取 |
| **Custom** | 綁定至特定位址 |

### 驗證

| 方法 | 說明 |
|------|------|
| **Token** | WebSocket 不記名令牌（UUID 或自訂字串） |
| **Password** | 基於密碼的驗證（bcrypt 雜湊） |
| **Trusted Proxy** | 用於帶有預驗證標頭的反向代理 |
| **Local Trust** | 回送連接自動核准 |

## 設定

Gateway 透過 `neotask.json`（JSON5 格式）進行設定。主要區段：

| 區段 | 控制 |
|------|------|
| `agents` | 代理程式清單、預設值、工作空間 |
| `gateway` | 連接埠、綁定模式、驗證、重新載入行為 |
| `channels` | 每頻道設定和憑證 |
| `tools` | 工具權限、設定檔、安全性 |
| `plugins` | 外掛載入、啟用、每外掛設定 |
| `models` | 提供者驗證、備援、提供者設定 |
| `skills` | 技能目錄、每技能設定 |
| `browser` | 瀏覽器設定檔、連接埠、無頭模式 |
| `cron` | 排程器設定 |
| `session` | 重置規則、壓縮閾值 |
| `messages` | TTS 設定、媒體策略 |
| `memory` | 記憶體索引設定 |
| `security` | 沙盒、提升模式、核准 |

### 熱重載

設定更改可以在不重新啟動的情況下套用：

| 模式 | 行為 |
|------|------|
| **Hybrid**（預設） | 熱套用安全更改，其他更改需重新啟動 |
| **Hot** | 只套用熱安全更改，忽略其他更改 |
| **Restart** | 在任何需要重新載入的更改時重新啟動 |
| **Off** | 無自動重新載入 |

## 遠端存取

### Tailscale（推薦）

Tailscale 提供安全的零設定遠端存取：

- 將 Gateway 綁定到您的 Tailnet
- 從同一 Tailscale 網路上的任何裝置存取
- 透過 MagicDNS 自動 DNS
- Tailscale Serve 可以透過 HTTPS 暴露儀表板

### SSH 隧道

透過 SSH 轉發 Gateway 連接埠：

- 簡單、安全，無需更改設定
- 適用於任何支援 SSH 的機器
- 支援完整的 WebSocket 協定和控制 UI

### 安全規則

- **Loopback + SSH/Tailscale** 是最安全的組合
- 非回送綁定需要驗證令牌設定
- 可提供 TLS 指紋釘選以獲得額外安全性
- 預設情況下，遠端連接停用瀏覽器控制

## 健康監控

### 健康端點

`/health` HTTP 端點返回：

- Gateway 狀態
- RPC 活躍性
- 每頻道健康狀況（連接狀態、驗證狀態、帳戶數量）
- 瀏覽器就緒狀態
- 活躍代理程式和已連接節點
- 正常運行時間

### 探測

- **RPC 活躍性**, WebSocket 連接 + 回聲測試
- **頻道健康**, 每頻道驗證檢查 + API ping
- **瀏覽器就緒性**, 連接埠檢查、程序檢查
- **節點連通性**, 上次心跳時間戳記

## 探索

### Bonjour/mDNS

當綁定至區域網路時，Gateway 透過多播 DNS 廣播自己：

- 服務類型：`_neotask-gw._tcp`
- 包含連接埠、傳輸方式、TLS 狀態和 Tailscale DNS 資訊
- 伴侶應用程式自動探索 Gateway

### 廣域探索

透過可設定的超時時間探索網路上的 Gateway。支援本機 Bonjour 和 Tailscale DNS 探索。

## 多個 Gateway

您可以使用設定檔在同一台機器上執行多個 Gateway 實例：

- 每個設定檔都有獨立的設定、工作空間、工作階段和狀態
- 每個 Gateway 使用不同的連接埠
- 適用於隔離（個人與工作）或測試

## 診斷

### 醫生

內建診斷工具檢查：

- 設定有效性
- 檔案權限
- 頻道連通性
- 模型驗證狀態
- Node.js 版本相容性
- 常見設定錯誤

獲得許可後，它可以自動修復許多問題。

### 日誌記錄

Gateway 日誌寫入每日 JSONL 檔案：

- 每次完成的令牌使用量追蹤
- 頻道事件日誌
- 帶有結構化上下文的錯誤日誌記錄
- 可設定的日誌層級