进阶 jean.build 2026-10-18 10:33:18 · 28 阅读

第17章 Web 访问与无头模式

Web Access 与 Headless 模式 每个 Jean 实例都支持通过 HTTP/WebSocket 暴露完整的 UI,无论是桌面端还是无头(headless)服务器,均提供 token 认证及兼容 Tailscale 的网络绑定。

所有 Jean 实例都能运行 Web Access:这是一个内嵌的 HTTP + WebSocket 服务,让浏览器可以访问相同的界面。

两种模式:

| 模式 | 如何获取 Web Access | | :--- | :--- | | 原生桌面端 (macOS / Windows / Linux) | 进入 偏好设置 → Web Access,启用 HTTP 服务,设置端口/绑定地址,复制带 token 的 URL | | 无头服务器 (jean-server) | 始终可用 —— 该进程本身即 Web Access 端点 |

你可以用它从局域网内的其他机器、手机/平板浏览器或远程主机打开 Jean。默认启用 token 认证;只要绑定地址不是 localhost,就务必保持开启。

Web Access 提供什么 HTTP 服务负责提供前端资源,并通过 WebSocket 维持应用状态连接。 实际应用中,这意味着你可以:

- 在同一台机器或跨网络的浏览器中打开 Jean - 继续使用主机实例上的相同项目、worktree 和会话 - 复制带 token 的 URL 以便快速访问 - 将原生桌面应用连接到远程 Jean 实例(参见“从原生应用连接”)

桌面应用(原生端)

- 打开 偏好设置 → Web Access - 启用 HTTP 服务(可选开启“自动启动”) - 设置 端口(默认 3456)和 绑定地址 - 在浏览器中打开显示的 URL(含 ?token=...),或分享给能访问该主机的设备

Jean 会自动列出该机器可能的绑定主机选项,无需手动猜测地址。

可配置项 在 偏好设置 → Web Access 中可配置:

- 服务是否运行 - 端口 - 绑定主机 - 启动时是否自动运行 - 是否需要 token - 重新生成 token

默认行为 桌面端的安全基线是:

- 禁用 HTTP 服务 - 仅绑定 localhost - 必须提供 token

除非有明确理由需要更广地暴露 Jean,否则请保持此默认设置。

网络访问(推荐:Tailscale) Web Access 绑定的是普通 TCP 端口(默认 3456)。若要访问本地机器以外的设备,建议优先使用私有网状 VPN,而非将端口暴露给公网:

- Tailscale(推荐):将 Jean 绑定到 Tailscale IP(或使用安装器的 --host tailscale 预设),然后从 tailnet 中的任意设备打开 URL - 其他选项:WireGuard、ZeroTier、SSH 隧道,或在 127.0.0.1 前加一层带 TLS 的反向代理

保持启用 token 认证,使用长随机 token(openssl rand -base64 32),并在不受信任的网络上避免绑定 0.0.0.0,除非你同时终结了 TLS 并限制了可访问该端口的对象。

无头服务器 (jean-server) jean-server 是一个独立的 Linux 二进制文件:仅依赖 Tokio/Axum —— 无 Tauri、WebView、GTK 或显示服务器。支持 Linux amd64 和 arm64(要求 glibc + OpenSSL 3;推荐 Ubuntu 22.04+ / Debian 12+)。

```bash jean-server --host 127.0.0.1 --port 3456 # 或指定 token: jean-server --host 127.0.0.1 --port 3456 --token "$JEAN_TOKEN" ``` 启动时,Jean 会打印浏览器 URL。若启用 token 认证,URL 中将包含 token 作为查询参数。

选项与环境变量

| CLI 选项 | 环境变量 | 默认值 | | :--- | :--- | :--- | | --host | JEAN_HOST | 127.0.0.1(或安装时选择) | | --port | JEAN_PORT | 3456 | | --token | JEAN_TOKEN | 已保存或生成的 token | | --no-token | JEAN_NO_TOKEN=1 | 关闭 | | --allow-unsafe-no-token | JEAN_ALLOW_UNSAFE_NO_TOKEN=1 | 关闭 | | n/a | JEAN_ALLOWED_ORIGINS | 同源 + 原生 Jean 客户端 |

--host 接受具体地址或预设值,如 localhost、all / 0.0.0.0、lan、tailscale(自动检测 Tailscale IPv4)。若使用公网绑定且传入 --no-token,Jean 会拒绝执行,除非同时传入 --allow-unsafe-no-token。建议保持启用 token 认证。

安装(Release 二进制 + systemd) 交互式安装(有 TTY 时提示选择绑定接口和端口):

```bash curl -fsSL https://raw.githubusercontent.com/coollabsio/jean/main/scripts/install-jean-server.sh | sudo bash ``` 非交互式(默认绑定 127.0.0.1:3456,或传入 --host / --port):

```bash curl -fsSL https://raw.githubusercontent.com/coollabsio/jean/main/scripts/install-jean-server.sh | sudo bash -s -- -y ``` 常用选项:

