xiantong 文档
服务器

远程服务器

以浏览器、桌面和 CLI 访问方式将 xiantong 作为远程服务器运行

xiantong 可以作为远程服务器运行，让您在远程机器上保持长期会话，并从多个客户端访问：桌面应用、浏览器或 CLI。远程服务器适合需要长时间运行任务、统一团队工作区、或在更强计算资源上执行 Agent 任务的场景。

本页保留远程服务器的通用配置和安全建议。具体安装包、容器镜像或内部部署产物请以您当前 xiantong 发行渠道提供的信息为准。

适用场景#

  • 在服务器上持续运行长任务，不依赖本地电脑一直在线
  • 多台设备访问同一个远程工作区
  • 通过浏览器访问 Web 界面
  • 通过 CLI 进行脚本化和自动化操作
  • 将计算密集型任务放到更强的机器上运行

先决条件#

根据部署方式准备环境：

  • 远程主机：Linux 或 macOS 服务器
  • 运行时：按发行包要求安装所需运行时（例如 Bun / Node.js）
  • 网络：可被客户端访问的主机名或 IP
  • 认证令牌：用于客户端连接的 XIANTONG_SERVER_TOKEN
  • TLS：非本机访问建议使用 TLS 或放在安全隧道/反向代理后

生成令牌示例：

export XIANTONG_SERVER_TOKEN=$(openssl rand -hex 32)
echo $XIANTONG_SERVER_TOKEN # 请保存好，令牌无法反查

启动服务器#

远程服务器启动时通常需要指定认证令牌、监听地址和端口：

XIANTONG_SERVER_TOKEN=$XIANTONG_SERVER_TOKEN \
XIANTONG_RPC_HOST=0.0.0.0 \
XIANTONG_RPC_PORT=9100 \
xiantong-server

如果使用 TLS，可同时设置证书和私钥：

XIANTONG_SERVER_TOKEN=$XIANTONG_SERVER_TOKEN \
XIANTONG_RPC_HOST=0.0.0.0 \
XIANTONG_RPC_TLS_CERT=/path/to/cert.pem \
XIANTONG_RPC_TLS_KEY=/path/to/key.pem \
xiantong-server

服务器启动后会打印连接信息，通常包括：

XIANTONG_SERVER_URL=wss://0.0.0.0:9100
XIANTONG_SERVER_TOKEN=<your-token>

Web 界面#

远程服务器可以在同一端口提供浏览器可访问的 Web 界面。启用后，在浏览器中打开：

https://your-server:9100

如果未配置 TLS，也可在仅本机或受信网络中使用：

http://your-server:9100

认证#

登录时输入服务器令牌作为密码。登录成功后，服务器会签发会话 Cookie。

  • 登录尝试会按 IP 限流
  • 会话持续到登出或 Cookie 过期
  • 不要把令牌写入公开脚本、仓库或聊天记录

可用功能#

Web 界面提供与桌面应用类似的会话体验：创建会话、发送消息、管理工作区、查看历史记录等。部分 OAuth 或本地桌面能力可能依赖部署环境与客户端连接状态。

不要在公网无 TLS 暴露服务器。 服务器令牌和会话数据会通过网络传输。若无 TLS 或安全隧道，网络中的其他人可能拦截敏感信息。

连接客户端#

桌面应用（混合模式）#

在保留本地工作区的同时连接远程服务器：

  1. 点击侧栏中的工作区下拉菜单
  2. 选择 添加工作区… → 连接远程服务器
  3. 输入服务器 URL（例如 wss://192.168.1.100:9100）及令牌
  4. 点击 测试连接 验证
  5. 选择现有远程工作区，或在服务器上创建新工作区

连接后，远程工作区会与本地工作区共同出现在工作区切换器中。远程工作区不可达时，会显示离线状态。

桌面应用（精简客户端）#

在精简客户端模式下，应用主要连接远程服务器，核心逻辑在服务器端运行：

XIANTONG_SERVER_URL=wss://your-server:9100 \
XIANTONG_SERVER_TOKEN=<token> \
xiantong

Web UI#

在任意浏览器中打开服务器 URL，并使用令牌登录。适合在无需安装桌面客户端的设备上查看或继续会话。

CLI 客户端#

使用终端客户端进行脚本和自动化操作：

export XIANTONG_SERVER_URL=wss://your-server:9100
export XIANTONG_SERVER_TOKEN=<token>

xiantong-cli ping
xiantong-cli sessions
xiantong-cli send abc-123 "Run the tests"

完整命令参考 CLI 客户端。

环境变量#

变量是否必须默认值描述
XIANTONG_SERVER_TOKEN是—用于认证的承载令牌
XIANTONG_SERVER_URL否—客户端连接的服务器 URL
XIANTONG_RPC_HOST否127.0.0.1绑定地址；远程访问通常使用 0.0.0.0 或内网地址
XIANTONG_RPC_PORT否9100绑定端口
XIANTONG_RPC_TLS_CERT远程建议—PEM 证书文件（启用 wss://）
XIANTONG_RPC_TLS_KEY远程建议—PEM 私钥文件
XIANTONG_RPC_TLS_CA否—PEM CA 链文件（可选）
XIANTONG_WEBUI_DIR按部署而定—Web UI 静态资源目录
XIANTONG_DEBUG否false启用调试日志

