功能	说明
✅ XFCE4 桌面环境	轻量级、高性能的 Linux 桌面
✅ noVNC Web 访问	通过浏览器访问完整桌面
✅ 中文界面支持	完整的中文语言包和本地化
✅ 中文输入法	Fcitx5 + IBus 双输入法框架
✅ HTTP 音频流	远程桌面声音在浏览器中播放
✅ VSCode Desktop	代码编辑器，中文界面
✅ MCP Server	VSCode 作为 MCP 服务端
✅ DEB 软件管理	一键安装/卸载第三方 DEB 软件包
✅ 自定义分辨率	支持 800x600 等自定义分辨率
✅ 持久连接	解决 noVNC 频繁断开问题
✅ 可配置端口	所有端口可在配置文件中修改

🏗️ 目录结构


ch72_xfce4_desktop/
├── Makefile                      # 便捷命令入口 (推荐使用)
├── master_controller.sh          # 交互式管理菜单
├── audio_player.html             # 浏览器端音频播放器
│
├── scripts/                      # 安装和启动脚本
│   ├── install_xfce4_desktop.sh  # 主安装脚本
│   ├── install_audio.sh          # 音频系统安装
│   ├── install_vscode.sh         # VSCode Desktop 安装
│   ├── install_vscode_mcp.sh     # MCP Server 安装
│   ├── install_deb_package.sh    # DEB 软件安装器
│   ├── uninstall_deb_package.sh  # DEB 软件卸载器
│   ├── uninstall.sh              # 卸载脚本
│   ├── start_desktop_fixed.sh    # 桌面启动脚本
│   ├── start_audio.sh            # 音频服务启动
│   ├── audio_http_server.py      # HTTP 音频流服务器
│   ├── web_files_server.py       # Web 文件服务器
│   ├── status_desktop.sh         # 状态检查
│   ├── stop_desktop.sh           # 停止服务
│   └── test_all.sh               # 测试脚本
│
├── config/                       # 配置文件
│   ├── ports.conf               # 端口配置
│   ├── deb_installer.conf       # DEB 软件安装配置
│   ├── chinese-env.sh           # 中文环境变量
│   ├── audio_env.sh             # 音频环境配置
│   └── vscode/                  # VSCode 配置
│       ├── settings.json        # 用户设置
│       └── mcp/                 # MCP 配置
│
├── docs/                         # 详细文档
│   ├── AUDIO_STREAM_SETUP.md    # 音频流配置
│   ├── DEB_INSTALLER_PLAN.md    # DEB 安装器计划
│   ├── VSCODE_DESKTOP_INSTALLATION.md # VSCode 安装记录
│   └── VSCODE_MCP_SERVER_PLAN.md # MCP Server 计划
│
├── logs/                         # 日志文件
├── fonts/                        # 字体文件
└── themes/                       # 主题文件

🚀 快速开始

方法一：使用 Makefile（推荐）


# 查看帮助
make

# 完整安装
make install

# 启动所有服务（桌面 + 音频 + Web）
make start

# 查看状态
make status

# 停止服务
make stop

# 显示访问地址
make access

方法二：使用交互菜单


make menu
# 或
./master_controller.sh

访问地址

服务	端口	地址
远程桌面	6080	`https://<host>-6080.cnb.run/vnc_lite.html`
音频播放器	8888	`https://<host>-8888.cnb.run/audio_player.html`
音频流	8080	`https://<host>-8080.cnb.run/`

注意: 代理地址通过环境变量动态生成，无硬编码域名

⚙️ 端口配置

端口可在 config/ports.conf 中自定义：


# noVNC 桌面访问端口
NOVNC_PORT=6080

# HTTP 音频流端口
AUDIO_HTTP_PORT=8080

# Web 文件服务端口
WEB_FILES_PORT=8888

# VNC 服务端口
VNC_PORT=5901

# PulseAudio TCP 端口
PULSE_TCP_PORT=4713

# VSCode MCP Server 端口
MCP_SERVER_PORT=3000

修改后需重启服务: make stop && make start

🔊 音频系统

架构


远程桌面浏览器 → PulseAudio (remote-audio sink)
        ↓
