雨 雨天小六

腾讯云部署 Web Terminal Gateway：在浏览器使用 Codex CLI

· 更新于 2026-07-29 · 专栏：开源项目

#Codex#腾讯云#Web终端#Linux#部署教程#开源

本文介绍如何在腾讯云轻量应用服务器上部署 Web Terminal Gateway，并通过电脑或手机浏览器使用 Linux 终端和 Codex CLI。

部署过程不修改项目源码，只需要安装软件、克隆仓库并填写环境配置。浏览器关闭或网络断开后，服务器上的终端进程仍会继续运行，重新打开网页即可连接原会话。

一、准备服务器和域名

1. 购买轻量应用服务器

进入腾讯云轻量应用服务器购买页面，按下面的配置购买：

  • 地域选择海外，首选首尔一区或首尔二区；
  • 系统选择 Ubuntu 24.04 LTS 64 位；
  • 个人使用选择 2 核 2GB 即可；
  • 购买时长选择一年；
  • 登录方式优先选择 SSH 密钥。

我购买时的活动价格是 199 元一年。活动价格和续费价格可能变化，以购买页面为准。腾讯云当前提供首尔一区和首尔二区，详细说明见地域与网络连通性。

购买完成后，在服务器防火墙中添加以下规则：

  • 22/TCP：SSH 登录，来源尽量限制为自己的公网 IP；
  • 80/TCP：申请 HTTPS 证书；
  • 443/TCP：浏览器访问。

不需要开放 8787 端口。Web Terminal Gateway 只在服务器本机监听该端口，由 Caddy 负责公网访问。

2. 购买并解析域名

购买一个价格合适的域名。首年价格较低的域名通常只需要几元，下单时同时查看续费价格。

在腾讯云云解析 DNS 中添加 A 记录：

  • 主机记录：terminal；
  • 记录类型：A；
  • 记录值：轻量应用服务器的公网 IP。

例如域名是 example.com，完成后使用的地址就是 terminal.example.com。本文使用首尔服务器，不需要进行中国内地 ICP 备案。腾讯云域名解析步骤可参考添加域名解析。

二、安装基础环境

下面的命令假设服务器登录用户为 ubuntu。如果实际用户名不同，需要同时修改后续服务文件中的用户和家目录。

通过 SSH 登录服务器：

ssh ubuntu@服务器公网IP

安装 Git、Node.js 和编译工具：

sudo apt update
sudo apt install -y git curl build-essential python3 nodejs npm openssl
node --version
npm --version

Node.js 版本需要为 18 或更高。如果版本低于 18，先升级到当前 LTS 版本再继续。

三、安装并登录 Codex CLI

安装 Codex CLI：

sudo npm install -g @openai/codex@latest
codex --version

服务器没有桌面环境，使用设备码登录：

codex login --device-auth

根据终端提示，在电脑或手机上打开登录网址并输入一次性代码。完成后检查登录状态：

codex login status

设备码登录方式和其他认证选项见 Codex 认证文档。Codex 登录信息保存在当前 Linux 用户的 ~/.codex 目录中，因此后面的网关服务也要使用同一个用户运行。

四、克隆 Web Terminal Gateway

直接从 GitHub 克隆项目：

sudo git clone https://github.com/yutianxiao6/web-terminal-gateway.git /opt/web-terminal-gateway
sudo chown -R ubuntu:ubuntu /opt/web-terminal-gateway
cd /opt/web-terminal-gateway
npm ci
npm test

npm test 通过后再启动服务。如果安装 node-pty 时出现编译错误，检查 build-essential 和 python3 是否已经安装。

五、配置运行环境

创建用于存放项目的目录：

mkdir -p /home/ubuntu/projects

生成访问令牌：

openssl rand -hex 32

复制输出，然后基于项目示例创建配置文件：

sudo cp /opt/web-terminal-gateway/.env.example /etc/web-terminal-gateway.env
sudo nano /etc/web-terminal-gateway.env