仅本机开发时可省略 TLS；任何跨机器访问都建议使用 TLS、Tailscale、SSH 隧道或反向代理。

启动时运行#

Linux（systemd）#

在安全位置创建环境文件，例如 /etc/xiantong/server.env：

XIANTONG_SERVER_TOKEN=<your-token>
XIANTONG_RPC_HOST=0.0.0.0
XIANTONG_RPC_PORT=9100
XIANTONG_RPC_TLS_CERT=/path/to/cert.pem
XIANTONG_RPC_TLS_KEY=/path/to/key.pem

创建服务文件 /etc/systemd/system/xiantong-server.service：

[Unit]
Description=xiantong Server
After=network.target

[Service]
Type=simple
User=<your-user>
WorkingDirectory=/opt/xiantong
EnvironmentFile=/etc/xiantong/server.env
ExecStart=/usr/local/bin/xiantong-server
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable xiantong-server
sudo systemctl start xiantong-server

# 检查状态
sudo systemctl status xiantong-server

# 查看日志
journalctl -u xiantong-server -f

macOS（launchd）#

创建 ~/Library/LaunchAgents/com.xiantong.server.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
 "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
 <key>Label</key>
 <string>com.xiantong.server</string>
 <key>ProgramArguments</key>
 <array>
 <string>/usr/local/bin/xiantong-server</string>
 </array>
 <key>WorkingDirectory</key>
 <string>/opt/xiantong</string>
 <key>EnvironmentVariables</key>
 <dict>
 <key>XIANTONG_SERVER_TOKEN</key>
 <string>YOUR_TOKEN</string>
 <key>XIANTONG_RPC_HOST</key>
 <string>0.0.0.0</string>
 <key>XIANTONG_RPC_PORT</key>
 <string>9100</string>
 <key>XIANTONG_RPC_TLS_CERT</key>
 <string>/path/to/cert.pem</string>
 <key>XIANTONG_RPC_TLS_KEY</key>
 <string>/path/to/key.pem</string>
 </dict>
 <key>RunAtLoad</key>
 <true/>
 <key>KeepAlive</key>
 <true/>
 <key>StandardOutPath</key>
 <string>/tmp/xiantong-server.log</string>
 <key>StandardErrorPath</key>
 <string>/tmp/xiantong-server.log</string>
</dict>
</plist>

加载并启动：

launchctl load ~/Library/LaunchAgents/com.xiantong.server.plist

# 检查状态
launchctl list | grep xiantong

# 查看日志
tail -f /tmp/xiantong-server.log

# 停止并卸载
launchctl unload ~/Library/LaunchAgents/com.xiantong.server.plist

安全访问#

不建议将服务器直接暴露在互联网上。建议采用以下任一方式。

Tailscale（推荐）#

Tailscale 在设备间构建私有网状网络。服务器和客户端都安装即可，无需端口映射、证书或复杂防火墙规则。

# 在服务器上：仅绑定到 Tailscale IP
XIANTONG_RPC_HOST=100.x.y.z \
XIANTONG_SERVER_TOKEN=$TOKEN \
xiantong-server

Tailscale 提供端到端加密。服务器仅在您的 Tailscale 网络内可访问。

反向代理（nginx, Caddy）#

将服务器置于负责 TLS 终止和访问控制的反向代理之后。

Caddy：

xiantong.example.com {
 reverse_proxy localhost:9100
}

nginx：

server {
 listen 443 ssl;
 server_name xiantong.example.com;

 ssl_certificate /etc/letsencrypt/live/xiantong.example.com/fullchain.pem;
 ssl_certificate_key /etc/letsencrypt/live/xiantong.example.com/privkey.pem;

 location / {
 proxy_pass http://localhost:9100;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 proxy_set_header Host $host;
 }
}

使用反向代理时，建议将服务器绑定到本地（XIANTONG_RPC_HOST=127.0.0.1），由代理处理外部访问。

Cloudflare Tunnel#

Cloudflare Tunnel 可在无需开放端口或手动管理证书的情况下通过 HTTPS 暴露服务器。

# 快速隧道 —— 立即提供 HTTPS URL
cloudflared tunnel --url http://localhost:9100

若需永久自定义域名，可创建命名 tunnel，并将其路由到您的域名。保持 XIANTONG_RPC_HOST=127.0.0.1，确保服务器仅本地监听。

SSH 隧道#

适用于快速临时访问：

# 在客户端：将本地 9100 端口转发到远程服务器
ssh -L 9100:localhost:9100 user@your-server

然后从桌面应用或浏览器连接 ws://localhost:9100。流量会通过 SSH 加密传输。

浏览器工具#

内置 浏览器 可从远程工作区桥接到已连接的桌面客户端：页面在您的本地机器上打开，使用本地 cookies 和登录状态。当至少一个桌面客户端连接时，浏览器工具可用；仅 Web UI 或 CLI 客户端无法托管浏览器窗口。

版本兼容性#

服务器在连接握手中包含版本信息。当客户端连接到较旧服务器时，可能显示功能兼容性提示。建议客户端与服务器保持相近版本。

上一页深入链接