```bash # 公网绑定并指定 token sudo ./scripts/install-jean-server.sh \ --host 0.0.0.0 \ --port 3456 \ --token "$(openssl rand -base64 32)" \ -y

# 仅 Tailscale 绑定(自动检测 Tailscale IPv4)- 远程使用推荐 sudo ./scripts/install-jean-server.sh --host tailscale -y

# 仅当前用户(user systemd unit) ./scripts/install-jean-server.sh --user-install --host 127.0.0.1 -y ``` 安装脚本会下载最新 release、安装二进制文件、写入 env 文件(host/port/token),并注册 systemd 服务。重新运行即可升级;除非传入 --token,否则现有 token 会被保留。

Docker 镜像 Jean 发布了服务器镜像:

ghcr.io/coollabsio/jean-server: 在容器内绑定 0.0.0.0,保持启用 token 认证,并挂载 Jean 的应用数据目录,以便项目、偏好设置和会话能够持久化。

```bash docker run --rm \ -e JEAN_HOST=0.0.0.0 \ -e JEAN_PORT=3456 \ -e JEAN_TOKEN=change-me-long-random-token \ -p 127.0.0.1:3456:3456 \ -v jean-data:/home/jean/.local/share/com.jean.desktop \ ghcr.io/coollabsio/jean-server:latest ``` 若在 Jean 前面放置 Caddy、Nginx、Tailscale 或 SSH 隧道,请将宿主机端口绑定保留在 127.0.0.1。

健康检查 使用以下端点进行进程检查和部署探测:

- GET /healthz - 进程存活 - GET /readyz - HTTP 服务和 WebSocket 广播器已初始化

需要认证的 API 端点接受 ?token=... 或 HTTP bearer token:

```bash curl -H "Authorization: Bearer $JEAN_TOKEN" http://127.0.0.1:3456/api/auth curl "http://127.0.0.1:3456/api/init?token=$JEAN_TOKEN" ``` 反向代理与 Tailscale 反向代理无需重写路径。浏览器 UI 从同源使用 /api/init、/api/auth 和 /ws。

最小的 Caddy 路由如下:

```caddy jean.example.com { encode zstd gzip reverse_proxy 127.0.0.1:3456 } ``` 若仅限 Tailscale 访问,直接绑定到 Tailscale IP 并保持启用 token 认证:

```bash jean-server --host 100.x.y.z --port 3456 --token "$JEAN_TOKEN" # 或: sudo ./scripts/install-jean-server.sh --host tailscale -y ``` 从原生应用连接 在桌面应用中,点击标题栏的服务器图标,选择“添加远程”,然后输入完整的 Web Access URL(含 ?token=...),或分别输入服务器 URL 和 token。

选择远程端点会切换整个 Jean 后端,同时保留桌面应用的外壳(菜单、原生控件)。选定实例的命令和事件通过 HTTP/WebSocket 传输。在同一对话框(或命令面板)中选择“本地”即可返回桌面应用的本地后端。

原生 Jean 客户端的源被自动允许。支持 HTTP 和 HTTPS 服务器 URL;远程服务器请保持启用 token 认证。

服务器更新(裸机 Linux) 若从 Web Access 或已连接的原生客户端选择,jean-server 可以安装更新的二进制文件。后台不会自动安装 —— 只有在你确认“更新并重启”后才会执行 apply。

| 部分 | 行为 | | :--- | :--- | | 清单 | 最新 GitHub release 上的 server-latest.json | | 检查 | 若有新版本,Web Access / 远程客户端会显示更新提示 | | 应用 | 用户确认 → 下载、SHA-256 校验、重启服务或重新 exec | | 容器 | 不支持 —— 请改为更新 Docker/GHCR 镜像 | | 活跃会话 | 有聊天会话运行时,拒绝应用更新 |

安全建议

- 优先将 127.0.0.1 置于 Caddy/Nginx、SSH 隧道或 Tailscale 之后 - 任何非 localhost 绑定都保持启用 token 认证 - 使用长随机 token,例如 openssl rand -base64 32 - 仅当需要额外的跨域浏览器访问时,才设置 JEAN_ALLOWED_ORIGINS=https://jean.example.com;原生 Jean 客户端的源默认被允许

何时使用 Web 访问和无头模式适用于:

- Jean 运行在专用开发机或服务器上 - 希望通过浏览器访问长期运行的任务 - 需要检查会话状态而不必打开该主机上的桌面窗口 - 希望有一个功能强大的主机和较轻量级的客户端(浏览器或原生远程)

延伸阅读

本地优先与安全 归档、恢复与更新 观点化插件 一键安装精选工具,减少 token 用量并重塑跨后端的 agent 行为。 归档、恢复、更新 保持工作区整洁,恢复有用的历史,并了解 Jean 如何更新和清理本地状态。

评论 (0)