HTTP 音频服务器 (端口 8080)
        ↓ PCM 流 (44100Hz, 16-bit, stereo)
audio_player.html (Web Audio API)
        ↓
用户耳机/音箱

使用方法

打开远程桌面: https://<host>-6080.cnb.run/vnc_lite.html
打开音频播放器: https://<host>-8888.cnb.run/audio_player.html
点击"开始播放"
在远程桌面中播放视频/音乐

音频命令


make audio-install   # 安装音频系统
make audio-start     # 启动音频服务
make audio-status    # 查看音频状态
make audio-stop      # 停止音频服务

💻 VSCode Desktop

安装


make vscode-install

命令区分

命令	用途
`code`	VSCode Server (远程 SSH 开发)
`vscoded`	VSCode Desktop (远程桌面 GUI)
`code-desktop`	VSCode Desktop (备用)

功能

中文界面 (已配置)
用户设置 (自动复制 config/vscode/settings.json)
Docker 环境兼容

VSCode 命令


make vscode-install  # 安装 VSCode Desktop
make vscode-check   # 检查安装状态

🤖 MCP Server

概述

VSCode Desktop 可以配置为 MCP 服务器，让本地客户端（如 Claude Desktop）通过 npx 连接并执行命令。

安装


make vscode-mcp-install

手动安装扩展

在远程桌面中打开 VSCode
按 Ctrl+Shift+X 打开扩展市场
搜索: JuehangQin.vscode-mcp-server
点击 Install
点击状态栏的 MCP 图标开启服务

客户端配置

编辑 Claude Desktop 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json


{
  "mcpServers": {
    "vscode-mcp-server": {
      "command": "npx",
      "args": ["mcp-remote@next", "http://localhost:3000/mcp"]
    }
  }
}

MCP 管理命令


make vscode-mcp-install  # 安装扩展
make vscode-mcp-start    # 启动 VSCode
make vscode-mcp-stop     # 停止 VSCode
make vscode-mcp-status   # 查看状态
make vscode-mcp-help     # 显示帮助

📦 DEB 软件管理

概述

DEB 软件安装器支持一键安装/卸载第三方 DEB 软件包，自动处理依赖问题和 Docker 环境兼容性。

配置文件

编辑 config/deb_installer.conf 添加软件：


# Obsidian - 知识管理/笔记软件
OBSIDIAN_DEB_URL="https://github.com/obsidianmd/obsidian-releases/releases/download/v1.11.7/obsidian_1.11.7_amd64.deb"
OBSIDIAN_NO_SANDBOX="true"  # Docker 环境需要无沙箱模式

安装命令


make deb-list               # 列出可安装软件
make deb-install-obsidian   # 安装 Obsidian
make deb-install-all        # 安装所有软件
make deb-clean              # 清理下载目录

卸载命令


make deb-uninstall          # 交互式多选菜单（美观界面）
make deb-uninstall-all      # 自动卸载所有（-y 模式）
make deb-uninstall-name NAME=obsidian  # 卸载指定软件
make deb-status             # 查看已安装软件

交互式卸载菜单

运行 make deb-uninstall 会显示美观的多选菜单：


╔════════════════════════════════════════════════════════════════╗
║  📦 DEB 软件卸载器 - 多选菜单                              ║
╠════════════════════════════════════════════════════════════════╣
║  [j/k] 上下移动  [空格] 选择  [a] 全选  [回车] 确认  [q] 退出  ║
╠════════════════════════════════════════════════════════════════╣
║  请选择要卸载的软件:                                       ║
╟────────────────────────────────────────────────────────────────╢
║  ▶ ● obsidian [已安装]
║    ○ notegen [未安装]
╠════════════════════════════════════════════════════════════════╣
║  已选择: 1 个软件包                                        ║
╚════════════════════════════════════════════════════════════════╝

特性

✅ 智能下载: 自动检测已下载文件，跳过重复下载
✅ 自动下载: 带时间戳命名，保存到 /root/Desktop/dl30_downloads/
✅ 依赖修复: 自动执行 apt --fix-broken install
✅ 重试机制: 安装失败时最多重试 3 次
✅ 无沙箱模式: Docker 环境兼容（类似 Chrome/VSCode）
✅ 桌面集成: 自动创建桌面快捷方式和包装脚本
✅ 可执行文件检测: 智能识别 Electron 应用的正确可执行文件

