Devtop — Web 桌面开发环境

基于 linuxserver/webtop (Ubuntu XFCE) 构建的容器化开发桌面环境，针对 CNB 云原生开发平台优化。

核心特性

特性	说明
Web 桌面	通过浏览器访问完整 XFCE 桌面 (HTTP 3000 / HTTPS 3001)
中文支持	Locale、字体、fcitx5 输入法开箱即用
开发工具链	Node.js、Go、Rust、Python (uv)、Bun、pnpm 预装
VS Code Server	内置 code-server + CNB 扩展
Docker (DinD)	容器内可用 Docker
配置持久化	`/config` (abc 用户 HOME) 完整实时同步到 `/workspace/config`，容器重建不丢失

文件结构

.
├── .cnb.yml                      # CNB 平台配置（镜像、环境变量、启动命令）
├── .gitignore                    # 排除 /config 持久化目录等
├── README.md                     # 本文件
├── webtop-env.md                 # 详细环境技术文档
├── assets/
│   └── welcome.sh                # 容器启动回调（启动前持久化预处理）
├── devtop-env/
│   ├── Dockerfile                # 镜像构建定义
│   ├── settings.json             # VS Code 机器级配置
│   ├── cnb-init-from             # CNB 仓库初始化工具
│   ├── cnb-init-from-without-lfs
│   └── scripts/
│       ├── start-webtop.sh       # webtop 服务启动脚本（核心）
│       ├── add-zsh-plugins.sh    # zsh 插件配置
│       └── set-zsh-env.sh        # zsh 环境变量配置
├── devtop-push/
│   └── push.sh                  # 镜像推送脚本
└── config/
    └── .tmux.conf               # tmux 默认配置（构建时 COPY 进镜像）

配置持久化机制（重点）

在终端中运行来同步 /workspace 到仓库

cd /workspace && bash sync-workspace.sh

问题：CNB 平台仅持久化 /workspace，而 webtop 的 abc 用户 HOME 为 /config。容器重建后，/config 中的用户配置（oh-my-zsh、zshrc、XFCE 设置、npm 缓存、IDE 配置等）会丢失。

方案：只保留一套持久化机制，把 /workspace/config 作为 /config 的唯一持久化实体。

单根持久化：`/workspace/config`

通过 mount --bind 将 /workspace/config 绑定到 /config，实现零延迟、零后台进程的完整实时同步。

/workspace/config  ──bind mount──►  /config

场景	行为
首次启动	将 `/config` 默认内容复制到 `/workspace/config`，然后执行 bind mount
日常运行	`/config` 的所有读写实时落到 `/workspace/config`，完全透明
容器重建后	`/config` 被重置，但 `/workspace/config` 保留；启动时直接 bind mount，完整恢复
权限	bind mount 后自动 `chown -R abc:abc /config`
重复启动	已检测到 `/config` 由 `/workspace/config` 提供时，脚本不会继续叠加新的 bind mount

技术实现

devtop-env/scripts/start-webtop.sh 中的 setup_persist() 函数负责初始化 /workspace/config 并执行 bind mount
assets/welcome.sh 在调用 start-webtop 之前先 source 并执行 setup_persist，自身不负责启动服务，确保即使不重建镜像也能生效
/workspace/config 已加入 .gitignore，不会被提交到仓库

现在只需要理解一件事：/config 的持久化实体就是 /workspace/config。

构建与部署

前置条件

本地安装 Docker
登录 CNB Docker 制品库：docker login docker.cnb.cool

构建镜像

docker build -t devtop:latest ./devtop-env

推送镜像

bash ./devtop-push/push.sh

生效方式

推送镜像后，在 CNB 平台停止并重新打开 workspace
新镜像会自动拉取，持久化数据自动恢复

使用方式

Web 桌面访问

HTTP：http://<host>:3000/
HTTPS：https://<host>:3001/（推荐，WebCodecs 需要）
CNB 代理：通过 CNB_VSCODE_PROXY_URI 端口映射访问

手动启动 webtop

start-webtop        # 前台运行
start-webtop &      # 后台运行

持久化数据重置

如需重置某项配置到镜像默认状态：

# 例如重置 zsh 配置
rm -rf /workspace/config/.zshrc
# 重启容器或重新运行 start-webtop

环境变量

变量	说明
`PUID` / `PGID`	容器内 abc 用户映射的宿主机 UID/GID
`TZ`	时区，默认 `Asia/Shanghai`
`LC_ALL`	语言环境，默认 `zh_CN.UTF-8`
`SELKIES_MASTER_TOKEN`	Selkies 安全令牌，自动取自 `CNB_TOKEN`
`PIXELFLUX_WAYLAND`	设为 `true` 启用 Wayland 模式