// setup guide

Ubuntu 新机器 安装指引

按步骤完成配置,点击每个模块右侧 ○ 标记已完成

适用 Ubuntu 22.04 / 24.04 10 个安装模块 点击标题展开步骤
// 安装进度
已完成 0 / 9 个模块
00 🔄
系统更新
安装任何软件前的第一步
步骤 1 — 更新包列表
同步仓库索引,确保后续安装获取最新版本。
sudo apt update
步骤 2 — 升级已安装软件
将系统中所有可升级的包更新到最新版。
sudo apt upgrade -y
升级过程可能需要几分钟,如遇到内核更新提示,直接按 Enter 确认即可。
步骤 3 — 安装常用基础工具
后续步骤会用到这些工具,提前安装。
sudo apt install -y curl wget git vim htop unzip
01 👤
新建用户 ubuntu
创建非 root 的日常操作账户
步骤 1 — 创建用户
创建名为 ubuntu 的新用户,系统会引导你设置密码和基本信息。
sudo adduser ubuntu
按照提示输入密码(至少8位),其他信息(Full Name 等)可直接回车跳过。
步骤 2 — 赋予 sudo 权限
将 ubuntu 用户加入 sudo 组,使其可以执行管理员命令。
sudo usermod -aG sudo ubuntu
步骤 3 — 验证
切换到新用户并验证 sudo 权限是否生效。
su - ubuntu
sudo whoami
# 应输出: root
步骤 4 — 配置 SSH 密钥(推荐)
将你的本机公钥复制到新用户,以便直接 SSH 登录,无需密码。
# 在本机执行(把 SERVER_IP 替换为你的服务器 IP)
ssh-copy-id ubuntu@SERVER_IP
02 🐳
安装 Docker
容器运行时 + Docker Compose
步骤 1 — 清理旧的/损坏的 Docker 源
如果之前配置过 Docker 源且出现报错,先删除旧文件再重新添加。
sudo rm -f /etc/apt/sources.list.d/docker.list
# 清理后测试更新是否正常
sudo apt update
步骤 2 — 安装依赖
sudo apt install -y ca-certificates curl gnupg lsb-release
步骤 3 — 添加 Docker GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
步骤 4 — 添加 Docker 官方仓库
此命令会自动检测你的 Ubuntu 版本(noble = 24.04 / jammy = 22.04)。
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
步骤 5 — 安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
步骤 6 — 验证安装
sudo docker run hello-world
# 看到 "Hello from Docker!" 表示安装成功
步骤 7 — 免 sudo 运行 Docker
将当前用户加入 docker 组,重新登录后生效。
sudo usermod -aG docker $USER
# 重新登录 SSH 或执行以下命令使其立即生效
newgrp docker
03 🟩
安装 Node.js & npm
使用 nvm 管理多版本 Node
方案 A — 使用 nvm(推荐,可管理多版本)
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc

# 安装最新 LTS 版 Node.js
nvm install --lts

# 设为默认版本
nvm alias default node

方案 B — 通过 NodeSource 仓库安装(固定版本)
# 以 Node.js 20 LTS 为例
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
验证
node -v   # 例: v20.18.0
npm -v    # 例: 10.8.2
04 📊
安装 Beszel Agent
轻量级服务器监控探针
方案 A — Docker 方式运行(推荐)
在 Beszel 控制面板中添加系统后,会生成唯一的 KEY,替换下方 YOUR_KEY。
docker run -d \
  --name beszel-agent \
  --network host \
  --pid host \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e KEY="YOUR_KEY" \
  henrygd/beszel-agent
将 YOUR_KEY 替换为 Beszel Hub 控制台给出的公钥字符串。

方案 B — 二进制方式安装
# 下载并安装(一键脚本)
curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh \
  -o install-agent.sh && bash install-agent.sh
脚本会引导你输入 Hub 地址和 KEY,并自动注册为 systemd 服务。
验证
# Docker 方式
docker logs beszel-agent

# 服务方式
sudo systemctl status beszel-agent
05 🔒
安装 Tailscale
零配置 VPN 组网 / 支持 Headscale 自建
方案 1 — 一键脚本安装(官方)
curl -fsSL https://tailscale.com/install.sh | sh

