【实用的开源工具】Nexterm：在浏览器里管理 SSH、VNC 和 RDP 服务器

「实用的开源工具」系列：我只收集值得用的开源项目，写清楚它能做什么、怎么部署、有哪些坑，并在文末标明出处。内容整理自官方文档，核对日期 2026-10-31，具体版本以官方为准。

项目信息卡

它能做什么

按官方 README 的列表：

• 远程连接：SSH、VNC、RDP。
• 文件管理：通过 SFTP 管理远程文件。
• 安全相关：双因素认证、OIDC 单点登录；README 的安全一节还列了会话管理和密码加密。
• 组织：可以把用户和服务器分到不同的“组织”里。
• 其他：README 还提到通过 Docker 部署应用、管理 Proxmox 的 LXC 和 QEMU 容器；文档里有脚本与代码片段（Snippets）、远程浏览器、命令行工具 nt 等功能，这篇不展开。

适合谁：服务器和机器比较多、想用一个入口、不用在每台电脑上装客户端的人。不适合：想找“成熟稳定、长期不用管”的工具的人，因为官方自己标了 Beta。

部署

官方有三个镜像，简单场景用全合一的 nexterm/aio（服务端、网页客户端和连接引擎都在一个容器里）。需要把引擎放到别的网络、或者跑多个引擎时，才用 nexterm/server 加 nexterm/engine 的拆分方式，这篇只讲全合一。

第 1 步：生成加密密钥

官方给的命令：

openssl rand -hex 32

不要直接用文档里的示例密钥。 官方文档和仓库的 .env.example 里都有一串写死的示例值，那是公开的。请自己生成。

第 2 步：Compose 文件

先建目录，并把密钥放进 .env（Compose 会自动读取同目录的 .env，这一步是我的写法，目的是不把密钥写进 compose 文件里）：

mkdir -p /opt/nexterm && cd /opt/nexterm
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" > .env
chmod 600 .env

compose.yaml（结构来自官方文档的 All-In-One / Bridge Network 示例，我改了三处：端口只绑定 127.0.0.1、密钥从 .env 读取、镜像用固定版本；TRUST_PROXY 见下文说明）：

services:
  nexterm:
    image: nexterm/aio:1.2.2-BETA
    environment:
      ENCRYPTION_KEY: "${ENCRYPTION_KEY}"
      TRUST_PROXY: "1"
    ports:
      - "127.0.0.1:6989:6989"
    restart: always
    volumes:
      - nexterm:/app/data
volumes:
  nexterm:

启动：

docker compose up -d

• 1.2.2-BETA 是我在 Docker Hub 的标签列表里看到的、与 GitHub 最近版本同名的标签（latest 也存在）。你部署时请再确认一次标签存在，或者改用官方示例里的 latest。
• TRUST_PROXY：README 说明，前面有几层反向代理就填几，单个 Nginx 或 Traefik 用 1，这样日志和审计里记录的是真实客户端 IP；只有代理确实设置了 X-Forwarded-For 时才开，否则客户端可以伪造 IP。如果你不套反向代理，把这一行删掉。

官方推荐的 Host 网络，和我选 Bridge 的原因

官方文档给了两种方式，并写明 Host Network 是强烈推荐的：它让 Nexterm 直接使用宿主机的网络，Wake-on-LAN 和通过 localhost 连接服务器都需要它；只有确实需要网络隔离时才用 Bridge。

所以要选哪种取决于你要连什么：

• 只连远程服务器、并且前面套反向代理：用上面的 Bridge + 127.0.0.1 绑定，暴露面更小。
• 需要 Wake-on-LAN，或者要连宿主机本机（localhost）：按官方推荐改成 network_mode: host，同时去掉 ports。这种方式下容器直接监听宿主机的 6989 端口，请用防火墙或监听设置自己限制访问。

官方 Compose（Host 网络）的写法是：

services:
  nexterm:
    image: nexterm/aio:latest
    environment:
      ENCRYPTION_KEY: "替换成你生成的密钥"
    network_mode: host
    restart: always
    volumes:
      - nexterm:/app/data
volumes:
  nexterm:

端口和环境变量（README 列出的）

第一次使用

我读到的官方文档里没有描述首次打开页面时怎么创建第一个账号，所以这里不替它编流程。能确认的只有：

1. 打开 http://127.0.0.1:6989（远程服务器可以先用 SSH 端口转发访问）。
2. 按页面提示操作。如果页面上没有让你创建账号的入口，或者管理员密码丢了，官方的服务端命令行工具 ntctl 可以直接在服务器上建账号、重置密码：

docker exec -it nexterm ntctl user:list
docker exec -it nexterm ntctl user:create alice --admin
docker exec -it nexterm ntctl user:reset-password alice

这里的 nexterm 是容器名。上面的 Compose 没写 container_name，Compose 生成的名字不是 nexterm，请先 docker ps 看实际名字，或者直接在 compose.yaml 的 nexterm 服务下加一行 container_name: nexterm。user:create 不带 --password 时会交互式询问密码。

1. 登录后，官方文档里的设置入口有：Settings → Authentication（添加 OIDC 提供者）、Settings → Sources（接入 Git 仓库里的脚本和代码片段）。
2. 想在不开浏览器的情况下连接，可以看官方的命令行工具 nt（nt login、nt ls、nt connect），需要自己用 Rust 从源码构建，这里不展开。

反向代理（Nginx）

官方说明：套反向代理时必须开启 WebSocket 支持。官方的 Nginx 示例（我把域名换成 example.com，并按官方“有 SSL 就用 listen 443 ssl http2”的提示改成了 443，证书路径请换成你的）：

