Docker 中运行 Web TUI¶

把 Synapse Web TUI 以 Docker 容器作为沙箱运行：浏览器通过 WebSocket 连接 textual-serve，服务端为每个浏览器会话启动一个 synapse tui 子进程。

镜像不包含 Rust 工具链，运行时依赖全部通过预编译 wheel 安装，只依赖 python:3.12-slim 基础镜像，镜像体积最小。

入口¶

Web 启动器已作为包内模块和独立控制台命令提供：

synapse.web（python -m synapse.web）
synapse-web（wheel 安装后直接可用）

synapse-web --host 0.0.0.0 --port 8000

源码仓库中的 scripts/serve_web.py 保留为兼容薄包装，行为一致。

镜像构建¶

方式一：从 PyPI 安装发布版本¶

docker build -f Dockerfile.web -t synapse-web .

默认使用 pypi 模式，从 PyPI 安装 synapse-cli-agent==0.1.25（即 Dockerfile.web 中 ARG SYNAPSE_VERSION 的默认值）及其依赖（包括已有预编译 wheel 的 synapse-core-tool）。

如需指定版本：

docker build -f Dockerfile.web \
  --build-arg SYNAPSE_VERSION=0.1.25 \
  -t synapse-web .

方式二：安装本地构建的 wheel¶

先把本地 wheel 放入构建上下文 dist/，然后使用 local 模式：

docker build -f Dockerfile.web --build-arg SYNAPSE_MODE=local -t synapse-web .

在远程机器上构建¶

# 在远程机器 root@gateway1 上执行
scp Dockerfile.web root@gateway1:/tmp/synapse/
ssh root@gateway1
cd /tmp/synapse
docker build -f Dockerfile.web -t synapse-web .

运行¶

docker run --rm -d --name synapse-web \
  -p 8000:8000 \
  -v "$PWD:/workspace" \
  synapse-web

然后浏览器访问：

http://<gateway1-ip>:8000

/workspace 是 agent 的工作目录，也是配置（.synapse/）和会话数据的落盘位置，通过 volume 挂载到宿主机即可持久化。

行为说明¶

synapse-web 进程常驻，负责 HTTP 页面和 WebSocket。
浏览器每次刷新会断开旧 WebSocket 并建立新连接，服务端会重新启动一个 synapse tui 子进程；界面与内存状态会重置，但会话、配置和主题等持久化数据仍从 /workspace 恢复。
每个浏览器标签页对应一个独立的 TUI 子进程。
agent 的工具执行都发生在容器内，适合作为沙箱隔离。
容器以非 root 用户 synapse 运行，镜像只暴露 8000 端口。

通过 nginx 443 反向代理¶

容器不应直接监听公网。推荐让容器只绑定本机回环地址，由 nginx 承担 TLS 与公网入口：

docker run --rm -d --name synapse-web \
  -p 127.0.0.1:8000:8000 \
  -v "$PWD:/workspace" \
  synapse-web \
  --host 127.0.0.1 --port 8000 \
  --public-url https://synapse-agent.best/tui

--public-url 是必须的：textual-serve 用它生成页面中的 WebSocket 与静态资源地址。不设置时默认使用 http://<host>:<port>，经 nginx 反代后浏览器无法连接。 https:// 前缀会自动推导出 wss://。

nginx 站点中为 Web TUI 增加一个路径并转发到回环端口（需支持 WebSocket 升级）：

location /tui/ {
    proxy_pass http://127.0.0.1:8000/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400;
}

重载配置后访问：

https://synapse-agent.best/tui