方案 2 — 手动添加仓库安装
适合网络受限或需要固定仓库来源的情况。24.04 用 noble,22.04 用 jammy。
# 添加签名密钥(Ubuntu 24.04 noble)
curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/noble.noarmor.gpg \
  | sudo tee /usr/share/keyrings/tailscale-archive-keyring.gpg >/dev/null

curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/noble.tailscale-keyring.list \
  | sudo tee /etc/apt/sources.list.d/tailscale.list

sudo apt update && sudo apt install -y tailscale

接入自建 Headscale 服务器
安装完成后,使用以下命令连接到你的 Headscale 服务器(替换 IP 地址和端口)。
# 配置并启动(一次性命令)
echo 'TS_DEBUG_FORCE_HTTP_ONLY=true' | sudo tee -a /etc/default/tailscaled
sudo systemctl restart tailscaled
sudo tailscale up \
  --reset \
  --force-reauth \
  --accept-dns=false \
  --login-server=http://YOUR_HEADSCALE_IP:41641
将 YOUR_HEADSCALE_IP 替换为你的 Headscale 服务器 IP 地址。
在 Headscale 服务端注册节点
运行 tailscale up 后,终端会输出一个注册 key,在 Headscale 服务器上执行。
# 在 Headscale 服务器上执行(替换 YOUR_NODE_KEY)
docker exec headscale headscale nodes register \
  --key YOUR_NODE_KEY \
  --user admin

# 查看所有节点
docker exec headscale headscale nodes list

# 重命名节点(-i 后跟节点 ID,替换 NEW_NAME)
docker exec -it headscale headscale nodes rename -i NODE_ID NEW_NAME
06 🔄
安装 Syncthing
去中心化文件同步工具(Docker 部署)
步骤 1 — 创建目录结构
mkdir -p ~/syncthing/config ~/syncthing/data
步骤 2 — 设置目录权限
Syncthing 容器默认以 UID 1000 运行,需要匹配主机权限。
sudo chown -R 1000:1000 ~/syncthing/config ~/syncthing/data
sudo chmod -R 775 ~/syncthing/config ~/syncthing/data
步骤 3 — 使用 Docker Compose 启动
在 ~/syncthing 目录下创建 docker-compose.yml 文件。
# 创建 compose 文件
cat > ~/syncthing/docker-compose.yml <<'EOF'
services:
  syncthing:
    image: linuxserver/syncthing:latest
    container_name: syncthing
    hostname: syncthing
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/config
      - ./data:/data
    ports:
      - 8384:8384    # Web UI
      - 22000:22000  # 同步协议 TCP
      - 22000:22000/udp
      - 21027:21027/udp
    restart: unless-stopped
EOF
步骤 4 — 启动服务
cd ~/syncthing && docker compose up -d
# 访问 Web UI: http://YOUR_SERVER_IP:8384
首次访问 Web UI 时,建议立即在「Actions → Settings」中设置访问密码。
07 ☁️
安装 Cloudflared + Caddy
Cloudflare 隧道 + 反向代理
Cloudflared — 安装
将你的服务通过 Cloudflare 隧道暴露到互联网,无需开放端口。
# 下载并安装 cloudflared
curl -L --output cloudflared.deb \
  https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb
rm cloudflared.deb
Cloudflared — 登录并创建隧道
# 登录 Cloudflare(会弹出授权链接)
cloudflared tunnel login

# 创建隧道(替换 TUNNEL_NAME)
cloudflared tunnel create TUNNEL_NAME

# 配置 DNS 路由(替换域名和隧道 ID)
cloudflared tunnel route dns TUNNEL_NAME your.domain.com
Cloudflared — 创建配置文件并运行
# 创建配置文件(替换 TUNNEL_ID 和域名)
mkdir -p ~/.cloudflared
cat > ~/.cloudflared/config.yml <<'EOF'
tunnel: TUNNEL_ID
credentials-file: /root/.cloudflared/TUNNEL_ID.json
ingress:
  - hostname: your.domain.com
    service: http://localhost:8080
  - service: http_status:404
EOF

# 安装为系统服务
sudo cloudflared service install
sudo systemctl start cloudflared