server {
    listen 443 ssl http2;
    server_name nexterm.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:6989;
        proxy_http_version 1.1;

        # WebSocket support
        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-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 86400;
    }
}

官方文档还给了 Apache、Caddy、Traefik 和 Cloudflare Tunnel 的写法，见文末出处。

不用反向代理：让 Nexterm 自己提供 HTTPS

官方 SSL 文档的做法：把证书放在数据目录的 certs 下，文件名固定为 cert.pem（证书）和 key.pem（私钥），Nexterm 会自动检测并启动 HTTPS 服务。HTTPS 默认端口是 5878，可以用 HTTPS_PORT 修改。用 Docker 时在 compose 里加：

services:
  nexterm:
    environment:
      HTTPS_PORT: 5878   # 可选，默认就是 5878
    ports:
      - "5878:5878"
    volumes:
      - ./certs:/app/data/certs

官方也给了 certbot 申请 Let's Encrypt 证书后，把 fullchain.pem、privkey.pem 复制成 cert.pem、key.pem 的步骤，复制后需要重启 Nexterm。证书会过期，复制是手动的，续期后要重新复制并重启，这是我的提醒，不是官方原话。

更新与卸载

官方文档里我没有读到专门的升级章节，下面是通用的 Docker Compose 做法，不是项目的专属说明。

更新：先备份，再换版本。

cd /opt/nexterm
docker run --rm -v nexterm_nexterm:/data -v "$PWD":/backup alpine tar czf /backup/nexterm-data-$(date +%F).tgz -C /data .
# 把 compose.yaml 里的镜像标签改成新版本（先确认标签存在），然后：
docker compose pull
docker compose up -d

• 命名卷的实际名字是“项目名_卷名”，目录叫 nexterm 时通常是 nexterm_nexterm，用 docker volume ls 确认。
• 官方已经提醒 Beta 阶段要备份。.env 里的 ENCRYPTION_KEY 也要一起保存：ntctl 文档说明读取加密字段需要和服务端相同的密钥，密钥丢了，库里加密保存的密码和密钥就读不出来（这是我据此做的推断）。

卸载：

cd /opt/nexterm
docker compose down        # 停止并删除容器，保留数据卷
docker compose down -v     # 同时删除数据卷，里面的数据不可恢复

踩坑清单

1. 它还是 Beta。 官方安装文档开头就写了，要定期备份，遇到问题去 GitHub 提 issue。别把它当成唯一的入口，SSH 本身要保留。
2. ENCRYPTION_KEY 必须自己生成，且要保管好。 官方示例里的值是公开的；密钥丢了或换了，已保存的密码、SSH 密钥和口令就无法解密（后半句是我的推断，依据是 README 说明该密钥用于加密这些内容）。
3. 官方推荐 Host 网络，不是随便写的。 Wake-on-LAN 和连 localhost 依赖它；换成 Bridge 后这些功能会受影响。
4. 反向代理必须开 WebSocket。 缺了 Upgrade 和 Connection 两行，终端连不上。官方示例还设了 proxy_read_timeout 86400，避免长连接被 Nginx 默认超时断开（后半句是我的解释）。
5. TRUST_PROXY 不能乱开。 README 明确说：没有代理设置 X-Forwarded-For 时开启，客户端可以伪造 IP，会污染日志和审计。
6. Docker 发布的端口通常会绕过 ufw 之类的防火墙（通用经验）。所以示例里写 127.0.0.1:6989:6989，官方原示例是 6989:6989，对所有网卡开放。开着 SSH 管理入口给公网，是高风险的事，建议再加 2FA（官方支持双因素认证）。
7. 自带 HTTPS 的证书是手动复制的。 官方步骤里，certbot 签发后需要复制成 cert.pem、key.pem 并重启；自签证书只适合测试，浏览器会警告。
8. 远程浏览器有明确限制。 官方文档说明：它会忽略证书错误（因为内网设备常用自签证书）、不支持下载文件、不支持音频、不能直接输入希腊文、西里尔文和中日韩文字（需要粘贴）；剪贴板访问需要 Nexterm 通过 HTTPS 提供。
9. OIDC 回调地址必须完全一致。 官方排错写的是 Redirect URI 要精确匹配，注意末尾斜杠和 http/https。官方示例的回调路径是 /api/auth/oidc/callback，登出回调是 /api/auth/oidc/logout/callback。Authentik 的 Issuer URL 末尾的斜杠也有影响。
10. SSO 配坏了可以用 ntctl auth:enable internal 救回来。 它会启用内置账号密码登录并关闭其他方式，之后按官方说明需要重启服务器让缓存刷新。
11. ntctl db:query 里的危险语句要小心。 官方说明 DROP、TRUNCATE、DELETE、ALTER 开头的语句会要求确认，加 --force 就跳过确认。
12. 密码类信息别写进命令历史。 ntctl user:create --password 会把密码留在 shell 历史里（通用提醒），不带这个参数让它交互询问更好。

出处

• Nexterm 官方仓库 README（功能、镜像、环境变量、许可证）
• 官方文档：Installation（在线版：docs.nexterm.dev/installation）
• 官方文档：Reverse Proxy & Cloudflare Tunnel
• 官方文档：Enabling SSL/HTTPS
• 官方文档：OIDC Authentication
• 官方文档：Server CLI（ntctl）
• 官方文档：CLI（nt）
• 官方文档：Remote Browser
• Docker Hub：nexterm/aio 标签列表