基于CNB官方 default-dev-env（Debian:bookworm） 开发环境构建的完整 KDE Plasma 桌面环境，支持 VNC 和 noVNC 访问，包含火狐浏览器、Microsoft Edge、完整中文环境和中文输入法支持。

在你的CNB项目中快速启动

# 添加以下内容到 .cnb.yml 文件中
$:
  vscode:
    - docker:
        image: docker.cnb.cool/xqitw/kde-dev-env:latest
      services:
        - vscode
        - docker
      env:
        RUN_AS_ROOT: false
        GEOMETRY: 1920x1080
        # 注意修改VNC连接密码
        VNC_PASSWORD: <PASSWORD>
        CNB_WELCOME_CMD: /usr/local/bin/start.sh
      stages:
        - name: vscode go
          type: vscode:go

• 🖥️ 桌面环境: KDE Plasma 现代桌面环境
• 👥 多用户支持: root 和 kdeuser 双用户模式，灵活切换
• 🔗 远程访问: VNC 服务器 (5901) + noVNC Web 访问 (6080)
• 🌐 浏览器: Microsoft Edge（含安全模式启动）
• 🪟 Windows应用: CrossOver 兼容层，可运行 Windows 软件
• 🛠️ 开发工具: JetBrains Toolbox、HexHub
• 💬 通讯软件: 微信 Linux 版
• 🇨🇳 中文支持: 完整中文语言环境 + 中文字体
• ⌨️ 中文输入: fcitx5 拼音输入法，完美支持各应用
• 🐚 Shell 环境: zsh + oh-my-zsh，支持语法高亮和自动补全
• 📦 软件源: 阿里云镜像源，加速下载
• 🎨 用户友好: 桌面快捷方式 + 图形化配置工具
• ⚡ CNB集成: 支持 CNB 平台自动构建和部署

1. 配置环境变量 (可选)

   编辑 docker-compose-kde.yml：

   environment:
     - GEOMETRY=1920x1080      # 屏幕分辨率
     - VNC_PASSWORD=vncpassword # VNC 连接密码
   

2. 启动容器

   docker compose -f docker-compose-kde.yml up -d
   

3. 访问桌面

   • Web 访问 (推荐): http://localhost:6080/vnc.html
   • VNC 客户端: localhost:5901

地址: http://localhost:6080
密码: vncpassword (或您设置的密码)

地址: localhost:5901
密码: vncpassword (或您设置的密码)

在 docker-compose-kde.yml 中修改：

environment:
  - GEOMETRY=1366x768  # 可选: 1280x720, 2560x1440 等

在 docker-compose-kde.yml 中修改：

environment:
  - VNC_PASSWORD=yourpassword  # 设置您的密码，root和kdeuser共用此密码

在 docker-compose-kde.yml 中修改：

environment:
  - RUN_AS_ROOT=true  # 设置为 true 以 root 用户运行，false 为 kdeuser 用户

# 启动容器（默认使用 kdeuser）
docker compose -f docker-compose-kde.yml up -d

# 以 root 用户启动容器
export RUN_AS_ROOT=true
docker compose -f docker-compose-kde.yml up -d

# 停止容器
docker compose -f docker-compose-kde.yml down

# 重启容器
docker compose -f docker-compose-kde.yml restart

# 查看容器日志
docker logs kde-desktop

├── .cnb/                        # CNB 平台配置目录
│   ├── web_trigger.yml         # Web 触发器配置
│   └── *.yml                   # CI/CD 流水线配置
├── scripts/kde/                 # KDE 环境配置脚本目录
│   ├── configure-fcitx5-kdeuser.sh    # kdeuser 用户输入法配置
│   ├── configure-fcitx5-root.sh       # root 用户输入法配置
│   ├── configure-zsh-kdeuser.sh       # kdeuser 用户 zsh 配置
│   ├── create-desktop-icons-kdeuser.sh # kdeuser 用户桌面图标
│   ├── create-desktop-icons-root.sh    # root 用户桌面图标
│   ├── start.sh                  # VNC 服务启动脚本
│   └── xstartup                  # X11 启动配置
├── docker-compose-kde.yml       # Docker Compose 配置
├── kde.Dockerfile               # Docker 镜像构建文件
└── README.md                    # 项目说明文档

• 切换快捷键: Ctrl + Space（推荐使用）
• 配置工具: 系统设置 → 区域设置 → 输入法
• 支持应用:
  • ✅ Microsoft Edge、Firefox 等浏览器
  • ✅ CrossOver 内的 Windows 应用
  • ✅ 终端、Konsole
  • ✅ KDE 原生应用
  • ✅ JetBrains IDE、VS Code
• 输入法引擎: fcitx5 + 中文拼音输入法
• 皮肤主题: Breeze（与 KDE 主题完美融合）

• kdeuser 用户（默认）:
  • 更安全的日常使用模式
  • 自动配置 oh-my-zsh 和插件
  • 完整的桌面快捷方式
• root 用户:
  • 适用于需要管理员权限的操作
  • Microsoft Edge 提供安全模式启动
  • 适合开发和系统管理任务

