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 使用跟踪
- 频道事件日志
- 带结构化上下文的错误日志
- 可配置的日志级别