只需要确认或修改以下配置：

  • HOST=127.0.0.1；
  • PORT=8787；
  • WEB_AUTH_TOKEN 填写刚才生成的随机令牌；
  • DEFAULT_WORKSPACE=/home/ubuntu/projects；
  • ALLOWED_WORKSPACE_ROOT=/home/ubuntu/projects；
  • TERMINAL_MODE=codex；
  • TERMINAL_BIN=codex；
  • CODEX_HOME=/home/ubuntu/.codex；
  • MAX_TERMINAL_SESSIONS=4。

保存后设置文件权限：

sudo chown root:root /etc/web-terminal-gateway.env
sudo chmod 600 /etc/web-terminal-gateway.env

ALLOWED_WORKSPACE_ROOT 决定网页终端可以访问的目录范围。不要设置为 /，需要操作的 Git 仓库统一放在 /home/ubuntu/projects 中。

六、启动 Web Terminal Gateway

项目已经提供 systemd 服务文件，直接复制并启动：

sudo cp /opt/web-terminal-gateway/web-terminal-gateway.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now web-terminal-gateway
sudo systemctl status web-terminal-gateway --no-pager

服务文件默认使用：

  • 运行用户：ubuntu；
  • 应用目录：/opt/web-terminal-gateway；
  • 配置文件：/etc/web-terminal-gateway.env；
  • Codex 配置目录：/home/ubuntu/.codex。

如果服务器用户名不是 ubuntu，执行 sudo nano /etc/systemd/system/web-terminal-gateway.service，修改 User、Group 和 HOME 后重新启动服务。

查看运行日志：

sudo journalctl -u web-terminal-gateway -n 100 --no-pager

七、配置域名和 HTTPS

安装 Caddy：

sudo apt install -y caddy

编辑配置文件：

sudo nano /etc/caddy/Caddyfile

写入下面两行，并替换成自己的域名：

terminal.example.com {
    reverse_proxy 127.0.0.1:8787
}

检查并重新加载配置：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager

域名解析正确，且 80、443 端口已经开放时，Caddy 会自动申请并续期 HTTPS 证书。

八、打开浏览器终端

第一次访问时，在地址后添加网关令牌：

https://terminal.example.com/?token=你的WEB_AUTH_TOKEN

页面会把令牌保存在当前浏览器中，并从地址栏删除。不要把带令牌的地址发送给其他人。

进入页面后按下面的步骤使用：

  1. 在“模式”中选择 Codex 或 Linux 终端；
  2. 在“起始目录”中选择 /home/ubuntu/projects 下的项目；
  3. 点击“启动终端”；
  4. 在电脑上直接使用终端输入，在手机上使用页面底部的移动端输入框；
  5. 另一台设备打开同一会话时，点击“接管输入”即可切换控制设备。

九、会话恢复

刷新网页、关闭浏览器或临时断网不会关闭服务器上的终端进程。重新打开网页后，可以从会话列表连接原来的终端。

以下操作会结束正在运行的终端：

  • 点击网页中的“关闭会话”；
  • 重启 Web Terminal Gateway 服务；
  • 重启或关闭服务器。

如果服务或服务器已经重启，重新创建 Codex 终端，然后执行：

codex resume

该命令可以继续之前保存的 Codex 对话。

十、更新项目

更新前先结束正在运行的任务。更新命令如下：

cd /opt/web-terminal-gateway
git pull --ff-only
npm ci
npm test
sudo systemctl restart web-terminal-gateway

更新 Codex CLI：

sudo npm install -g @openai/codex@latest

常见问题

页面显示 502

执行 sudo systemctl status web-terminal-gateway 和 sudo journalctl -u web-terminal-gateway -n 100，检查网关是否启动成功。

启动 Codex 时提示未登录

执行 codex login status。确认登录 Codex 的 Linux 用户和 systemd 服务中的 User 相同，并确认 CODEX_HOME 指向该用户的 .codex 目录。

HTTPS 证书申请失败

检查域名 A 记录是否指向当前服务器公网 IP，并确认腾讯云防火墙已经开放 80 和 443 端口。

更换电脑后提示未授权

新浏览器没有保存网关令牌。重新访问一次 https://域名/?token=WEB_AUTH_TOKEN 即可。

相关链接

评论

← 返回文章列表