Mote 是一套个人远程动作系统:用 iPhone 锁定自己的 Mac。一台 Relay,操作者自己的一台或多台 Mac。推荐用自己的 Cloudflare 账号一键部署;也可以在自己的机器上用 Docker 自托管。
当前 iPhone 侧走 Apple 快捷指令 + Siri。快捷指令向你的公网 Relay(文档示例 relay.example.com)发送经过认证的 HTTPS 请求。Mote Relay 再通过持久、已认证的 WebSocket 把命令转发给 Mote Agent(运行在 Mote for Mac 中)。同一进程在该基址提供 Mote Relay Dashboard。原生 Mote iOS 尚未进仓库;后端已预留活动来源 ios,见 docs/ios.md。
当前:
Apple Shortcut / Dashboard → Mote Relay → Mote Agent → Lock
下一步:
Mote iOS → 同一条 HTTPS 命令 API → Mote Relay → Mote Agent
之后(未实现):
Mote iOS → 可用时走本地直连 → Relay 回退
本仓库名为 mote。Relay 只是后端组件,不是产品名。
文档和默认常量里的 relay.example.com、192.0.2.10、com.example.mote 是示例,请换成自己的公网主机名、源站地址和 Bundle ID。生产 Relay 用 MOTE_PUBLIC_URL;Mac 用设置里的 Relay URL 或 MOTE_RELAY_URL。
推荐用自己的 Cloudflare 账号一键部署。点下去会克隆这个仓库、创建 Worker 和 Durable Object,并接上 Workers Builds:之后推送到自己克隆仓库的生产分支,部署会跟着更新。
- 点上面的按钮,登录自己的 Cloudflare 账号。
- 填写
MOTE_ADMIN_PASSWORD(至少 12 位)。用户名是admin。Workers Builds 的构建命令用npm run build,部署命令用npx wrangler deploy。 - 打开
https://mote.<你的子域>.workers.dev,用这个账号登录 Dashboard。 - 在自己的 Mac 上用 Xcode 打开
macos/Mote.xcodeproj。把 Bundle ID 从com.example.mote换成自己的,选自己的 Development Team,Run 或 Archive 安装。仓库不提供现成签名包;别人的.app不能直接拿来用。 - 打开 Mote,把 Relay URL 填成这个
https://mote.<子域>.workers.dev,点 Pair。 - 浏览器打开同一地址,Dashboard Allow。iPhone 快捷指令也指向该 HTTPS 基址。见 docs/shortcuts.md。
维护本仓库、希望 git push 到 main 就更新这一份线上 Relay 时,在 GitHub 仓库 Secrets 里设置 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID。.github/workflows/deploy-cloudflare.yml 会在推送到 main 时执行 wrangler deploy。按钮克隆出去的副本不会自动跟上本仓库的新提交;对方把上游拉进自己的克隆再推送,Workers Builds 会重新部署。
Docker Compose 仍然可用。任意能跑 Docker 的机器,前面加一层公网 HTTPS 即可。客户端(Mac、快捷指令、Dashboard 浏览器)只使用该公网主机名,不要打局域网 IP。
- 准备一台 Docker 主机,以及一个公网 HTTPS 主机名(Cloudflare Tunnel、Caddy、nginx 或其他反向代理均可)。
- 克隆本仓库。
cd deploy && cp .env.example .env,把MOTE_PUBLIC_URL改成https://你的主机名。- 在
deploy/执行docker compose up -d --build。 docker compose exec -it relay node dist/cli.js admin create --username admin。- Mac、配对和快捷指令与上面第 4–6 步相同,Relay URL 换成你的公网主机名。
已经在 Proxmox VE 宿主机上跑 Cloudflare Tunnel 时,可以把 Relay 放进 LXC,源站指到 LXC:3000。步骤见 deploy/pve/README.md 和 docs/deployment.md。
- 自托管:一台 Relay,操作者自己的一台或多台 Mac。
- iPhone 用 Apple 快捷指令 + Siri;Dashboard 也可以发
lock。 - 快捷指令与之后的 iOS 客户端始终访问公网 HTTPS 基址(文档示例
https://relay.example.com;在家和外出同一主机名)。 - Mote for Mac 始终连接该基址上的
wss://…/v1/ws/device。未配置时走wss://…/v1/ws/pair。 - 在家和外出都走同一条公网主机名。当前不使用 Split DNS。
- 生产配对:Mac 填 Relay URL,点 Pair,Dashboard Allow,凭据写入钥匙串后立刻连接。
- 唯一动作为
lock。 - 架构中永不包含任意 shell 执行。
- 原生 iOS 应用尚未实现。个人分发计划是付费 Apple Developer + Xcode 直装,不上架 App Store。
推荐部署是 Cloudflare Worker:HTTPS 在 *.workers.dev(或你自己的域名)上终止,SQLite 和 Mac 的 WebSocket 在同一个 Durable Object 里。
自托管时,Relay 是单个 Docker 容器。公网 HTTPS 终止在你自己的 Tunnel 或反向代理上;Compose 栈里没有 Caddy、Nginx 或 cloudflared。
Public hostname
→ your HTTPS front (Tunnel / reverse proxy)
→ Docker host :3000
→ mote-relay
Docker host
└── Docker
└── mote-relay :3000
└── SQLite volume mote_data
若你已经在 Proxmox VE 宿主机上跑 Cloudflare Tunnel,可以把 Relay 放进 LXC,源站指到 LXC:3000。这是可选拓扑,步骤见 deploy/pve/README.md。
可选:PVE Host
│
├── existing cloudflared
│
└── CT: mote-relay
IP: 192.0.2.10
│
└── Docker
└── Relay :3000
快捷指令和 Mac 都不要使用 http://192.0.2.10:3000。该地址只是源站配置,不是客户端 URL。
relay.example.com
│
├── / Dashboard
├── /admin/api/* Admin API
├── /admin/api/events Dashboard SSE(只推 topic)
├── /v1/* Machine API
├── /v1/ws/device Mac WebSocket
├── /v1/ws/pair Pairing WebSocket
├── /v1/pair/requests 公开配对请求
├── /s/:deviceId Shortcut 安装页
├── /health
└── /ready
PUBLIC
Apple Shortcut
│
│ HTTPS
▼
relay.example.com
Browser / Dashboard
│
│ HTTPS
▼
relay.example.com
Mote for Mac
│
│ WSS
▼
relay.example.com
│
▼
Your HTTPS front
│
▼
Docker host :3000
│
▼
Mote Relay
│
├── Dashboard + Admin API + SSE
└── 持久、已认证的 WebSocket
▼
Mote Agent
▼
macOS 锁屏
命令协议与 Relay HTTP API 保持传输无关,以便以后增加原生 iOS 和本地直连时不必重写后端。见 docs/architecture.md。
mote/
├── docs/ 架构、协议、安全、部署、开发、快捷指令、iOS
├── design.md 视觉与文案规范
├── macos/ Mote for Mac(Xcode 工程、应用、测试)
├── dashboard/ Mote Relay Dashboard(React + Vite)
├── relay/ Mote Relay(Node.js + TypeScript)
├── deploy/ Docker Compose;PVE 为可选说明
├── scripts/ 辅助脚本
└── .github/ 后续 CI 工作流
仓库里还没有 ios/ 目录。
| 区域 | 技术 | 状态 |
|---|---|---|
| Mote for Mac | Swift 6、SwiftUI、菜单栏、ServiceManagement、URLSession WebSocket、Network.framework、Keychain、CoreGraphics | 已实现(1.5.6) |
| Mote Relay | Node.js、TypeScript、Fastify、WebSocket、SQLite;Cloudflare Worker + Durable Object 一键部署 | 已实现 |
| Dashboard | React、TypeScript、Vite、shadcn/ui;管理员 SSE 通知后再拉 REST | 由 Relay 静态托管 |
| 传输 | HTTPS + 持久、已认证的 WebSocket;配对另有 /v1/ws/pair |
已实现 |
| 家庭与远程 | 推荐:Cloudflare Worker。自托管:公网 HTTPS(Tunnel、反向代理等)→ Docker :3000 |
已文档化 |
| 触发 | Apple 快捷指令 + Siri;Dashboard 也可发 lock |
配置步骤已文档化 |
| Mote iOS | 计划:SwiftUI、同一条 send_command HTTPS API、付费开发者账号 + Xcode 直装 |
尚未实现 |
Phase 1 — 仓库基础 已完成。
Phase 2 — Mote for Mac 已完成。原生 Mac 应用、菜单栏 Agent、钥匙串凭据、命令校验、锁屏动作和出站 WebSocket 均已实现。当前版本 1.5.6(build 14)。Release 可填写并保存 Relay URL。
Phase 3 — Mote Relay 已完成。Fastify HTTP API、设备 WebSocket、配对、SQLite、CLI、Docker 镜像、Compose 栈均已实现。同一容器提供管理员 Dashboard。PVE 文档是可选路径。
Phase 4 — Apple 快捷指令 配置步骤已文档化。仓库不附带 .shortcut 文件。见 docs/shortcuts.md。
Phase 5 — Mote iOS 尚未实现。个人用原生客户端,走现有命令 API,不上架 App Store。见 docs/ios.md。
之后 — 本地直连 未实现。Bonjour / 家庭直连属于 Future / not implemented。
- 加入手机 App(Mote iOS):原生客户端,走现有
send_commandHTTPS API,Xcode 直装到自己的 iPhone,不上架。见 docs/ios.md。
- 动作来自预定义允许列表。当前唯一动作是
lock。 - 禁止任意 shell 命令、可执行路径,以及远程下发的 AppleScript。
- Mote Relay 不是通用远程代码执行系统。
- 快捷指令凭据(
send_command)与 Mac 设备凭据(device_connection)不可互换。管理员使用独立的用户名/密码会话,不能用 Shortcut token 或设备凭据登录 Dashboard。 - 生产流量仅使用 HTTPS/WSS。
- 密钥永不提交。macOS 设备凭据存放在钥匙串;Relay 只保存哈希。
- 命令很快过期。离线锁屏不会排队。
细节见 docs/security.md、docs/protocol.md 和 docs/shortcuts.md。
- Phase 1 — 仓库基础 — 已完成。
- Phase 2 — Mote for Mac — 已完成。
- Phase 3 — Mote Relay — 已完成。含配对与 Dashboard。
- Phase 4 — Apple 快捷指令 — 已文档化。Siri + 快捷指令触发
lock。 - Phase 5 — Mote iOS — 下一步。个人 Xcode 直装,不上架;更新版本再 Run 一次即可。
- 之后 — 本地直连 — Bonjour 与 Relay 回退。尚未开始。
| 文件 | 范围 |
|---|---|
| 架构 | 产品组件、当前形状、下一步 iOS |
| 协议 | WebSocket 线上格式、配对、快捷指令 HTTP、管理员 SSE |
| 快捷指令 | 当前 iPhone 配置、Siri、curl 验证 |
| iOS | 个人分发、Xcode 直装、与现有 API 的衔接 |
| 安全 | 凭据角色、哈希、执行边界 |
| 部署 | Cloudflare 一键部署、Compose、可选 PVE |
| 开发 | 本地命令、质量约定、阶段状态 |
| 设计语言 | 视觉与文案规范;窗口尺寸以已落地界面为准 |
| Mote for Mac | Mac 客户端构建、签名、配对、验证 |
| Mote Relay | Relay 开发、CLI、HTTP API |
| Dashboard | 管理界面本地开发 |
| 部署文件 | Compose / Relay 发布端口 |
| PVE | 可选:LXC、现有 Tunnel、第一台设备流程 |