智能跳过下载

安装时会自动检查下载目录是否已有该软件的 deb 文件：


# 已有文件时
[成功] 发现已下载的文件: 20260226_153854_obsidian_1.11.7_amd64.deb
[信息] 跳过下载，直接使用已有文件

# 没有文件时
[信息] 正在下载: obsidian...

🔤 输入法使用

Fcitx5 (推荐)

切换快捷键: Ctrl + Space
支持: 拼音、五笔、云拼音等

IBus (备用)

切换快捷键: Super + Space

🛠️ 故障排除

问题1: noVNC 频繁断开

解决方案: 脚本已配置心跳和超时参数

问题2: 中文显示乱码


locale-gen zh_CN.UTF-8
update-locale LANG=zh_CN.UTF-8

问题3: 输入法无法切换


killall fcitx5
fcitx5 &

问题4: 音频有噪音

确保采样率匹配 (44100Hz)
刷新音频播放器页面

问题5: VSCode 扩展安装失败

在远程桌面中手动安装扩展

🗑️ 卸载

卸载命令


make uninstall              # 交互式卸载
make uninstall-force        # 强制卸载（跳过确认）

卸载内容

XFCE4 桌面环境
VSCode Desktop
音频系统 (PulseAudio)
浏览器 (Chrome)
输入法 (Fcitx5, IBus)

保留内容

ch72 模块目录下的所有文件 (config/、logs/、scripts/ 等)

🔧 高级配置

自定义分辨率

编辑 start_desktop_fixed.sh：


RESOLUTION="1024x768"

添加 VSCode 设置

编辑 config/vscode/settings.json：


{
  "editor.formatOnSave": true,
  "editor.fontSize": 14
}

重新安装 VSCode 后生效：


./scripts/install_vscode.sh -f

日志分析


make logs       # 列出日志
make tail       # 实时查看桌面日志

📚 文档索引

文档	说明
docs/AUDIO_STREAM_SETUP.md	音频流配置详解
docs/AUDIO_SUPPORT_PLAN.md	音频支持计划
docs/DEB_INSTALLER_PLAN.md	DEB 软件安装器计划
docs/VSCODE_DESKTOP_INSTALLATION.md	VSCode 安装记录
docs/VSCODE_MCP_SERVER_PLAN.md	MCP Server 计划
docs/obsidian-install-fix.md	Obsidian 安装问题排查与修复

📋 Makefile 命令速查


# 常用
make install     # 安装桌面环境
make start       # 启动所有服务
make stop        # 停止所有服务
make status      # 查看状态
make access      # 显示访问地址

# 音频
make audio-install   # 安装音频系统
make audio-start     # 启动音频
make audio-status    # 查看状态

# VSCode
make vscode-install  # 安装 VSCode
make vscode-check    # 检查状态

# MCP
make vscode-mcp-install  # 安装 MCP 扩展
make vscode-mcp-status   # MCP 状态
make vscode-mcp-help     # MCP 帮助

# DEB 软件管理
make deb-list              # 列出可安装软件
make deb-install-obsidian  # 安装 Obsidian
make deb-install-all       # 安装所有软件
make deb-uninstall         # 交互式卸载菜单
make deb-uninstall-all     # 自动卸载所有
make deb-status            # 查看已安装软件

# 卸载
make uninstall           # 交互式卸载
make uninstall-force     # 强制卸载

# 其他
make test        # 运行测试
make menu        # 交互菜单
make logs        # 查看日志
make tail        # 实时日志

📞 技术支持

如遇问题，请检查：

日志文件 (logs/ 目录)
服务状态 (make status)
网络连接和端口可用性

📄 许可证

本项目基于 Debian/Ubuntu 官方软件包，遵循相应开源许可证。

🙏 致谢

XFCE 团队提供优秀的桌面环境
noVNC 项目提供 Web VNC 解决方案
Fcitx 团队提供输入法框架
JuehangQin 提供 VSCode MCP Server 扩展

最后更新: 2026-02-26 版本: 2.1 维护者: OpenClaw Automation

35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen

京ICP备11018762号-111