# Gateway

## 什么是 Gateway？

Gateway 是 Neotask 的核心 -- 一个单一的长期运行服务，管理所有代理会话、消息频道、工具执行和设备连接。一切都通过 Gateway 流转。

它是一个 WebSocket 服务器，监听来自客户端（桌面应用、移动应用、Web 仪表盘）的连接，并管理整个 AI 助手的生命周期。

## 架构

### 组件

- **WebSocket 服务器** -- 接受客户端连接（默认端口 18789）
- **HTTP 服务器** -- 提供控制 UI、画布主机和健康端点
- **频道适配器** -- 维护与消息平台（WhatsApp、Telegram、Discord 等）的连接
- **会话管理器** -- 持久化和管理代理对话状态
- **Cron 调度器** -- 运行计划任务和心跳唤醒
- **插件运行时** -- 加载和管理插件生命周期
- **浏览器服务** -- 控制 Chromium 实例用于 Web 自动化

### 绑定模式

| 模式 | 描述 |
|------|-------------|
| **Loopback** | 默认。仅可从 localhost（127.0.0.1）访问 |
| **LAN** | 在本地网络上可访问。通过 Bonjour/mDNS 自动发现 |
| **Tailnet** | 通过 Tailscale VPN 使用 MagicDNS 访问 |
| **Custom** | 绑定到特定地址 |

### 认证

| 方法 | 描述 |
|--------|-------------|
| **Token** | WebSocket bearer token（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** 是最安全的组合
- 非回环绑定需要配置认证 token
- 可用 TLS 指纹固定以增强安全性
- 远程连接默认禁用浏览器控制

## 健康监控

### 健康端点

`/health` HTTP 端点返回：

- Gateway 状态
- RPC 活跃性
- 按频道健康状态（已连接、认证状态、账户数量）
- 浏览器就绪状态
- 活跃代理和连接的节点
- 运行时间

### 探针

- **RPC 活跃性** -- WebSocket 连接 + 回声测试
- **频道健康** -- 按频道的认证检查 + API ping
- **浏览器就绪** -- 端口检查、进程检查
- **节点连接** -- 最后心跳时间戳

## 发现

### Bonjour/mDNS

绑定到 LAN 时，Gateway 通过多播 DNS 广播自己：

- 服务类型：`_neotask-gw._tcp`
- 包括端口、传输协议、TLS 状态和 Tailscale DNS 信息
- 伴侣应用自动发现 Gateway

### 广域发现

使用可配置的超时跨网络发现 Gateway。支持本地 Bonjour 和 Tailscale DNS 发现。

## 多 Gateway

您可以使用配置文件在同一台机器上运行多个 Gateway 实例：

- 每个配置文件有独立的配置、工作空间、会话和状态
- 每个 Gateway 使用不同端口
- 适用于隔离（个人 vs 工作）或测试

## 诊断

### Doctor

内置诊断工具检查：

- 配置有效性
- 文件权限
- 频道连接性
- 模型认证状态
- Node.js 版本兼容性
- 常见错误配置

在获得许可后，它可以自动修复许多问题。

### 日志

Gateway 日志写入每日 JSONL 文件：

- 按完成的 token 使用跟踪
- 频道事件日志
- 带结构化上下文的错误日志
- 可配置的日志级别