Caddy — 安装
Caddy 是自动 HTTPS 的轻量反向代理,适合本地服务转发。
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy -y
Caddy — 基础 Caddyfile 示例
# 编辑 /etc/caddy/Caddyfile
your.domain.com {
    reverse_proxy localhost:8080
}

# 重启服务使配置生效
sudo systemctl reload caddy
08
安装 Gemini CLI
Google Gemini 命令行工具
前置条件
需要先完成 Node.js & npm 的安装(模块 03)。
# 确认 Node.js 版本 ≥ 18
node -v
安装 Gemini CLI
npm install -g @google/gemini-cli
配置 API Key
在 Google AI Studio 获取 API Key,然后设置为环境变量。
# 写入 ~/.bashrc,永久生效(替换 YOUR_API_KEY)
echo 'export GEMINI_API_KEY="YOUR_API_KEY"' >> ~/.bashrc
source ~/.bashrc
验证
gemini --version
gemini "Hello, who are you?"
首次运行会提示登录或使用 API Key,按提示操作即可。
09 🖥️
Xfce 桌面 + XRDP
通过 Windows 远程桌面访问图形界面(Xorg 模式)
步骤 1 — 安装 Xfce 桌面环境
安装核心组件和常用插件(xfce4-goodies 包含面板插件、终端等),安装过程如提示选择显示管理器,选 lightdm 即可。
sudo apt install -y xfce4 xfce4-goodies
步骤 2 — 安装 xrdp
xrdp 提供 RDP 协议支持,安装后自动启动并监听 3389 端口。
sudo apt install -y xrdp
步骤 3 — 强制使用 Xorg(关键!)
编辑 xrdp 启动脚本,清除 Wayland 环境变量,避免黑屏或兼容性问题。
sudo nano /etc/xrdp/startwm.sh
在最后两行 test -x /etc/X11/Xsession上方插入以下两行,然后 Ctrl+O 保存,Ctrl+X 退出。
unset DBUS_SESSION_BUS_ADDRESS
unset XDG_RUNTIME_DIR
修改后完整文件应如下所示:
#!/bin/sh
# xrdp X session start script (c) 2015, 2017, 2021 mirabilos
# published under The MirOS Licence
# Rely on /etc/pam.d/xrdp-sesman using pam_env to load both
# /etc/environment and /etc/default/locale to initialise the
# locale and the user environment properly.
if test -r /etc/profile; then
        . /etc/profile
fi
if test -r ~/.profile; then
        . ~/.profile
fi

unset DBUS_SESSION_BUS_ADDRESS
unset XDG_RUNTIME_DIR

test -x /etc/X11/Xsession && exec /etc/X11/Xsession
exec /bin/sh /etc/X11/Xsession
步骤 4 — 重启 xrdp 服务
sudo systemctl restart xrdp
# 验证服务状态,应显示 active (running)
sudo systemctl status xrdp
步骤 5 — 开放防火墙端口
sudo ufw allow 3389/tcp
sudo ufw status
如果 VPS 提供商有独立安全组(腾讯云、阿里云、AWS 等),还需要在控制台入站规则中放行 TCP 3389 端口。
步骤 6 — 连接远程桌面
使用你的系统用户名和密码登录,不要用 root 用户。
# Windows:Win + R → 输入 mstsc → 填入 VPS IP → 连接
# macOS:App Store 安装 Microsoft Remote Desktop
# Linux:使用 Remmina 客户端

登录账号:你的系统用户名(如 ubuntu)
密码:对应用户的 SSH 登录密码

常见问题排查
Q1:连接后黑屏或没有面板
检查步骤 3 的两行 unset 是否正确添加,确认后重启 xrdp 再试。
Q2:连接后闪退或立即断开
# ~/.xsession 文件可能有干扰,备份后重试
mv ~/.xsession ~/.xsession.bak
sudo systemctl restart xrdp
Q3:提示"无法连接到远程计算机"
通常是防火墙问题,检查 ufw 和云控制台安全组是否都已放行 3389。
Q4:验证是否运行 Xorg(非 Wayland)
echo $XDG_SESSION_TYPE
# 输出 x11 表示正常
// ubuntu-setup-guide
点击模块右侧圆圈标记完成状态 · 进度自动保存到浏览器