• 启动方式: 桌面 "CrossOver" 快捷方式
• 首次使用: 需要配置 Windows 容器（推荐 Windows 10）
• 可安装应用: Microsoft Office、Adobe 软件、经典游戏等
• 注意事项:
  • CrossOver 为演示版本，功能完整但可能有水印
  • 部分软件可能需要额外配置或兼容性调整
  • 建议在容器内使用，避免影响主机系统
  • 首次启动较慢，请耐心等待初始化

• JetBrains Toolbox:
  • 桌面快捷方式一键启动
  • 可安装 IntelliJ IDEA、PyCharm、WebStorm 等
  • 自动检测已安装的 IDE
• HexHub:
  • 先进的数据库、Docker、SSH、SFTP桌面GUI工具
• 微信:
  • Linux 原生版本，功能完整
  • 支持文件传输、语音通话
  • 注意：需扫码登录，建议使用手机微信

• kdeuser 用户: 直接启动，功能完整
• root 用户: 自动使用安全模式（--no-sandbox）
• 优势: 专为容器环境优化，避免权限问题
• 快捷方式: 桌面提供专用图标，自动选择合适模式

• Microsoft Edge: 网页浏览器（智能选择运行模式）
• CrossOver: Windows 应用兼容层
• HexHub: 先进的数据库、Docker、SSH、SFTP桌面GUI工具
• JetBrains Toolbox: IDE 管理工具
• 微信: 即时通讯软件

• 默认 Shell: zsh（替代传统 bash）
• 插件支持:
  • zsh-autosuggestions：命令自动补全建议
  • zsh-syntax-highlighting：语法高亮显示
• 用户配置:
  • kdeuser 用户：完整 oh-my-zsh 环境
  • root 用户：优化的 zsh 配置
• 优势: 更智能的命令提示、更丰富的主题、更好的交互体验

• 智能命令历史搜索
• 语法错误实时高亮
• 自动建议可能的命令
• 美观的命令行界面

端口	服务	说明
5901	VNC Server	VNC 客户端连接端口
6080	noVNC Web	Web 浏览器访问端口 (自动跳转)

• Docker: 20.10+
• 内存: 推荐 8GB+ (CrossOver 需要)
• 存储: 建议 16GB+ (Windows 容器空间)
• 网络: 稳定的网络连接

Q: 容器启动很慢？ A: 首次启动需要初始化 KDE 环境、输入法、桌面图标等，建议等待 2-3 分钟。后续启动会更快。

Q: 中文显示异常或乱码？ A:

• 检查系统语言环境：echo $LANG 应该显示 zh_CN.UTF-8
• 确认中文字体安装：fc-list | grep -i chinese
• 重启容器可解决大部分显示问题

Q: 输入法无法切换或候选框不显示？ A:

• 确保按 Ctrl + Space 组合键（非 Caps Lock）
• 检查 fcitx5 状态：ps aux | grep fcitx5
• 重启输入法：killall fcitx5 && fcitx5 -d &
• 某些应用首次启动可能需要手动激活输入法

Q: Edge 浏览器无法启动？ A:

• kdeuser 用户：直接使用桌面快捷方式
• root 用户：已自动使用安全模式启动脚本
• 如仍失败，检查日志：docker logs kde-desktop

Q: CrossOver 启动失败或报错？ A:

• 首次启动需要初始化 Windows 容器，请耐心等待
• 确保有足够的磁盘空间（建议至少 5GB 可用空间）
• 如提示许可证问题，这是正常的演示版限制

Q: 桌面快捷方式点击无响应？ A:

• 检查文件权限：ls -la ~/Desktop/*.desktop
• 确保文件可执行：chmod +x ~/Desktop/*.desktop
• root 用户桌面在 /root/Desktop，kdeuser 用户在 /home/kdeuser/Desktop

Q: VNC 连接被拒绝？ A:

• 确认容器运行状态：docker ps
• 检查端口映射：docker port kde-desktop
• 验证防火墙设置，确保 5901 和 6080 端口开放

Q: noVNC Web 界面显示黑屏？ A:

• 等待 VNC 服务器完全启动（通常 10-30 秒）
• 刷新浏览器页面或清除缓存
• 检查容器日志查找具体错误信息

构建镜像:

• 在项目页面的 Web 界面点击 "构建KDE镜像" 按钮
• 可自定义镜像版本号，默认使用 latest

生成 Wiki:

• 点击 "生成项目wiki" 按钮自动生成项目文档
• Wiki 将基于当前仓库内容创建，便于团队协作

环境变量说明:

• DOCKER_IMAGE_VERSION: 镜像版本标签
• CNB_REPO_SLUG: 仓库标识名
• CNB_BRANCH: 分支名称

• 基础镜像: cnbcool/default-dev-env:latest
• 操作系统: Debian 12 (Bookworm)
• 桌面环境: KDE Plasma
• VNC 服务: TigerVNC + noVNC
• 输入法: fcitx5 + 中文拼音输入法
• Shell 环境: zsh + oh-my-zsh + 插件生态
• 包管理: apt + 阿里云镜像源
• 容器编排: Docker Compose
• CI/CD: CNB 平台集成

本项目基于 MIT 许可证开源。详情请参见 LICENSE 文件。

---

提示: 首次使用建议通过 Web 浏览器访问，体验更佳！